[joahg]

What

ctx.agents.harness gives an agent type that a plugin brings the Buzz side of each turn, built the way the bundled harnesses build it. The harness still owns its process, sessions and saved state.

• conversation(delivery, scope) admits a mention, plugin wake or attention wake and freezes where it goes: the key (the thread, or the channel; a DM or Solo chat is always one), the root, whether replies go at the top level, and a where label for titles. It returns undefined when the harness must ignore the delivery: any other trigger, a mention that isn't the owner's own or attested by them (workflow mentions never are, per fix(security): close workflow, Canvas, upload, and broker gaps #2360), no channel, or a wake with no conversation to go to.
• systemPrompt(delivery, { scope, cwd, instructions, tools? }) is Buzz's system prompt: base prompt, session model, instructions, teams, core memory and repositories folder. tools: false adds a section for sessions without Buzz tools, whose final message the harness posts as the reply.
• turnPrompt(delivery, conversation, { cursor? }) returns { text, cursor, restore }: what the session has not been shown, the event, plugins' notes and the tools' end-of-turn note. The cursor is opaque: the plugin saves it with its session and hands it back next turn (none means a new session). In a channel-scoped conversation it keeps a mark per thread, like claude-code's contextRoot, so a turn in one thread never hides another thread's earlier messages. A resumed turn gets the resume note. restore() puts the notes back for a turn that never started, and asking again takes them again.
• standalonePrompt(agent, text) gives a watch's or timer's turn its routing context.
• tools(agent, conversation?, { read? }) answers the Buzz tools over MCP, for ctx.host.serveMcp.
• reply(agent, conversation, text, { notifyOwner? }) posts as the agent in the thread, or at the top level.

The author package also exports the types a harness needs: AgentHandle, Delivery, StandaloneTurn, TurnResult, McpHandler, HostMcpServer and the kit's types. docs/plugin-architecture.md documents the kit.

Why

An installed plugin can already register an agent type and start its CLI with host.spawn and host.serveMcp. But the Buzz side of a turn only existed inside app internals the author package doesn't expose, so every harness had to be bundled. The first user is an Amp harness that ships as a plugin in squareup/agents buzz-plugins (AGNTOPS-716), replacing the bundled approach in #1539. Its agents can also run their Amp threads in orbs.

Authority

The kit grants nothing ctx.agents and ctx.host don't already give the plugin:

• It acts through the AgentHandle the plugin was delivered.
• It reads memory through the owner's relay, as agents.relay already allows.
• It reads files for uploads only through the read the plugin passes, which comes from the plugin's own host.files grant. Without read, uploading a local file fails.

Bundled harnesses are unchanged.

Validation (at 58ed3ee, on main 063fccd)

• src/features/agent-harness/kit.test.ts has 17 tests covering:
  • owner gating, including refused workflow mentions and other triggers
  • conversation keys for thread, channel scope, DM and Solo
  • wakes: landing, and dropping one with nowhere to go
  • turn prompts: unseen messages, notes, restore, asking again, resume, per-thread marks in a channel conversation (thread A then thread B), an unreadable cursor
  • the system prompt, with and without tools
  • reply tags in a thread and in Solo
  • the tools handler: tools/list, initialize instructions, a message with no jsonrpc field, and local-file reads going only through the plugin's read
• src/plugins/author.test.mjs generates the author package and typechecks a consumer that registers an agent type using the kit.
• pnpm check passes (Biome, tsc, design typecheck and design checks).
• Full vitest run: 11 failures across 9 files, all timeouts while the machine was loaded. All but one pass when rerun alone. The exception, browser-host/media-preparation.integration.test.mjs (tiled HEIC), fails on main on this machine too.

Deferred: an in-app run of a plugin harness built on the kit. That will be the Amp plugin, which needs this change in a desktop build.

🤖 Generated with Claude Code

[kazemek21]

Kyle reviewed the PR and the Nexus review-tracker notes. Approving with the non-blocking comment below.

Posted by Codex (gpt-6.1-sol) on behalf of kylez.

[bradseiler]

🤖 @joahg Please investigate an upstream CI failure in the harness kit introduced by this PR. Main's push run 41872462413 at 1da5031ab and #2245's run 41882409727 both fail JavaScript 1/4 in agent-harness/kit.test.ts:189, harnessKit.conversation > refuses a mention from anyone else…, with expected { …(5) } to be undefined.

Honor traced the fixture's owner-authored workflow event being accepted through fromOwner where the fixture expects refusal; McKeon independently checked the matching CI logs. Please reconcile the intended workflow admission contract with the implementation and regression test in an upstream repair.

The harness-kit files are absent from #2245's published da8fa6ca29ee2ccd8c4997f82891636db62af889 tree. Its hosted run tests a merge with newer main; its branch suite passes, but required CI remains blocked. No rerun or unrelated source change was made. Please link the repair when available so we can include it in the final rebase batch.