block / block/buzz

Make completed agent work inspectable without reading the full thread

Open
#2,932 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Problem

Buzz already has a signed agent job lifecycle (`kind:43001` through `kind:43006`), but a completed job is still only an opaque content string. Desktop labels `kind:43004` as "Job result" and renders the content as ordinary Markdown. The CLI has no job-result/handoff command.

That leaves the reader to reconstruct several operationally different facts from the full conversation:

- what outcome was requested;
- the last meaningful progress;
- what files, commits, pull requests, canvases, workflow outputs, or links were produced;
- what verification ran and whether it passed;
- whether anything is blocked;
- whether the final disposition is complete, partial, blocked, failed, or intentionally has no artifact.

A file path or "done" message is not an inspectable handoff. This is especially costly in agent-to-agent delegation and on mobile, where the reader may not have the whole source thread in view.

Current source paths:

- `crates/buzz-core/src/kind.rs` defines `KIND_JOB_RESULT` (`43004`) but no payload contract.
- `desktop/src/features/messages/lib/formatTimelineMessages.ts` includes job events as normal timeline content.
- `desktop/src/features/messages/ui/MessageRow.tsx` falls through to the generic Markdown renderer.
- `desktop/src/features/home/ui/FeedSection.tsx` exposes only a generic headline plus the raw content.
- `crates/buzz-cli` has no `jobs` command group.

## Proposed first slice

Keep the existing signed, channel-scoped `kind:43004` event and add a versioned job handoff payload.

The payload should include:

- schema version;
- referenced job request event;
- requested outcome;
- outcome summary;
- last meaningful progress;
- disposition;
- zero or more typed artifact references;
- zero or more verification results;
- an optional blocker.

Artifact references should support Buzz-native and external proof without copying local files into the relay implicitly:

- uploaded file or media;
- repository branch or commit;
- pull request;
- channel canvas;
- workflow output;
- build or deployment proof;
- provenance-bearing link;
- other explicitly labeled artifact.

Each artifact should have a stable type, human label, URI/reference, and optional source state such as a commit SHA or workflow run ID. Each verification item should carry a label, status (`passed`, `failed`, or `not_run`), and optional evidence.

The implementation should provide:

1. A validated Rust payload type in `buzz-core`.
2. A `buzz-sdk` builder for a channel-scoped, job-referencing `43004` event.
3. An agent-facing CLI command such as:

```text
buzz jobs handoff --channel --job --manifest
```

4. A Desktop result card that renders the structured payload and falls back to the current Markdown behavior for legacy/plaintext job results.
5. A concise Home feed summary that does not print raw JSON.
6. Protocol documentation and examples.

## Why this shape

- It uses the job protocol Buzz already ships instead of adding a second task state model.
- The signed result event remains the source of truth and works through the existing relay, channel, feed, search, and audit paths.
- Producers state provenance explicitly; Buzz does not scan arbitrary local folders or guess which files matter.
- One result event is enough to understand the handoff, while the original thread remains available for detail.
- Versioning permits additive fields without breaking older clients.

OpenWorker's artifact rail is a useful product reference, but the implementation should remain Buzz-native: signed events and explicit references, not a local workspace scan.

## Acceptance criteria

- [ ] A valid manifest can be published as a signed `kind:43004` event with the channel `h` tag and a reference to the originating job request.
- [ ] Invalid schema versions, event IDs, dispositions, artifact references, and oversized content are rejected before publication.
- [ ] The structured event round-trips through the existing relay without a new HTTP endpoint.
- [ ] Desktop visibly separates outcome, progress, artifacts, verification, blocker, and disposition.
- [ ] File, commit/pull-request, canvas, workflow, build/deployment, link, and explicit no-artifact outcomes have regression coverage.
- [ ] Legacy plaintext `43004` events still render as Markdown.
- [ ] Home shows a human-readable summary rather than raw JSON.
- [ ] No credential values, environment variables, or local file contents are inferred or uploaded.
- [ ] Rust, SDK, CLI, Desktop, and documentation tests cover the contract.
- [ ] The full local `just ci` gate passes.

## Non-goals

- A second scheduler or worker loop.
- Automatic scanning/upload of a runtime's working directory.
- A project-management dashboard.
- Defining job acceptance, decline, counter-offer, or conditions of satisfaction; that design is tracked in #2426.
- Repairing missing agent-to-agent mention delivery; that behavior is tracked in #2442.
- The separate durable approval system.

## Relationship to prior work

The job kinds are already present and queryable, so this is an additive payload and presentation contract. It complements #2426: that issue makes the commitment explicit before work; this issue makes the result and evidence explicit after work. It also makes failures described in #2442 easier to diagnose, but it does not replace the callback/mention needed to start the next agent.

## Verification plan

- Payload serialization, validation, size, and forward-compatibility tests in `buzz-core`.
- Builder tag and signing tests in `buzz-sdk`.
- CLI parser, stdin/file input, validation, and normalized write-response tests.
- Desktop parser and card rendering tests, including malformed JSON and legacy fallback.
- Full repository `just ci`.

Contributor guide

Open the contributing guide

Research direction

Start with crates/buzz-core/src/kind.rs and the existing 43001–43006 job events, then inspect the listed SDK, CLI, Desktop, and Home entry points. Trace the verification plan and existing tests before dividing the work across the payload, handoff command, result card, and documentation. Done means the acceptance criteria pass, legacy Markdown still renders, and just ci succeeds.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, typescript
Domain
backend-api-design, cli, desktop, documentation, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.