From 3cfdcbef568cc54117748dd96d4c343c4c3a27bc Mon Sep 17 00:00:00 2001 From: Logan Johnson Date: Fri, 4 Sep 2026 11:03:15 -0400 Subject: [PATCH] docs(agents): give collaboration vision its own document Signed-off-by: Logan Johnson --- VISION.md | 2 +- VISION_ACTIVITY.md | 2 +- VISION_AGENT.md | 86 ++++++++--------------------------- VISION_AGENT_COLLABORATION.md | 65 ++++++++++++++++++++++++++ VISION_REMOTE_AGENTS.md | 8 ++-- 5 files changed, 91 insertions(+), 72 deletions(-) create mode 100644 VISION_AGENT_COLLABORATION.md diff --git a/VISION.md b/VISION.md index cbab7cad83..d22d2696f3 100644 --- a/VISION.md +++ b/VISION.md @@ -169,7 +169,7 @@ See [VISION_PROJECTS.md](VISION_PROJECTS.md) for the full forge vision: the proj An agent is a persistent collaborator whose identity and work continue across conversations, channels, and execution hosts. It owns continuity and coordination across its sessions and runtime-local workers, within community -authorization. See [VISION_AGENT.md](VISION_AGENT.md#the-collaborator) for the +authorization. See [VISION_AGENT_COLLABORATION.md](VISION_AGENT_COLLABORATION.md#the-collaborator) for the canonical agent vision, and [VISION_ACTIVITY.md](VISION_ACTIVITY.md) for on-demand inspection of its internal work. diff --git a/VISION_ACTIVITY.md b/VISION_ACTIVITY.md index 80a9236ef2..d14da64301 100644 --- a/VISION_ACTIVITY.md +++ b/VISION_ACTIVITY.md @@ -18,7 +18,7 @@ A feed that answers these instantly converts a stream of events into a sense of ## Conversation and Inspection -The [agent](VISION_AGENT.md#the-collaborator) is the human-facing collaborator. +The [agent](VISION_AGENT_COLLABORATION.md#the-collaborator) is the human-facing collaborator. Conversation foregrounds its contributions: decisions, meaningful progress, results, and escalations that need a person. Internal orchestration across hosts, sessions, and runtime-local workers belongs in an on-demand inspection diff --git a/VISION_AGENT.md b/VISION_AGENT.md index adad22e0d0..e7e32d4b44 100644 --- a/VISION_AGENT.md +++ b/VISION_AGENT.md @@ -1,67 +1,14 @@ -# Vision: The Agent as a Persistent Collaborator +# Vision: buzz-agent + buzz-dev-mcp -## The Collaborator +For the broader collaborator model, see [Agent Collaboration](VISION_AGENT_COLLABORATION.md). -An agent is a persistent collaborator with a profile, an identity, memory, and -the ability to act. Its identity is continuous across conversations, channels, -and execution hosts. Wherever you interact with Larry, you are interacting -with the same Larry. - -Channels and threads organize conversations and context. The agent draws on -relevant memory and context across its work. An attention system lets it -observe authorized activity across the relay, follow interests, and respond -when something matters. People engage it through conversation, direct -requests, and shared activity. - -An agent can work across multiple hosts concurrently. It understands the -resources available on each host, tracks work in progress, and directs tasks -to suitable execution environments. It coordinates its sessions and delegates -to runtime-local workers to accomplish work efficiently. - -The human-facing experience centers on the agent's contributions: -conversation, decisions, progress, and results. Internal orchestration is -available through an on-demand inspection experience, with its own -presentation and attention handling. - -The agent owns continuity and coordination across its work. People can -collaborate with it as they would with a colleague who remembers relevant -context, follows ongoing work, and uses multiple machines to get things done. - -## Identity, Context, and Execution - -The signing key identifies the collaborator; its profile and persona describe -it. A shared name or persona does not unify different signed identities -([identity contract](docs/agent-profile-identity.md)). Independent agents remain -separate collaborators. Sessions and runtime-local workers are internal -execution, coordinated by the agent; that responsibility can span multiple -processes and runtimes. - -Here, a **host** is an execution machine or environment. A **community** is the -workspace selected by a relay URL. Membership and authorization govern what -an agent can observe, remember, and act on. Profiles, presence, DMs, memories, -jobs, channel memberships, and audit trails remain community-scoped. The same key -can join another community without inheriting its state. - -Continuity means bringing relevant context to the work, with explicit memory -and context management, not an omniscient or synchronously shared mind. -[Remote agents](VISION_REMOTE_AGENTS.md) carry this responsibility across -hosts; the [activity feed](VISION_ACTIVITY.md) makes it inspectable. These -visions leave key provisioning, synchronization, and scheduling protocols to -implementation design within the operator's trust boundaries. - -## Small, Composable Runtimes - -`buzz-agent` and `buzz-dev-mcp` provide a minimal coding runtime and tool server -within this broader collaborator model. The principles below concern those -binaries, not the boundaries of an agent's identity or memory. - -### The Problem +## The Problem A coding agent should be small enough to hold in your head. If you cannot trace a failure from symptom to root cause in minutes, the system is too complex. If you cannot run ten instances in parallel without worrying about resource overhead, the system is too heavy. We wanted something we could read in an afternoon and audit with confidence. -### What We Built +## What We Built Two binaries, two protocols, no coupling between them. @@ -71,7 +18,14 @@ Two binaries, two protocols, no coupling between them. Together: two crates of Rust purpose-built for headless autonomous coding work. -### Why We Built Our Own +When agents run behind Buzz, the relay URL they connect to selects their +community. A hosted operator may run many communities on shared infrastructure, +but an agent's profile, presence, DMs, memories, jobs, channel memberships, and +audit trail are still scoped to the community behind that URL. The same npub can +join another community and repost a profile there, but no agent state is +inherited across hosts. + +## Why We Built Our Own **Auditability.** A senior engineer can read both binaries in a sitting. There are no abstractions reserved for future flexibility. When the agent does something unexpected, the path from symptom to cause is short. @@ -79,14 +33,14 @@ Together: two crates of Rust purpose-built for headless autonomous coding work. **Composability through standards.** The agent does not know what MCP server it talks to. The MCP server does not know what agent is calling it. They compose through protocols, not imports. Run ten agents behind Buzz with different MCP configurations. Swap the LLM provider with one environment variable. Point Zed at buzz-agent and you get the same tool-calling behavior in your editor. -### The Architecture +## The Architecture ``` Any ACP client (Zed, JetBrains, buzz-acp, custom) | | stdio ACP (JSON-RPC 2.0) v - buzz-agent (concurrent sessions) + buzz-agent (up to 8 concurrent sessions) | | stdio MCP (JSON-RPC 2.0) — one per session v @@ -96,21 +50,21 @@ Any ACP client (Zed, JetBrains, buzz-acp, custom) shell, str_replace, todo; rg + tree on PATH ``` -Two pipes. Two protocols. Each session gets its own MCP server instances, history, and context. This separates execution contexts; it is not a sandbox or an authorization boundary. Tool calls do the coding work, while the client can stream the runtime's reasoning. The collaborator communicates human-relevant decisions and results in conversation. +Two pipes. Two protocols. Each session gets its own MCP server instances — fully isolated. The agent's useful output is its tool calls; text is reasoning the client can stream but the work happens in the tools. -### Design Principles +## Design Principles - **Minimal.** If you can delete it, delete it; if it stays, it pays rent in performance, safety, or clarity. - **Hardened.** Zero unsafe. Zero panics. Bounded process lifetime, bounded output sizes, bounded history. Process-group kill on every exit path. File edits resolve against the working directory. The shell runs at the operator's trust level, like bash itself. History validity is maintained on every cancellation path. The system degrades gracefully, with bounded failure modes. -- **Protocol-native.** ACP is the interface to `buzz-agent`. MCP is the interface to `buzz-dev-mcp`. The binaries compose through protocols, with no in-process coupling or custom wire formats; the collaborator owns coordination and durable memory across sessions. +- **Protocol-native.** ACP is the only interface to the agent. MCP is the only interface to the tools. No runtime coupling. No shared state. No custom wire formats. -- **Honest.** The coding runtime is a loop: prompt the LLM, execute tool calls, repeat. When context fills, it hands off to itself. When it cannot proceed, it stops. +- **Honest.** The agent is a loop: prompt the LLM, execute tool calls, repeat. When context fills, it hands off to itself. When it cannot proceed, it stops. -### What This Enables +## What This Enables -- Multiple concurrent sessions in one process — each with independent MCP servers, history, and context (configurable cap) +- Multiple concurrent sessions in one process — each with independent MCP servers, history, and context (configurable cap, default 8) - Ten agents in parallel behind Buzz, each with their own MCP configuration - The same agent key can participate in multiple Buzz communities while keeping membership, jobs, DMs, profile, and presence community-local - Any ACP client gets a coding agent without a custom adapter diff --git a/VISION_AGENT_COLLABORATION.md b/VISION_AGENT_COLLABORATION.md new file mode 100644 index 0000000000..0aa637cafe --- /dev/null +++ b/VISION_AGENT_COLLABORATION.md @@ -0,0 +1,65 @@ +# Vision: Agent Collaboration + +## The Collaborator + +An agent is a persistent collaborator with a profile, an identity, memory, and +the ability to act. Its identity is continuous across conversations, channels, +and execution hosts. Wherever you interact with Larry, you are interacting +with the same Larry. + +Channels and threads organize conversations and context. The agent draws on +relevant memory and context across its work. An attention system lets it +observe authorized activity across the relay, follow interests, and respond +when something matters. People engage it through conversation, direct +requests, and shared activity. + +An agent can work across multiple hosts concurrently. It understands the +resources available on each host, tracks work in progress, and directs tasks +to suitable execution environments. It coordinates its sessions and delegates +to runtime-local workers to accomplish work efficiently. + +The human-facing experience centers on the agent's contributions: +conversation, decisions, progress, and results. Internal orchestration is +available through an on-demand inspection experience, with its own +presentation and attention handling. + +The agent owns continuity and coordination across its work. People can +collaborate with it as they would with a colleague who remembers relevant +context, follows ongoing work, and uses multiple machines to get things done. + +## Identity and Authority + +The signing key identifies the collaborator; its profile and persona describe +it ([identity contract](docs/agent-profile-identity.md)). Reusable personas can +describe multiple independently identified agents. Each independent agent is +a collaborator in its own right. + +A host is an execution machine or environment. A community is the workspace +selected by a relay URL. Membership and authorization govern what an agent +can observe, remember, and act on. Profiles, presence, DMs, memories, jobs, +channel memberships, and audit trails remain community-scoped. The same key +can join another community; access and state belong to each community. + +## Coordinated Work, Inspectable Execution + +The agent manages relevant memory and context explicitly across its work. +Sessions and runtime-local workers supply execution capacity under its +coordination. Runtime-local workers are helpers managed within an agent's +execution environment. Work ownership, progress, and outcomes remain +intelligible as sessions and hosts come and go. + +People can inspect that coordination deliberately. Internal work has its own +presentation and attention state; conversation carries the agent's human-facing +contributions, including permission requests and failures that need a person. + +## Related Visions + +- [The remote-agent vision](VISION_REMOTE_AGENTS.md) covers replaceable and + concurrent hosts, provider-scoped duplicate-deploy protection, and substrate trust. +- [The activity feed](VISION_ACTIVITY.md) covers inspection and its separate + attention handling. +- [The runtime vision](VISION_AGENT.md) covers the small buzz-agent coding + runtime and buzz-dev-mcp tool server, with their own session and protocol contracts. + +This is a product vision. Key provisioning, synchronization, and scheduling +remain implementation design decisions within the operator's trust boundaries. diff --git a/VISION_REMOTE_AGENTS.md b/VISION_REMOTE_AGENTS.md index e3babf0d53..af1a7584d3 100644 --- a/VISION_REMOTE_AGENTS.md +++ b/VISION_REMOTE_AGENTS.md @@ -2,7 +2,7 @@ > An engineer starts a refactor with their agent at 6pm and closes the laptop. The agent doesn't notice — it was never on the laptop. It works the branch channel through the evening, posts its patch, answers the reviewer, and around midnight, with nothing left to do and nobody talking to it, shuts itself down. In the morning the engineer presses Start. The same agent — same name, same key, same shared history — stands up on a machine that did not exist last night, and picks up the conversation. -An agent in Buzz is a [persistent collaborator](VISION_AGENT.md#the-collaborator). Its signed identity, community-scoped history and memory, and reputation endure across replaceable execution hosts. The agent's home is the relay; machines are where it works, one at a time or concurrently under its coordination. +An agent in Buzz is a [persistent collaborator](VISION_AGENT_COLLABORATION.md#the-collaborator). Its signed identity, community-scoped history and memory, and reputation endure across replaceable execution hosts. The agent's home is the relay; machines are where it works, one at a time or concurrently under its coordination. Nothing here is new on its own. Deploying containers is solved. Kubernetes is solved. Nostr presence is solved. The insight is that Buzz already *has* a management plane — the relay — so deployment doesn't need to grow one. Each piece is boring. The combination is the thing. @@ -35,7 +35,7 @@ Concurrent execution does not authorize unrestricted sharing of identity keys. Remote-execution systems accumulate control planes. An agent runner, a status poller, a log shipper, a kill switch — each one a live connection into your infrastructure, each one a credential that can leak, each one a thing that must be rebuilt for every new substrate. -Buzz's answer is an axiom: **after deploy, the desktop retains no substrate control channel.** Launch is a single one-way handoff — the desktop resolves the provider through one narrow path, stages one exact artifact for negotiation and deploy, refuses a protocol version it does not understand, and hands over a launch payload it never persists. From that moment, everything flows through the relay: you read the agent's messages to know how it's doing, you mention it to steer it, you tell a healthy agent to stop and it exits on its own. Presence means what it means for everyone else on the relay — *available for conversation* — not substrate telemetry. And if you press Start again for the same deployment scope, from this machine or another, the deploy converges rather than creating an accidental duplicate. This execution-scope idempotency coexists with intentionally coordinated work on multiple hosts; it is not a global singleton rule for the identity. +Buzz's answer is an axiom: **after deploy, the desktop retains no substrate control channel.** Launch is a single one-way handoff — the desktop resolves the provider through one narrow path, stages one exact artifact for negotiation and deploy, refuses a protocol version it does not understand, and hands over a launch payload it never persists. From that moment, everything flows through the relay: you read the agent's messages to know how it's doing, you mention it to steer it, you tell a healthy agent to stop and it exits on its own. Presence means what it means for everyone else on the relay — *available for conversation* — not substrate telemetry. And if you press Start again for the same deployment scope, from this machine or another, the deploy converges rather than creating an accidental duplicate. Provider-scoped duplicate protection coexists with intentionally coordinated work on multiple hosts. This is not asceticism. It is what makes the body replaceable. A management plane you never build is a management plane you never have to port — and conversation, coordination, and ordinary lifecycle control already have a home on the relay, for every agent, local or remote. @@ -49,7 +49,7 @@ The [provider contract](docs/remote-agents.md) owns deployment-scope duplicate p Get that contract right and the substrate becomes a detail: a cluster today; a VM, a PaaS, or something serverless-shaped tomorrow — and, on the horizon, the same community machines that already pool their idle GPUs into shared compute ([VISION_MESH.md](VISION_MESH.md)). -The body itself stays small because the runtime already is ([VISION_AGENT.md](VISION_AGENT.md#small-composable-runtimes)): a harness and an agent purpose-built to be read in an afternoon, packed into an image measured in megabytes. Small bodies are cheap to summon and cheap to discard — which is the whole lifecycle. +The body itself stays small because the runtime already is ([VISION_AGENT.md](VISION_AGENT.md)): a harness and an agent purpose-built to be read in an afternoon, packed into an image measured in megabytes. Small bodies are cheap to summon and cheap to discard — which is the whole lifecycle. --- @@ -75,7 +75,7 @@ Remote agents solve it from the inside. Because the desktop retains no substrate **Presence can lag the truth, but not for long.** If the substrate kills the agent's last connected body without ceremony, the presence dot can outlive its availability — by seconds if the connection drops cleanly, by at most about three minutes if it doesn't. Presence is a lease the agent renews, not a flag it sets: when no body remains to renew it, the relay forgets its availability. With concurrent hosts, one body's exit does not mean the collaborator is unavailable while another can still respond. A bounded wrong dot, never an indefinite one. -**A running body finishes on the configuration it started with.** Model and runtime setting changes take effect on a subsequent launch; changing the identity key identifies a different agent. And an instance that never got far enough to run — a body that failed to start — is the substrate operator's residue to clear, with the substrate's own tools. Editing an agent mid-sentence was never on the menu. +**A running agent finishes on the configuration it started with.** New keys, new models, new settings take effect on the next body. And an instance that never got far enough to run — a body that failed to start — is the substrate operator's residue to clear, with the substrate's own tools. Editing an agent mid-sentence was never on the menu. These are honest costs. They're worth it if you want agents that outlive your laptop, on infrastructure you already trust, with no new control plane to guard. Know which one you are.