jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-10-28 21:11:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(agents): give collaboration vision its own document

Browse Source 
Signed-off-by: Logan Johnson <loganj@squareup.com>
This commit is contained in:
Logan Johnson
2026-09-04 11:03:15 -04:00
parent 8250ac0ddb
commit 3cfdcbef56
5 changed files with 91 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
VISION.md
View File

@@ -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.

2
VISION_ACTIVITY.md
View File

@@ -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

86
VISION_AGENT.md
View File

@@ -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

65
VISION_AGENT_COLLABORATION.md Normal file
View File

@@ -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.

8
VISION_REMOTE_AGENTS.md
View File

@@ -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.