Route Project Work notices into Agent sessions with coalescing

[LanicBlue]

Context

T3 is the Project Consumer for its configured authenticated Client. Project Service delivers structured Work facts to a target agentId + projectId; T3 owns the mapping to runtime Sessions.

Dependencies:

• Project Service structured notice: https://github.com/LanicBlue/project-service/issues/15
• Project Service authenticated Agent binding: https://github.com/LanicBlue/project-service/issues/14
• Stable Consumer SDK artifact: https://github.com/LanicBlue/project-service/issues/12

Project Service must not know T3 Session, Thread, provider, model, workspace, or prompt-delivery details.

Consumer adapter

Integrate the supported ProjectConsumerRuntime with a thin T3 adapter:

interface RuntimeConsumerAdapter {
  listAgents(): Promise<AgentDescriptor[]>
  wakeAgent(input: StructuredWorkNotice): Promise<void>
}

listAgents() returns configured agentId + agentName. The authenticated Project Client identity comes from the credential, not a self-declared Consumer ID.

Only one active Consumer connection is allowed for the configured Project Client.

Session routing

Maintain one current Session for each:

logicalAgentId + Project Service projectId

Routing rules:

• no current Session: create one using the Agent's Provider Instance and mapped T3 project/workspace;
• active/idle Session: send one aggregate Work notification;
• busy Session: record that Work is available and defer/coalesce the notification;
• after the current Turn finishes: query authoritative open/assigned Work and send at most one aggregate notification;
• archived Session: it is no longer current; create a new Session;
• replayed noticeId/runId: do not create duplicate wake messages.

Project names and Agent names are display metadata only and may update without changing the mapping.

Aggregate notification

Do not inject each Project notice verbatim. Prefer a compact notification such as:

There are 3 assigned Work items waiting. Use the Project tools to inspect them.

The count must be refreshed from Project Service's authoritative assigned/open Work query before delivery. T3's local pending set is only debounce/dedup state, never a second Work lifecycle.

The Agent then uses internal MCP Project tools; it never receives the Project service credential or direct authenticated HTTP instructions.

Delivery semantics

• Consumer ACK means T3 accepted/routed the notice.
• ACK does not mean the Agent is running or Work completed.
• If routing fails, return the protocol's delivery failure code.
• Credential errors update integration status but do not delete the current Session.
• T3 restart/reconnect must not multiply notifications for the same still-pending notice.

Acceptance criteria

• T3 advertises configured Agents with stable ID plus display name.
• One active Project Consumer connection exists for the configured Client.
• Structured notices map by agentId + projectId to one current Session.
• Missing Sessions are created with the configured Agent/provider/workspace binding.
• Busy Sessions receive coalesced notification after the Turn, not repeated interrupts.
• Notification count comes from authoritative Project Work state.
• Duplicate/replayed notices do not create duplicate wake messages.
• Archived Sessions cause creation of a new current Session.
• Agent/Project renames affect display only.
• Credential errors preserve Sessions.
• Tests cover idle, busy, missing, archived, replay, reconnect, and restart cases.

Non-goals

• Do not mirror Project Work lifecycle into T3.
• Do not infer Agent runtime activity in Project Service.
• Do not make Project Service select a T3 Session.

[LanicBlue]

Completed in d685c4c5 (2ed6a3a5 amended).

Delivered

• Runtime integration: the vendored SDK's ProjectConsumerRuntime as a server-lifetime service — exactly ONE WS connection for the configured client (credential rides the hello; ws URL derived from the local-only base URL), inventory answered live from settings (logicalAgents changes never restart the connection), single-instance swap on URL/credential change (old closed before new opens).
• Session routing (ProjectWorkNoticeRouting): one current session per (agentId, PS projectId) — missing/archived sessions are created on the agent's provider instance with the bound T3 project; busy sessions record work and receive at most one coalesced aggregate after the turn; the queued-turn window cannot stack a second notification.
• Aggregate-only delivery: notices are triggers; the delivered message is one compact notification whose count is re-queried from the authoritative Work state (the Extend the internal MCP with trusted Project/Wiki capabilities #3 Work client) at delivery time. T3 holds no Work lifecycle mirror.
• ACK semantics: resolving = routed, never "the agent ran"; routing failures map to the protocol failure codes (AGENT_NOT_FOUND/AGENT_NOT_DISPATCHABLE drive PS repair).

Adversarial review (3 HIGH + 4 LOW, all confirmed) — fixed in the same commit

• HIGH concurrent replay bursts created duplicate sessions/aggregates (check-then-act across async seams) → every routing pass now serialized per key (Semaphore), pinned by it.live concurrency tests.
• HIGH flush-window double dispatch (phase mutated after dispatch) → same serialization; pinned.
• HIGH deferred post-turn delivery failure permanently dropped already-ACKed work → pendingWork stays set; the next thread event/wake retries.
• LOW: transient settings/secret read failures now retry on a 10s re-sync (deliberate disables never do); Work-path credential rejections surface as integration status (not a bare "connected"); test-harness dispatch now projects thread.create transactionally like the engine — the concurrency tests proved that seam load-bearing.
• Documented design choice: restart does NOT adopt the pre-restart session; a replayed still-pending notice creates the next current session exactly once (at-least-once across a restart boundary, never multiplying within a process).

Gates

root typecheck 15/15 (0 errors / 0 warnings) · apps/server 247 files / 2671 tests passed (baseline 2666 + 5) · lint/format clean · vendored SDK byte-identical (sha256 verified).

Next: E2E with a real PS — needs an operator client (PS WebUI console) + an ordinary client credential pasted into T3's Project Service settings, then: PS assigns work to a T3-advertised agent → notice → T3 session turn → agent uses project_work_list/project_work_submit → PS flow advances by Work submission.