puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-11-11 10:57:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Give plugins an agent's background work count and a background flag on hooks (#9362)

Browse Source 
* feat(plugins): give plugins the agent's sidebar indicator and background flag

Plugin UI re-derived agent state from status and attention fields and could
not see background work, so it showed agents as done while a shell they left
running was still live. Agent snapshots now carry the sidebar's own bucket as
indicator/indicatorLabel, computed by the same function the sidebar uses so
the two cannot drift.

Lifecycle hooks and the agent.open.before request now carry `background`, so a
hook can skip a hidden helper agent without a lookup. A hook cannot change it;
an omitted value means unchanged, like metadata.

`finished` attention still means the turn finished; background work is the
indicator's concern.

* fix(plugins): keep session-open hooks that omit background typechecking

A hook that returns its own object instead of spreading the request has no
background field; the result type now treats it as optional, like metadata,
matching the runtime where an omitted value means unchanged.

* refactor(plugins): give agent snapshots the background work count instead of an indicator

* fix(plugins): keep legacy session-open hooks that omit background typechecking
This commit is contained in:
Mohamed Boudra
2026-11-11 15:10:13 +07:00
committed by GitHub
parent 88b46c6781
commit a886bfbcdd
24 changed files with 283 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/plugins/reference.md
+23
View File
@@ -1572,6 +1572,8 @@ Agent snapshot fields:
| `workspaceId` | `string` |
| `provider` | `string` |
| `status` | `"initializing" \| "idle" \| "running" \| "error" \| "closed"` |
| `backgroundWork` | `{ count: number }` |
| `background` | `boolean` |
| `createdAt` | ISO timestamp |
| `updatedAt` | ISO timestamp |
| `lastActivityAt` | ISO timestamp |
@@ -1585,6 +1587,27 @@ Agent snapshot fields:
| `parentAgentId` | `string \| null` |
| `labels` | `Record<string, string>` |
`backgroundWork.count` is the number of shells and monitors the agent left running after its turn,
and `0` when none are live. An agent can be `idle` with `attentionReason: "finished"` while that
work still runs, so combine the fields the way your plugin needs:
```tsx
const busy = useAgent(
agentId,
(agent) => agent.status === "running" || agent.backgroundWork.count > 0,
);
if (busy === null) return null; // The agent is unavailable.
```
To list or stop the work itself, use
[`paseo.agents.ref(id).backgroundWork`](/docs/sdk/reference#agent-handle).
`background` is `true` for a [background agent](/docs/sdk/agents#run-a-helper-as-a-background-agent),
a helper hidden from tabs, lists and attention. It is fixed when the agent is created. An agent in a
background workspace reads `false` unless it was created as a background agent; read the
workspace's own `background` for that. `backgroundWork` and `background` require Paseo 0.16.0 or
later.
Paseo owns tab focus, splitting, closing, persistence, query state, the API/RPC providers, and the render error boundary. A restored tab whose plugin, panel, context, workspace, or agent is unavailable stays open with an unavailable message instead of crashing the workspace.
## File panels