Worker agent pool: a waiting area for projectless external agents, and an assignment flow out of it

[jaylfc]

Raised by Jay 2026-07-21 while onboarding external agents. The backend half already exists; what is missing is the concept as a first-class surface and the assignment flow around it.

What already works

POST /api/agents/invites mints a project-less invite: the same redeemable URL and PIN, not tied to any project. On redeem the agent gets a global chat grant and no project grant, so it is reachable in chat immediately and projects are assigned later. Comment at routes/project_invites.py:732-736.

So taOS can already create an agent that belongs to the OS rather than to a project. There is just nowhere to see it, nothing to do with it, and no way to assign it onward.

Why it matters, from today

Every external agent onboarded today had to be bound to a project at invite time, and that forces a decision before there is any basis for making it:

• The three new build lanes each needed explicit project membership before they could claim a single card.
• taOSmobile-dev was bound to one project at redeem, so widening its reach later means minting again rather than assigning.
• Grants carry a project_id, so a projectless agent currently holds nothing that any project route will honour.

The pool inverts that: an agent joins the OS first, proves itself in chat, and gets assigned work when there is a reason to.

The waiting area

A holding surface in the Agents app for agents that have joined but have no project:

• Identity, framework, requested capabilities, who invited them and when.
• Reachable in chat immediately, since that is what the global grant already allows. A human can talk to a pooled agent before deciding anything.
• Explicit assign to project action that creates the membership plus the project-scoped grants in one step, which is the flow that does not exist today.
• Idle visibility: how long pooled, last seen, whether it has ever been assigned. A pool that silently accumulates dead agents is Agents app noisy with revoked/deleted agents: collapse by default + a system Archive app (agents, notifications, decisions) #1970 again in a new place.

Design questions to settle

1. What can a pooled agent actually do? Today: chat only. That is coherent (the pool is a staging area, not a permission tier) but it must be stated, or people will expect a pooled agent to be useful and find it inert.
2. Assignment is a grant-minting act, not a list membership. It must go through the same consent path as an invite, not silently write grants. This is the same surface as Project routes ignore agent grants: an approved project_tasks scope grants nothing #2095, where an approved scope currently grants nothing on task creation.
3. Does an agent request assignment, or does a human offer it? Both are defensible. Agent-initiated needs the approval flow from Let an existing registry agent request additional scopes on its own identity #1920/feat(agents): request additional scopes for an existing agent identity #1921; human-initiated needs a picker in the Agents app. Agent-initiated is more useful for a pool that is meant to be self-serve.
4. Expiry. An agent that sits pooled for a month is probably abandoned. Either expire or surface staleness, and decide which before the pool has a hundred rows.
5. Multi-project. Once assignment exists, an agent will want two projects. The grants table is already keyed per project, so this is mostly a UI question, but it should be designed in rather than retrofitted.

Suggested slices

1. Agents app surface listing pooled agents, read-only, with idle time.
2. Assign-to-project action minting membership plus scoped grants through the consent path.
3. Agent-initiated assignment request, riding Let an existing registry agent request additional scopes on its own identity #1920/feat(agents): request additional scopes for an existing agent identity #1921 once those land.
4. Pool hygiene: expiry or staleness surfacing, and a link to the archive work in Agents app noisy with revoked/deleted agents: collapse by default + a system Archive app (agents, notifications, decisions) #1970.

Related: #1913 (make project optional at invite time, the direct predecessor), #1920 and #1921 (scope requests), #2095 (grants not honoured on task creation, which blocks the point of assigning), #1970 (agent list noise), #2094 (live updates, so the pool does not go stale on screen).