Add user orchestrator for agent messaging and observation

[sethkarten]

Summary

This combines #164 and #173 into one user orchestrator surface for supervising multi-agent Prime Agent workflows:

• adds the agent-message skill and daemon-backed direct session messaging
• adds the agent-observe skill for read-only inspection of active agent sessions
• adds the orchestration-heartbeat skill to initialize or refresh an internal orchestrator RLM heartbeat
• exposes daemon CLI controls for listing queued messages, sending direct follow-ups, pausing/resuming delivery, and clearing a session queue
• wires the host-backed capabilities through native Prime Agent session services

The design is based on the same constraint structure as cognitive load theory and the multi-agent communication framing in Interpretable Learned Emergent Communication for Human-Agent Teams: keep coordination channels sparse, bounded, interpretable, and directly relevant to the user/operator task. The orchestrator should reduce the need to manually track session state across tmux panes, files, and memory while avoiding an unbounded chat fabric between agents.

Orchestration heartbeat

orchestration_heartbeat.initialize() creates or updates a labeled internal RLM heartbeat for the current orchestrator session. The heartbeat prompt tells the orchestrator to:

• inspect active sessions with agent_observe
• summarize each session as active, waiting, blocked, error, or completed
• include progress and explicit blockers
• recommend next actions and draft target messages when intervention is useful
• ask for user approval before cross-session messages unless a specific messaging policy was already approved
• refresh against newly visible sessions during recurring checks

This is intentionally layered on RLM heartbeats, not the user-visible /heartbeat, so the model cannot mutate the user-level heartbeat while managing orchestration checks.

Safety model

• No broadcast. Messages must target one known active session.
• No offline inbox or remote/SSH delivery in this PR.
• Message bodies are bounded by MAX_AGENT_MESSAGE_CHARS.
• Pending queues are capped by MAX_PENDING_AGENT_MESSAGES.
• Sends are rate-limited per source/target pair.
• Queues can be paused, resumed, listed, and cleared from the daemon CLI.
• Observation is read-only, count/character bounded, and exposes tool call names without tool arguments.
• Skills fail closed when no daemon controller is available.

Combined PRs

• Supersedes Add safe daemon-backed agent messaging #164: safe daemon-backed agent messaging
• Supersedes Add read-only agent observe skill #173: read-only agent observe skill

Validation

• npm run build
• npx vitest --run packages/coding-agent/test/agent-observe.test.ts packages/coding-agent/test/agent-session-bus.test.ts packages/coding-agent/test/agent-session-services.test.ts packages/coding-agent/test/kernel-agent-message-skill.test.ts packages/coding-agent/test/kernel-agent-observe-skill.test.ts packages/coding-agent/test/kernel-orchestration-heartbeat-skill.test.ts packages/coding-agent/test/kernel-rlm-heartbeat-skill.test.ts packages/coding-agent/test/suite/agent-session-observe.test.ts packages/coding-agent/test/builtin-skills.test.ts packages/coding-agent/test/daemon-command.test.ts packages/coding-agent/test/daemon-mode.test.ts
• npm run check
• pre-commit npm run check

---

Note

High Risk
Large changes to AgentSession prompt/queue lifecycle and concurrent delivery in the daemon; bugs could mis-route messages, deadlock busy sessions, or leak bounded observe previews across sessions.

Overview
Adds daemon-backed multi-session orchestration: active Prime Agent sessions can message each other, inspect peers read-only, and run a recurring internal orchestrator heartbeat.

Agent messaging routes direct text to one live session via new daemon RPC (send_message) and CLI (daemon send, daemon agent-messages). Delivery uses daemon-derived sender identity, no broadcast, size/queue/rate limits, per-target locking, and pause/resume/clear controls. AgentSession gains acceptAgentMessagePrompt / queueAgentMessagePrompt and a refactored _prompt path (skip extensions, queueIfBusy, delivery receipts) so cross-session prompts do not race normal user prompts.

