Today the chat agent can only observe autonomous work -- list tasks, read logs -- and act on it as an outsider through coarse verbs (spawn, stop). It cannot TALK to a running agent. An operator who can see a task going wrong has no way to say "stop guessing, the config lives at X" without killing the task and starting over, losing everything the agent had already worked out. Archie should behave like a living system whose parts can address each other, not a set of isolated processes with a dashboard bolted on.
Prior art: pi-intercom
Pi ships pi-intercom, which solves this shape for Pi sessions on one machine and is worth reading before designing (/home/sam/.pi/agent/npm/node_modules/pi-intercom; skills/pi-intercom/SKILL.md is the usage guide). Its model:
Sessions take names (/name planner, /name worker-backend) and address each other by name.
ask -- BLOCKS until the target replies, with a timeout. The blocking form is the interesting one: it lets a worker stop and get a decision instead of guessing.
reply -- answers an inbound ask, threaded automatically.
pending -- lists unresolved inbound asks, i.e. who is waiting on you.
list -- connected sessions and their state (idle / thinking / tool), for discovering targets.
Its use cases map directly onto archie: planner-to-worker delegation, context and findings handoff, blocking clarification, subagent escalation (need_decision, interview_request), cross-project coordination.
What is genuinely different here
Do NOT copy pi-intercom's transport. It ships its own local IPC broker (broker/broker.ts, a socket server with framing, spawn and runtime-claim logic) because Pi has no message bus. Archie already has one: NATS, with per-task subjects already defined in internal/agentexec/subjects.go (archie.agent..system and .events) and a request/reply pattern already used by taskrun, forgerpc, storerpc and worktreerpc. Building a second broker alongside it would be the "two parallel abstractions" mistake this repo already made once with gateway.BasePlatformAdapter.
So the real design questions are:
Does agent-directed messaging ride the existing per-task subjects, or does it need its own contract and subject family? Note CLAUDE.md's recorded NATS traps -- work-queue retention forbids overlapping consumers, and reply inboxes are core-NATS-only and are not stream subjects.
What is addressable? Running tasks have ids. The curator, channels and the daemon itself do not have a uniform identity for this purpose. An address space has to be decided before verbs are.
How does a BLOCKING ask work against an agent that is mid-model-call? A worker is not sitting in a receive loop; it is inside an agentloop turn. Delivering a message it will actually notice, without corrupting the turn, is the hard part -- and is where this stops being a transport problem.
Authorization: an operator messaging their own task is fine. Cross-identity messaging is not, and multi-identity deployments are supported (deployments/multi-forge-github-gitea.toml). Whatever the gateway's task tools enforce for identity scoping, this must enforce too.
Does an inbound operator message become part of the agent's context permanently, or a one-shot injection? This decides whether it can be used to steer a task or only to interrupt it.
Relationship to existing work
Overlaps archie-core-absb (agent cannot send local files) only in spirit: both are about the agent being able to communicate outward.
The curator (internal/domain/curator) is a natural second participant after running tasks.
Any design here should be checked against docs/architecture/organisation.md: the domain declares the contract it needs; the transport implements it.
Success Criteria
An operator can address a running agent from chat and have it receive the message without the task being killed and restarted; a blocking ask returns the agent's answer or times out cleanly; participants are discoverable with their current state; messaging is identity-scoped so one identity cannot address another's work; the mechanism reuses the existing NATS transport rather than introducing a second broker; a design decision is recorded in docs/prds/ before implementation, per CLAUDE.md's scope discipline.
Notes
Provenance correction 2026-08-25: this bead's description says 'Pi ships pi-intercom'. That is WRONG and Sam corrected it -- pi-intercom is a THIRD-PARTY PLUGIN written by a different developer solving their own problem, not a Pi feature and not endorsed by Pi. Weigh it accordingly: it is one developer's solution worth reading for its verb vocabulary (send/ask/reply/pending/list) and for the blocking-ask idea, not a reference implementation carrying Pi's design authority. The architectural judgement in this bead stands unchanged: do NOT adopt its broker, because archie already has NATS.
Close reason
Closed
Imported from beads archie-core-8s7v · GitHub #633 · type epic · priority P2 · created 2026-08-24 · closed 2026-09-23
Today the chat agent can only observe autonomous work -- list tasks, read logs -- and act on it as an outsider through coarse verbs (spawn, stop). It cannot TALK to a running agent. An operator who can see a task going wrong has no way to say "stop guessing, the config lives at X" without killing the task and starting over, losing everything the agent had already worked out. Archie should behave like a living system whose parts can address each other, not a set of isolated processes with a dashboard bolted on.
## Prior art: pi-intercom
Pi ships `pi-intercom`, which solves this shape for Pi sessions on one machine and is worth reading before designing (/home/sam/.pi/agent/npm/node_modules/pi-intercom; skills/pi-intercom/SKILL.md is the usage guide). Its model:
- Sessions take names (`/name planner`, `/name worker-backend`) and address each other by name.
- `send` -- fire-and-forget notification. Task assignment, status, notice.
- `ask` -- BLOCKS until the target replies, with a timeout. The blocking form is the interesting one: it lets a worker stop and get a decision instead of guessing.
- `reply` -- answers an inbound ask, threaded automatically.
- `pending` -- lists unresolved inbound asks, i.e. who is waiting on you.
- `list` -- connected sessions and their state (idle / thinking / tool), for discovering targets.
- Its use cases map directly onto archie: planner-to-worker delegation, context and findings handoff, blocking clarification, subagent escalation (`need_decision`, `interview_request`), cross-project coordination.
## What is genuinely different here
Do NOT copy pi-intercom's transport. It ships its own local IPC broker (broker/broker.ts, a socket server with framing, spawn and runtime-claim logic) because Pi has no message bus. **Archie already has one**: NATS, with per-task subjects already defined in internal/agentexec/subjects.go (archie.agent.<id>.system and .events) and a request/reply pattern already used by taskrun, forgerpc, storerpc and worktreerpc. Building a second broker alongside it would be the "two parallel abstractions" mistake this repo already made once with gateway.BasePlatformAdapter.
So the real design questions are:
1. Does agent-directed messaging ride the existing per-task subjects, or does it need its own contract and subject family? Note CLAUDE.md's recorded NATS traps -- work-queue retention forbids overlapping consumers, and reply inboxes are core-NATS-only and are not stream subjects.
2. What is addressable? Running tasks have ids. The curator, channels and the daemon itself do not have a uniform identity for this purpose. An address space has to be decided before verbs are.
3. How does a BLOCKING ask work against an agent that is mid-model-call? A worker is not sitting in a receive loop; it is inside an agentloop turn. Delivering a message it will actually notice, without corrupting the turn, is the hard part -- and is where this stops being a transport problem.
4. Authorization: an operator messaging their own task is fine. Cross-identity messaging is not, and multi-identity deployments are supported (deployments/multi-forge-github-gitea.toml). Whatever the gateway's task tools enforce for identity scoping, this must enforce too.
5. Does an inbound operator message become part of the agent's context permanently, or a one-shot injection? This decides whether it can be used to steer a task or only to interrupt it.
## Relationship to existing work
- Overlaps archie-core-absb (agent cannot send local files) only in spirit: both are about the agent being able to communicate outward.
- The curator (internal/domain/curator) is a natural second participant after running tasks.
- Any design here should be checked against docs/architecture/organisation.md: the domain declares the contract it needs; the transport implements it.
## Success Criteria
An operator can address a running agent from chat and have it receive the message without the task being killed and restarted; a blocking ask returns the agent's answer or times out cleanly; participants are discoverable with their current state; messaging is identity-scoped so one identity cannot address another's work; the mechanism reuses the existing NATS transport rather than introducing a second broker; a design decision is recorded in docs/prds/ before implementation, per CLAUDE.md's scope discipline.
### Notes
Provenance correction 2026-08-25: this bead's description says 'Pi ships pi-intercom'. That is WRONG and Sam corrected it -- pi-intercom is a THIRD-PARTY PLUGIN written by a different developer solving their own problem, not a Pi feature and not endorsed by Pi. Weigh it accordingly: it is one developer's solution worth reading for its verb vocabulary (send/ask/reply/pending/list) and for the blocking-ask idea, not a reference implementation carrying Pi's design authority. The architectural judgement in this bead stands unchanged: do NOT adopt its broker, because archie already has NATS.
### Close reason
Closed
---
_Imported from beads `archie-core-8s7v` · GitHub #633 · type epic · priority P2 · created 2026-08-24 · closed 2026-09-23_
sam
added the mediumepic labels 2026-10-27 13:39:24 +00:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Today the chat agent can only observe autonomous work -- list tasks, read logs -- and act on it as an outsider through coarse verbs (spawn, stop). It cannot TALK to a running agent. An operator who can see a task going wrong has no way to say "stop guessing, the config lives at X" without killing the task and starting over, losing everything the agent had already worked out. Archie should behave like a living system whose parts can address each other, not a set of isolated processes with a dashboard bolted on.
Prior art: pi-intercom
Pi ships
pi-intercom, which solves this shape for Pi sessions on one machine and is worth reading before designing (/home/sam/.pi/agent/npm/node_modules/pi-intercom; skills/pi-intercom/SKILL.md is the usage guide). Its model:/name planner,/name worker-backend) and address each other by name.send-- fire-and-forget notification. Task assignment, status, notice.ask-- BLOCKS until the target replies, with a timeout. The blocking form is the interesting one: it lets a worker stop and get a decision instead of guessing.reply-- answers an inbound ask, threaded automatically.pending-- lists unresolved inbound asks, i.e. who is waiting on you.list-- connected sessions and their state (idle / thinking / tool), for discovering targets.need_decision,interview_request), cross-project coordination.What is genuinely different here
Do NOT copy pi-intercom's transport. It ships its own local IPC broker (broker/broker.ts, a socket server with framing, spawn and runtime-claim logic) because Pi has no message bus. Archie already has one: NATS, with per-task subjects already defined in internal/agentexec/subjects.go (archie.agent..system and .events) and a request/reply pattern already used by taskrun, forgerpc, storerpc and worktreerpc. Building a second broker alongside it would be the "two parallel abstractions" mistake this repo already made once with gateway.BasePlatformAdapter.
So the real design questions are:
Relationship to existing work
Success Criteria
An operator can address a running agent from chat and have it receive the message without the task being killed and restarted; a blocking ask returns the agent's answer or times out cleanly; participants are discoverable with their current state; messaging is identity-scoped so one identity cannot address another's work; the mechanism reuses the existing NATS transport rather than introducing a second broker; a design decision is recorded in docs/prds/ before implementation, per CLAUDE.md's scope discipline.
Notes
Provenance correction 2026-08-25: this bead's description says 'Pi ships pi-intercom'. That is WRONG and Sam corrected it -- pi-intercom is a THIRD-PARTY PLUGIN written by a different developer solving their own problem, not a Pi feature and not endorsed by Pi. Weigh it accordingly: it is one developer's solution worth reading for its verb vocabulary (send/ask/reply/pending/list) and for the blocking-ask idea, not a reference implementation carrying Pi's design authority. The architectural judgement in this bead stands unchanged: do NOT adopt its broker, because archie already has NATS.
Close reason
Closed
Imported from beads
archie-core-8s7v· GitHub #633 · type epic · priority P2 · created 2026-08-24 · closed 2026-09-23