Agent observe exposes bounded list/get/recent-message previews through host handlers and the agent-observe Python skill; observation cannot mutate other sessions.

Orchestration heartbeat (orchestration-heartbeat skill) composes agent_observe and rlm_heartbeat to create or refresh a labeled internal RLM heartbeat with compact progress/blocker/action instructions (separate from user /heartbeat).

Kernel bootstrap now discovers sibling Python skill dependencies from pyproject.toml and installs them in topological order. Orchestration-related skills are hidden unless the matching daemon controllers are wired on the session.

^{Reviewed by Cursor Bugbot for commit 9454cba. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add agent-to-agent messaging, observation, and orchestration heartbeat skill to daemon

• Introduces cross-session agent messaging via AgentSession.acceptAgentMessagePrompt/queueAgentMessagePrompt and a daemon sendAgentSessionMessage method with per-target locking, rate limiting, queue capacity guards, and pause/resume controls.
• Adds two new Python skills: agent-message (list agents, send messages) and agent-observe (list/get agents, fetch recent messages), each bridged to host handlers in AgentSession.
• Introduces the orchestration-heartbeat Python skill that generates recurring heartbeat instructions by observing active sessions and managing labeled RLM heartbeats.
• Extends daemon-mode.ts with new RPC commands (send_message, agent_messages_status/pause/resume/clear) and AgentObserveController wiring; adds daemon send and daemon agent-messages CLI subcommands.
• Refactors kernel bootstrap in bootstrap.ts to auto-discover sibling Python skill dependencies from pyproject.toml and install them in topological order.
• Risk: _prompt in AgentSession is significantly refactored with new accepted-prompt lifecycle tracking; existing callers relying on preflight callback shape receive a new queued flag parameter.

Changes since #207 opened

• Modified AgentSession.acceptAgentMessagePrompt to defer and queue accepted agent messages when the session becomes busy between preflight validation and prompt handoff [7ca681b]
• Added test coverage for queueing accepted agent messages when the session becomes busy before handoff [7ca681b]
• Modified AgentSession.acceptAgentMessagePrompt to fold pending next-turn messages into queued agent message prompts when the session is busy or becomes busy at handoff [7bed563]
• Added AgentSession._queuePromptWithPendingNextTurnMessages helper method and AgentSession._buildPromptContent utility to construct combined prompt content arrays [7bed563]
• Extended AgentSession._queueSteer and AgentSession._queueFollowUp to accept optional prebuilt content arrays [7bed563]
• Added test case verifying that pending next-turn context is folded into accepted agent messages queued while the session is busy [7bed563]
• Fixed context restoration in AgentSession.acceptAgentMessagePrompt when handoff busy rejection occurs without streamingBehavior [c6c4ad9]
• Moved queue update event emissions to occur after agent method invocations in AgentSession._queueSteer and AgentSession._queueFollowUp [c6c4ad9]
• Added test case verifying next-turn context restoration during handoff busy rejection in agent-session-prompt.test.ts [c6c4ad9]
• Added test case verifying queue clearing behavior with queue_update listeners in agent-session-queue.test.ts [c6c4ad9]
• Added synchronization to AgentDaemon prompt handler to await in-flight agent-message accept operations before starting daemon-originating prompts [9454cba]

^{Macroscope summarized 009ef1c.}

[sethkarten]

@kevinjosethomas addressed the agent-message queue and startup-race comments.

Changes pushed to feature/user-orchestrator:

• agent_messages_clear now removes only queued agent-message prompts instead of clearing unrelated user/heartbeat queue entries.
• Agent-message delivery treats existing pending queued work as busy, so new messages enqueue behind existing work instead of jumping ahead.
• Daemon session state is registered before extension binding, so session_start handlers can safely call agent-message / heartbeat host APIs.
• Added regression coverage for selective clear, pending-work ordering, and session-start host-controller availability.
• npm run check passed locally and via pre-commit.

GitHub CI is running on the pushed head now.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 14 total unresolved issues (including 13 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c6c4ad9. Configure here.}