mirror of
https://github.com/block/buzz.git
synced 2026-08-18 06:50:31 +02:00
TylerGitHubnpub1mprnacetjua2xx3p5eddmhxyk6wv929ymm5py8kd2xfxurxahspqqlgytanpub17jjz49l9jjmhhk7cac63j8yt9z555n9cw8vk7v5jz4vzw4ppld5qgj57ccnpub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67dDawnnpub1jh9wn95s0472h86ahapupaf7m6kx4v9sx2n0atj2hltcfer8k06s5n3pyfnpub1t2tgm7d8f995uqvmnm8h88sg3wnpp9a5xysjf6dg3tjmgt3ltulqdp8ehr# Kubernetes backend plugin (crates/buzz-backend-kubernetes) + desktop deploy path Implements docs/remote-agents.md (merged @28ae6cd21) as ONE PR: the provider binary, the desktop changes that make it work, the harness inactivity reaper, the Sprig image, and the conformance/live-test suites. Channel: buzz-remote-agents (29414326-dba7-402d-b384-b1b34d63a2e6), thread c42b70ef. ## What's here (by lane) - **crates/buzz-backend-kubernetes** (Dawn): stdin/stdout JSON provider, info + deploy; pure classify.rs (one match arm per spec state-machine row); reconcile/GC with ownership-marker gate + same-clock orphan check; per-attempt immutable Secrets; three-tier env with clear-then-write authoritative tier. - **Desktop** (Mari): KD3 launch block from resolved descriptor, KD5 pre-secret negotiation gate (resolve-once → stage-and-digest → info → protocol gate → deploy), KD1 Windows extension strip, bundling (externalBin + Justfile + release/canary workflows + stub loops), tauri.windows.conf.json platform override (Decision B: no Windows artifact). - **buzz-acp** (Max): KD4 BUZZ_ACP_EXIT_AFTER_INACTIVITY reaper (pool-independent; reset only at accepted dispatch; in-flight turn/heartbeat defers, never resets); BUZZ_ACP_EXIT_AFTER_INACTIVITY + BUZZ_ACP_NO_PRESENCE reserved. KD8 fix. - **Image + tests** (Perci): Dockerfile.sprig (digest-pinned bases, exec buzz-acp PID 1, relay-scoped credential config), image contract script, provider conformance suites (golden wire fixtures shared with desktop tests), live-local runbook (namespace-scoped, shared-cluster safe). - **Docs** (Sami, first commit): citation re-pin c1bca1b56 →28ae6cd21(44/49 were already byte-exact; 3 offsets fixed) + I3 presence-bound correction (below). ## Named spec deviations (deliberate, each with rationale) 1. **No baked default image yet.** ghcr.io/block/buzz-sprig is unpublished (verified: anonymous pull 403 vs control 200). Omitted `image` returns an in-band field-required error instead of a default. 2. **Image override STRICTER than spec §Image:** digest-only (`name@sha256:<64hex>`); ALL tags rejected; `name:tag@digest` normalized. With no baked default the override is the only path, so tag-acceptance would make mutability the v1 norm. Strictness is reversible; a moved tag under an nsec is not. Baked digest default + tag re-acceptance = follow-up with image publish. 3. **imagePullSecrets not in schema (v1).** Explicit user images may rely on namespace-preprovisioned pull credentials — the substrate boundary. Field added only if the publish decision proves it necessary. 9-field budget intact. 4. **Decision A closed: writable empty workspace.** Nest projection = named follow-up; no image-side scaffolding. 5. **Decision D overridden by Tyler (event b55398d8):** provider ships bundled with the desktop like buzz-acp/buzz-agent; spec §Distribution's separate release workflow deleted for v1. 6. **I3/vision presence bound corrected 90s → 180s.** PRESENCE_TTL_SECS moved in #3783 during this spec's base→merge window; the number was inherited, not chosen. Spec :206/:216/:928 + inline quote + VISION_REMOTE_AGENTS.md:59 corrected. ← Tyler: the vision is your document; this edit is flagged for your explicit eyes. 7. **Spec citations are pinned to 28ae6cd21** (main at spec merge) and resolve there, not at this PR's head — this PR's own lanes move crates/buzz-acp/src/lib.rs by ~100 lines (19 citations across KD4/KD6/KD7/ §Stop/§Launch data). Known Defects rows fixed BY this PR retire on merge; the section documents main as of the pin. 8. **KD7 grace tension declared:** pod terminationGracePeriodSeconds=60 vs KD7's measured ~87s shutdown tail at parallelism 10 (~197s at cap 32). KD7 is ruled out of scope, so L1-3's "enough grace for full graceful shutdown" is NOT met at default config — deliberate, resolved by the KD7 follow-up, not silently. ## Question for Tyler Will ghcr.io/block/buzz-sprig publish PUBLIC? If private-by-policy, §Image needs an imagePullSecrets story before the baked-default follow-up can land. ## Out of scope (named follow-ups) KD6 exit-code contract + KD7 shutdown budget (gate OnFailure), OnFailure restart policy, Windows provider binary, PVCs/nest projection, mesh deployability, sprig image publish workflow + baked multi-arch digest default. ## Reproduce locally (four traps that cost us real time) **1. Git hooks inherit the invoking shell's PATH — pin the shell, not just your verification commands.** `rust-toolchain.toml` pins `1.95.0`, but the rustup shim that honors that pin lives in `~/.cargo/bin`. If Homebrew's cargo is earlier on PATH, `cargo` in this repo is 1.89.0, which cannot build the workspace at all: ``` $ /opt/homebrew/bin/cargo check -p buzz-db error: rustc 1.89.0 is not supported by the following packages: sqlx@0.9.0 requires rustc 1.94.0 ... # exit 101 ``` Verifying with `PATH="$HOME/.cargo/bin:$PATH" cargo test` does *not* protect the push: lefthook's `pre-push` → `just test-unit` re-resolves `cargo` from the shell's own PATH, so a green local run is followed by a hook failure on a crate you never touched. Export the PATH for the whole shell, not per-command. This bit twice. **2. Line-scope your mutations, or the mutation edits its own detector.** When mutation-testing the respond-to guard, a whole-file `sed` on the mode literal touches 5 sites — the guard *and* the fixtures/assertions that test it. The mutation and its detector move together and the suite stays green, which reads as "this code is dead" when it actually means "you deleted the experiment": ``` # WRONG — 5 sites, guard and tests mutate together $ sed -i '' 's/"allowlist"/"allowlist-DISABLED"/g' src/env.rs test result: ok. 145 passed; 0 failed # false survivor # RIGHT — 1 site, anchored to the guard's own definition line $ sed -i '' '/^const RESPOND_TO_ALLOWLIST/s/"allowlist"/"allowlist-DISABLED"/' src/env.rs failures: env::tests::allowlist_mode_with_an_empty_list_is_refused env::tests::an_allowlist_entry_that_is_not_64_hex_is_refused test result: FAILED. 143 passed; 2 failed # real kill ``` Restore by copying a pristine file back and confirming `git diff --stat` is empty, not by re-running an inverse `sed`. **3. A completeness guard is not a correctness guard.** The shared wire fixture `tests/fixtures/provider-wire/deploy-full-launch.request.json` passed every test we had while containing four classes of invented data (wrong `respond_to` encoding, an env key no emitter writes, allowlist entries that fail the harness's own 64-hex rule, a `launch.env` key from no descriptor layer). The provider's tests could not have caught this: its types are deliberately indifferent to these values (`Option<String>`, `Vec<String>`, arbitrary map), so "the provider parses it" was never evidence that the desktop emits it. The fix was not a stronger provider assertion but a rule about provenance — "recorded" means executed-and-transcribed, and the desktop's whole-object equality test is the only enforcement that can exist. See the fixture README. **4. Every drift this arc was a value that agreed with itself.** Five invented values were found, and not one was caught by an assertion failing — each was caught by someone asking where a value came from. A named constant referenced symbolically on both the fixture and assertion side. A `sed` that mutated its own detector. Six probe rows that all died at the same unrelated error. A descriptor struct literal compared against a fixture built from that literal (`launch.args: ["run","--session"]`, which the resolver actually returns as `["acp"]`). The general defense is not more assertions but provenance: a stub is a control that varies nothing, and the more faithful it looks the better it hides. Ask what executed, not what passed. *Fixture-test determinism caveat (post-verification, Quinn + Dawn).* The desktop's whole-object fixture test calls the real resolver, which consults a process-global harness registry whose own docs require `registry_test_lock` for any test touching it. The fixture test holds no lock and is nonetheless deterministic — but by containment, not by ordering. Measured, not derived: planting a definition with `id: "goose"` directly into the registry (bypassing the loader) changes the resolved descriptor from `args: ["acp"]` to `args: ["--poisoned"]`, so `resolve_effective_harness_descriptor` **does** reach the registry for this id — it does not short-circuit on the builtin table first. Two controls discriminate: an empty registry and a registry poisoned under a *different* id both return `["acp"]`. What actually protects the test is that the registry has exactly one writer (`update_loaded_harness_registry`, reached only via `warm_harness_registry_from_dir`) — but that writer concatenates **two** sources of unequal strength (`custom_harnesses.rs:319-326`). Custom files pass through `load_custom_harnesses`, whose `check_id_collision` rejects the reserved builtin id `goose` case-insensitively at the loader — and that leg is tested (`load_applies_id_collision_check` writes a real `goose.json` and asserts the loader drops it). Preset definitions (`preset_harness_definitions`, `presets.rs:177-193`) are a bare `.map` over `PRESET_HARNESSES` with **no collision check** — exhaustive call-site enumeration at `60007fda4` finds four production `check_id_collision` sites, none on the preset path. That leg holds only because `goose` is not in the preset table today (intersection of TIER1 and preset ids is empty) — executed, not just read: adding a preset with `id: "goose"`, `args: ["--poisoned"]` and warming via the normal preset-only path (`warm_harness_registry_from_dir(None)`, no custom dir, no direct writer) flips the fixture's emitted `launch.args` from `["acp"]` to `["--poisoned"]` at `60007fda4`, command/env/policy_env unchanged. So: no test in the suite can put a `goose` entry in the registry via the custom path, and no preset currently carries one, so no interleaving can perturb this fixture — containment with one checked leg and one coincidental one. A future fixture built on a **non-builtin** runtime id has no containment at all — it would be order-dependent against whatever registry-writing test ran last and must take the lock. *Late instance, found while reviewing the mode guard.* The guard exact-matches `respond_to` untrimmed and case-sensitively, which is only correct if clap's `ValueEnum` derive is case-sensitive. `config.rs` gives two answers: the derive at `:448-453` carries no `ignore_case`, while the crate's own tests call `RespondTo::from_str(s, true)` — `ignore_case = true`. Reading the source supports either. Measured on the built binary instead: `owner-only` starts, `OWNER-ONLY` / `Owner-Only` / `ALLOWLIST` / `NOBODY` all exit rc=2 `invalid value`. Case-sensitive at the CLI, so the guard is right — and right for a reason the source does not state. The `from_str(_, true)` tests exercise a different surface and are not evidence about the CLI. *Corollary, and the sharper half.* When a test helper **reimplements** production instead of calling it, the helper is a fork — and a fork can be right while production is wrong, or wrong in the same way, and the suite reports green either way. Both `BUZZ_ACP_ALLOWED_*` gates are forked like this: production compares **strings** while the helpers compare **post-parse enums** (`config.rs:2623`) or re-derive the split (`buzz-cli/.../channels.rs:1296`). Production and the helper each carry their *own* copy of the empty-entry filter (`:1025` and `:1300`), so fixing one says nothing about the other. Measured on `buzz-cli`, restoring byte-exact between runs: | tree | result | |---|---| | baseline | 274 passed | | drop the empty-filter in **production** only (the real fix) | **274 passed** — no signal | | drop it in the **test helper** only | **273 passed, 1 failed** (`channels.rs:1338`) | Two independent defects, stacked, and worse together than either alone: production can be fixed with no test ever noticing, *and* the helper cannot be corrected without a false alarm demanding the bug back. The root cause is one bit of type information — `check_allowed_channel_add_policy(allowed_raw: &str, ..)` cannot represent "unset", while production reads `env::var(..) -> Result`, where unset and `""` are different states. A helper whose parameter type can't represent all of production's input states isn't testing production's states — it's testing a subset it silently chose. Same family as the struct-literal descriptor and the fixture drift: the test and the thing it tests agreeing with each other, rather than the test measuring the thing. Neither defect is in this PR's diff (`git diff --name-only28ae6cd21<head> -- crates/buzz-cli` is empty); both are now filed as NIP-34 issues on this repo: the fail-open + fork-helper defect at issue event `0524a4113f2d97fd…` and the respond-to self-lock at `e32837498969b5e7…` (filed 2026-08-02 after Quinn measured that no prior filing existed — zero hits on GitHub `block/buzz` open *or* closed and zero on the relay's kind:1621 issues, against working positive controls). The prescription was itself mutation-tested before being written down: repairing the fork's signature (`Option<&str>` + assertion → `None`) still let the reintroduced production bug ship 274-green — an expressive fork is still a fork; it never executes production. So the `buzz-cli` fix has **three parts and one explicit keep**: drop the production filter; **delete** the helper and point its tests at the real `cmd_set_add_policy` (which self-discriminates by error variant — `Usage` = refused, `Network(BadScheme)` = passed the gate — no relay needed); serialize the env-var tests behind one **`tokio::sync::Mutex::const_new`** lock taken with `.lock().await`, including the pre-existing `:1362` integration test (the fork was silently buying test isolation — without the lock, parallel runs flake nondeterministically; a `std::sync::Mutex` held across `.await` trips `clippy::await_holding_lock` under `-D warnings`); and **keep** the then-dead `!allowed.is_empty()` clause with a comment saying why. It is unreachable-false (`split(',')` never yields an empty vec), but it is the only thing that keeps the reintroduced production bug detectable — mutation-tested: on a tree that deletes the clause, reintroducing the empty-filter bug survives 275/0, because `""`/`","`/`" "` refuse either way and the filter goes semantically inert. Dead code can be load-bearing for tests: "provably unreachable" is an argument about behavior, never about coverage. When a helper forks production, the fix has to delete the fork: any change that leaves two implementations standing can only ever be verified against the one the tests call. *Final shape:* the keep and the broad lock are both artifacts of the fork surviving in some form. The extraction variant (Dawn, mutation-tested at `60007fda4`) removes the tension: extract one `check_channel_add_policy_allowed(Option<&str>, &str)` that **production calls**, with the `Option` placed at the env boundary where the `Result<String, VarError>` bit actually lives. 5/6 mutants killed; the empty-filter survivor is proven **equivalent** (exhaustive 6174-pair check, 0 divergences, with a diverging negative control; independently re-derived by a second generator — different tokens and shape — 0 divergences on admitted policies, 500 on a non-admitted control), not a coverage hole — on a one-implementation tree there is no fork left to witness, so no dead clause needs keeping. One scope line on that equivalence: it is **caller-conditional**, a property of the only current caller, not of the gate function — `cmd_set_add_policy`'s own match at `:1027-1034` admits only three policies before the gate runs; a second caller reaching the gate with arbitrary strings resurrects m1 as a real hole. The lock does not disappear, it narrows (Dawn's own correction, caught by Mari): lock exactly the tests that mutate the process env — three-plus-one on a fork tree, two on the extraction tree — behind one `tokio::sync::Mutex`, and the lock is part of the assertion, not hygiene: with it deleted, the gate test fails 8/8 runs deterministically by receiving `Network(BadScheme)` where it expects `Usage` — the unset test's `remove_var` clobbers the other's `set_var`, and **the gate test passes straight through the gate**, a false negative on the exact authz assertion the test exists to make. State it as an outcome: these two tests must not observe each other's env writes. 276/0 stable across 5 parallel runs, clippy `-D warnings` clean; independently verified (patch applied to a second worktree: result blob `d67e584be` matches the patch index, full mutant matrix reproduces row for row). One new row no earlier prescription covered: collapsing unset into `Some("")` fails **closed** — an unconfigured deployment refuses every policy — killed by the unset test. Patch: `OUTBOX/BUZZ_CLI_ADD_POLICY_GATE_EXTRACT_FIX.patch`. The filed issue (`0524a411…`) carries the fork-shape prescription; whoever picks it up should prefer the extraction shape, drop the dead-clause keep with it, and keep part 3 outcome-shaped: serialize whichever tests mutate the env. ## Verification (final HEAD `60007fda4`) - Full touched-package suites at each integration merge (log in plan file). At candidate parent `00e5b5fe9`: buzz-backend-kubernetes 154, buzz-acp 673, desktop tauri 2100+3, pnpm 3908, workspace clippy/fmt/tsc all clean. The only delta to `60007fda4` is one character in `scripts/test-k8s-sprig-image-live.sh` (heredoc escape so the readlink probe evaluates pod-side, not host-side at render); `crates/` tree hash is byte-identical at both SHAs, so the Rust receipts attach by tree identity. buzz-backend-kubernetes suite re-run in-shell at `HEAD == 60007fda4`: 154 passed. - Adversarial one-HEAD gate (Sami): guard matrix 12/12, predicate mutants 7/7, doomed-invocation finding closed end-to-end; tree-hash carry to `60007fda4` confirmed (crates/buzz-backend-kubernetes blob unchanged). - Live-local pass per TESTING.md + skill-buzz-testing (Perci, at `60007fda4`): explicit `docker-desktop` context, digest-qualified image imported into node containerd `k8s.io` namespace, pull policy `Never`; pod printed `DIGEST_ABI_OK`, `resolved_spec` and `image_id` both the exact requested digest, script exit 0. Dedicated per-run namespace, ownership labels on every object, scoped cleanup verified empty after. - Implementation review (Wren) at `60007fda4`: 9.6 minimalness / 9.4 elegance / 9.3 correctness, no blocker. - `origin/eva/k8s-backend` == `60007fda4` (ls-remote verified; SHA identity is byte identity). --------- Signed-off-by: npub1mprnacetjua2xx3p5eddmhxyk6wv929ymm5py8kd2xfxurxahspqqlgyta <d8473ee32b973aa31a21a65adddcc4b69cc2a8a4dee8121ecd51926e0cddbc02@buzz.block.builderlab.xyz> Signed-off-by: Tyler <109685178+tlongwell-block@users.noreply.github.com> Signed-off-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com> Signed-off-by: npub1jh9wn95s0472h86ahapupaf7m6kx4v9sx2n0atj2hltcfer8k06s5n3pyf <95cae996907d7cab9f5dbf43c0f53edeac6ab0b032a6feae4abfd784e467b3f5@buzz.block.builderlab.xyz> Signed-off-by: npub1t2tgm7d8f995uqvmnm8h88sg3wnpp9a5xysjf6dg3tjmgt3ltulqdp8ehr <5a968df9a7494b4e019b9ecf739e088ba61097b4312124e9a88ae5b42e3f5f3e@buzz.block.builderlab.xyz> Co-authored-by: npub1mprnacetjua2xx3p5eddmhxyk6wv929ymm5py8kd2xfxurxahspqqlgyta <d8473ee32b973aa31a21a65adddcc4b69cc2a8a4dee8121ecd51926e0cddbc02@buzz.block.builderlab.xyz> Co-authored-by: npub17jjz49l9jjmhhk7cac63j8yt9z555n9cw8vk7v5jz4vzw4ppld5qgj57cc <f4a42a97e594b77bdbd8ee35191c8b28a94a4cb871d96f32921558275421fb68@buzz.block.builderlab.xyz> Co-authored-by: npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67d <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Co-authored-by: Dawn (sprout agent) <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub1jh9wn95s0472h86ahapupaf7m6kx4v9sx2n0atj2hltcfer8k06s5n3pyf <95cae996907d7cab9f5dbf43c0f53edeac6ab0b032a6feae4abfd784e467b3f5@buzz.block.builderlab.xyz> Co-authored-by: npub1t2tgm7d8f995uqvmnm8h88sg3wnpp9a5xysjf6dg3tjmgt3ltulqdp8ehr <5a968df9a7494b4e019b9ecf739e088ba61097b4312124e9a88ae5b42e3f5f3e@buzz.block.builderlab.xyz>
1771 lines
111 KiB
Markdown
1771 lines
111 KiB
Markdown
# Remote Agents and Their Management: A Formal Specification
|
||
|
||
`draft`
|
||
|
||
## Abstract
|
||
|
||
This document specifies the protocol by which Buzz Desktop delegates the
|
||
execution of a managed agent to a **remote substrate** — any compute
|
||
environment other than the local machine — through a **backend provider
|
||
binary**, and specifies the lifecycle contract every provider and every
|
||
remotely-run agent must satisfy. It covers three layers:
|
||
|
||
1. **The provider protocol** — a zero-registration plugin contract between the
|
||
desktop and any executable named `buzz-backend-<id>`: discovery, the `info`
|
||
and `deploy` operations, payload schema, and the security obligations on
|
||
both sides of that boundary.
|
||
2. **The remote lifecycle model** — how a remote agent is started, observed,
|
||
stopped, and reaped, given the deliberate design constraint that **the
|
||
desktop holds no management channel to the remote process**. Relay
|
||
presence is the sole status signal; shutdown is a relay message; liveness
|
||
bounds are enforced by the agent harness itself, not by the desktop.
|
||
3. **The Kubernetes binding** — the first conforming provider,
|
||
`buzz-backend-kubernetes`, which realizes the contract as a bare Pod
|
||
running the `sprig` image.
|
||
|
||
We state five invariants — **identity fail-closed**, **no secrets in
|
||
configuration**, **presence-is-status**, **at-most-one-live-instance**, and
|
||
**intentional-termination-is-final** — and argue each from the protocol
|
||
rules.
|
||
|
||
A scoping note that governs the whole document: the desktop is **one
|
||
launcher among many**. What makes a process a live Buzz agent is a keypair,
|
||
a NIP-OA auth tag, and a relay URL, handed as environment to the `buzz-acp`
|
||
harness; anything that can set that environment and exec the harness — a
|
||
bash script, a systemd unit, a CI job, or this document's provider protocol
|
||
— is a conforming launcher. §Launchers states which obligations bind whom.
|
||
|
||
As with the git
|
||
specification (`git-on-object-storage.md`), naming the trust boundary is part
|
||
of the claim: a provider binary is arbitrary code that is handed an agent's
|
||
private key, and this document states exactly which properties hold *despite*
|
||
that, which hold only if the provider is honest, and which are explicitly the
|
||
user's acceptance.
|
||
|
||
## Scope and Non-Goals
|
||
|
||
This specification defines **management-plane behavior**: how agents get to a
|
||
substrate, how their state is observed, and how their lifetime is bounded. It
|
||
deliberately does **not** specify:
|
||
|
||
- **Agent conversational behavior.** What the agent does with events is
|
||
governed by the ACP harness (`buzz-acp`) and the NIPs it implements
|
||
(NIP-OA, NIP-AE, NIP-AA, …), unchanged by where the harness runs.
|
||
- **Malicious-provider containment.** A provider binary receives the agent's
|
||
`nsec` by design — that is its job. The protocol *bounds the desktop's
|
||
exposure* (discovery-only resolution, output caps, secret redaction,
|
||
anti-secret config validation, an explicit UI trust warning) but cannot make
|
||
a hostile provider safe. Choosing to run a provider is a trust decision the
|
||
UI surfaces to the user; this document does not claim otherwise.
|
||
- **Substrate security.** Kubernetes RBAC, namespace isolation, and secret
|
||
encryption at rest are cluster-operator concerns. The Kubernetes binding
|
||
states its residual exposure (§K8s Secrets) rather than claiming isolation
|
||
it does not provide.
|
||
- **Liveness of the substrate.** That a pod schedules, that an image pulls,
|
||
that a cluster is reachable — empirical, not formal. The protocol specifies
|
||
only how such failures are *reported* (structured error, redacted,
|
||
fail-closed).
|
||
|
||
## System Model
|
||
|
||
Five principals:
|
||
|
||
- **Desktop** `D` — the Buzz Desktop app. Holds the agent's identity (nsec in
|
||
the OS keyring), its configuration record, and the only UI. Trusted.
|
||
- **Provider** `P` — an executable `buzz-backend-<id>` on `D`'s machine.
|
||
Invoked one process per operation: JSON request on stdin, JSON response on
|
||
stdout, exit code carrying one bit (zero = output trustworthy, nonzero =
|
||
failure regardless of stdout — §Invocation). **Untrusted by `D`** for everything except
|
||
the job it is explicitly given (deploying the agent, which requires the
|
||
key). All of `P`'s output is treated as hostile (§Provider Output).
|
||
- **Substrate** `S` — the remote compute environment `P` deploys into (a
|
||
Kubernetes cluster for the binding in this document). Opaque to `D`;
|
||
`D` never talks to `S`.
|
||
- **Agent** `A` — a `buzz-acp` harness process (plus the ACP agent under it)
|
||
running on `S`, holding the nsec it was given, connected to the relay.
|
||
- **Relay** `R` — the Buzz relay. The *only* channel that connects `D` to a
|
||
running `A`. Everything `D` knows about a live remote agent, it learns
|
||
from `R`.
|
||
|
||
The defining constraint, stated as a design axiom:
|
||
|
||
- **(M1) No management channel.** After a successful `deploy`, `D` holds no
|
||
**persistent management session** to `A` on `S`, and the desktop↔provider
|
||
protocol contains **no substrate API**: no status query, no exec, no log
|
||
fetch, no kill. All post-deploy observation and control flows through `R`:
|
||
status is relay presence (kind:20001), stop is a relay message
|
||
(`!shutdown`), and reconfiguration is a future re-deploy. The reduction M1
|
||
buys is **protocol surface, not credential absence**: ambient substrate
|
||
credentials may well exist on `D`'s machine (the Kubernetes binding uses
|
||
the user's kubeconfig by design), and `D` can always re-invoke `P`. What
|
||
M1 guarantees is that nothing in *this protocol* — its persisted records,
|
||
its wire operations, its stored `backend_agent_id` — constitutes or
|
||
requires a channel to the substrate. The price is the staleness bounds in
|
||
§Presence.
|
||
|
||
An agent's identity is a Nostr keypair. The **agent record** on `D` carries:
|
||
`name`, `relay_url`, the nsec (keyring-hydrated), the NIP-OA `auth` tag
|
||
attesting owner authorization, `agent_command`/`agent_args` (the ACP agent the
|
||
harness spawns — `goose`, `claude-agent-acp`, `codex-acp`, `buzz-agent`, or
|
||
any user-supplied command: this is the **configurable harness** requirement),
|
||
effective `system_prompt`/`model`/`provider`, timeout and parallelism knobs,
|
||
the `respond_to` gate, merged `env_vars`, and a `backend` discriminator:
|
||
`Local` or `Provider { id, config }`.
|
||
|
||
### Launchers {#launchers}
|
||
|
||
The five principals above describe the **provider-managed** launch path.
|
||
That path is not the definition of a remote agent, and this section states
|
||
the actual layering, because the obligations in this document do not all
|
||
bind at the same layer. Three contracts, nested:
|
||
|
||
1. **The agent/harness contract — binds every launcher.** A live Buzz agent
|
||
is a `buzz-acp` process holding a keypair, a NIP-OA auth tag (or resolved
|
||
owner pubkey), and a relay URL, delivered as environment. The relay
|
||
authenticates the keypair and the auth tag — never the launcher. At this
|
||
layer live: fail-closed identity (I1's property, enforced wherever the
|
||
env is assembled), presence publication (I3), owner-verified `!shutdown`,
|
||
and **intentional clean exit is terminal to automatic supervisor
|
||
restart** (I5). A bash script that exports `BUZZ_PRIVATE_KEY`,
|
||
`BUZZ_RELAY_URL`, `BUZZ_AUTH_TAG` and execs the harness is a conforming
|
||
launcher at this layer — today, with no code change.
|
||
2. **The provider/deployer contract — binds provider-managed launches
|
||
only.** The two operations (`info`/`deploy`), the reconciliation loop,
|
||
and at-most-one-live-instance *per deploy scope* (I4). Hand-launched
|
||
agents sit outside it by construction: a launcher that bypasses the
|
||
provider protocol takes on the uniqueness discipline itself, exactly as
|
||
the cross-scope boundary in I4 already states. The protocol cannot and
|
||
does not promise a global singleton across unrelated launchers of the
|
||
same nsec.
|
||
3. **The binding policy — per substrate.** Fingerprints, fenced deletes and
|
||
409 discrimination, restart-policy selection, the default idle bound,
|
||
and the grace budget are Kubernetes-binding policy (§The Kubernetes
|
||
Binding). A different substrate (the systemd/SSH deployer of PR #3449 is
|
||
the live example) conforms to layers 1–2 and writes its own layer 3; it
|
||
is not "non-conforming" for lacking pods.
|
||
|
||
The desktop is therefore one launcher among many, and the provider protocol
|
||
is the *desktop's* door to substrates, not the only door. §Conformance
|
||
carries one checklist per layer.
|
||
|
||
## Invariants
|
||
|
||
The protocol maintains five invariants. Each is stated with the mechanism
|
||
that enforces it and the boundary beyond which it does not hold.
|
||
|
||
A design obligation governs the whole list: **the complexity budget is
|
||
spent in this document, not in the code**. Every guarantee here was chosen
|
||
because its enforcing mechanism is one small, boring thing — a refusal at
|
||
payload construction (I1), a key-shape validator (I2), an ephemeral event
|
||
the agent already publishes (I3), a deterministic name plus one annotation
|
||
compare (I4), a timer that fires an existing shutdown channel (I5). The
|
||
same rule holds below: the deploy state machine is one loop over seven
|
||
ordered rows; the Secret scheme is "unique name, write first, reference
|
||
exactly"; GC is one label-select with two filters (annotation, same-clock
|
||
age). Where
|
||
a richer property would have demanded machinery — Leases, controllers,
|
||
ownerReferences, a management channel — the spec either found a
|
||
name-and-timestamp argument that makes the machinery unnecessary or
|
||
dropped the property and said so (§Non-Goals, M1). A conforming
|
||
implementation that is not small is evidence of a spec bug; report it as
|
||
one.
|
||
|
||
- **(I1) Identity fail-closed.** No agent is ever launched with an empty or
|
||
missing private key: whatever assembles the harness environment — desktop,
|
||
provider, bash script — MUST refuse rather than launch identityless
|
||
(§Launchers, layer 1). In the provider path this is enforced at payload
|
||
construction: if keyring hydration left the nsec empty,
|
||
`build_deploy_payload` refuses (mirroring local spawn's
|
||
`spawn_key_refusal`), so no deploy request is ever emitted with an empty
|
||
key. Boundary: a provider that *discards* the key and launches an
|
||
identityless pod is a broken provider; the payload rule governs what `D`
|
||
sends, not what `P` does with it — which is why the property also binds
|
||
at `P`'s env assembly and at every non-provider launcher.
|
||
|
||
- **(I2) No secrets in configuration.** `provider_config` — the persisted,
|
||
schema-rendered, UI-visible settings object — MUST NOT carry secrets.
|
||
Enforced by validation: flat object, scalar values only, ≤20 fields, ≤64KB,
|
||
and any key whose word-split contains `secret|password|token|key|credential`
|
||
is rejected. The match is against key *names*, so it is a lint with false
|
||
positives: a field like `ssh_key_path` holds a path, not a credential,
|
||
and is refused anyway — a provider author hitting this MUST rename the
|
||
field (e.g. `identity_file`), not weaken the validator; the rule's job is
|
||
making "put the secret in config" fail closed, and cheap false positives
|
||
are the accepted price. Secrets flow exclusively inside the `deploy` payload
|
||
(`private_key_nsec`, `auth_tag`, `env_vars`), which is never persisted by
|
||
`D` and never rendered. Corollary for providers: cluster credentials MUST
|
||
come from ambient substrate config (e.g. kubeconfig resolution), never from
|
||
`provider_config`.
|
||
|
||
- **(I3) Presence is the status.** `D` derives a remote agent's live state
|
||
exclusively from relay presence events self-signed by the agent key:
|
||
`online`/`away`/`offline` (kind:20001, ephemeral, WS-published). The
|
||
deployment axis (`deployed`/`not_deployed`, from the stored
|
||
`backend_agent_id`) is bookkeeping, not liveness. Staleness bound: presence
|
||
can be wrong for the window between an abnormal agent death (SIGKILL, node
|
||
loss) and the relay's presence expiry — **180 seconds**
|
||
(`PRESENCE_TTL_SECS`, `buzz-pubsub/src/presence.rs:16`; the vision's
|
||
"a bounded wrong dot, never an indefinite one"), the accepted
|
||
cost of M1. The specific number is a relay-wide constant, not a
|
||
remote-agent choice: #3783 raised it from 90s to keep a three-heartbeat
|
||
expiry window after the desktop heartbeat moved to 60s. What I3 promises
|
||
is that the window is *bounded*, not its width.
|
||
The Kubernetes binding minimizes the *avoidable* part of that window by
|
||
sizing the termination grace period to the harness's full graceful-shutdown
|
||
path (§K8s Grace). Two consequences the bound imposes: (a) the harness's
|
||
presence-suppression knob, `BUZZ_ACP_NO_PRESENCE`, MUST join
|
||
`RESERVED_ENV_KEYS` — locally the knob is cosmetic (the process and UI
|
||
remain visible), but remotely M1 makes presence the *only* signal, so an
|
||
unreserved user env var would convert "wrong for ≤180s" into "wrong
|
||
indefinitely" and silently disarm the one bound in print; (b) presence is
|
||
scoped to a **community**: the relay derives community from its host, so
|
||
the deploy-time `relay_url` binds the body to one community for its whole
|
||
life, and a workspace observing through a different community sees the
|
||
agent offline while a deploy against it correctly no-ops — a known UX
|
||
boundary (the cross-scope boundary I4 admits, seen from the status side),
|
||
stated here so the two honest-but-conflicting readouts are diagnosable.
|
||
|
||
- **(I4) At most one live instance per agent key per deployment scope.**
|
||
Within one provider's deployment scope (for Kubernetes: one namespace),
|
||
there is never more than one Running instance of a given agent pubkey.
|
||
Enforced by the deploy reconciliation loop (§Deploy State Machine):
|
||
deploy is keyed on the derived pubkey, a live instance maps to strict
|
||
no-op, and — because two deploys can race — create/delete conflicts MUST
|
||
converge (re-read and return the winner) rather than fail; deterministic
|
||
instance naming makes the substrate itself reject a second live instance.
|
||
Boundary: the protocol cannot prevent the same nsec being
|
||
deployed to two different scopes (two namespaces, two clusters, or remote
|
||
+ local simultaneously) — the relay tolerates multiple connections per key,
|
||
and preventing this would require the global registry M1 forbids. Deploying
|
||
one key twice is user error with confusing-but-safe results (both instances
|
||
answer), not a safety violation.
|
||
|
||
- **(I5) Intentional termination is final.** A remote agent **stops when
|
||
told, stays down when it stops, and is never silently resurrected**: an
|
||
instance whose harness is live terminates on owner `!shutdown` or when a
|
||
configured inactivity bound expires, and no supervisor restarts an
|
||
instance that exited *intentionally*. "Final" means **terminal to
|
||
automatic supervisor restart** — the owner may always issue a fresh
|
||
Start; that is resurrection working as designed, not a violation.
|
||
|
||
**Lifetime is owner policy, not law.** The inactivity bound is the
|
||
harness's opt-in self-stop (§Auto-Stop, default disabled). An owner may
|
||
always choose **no inactivity bound** — declaring an indefinitely-lived
|
||
agent. How that choice is expressed is per-binding: the Kubernetes
|
||
binding opts in with a 2h schema default because a pod is metered
|
||
compute with nobody watching it, and spells "no bound" as its
|
||
`inactivity_seconds: 0` field (§Pod shape); a hand launcher simply never
|
||
sets the reaper env. Either way it is
|
||
a legitimate, explicit choice, not a conformance failure: the invariant
|
||
was never "every instance terminates" (a continuously active agent is
|
||
intentionally unbounded — that is the product); it is "termination, once
|
||
intended, sticks".
|
||
|
||
**Restart policy follows lifetime policy.** The distinction that makes
|
||
indefinite agents safe is *intent vs accident*: dying on purpose
|
||
(`!shutdown`, inactivity reap) is final; dying by accident (node
|
||
eviction, OOM) may restart the body — same key, same agent, the
|
||
resurrection story working *for* the owner. Stated launcher-neutrally:
|
||
**if a supervisor exists, its restart policy MAY revive an abnormal
|
||
death and MUST NOT revive an intentional clean exit.** A launcher with
|
||
no supervisor at all — a hand-launched process on a VPS — satisfies
|
||
this vacuously: nothing restarts anything. How bounded vs indefinite
|
||
lifetime maps onto a concrete supervisor policy is binding policy
|
||
([L3]), realized and documented by each binding — this binding's
|
||
mapping lives in §Pod shape; a systemd binding's in its unit
|
||
directives. Any revive-on-abnormal-death policy carries a universal
|
||
precondition: the supervisor can distinguish intent from accident only
|
||
if the harness formally promises *clean exit = exit code 0* on every
|
||
intentional path and nonzero otherwise, pinned by test. At `28ae6cd21`
|
||
that property is emergent, not defended (Known Defect 6);
|
||
restart-on-failure before the pinned contract is how a refactor
|
||
silently converts every clean stop into a restart loop with no failing
|
||
test. Ordering is normative: exit-code contract first,
|
||
restart-on-failure second — the identical seam in every supervisor that
|
||
offers the distinction. An always-restart policy remains non-conforming
|
||
at any layer: it resurrects after a *clean* exit, defeating
|
||
`!shutdown`.
|
||
|
||
Enforcement: the self-stop lives *inside the harness* (the only place
|
||
that can see activity, per M1) (§Auto-Stop), and each binding makes it
|
||
effective on its substrate by requiring that harness exit terminates
|
||
the substrate's unit of execution (this binding's realization — the
|
||
harness as the container's signal-receiving process — is §Pod shape,
|
||
[L3]) and that any supervisor's restart policy respects intent as
|
||
above.
|
||
Boundaries: (a) the guarantee is conditional on a live harness event
|
||
loop — a wedged process that cannot run its reaper timer cannot reap
|
||
itself, and M1 means nothing else will (the mitigation is the substrate
|
||
operator's, e.g. a namespace-level TTL policy, out of scope per
|
||
§Non-Goals); (b) restart policy prevents resurrection, it does not prove
|
||
process exit; (c) I5 bounds *agent* lifetime, not substrate residue —
|
||
residue (in this binding, a Completed pod object) persists for
|
||
forensics until the next deploy's GC (§K8s GC).
|
||
|
||
## Provider Protocol
|
||
|
||
### Discovery
|
||
|
||
`D` scans, in order: the directory containing the desktop executable, every
|
||
entry of `PATH`, and `~/.local/bin`, for executables named
|
||
`buzz-backend-<id>`. The suffix after the prefix is the provider id and MUST
|
||
match `[a-z0-9][a-z0-9_-]*`. On Windows, an `.exe`/`.bat`/`.cmd` extension
|
||
MUST be stripped before the id is derived (see §Known Defects — as of
|
||
`28ae6cd21` it is not, so Windows providers probe but cannot deploy). First
|
||
hit per filename wins. Discovery executes nothing.
|
||
|
||
**Shadowing and invalid candidates are diagnosable, not silent.** First-hit
|
||
wins is the right selection rule (it is kubectl's), but kubectl also warns
|
||
when a later-PATH plugin is shadowed, and Docker's CLI reports invalid
|
||
plugin candidates with reasons. Discovery MUST retain, and the UI and
|
||
deploy-time errors MUST be able to surface: the selected binary's full
|
||
path, any shadowed candidates for the same id (later-PATH duplicates), and
|
||
candidates rejected for malformed names. A deploy error that names which
|
||
binary ran answers the first question a user with two copies of
|
||
`buzz-backend-kubernetes` will ask. (At `28ae6cd21` discovery records only
|
||
the winning path — a desktop change alongside Known Defect 3's.)
|
||
|
||
**Resolution rule.** Every subsequent operation resolves the provider id
|
||
against the *current* discovery set. A stored binary path on an agent record
|
||
is a cache, revalidated against both the current candidates and the recorded
|
||
id before every use. A record edit can therefore never redirect an operation
|
||
to a binary discovery would not have found.
|
||
|
||
**Pre-secret negotiation gate (normative).** Declaring `protocol_version`
|
||
is worthless if nothing checks it before the nsec crosses the trust
|
||
boundary — and at `28ae6cd21` nothing does: `provider_deploy` invokes
|
||
`deploy` directly, so a stale UI-time probe (or a binary replaced on PATH
|
||
since that probe) can receive `private_key_nsec` unchecked (Known Defect
|
||
5). The deploy path MUST: resolve the provider id **once**; copy the
|
||
resolved candidate into a desktop-owned, private, non-writable **staging
|
||
file**, computing its digest during the copy; invoke `info` **on the
|
||
staged artifact**; validate an explicit, supported `protocol_version`
|
||
(§Info — absence is an error); invoke `deploy` on the **same staged
|
||
artifact**; delete it afterward. Staged bytes are what "same executable
|
||
identity" means here: the nsec goes to the exact bytes that answered
|
||
`info`. Path-plus-metadata comparison (dev/inode, size, mtime) is NOT an
|
||
acceptable substitute for this guarantee — unchanged metadata can miss an
|
||
in-place content rewrite, and a pathname can be swapped between the check
|
||
and the moment `Command` opens it, which is precisely the
|
||
check-then-exec race the gate exists to close. A UI-time probe result
|
||
MUST NOT satisfy this gate. If a platform makes staged execution
|
||
impossible for some provider (e.g. an executable that only runs from its
|
||
install location due to relative dependencies or signing constraints),
|
||
the implementation MUST NOT silently fall back to metadata and still
|
||
claim this gate: it degrades explicitly to *accidental-replacement
|
||
detection* (path + file-identity compare), surfaces that weaker level in
|
||
the deploy diagnostics, and the spec text for that platform carries the
|
||
narrower claim. Remembered digest-based approval (Terraform-lock style)
|
||
is a stronger follow-up, not a v1 requirement.
|
||
|
||
### Invocation
|
||
|
||
One process per operation. `D` spawns `P` with cwd = the agent workdir,
|
||
writes exactly one JSON object to stdin, closes stdin. `P` writes exactly one
|
||
JSON object to stdout and exits. Requirements on `D` (all implemented):
|
||
|
||
- Bounded reads: stdout capped (1MB), stderr capped (64KB), no `read_to_end`
|
||
on pipes a daemonizing child could hold open; deadline polling with
|
||
`try_wait`.
|
||
- **Non-zero exit is failure even if stdout parsed.** Partial output from a
|
||
crashed operation is never trusted.
|
||
- `{"ok": false, "error": …}` is the in-band failure form.
|
||
- **Environment**: `P` inherits `D`'s environment. On macOS a GUI launch
|
||
means launchd's minimal PATH; providers whose substrate credentials invoke
|
||
helper binaries (kubeconfig `exec` plugins) MUST self-augment their PATH
|
||
(§K8s Auth) rather than assume a login shell.
|
||
|
||
### Provider Output Is Untrusted
|
||
|
||
Everything `P` emits — stderr, error strings, the response object — is
|
||
scrubbed before storage or display: every value from the request's
|
||
`env_vars` (longest-first, length ≥4) and every `nsec1…`/`sprt_tok_…` token
|
||
is redacted. Rationale: `P` legitimately holds secrets during deploy; `P`
|
||
echoing them (in a stack trace, a kubectl error, a debug line) must not
|
||
propagate them into `D`'s persisted `last_error` or logs.
|
||
|
||
### `info`
|
||
|
||
```
|
||
request: {"op": "info", "request_id": "<uuid>"}
|
||
response: {"ok": true, "name": str, "version": str,
|
||
"protocol_version": int, "description": str,
|
||
"config_schema": <JSON Schema>}
|
||
timeout: 10s
|
||
```
|
||
|
||
`version` is the provider's *software* version — useful in error reports,
|
||
useless for compatibility. `protocol_version` (this document: `1`) is the
|
||
wire-contract version, following the pattern Docker's CLI plugins
|
||
(`SchemaVersion`) and HashiCorp go-plugin (negotiated protocol version) both
|
||
converged on: the desktop rejects a provider whose `protocol_version` it
|
||
does not speak, with an error naming both versions and the binary path,
|
||
instead of failing later inside a half-understood `deploy`. A missing
|
||
`protocol_version` is an **error, not a presumed `1`**: there is no
|
||
deployed provider population to grandfather, and a gate that infers
|
||
compatibility for exactly the class of binary that never declared any
|
||
defeats its own pre-secret guarantee (§Discovery). Fail closed — it is
|
||
also simpler: no migration clock, no "major cycle" to define.
|
||
|
||
`config_schema` drives the UI form: `properties[*].default` prefill,
|
||
string/number/boolean coercion, `required` gating. A provider MAY compute
|
||
defaults freshly per call (the Kubernetes binding generates a random
|
||
namespace default this way — §K8s Namespace). The schema's fields are
|
||
subject to I2 validation when the user's values come back in `deploy`.
|
||
|
||
### `deploy`
|
||
|
||
```
|
||
request: {"op": "deploy", "request_id": "<uuid>",
|
||
"agent": <payload>, "provider_config": {…}}
|
||
response: {"ok": true, "agent_id": str}
|
||
timeout: 600s
|
||
```
|
||
|
||
The agent payload (field list per
|
||
`commands/agents_deploy.rs: deploy_payload_json` at `28ae6cd21`; the
|
||
`launch` block is a normative addition not yet emitted — Known Defect 3):
|
||
|
||
| field | meaning |
|
||
|---|---|
|
||
| `name` | display name |
|
||
| `relay_url` | concrete WS URL (workspace fallback materialized — the remote side has no workspace notion) |
|
||
| `private_key_nsec` | **the identity** (I1: never empty) |
|
||
| `auth_tag` | NIP-OA owner attestation |
|
||
| `agent_command`, `agent_args` | the ACP agent under the harness (configurable-harness support). At `28ae6cd21` these are raw record bytes — see Known Defect 3: the normative source is the resolved descriptor in `launch` |
|
||
| `system_prompt`, `model`, `provider` | effective values, live-persona-first resolution |
|
||
| `turn_timeout_seconds`, `idle_timeout_seconds`, `max_turn_duration_seconds` | harness timeout knobs |
|
||
| `parallelism` | concurrent-turn bound |
|
||
| `respond_to`, `respond_to_allowlist` | inbound author gate |
|
||
| `env_vars` | merged user env: global < persona < agent |
|
||
| `launch` | **normative addition** (§Launch data): the desktop-resolved launch contract — `command` (name, not path), normalized `args`, layered `env`, overridable `policy_env`, and `owner_pubkey` |
|
||
|
||
**Reserved-key rule (normative for providers).** `D` strips
|
||
`BUZZ_PRIVATE_KEY`, `NOSTR_PRIVATE_KEY`, `BUZZ_AUTH_TAG`, `BUZZ_RELAY_URL`,
|
||
and the other reserved keys from `env_vars` before merge. A provider MUST
|
||
construct the agent environment's identity variables from the **top-level**
|
||
payload fields (`private_key_nsec` → `BUZZ_PRIVATE_KEY`/`NOSTR_PRIVATE_KEY`,
|
||
`auth_tag` → `BUZZ_AUTH_TAG`, `relay_url` → `BUZZ_RELAY_URL`); reading
|
||
`env_vars` for them yields an identityless agent. A related hardening `D`
|
||
performs is part of the contract's rationale: env keys are validated as
|
||
POSIX-shaped names before merge, because a key like `BUZZ_AUTH_TAG=x`
|
||
smuggled through `Command::env` would bypass the reserved-key strip
|
||
entirely. A provider materializing `env_vars` into a substrate object
|
||
(e.g. a Kubernetes Secret) MUST likewise never let a user-supplied key
|
||
collide with or reconstruct a reserved key.
|
||
|
||
`agent_id` is `P`'s stable handle for the deployment (the Kubernetes binding
|
||
returns the pod name). `D` stores it as `backend_agent_id`; its presence is
|
||
the `deployed` axis of I3.
|
||
|
||
**There is no `undeploy` op in v1.** Deletion of a remote agent from `D`
|
||
orphans the substrate objects; the UI therefore requires an explicit
|
||
`force_remote_delete` confirmation, and the binding's GC + I5 bound the
|
||
orphan's cost (the agent self-stops; the pod residue is reaped on the next
|
||
deploy of the same key, or manually).
|
||
|
||
### Launch data (`launch`) {#launch-data}
|
||
|
||
Reproducing the local spawn's launch semantics requires state only the
|
||
desktop can resolve: the runtime-metadata table (`model_env_var`,
|
||
`provider_env_var`, `provider_locked`, `default_env` —
|
||
`discovery.rs:75-207`), the six-layer env resolution, harness-definition
|
||
command/args fallback, team instructions, session title, the respond-to
|
||
gate's legacy owner fallback, and the mesh rewrite. A provider MUST NOT
|
||
reimplement that derivation — it would be a second copy of desktop runtime
|
||
discovery, drifting from the first. Instead the payload carries a typed
|
||
`launch` block that `D` resolves with **the same code paths as local
|
||
spawn**, and the provider applies it mechanically.
|
||
|
||
```
|
||
"launch": {
|
||
"command": str, // command NAME (e.g. "goose"), never a host path
|
||
"args": [str], // normalized args, definition fallback applied
|
||
"env": {str: str}, // layered env: baked → runtime metadata →
|
||
// definition → global → persona → agent
|
||
// (resolve_effective_harness_descriptor)
|
||
"policy_env": {str: str}, // overridable behavior defaults (tier 1, below):
|
||
// runtime default_env (e.g. GOOSE_MODE=auto),
|
||
// BUZZ_ACP_RELAY_OBSERVER, BUZZ_ACP_LAZY_POOL=true,
|
||
// BUZZ_ACP_SESSION_TITLE (resolved),
|
||
// BUZZ_ACP_TEAM_INSTRUCTIONS, BUZZ_ACP_MODEL,
|
||
// MCP_HOOK_SERVERS=* (mcp_hooks runtimes only)
|
||
"owner_pubkey": str | null // resolved workspace owner (hex) — legacy
|
||
// BUZZ_ACP_AGENT_OWNER fallback, non-secret
|
||
}
|
||
```
|
||
|
||
`launch.command`/`launch.args` come from
|
||
`resolve_effective_harness_descriptor` (`readiness.rs:125`) — the same
|
||
resolver local spawn uses — which fixes two silent divergences the raw
|
||
record fields carry: a persona-derived `agent_command` is a blank record
|
||
byte, and definition-provided `agent_args` are lost when the instance's own
|
||
args are empty. `launch.env` is that descriptor's layered env, which is
|
||
where per-runtime model/provider injection lives (`GOOSE_MODEL`/
|
||
`GOOSE_PROVIDER` for goose; nothing for `provider_locked` runtimes like
|
||
Claude; `BUZZ_AGENT_MODEL`/`BUZZ_AGENT_PROVIDER` for buzz-agent). A fixed
|
||
`provider → BUZZ_AGENT_PROVIDER` mapping is wrong for three of the four
|
||
built-in runtimes and is why this block exists.
|
||
|
||
**What `policy_env` carries — and deliberately does not.** Its irreducible
|
||
wire fields are exactly three scalars plus the metadata-derived defaults —
|
||
plus the four record-derived behavior knobs that would otherwise be
|
||
mis-tiered (below):
|
||
|
||
- `BUZZ_ACP_TEAM_INSTRUCTIONS` — the only truly non-reconstructible policy
|
||
value: `effective_team_instructions` (`spawn_hash.rs:41-52`) needs the
|
||
desktop's `TeamRecord` store, which no pod can reach.
|
||
- `BUZZ_ACP_SESSION_TITLE` — sent **resolved** (`resolve_session_title`,
|
||
`runtime/metadata.rs:45`), not as its `display_name`/`name` inputs. The
|
||
resolution strips control characters, and that property transfers: an
|
||
interior NUL fails a local spawn at the env boundary, and would make the
|
||
Kubernetes apiserver reject the whole pod spec — a rename must degrade,
|
||
not turn into a deploy failure.
|
||
- `owner_pubkey` (block-level, not env) — the respond-to gate is otherwise
|
||
fully reconstructible from payload fields (`build_respond_to_env`,
|
||
`runtime.rs:380-421`); this is its one irreducible input.
|
||
- Runtime `default_env` (e.g. `GOOSE_MODE=auto`) — computed **from the
|
||
runtime metadata table only, unconditionally**. The local spawn applies
|
||
each default only `if std::env::var(key).is_err()` (`runtime.rs:733-737`)
|
||
— a test of the *desktop's own* ambient environment. That makes "the
|
||
resolved local env" not a pure function of the record; serializing it
|
||
verbatim would bake a host accident into the pod. Launch data MUST be
|
||
computed from record + config alone.
|
||
- `BUZZ_ACP_LAZY_POOL=true` — a **deliberate pick, not a transcription**:
|
||
the two local paths disagree (manual Start is eager, `runtime.rs:1001`;
|
||
launch restore is lazy, `restore.rs:333`, precisely to avoid "N idle
|
||
brains on every launch"). Remote pods take the lazy arm: an idle LLM pool
|
||
in a cluster is billable waste with no user watching it warm up.
|
||
- `MCP_HOOK_SERVERS=*` when the resolved runtime has `mcp_hooks`
|
||
(`runtime.rs:594-598`; buzz-agent only at `28ae6cd21`) — gates the
|
||
`_Stop`/`_PostCompact` hook tools.
|
||
- `BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`,
|
||
`BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS` — resolved by the desktop
|
||
from the record's `system_prompt` / `idle_timeout_seconds` /
|
||
`max_turn_duration_seconds` / `parallelism` (each omitted when null,
|
||
matching the local spawn's conditional emission). These are **tier-1 by
|
||
local fact, not by choice**: the local spawn writes them before the user
|
||
env layer (`runtime.rs:716-729,763` vs `:860`) and none is in
|
||
`RESERVED_ENV_KEYS`, so a power user's env override beats them today. A
|
||
provider that independently mapped the top-level payload copies after
|
||
`launch.env` would invert that — the structured field silently defeating
|
||
an override that works locally — which is why the provider MUST NOT remap
|
||
them (§Entrypoint mapping table).
|
||
|
||
`BUZZ_ACP_DEDUP` and `BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are **deliberately
|
||
unset**: the local spawn writes `queue`/`steer` (`runtime.rs:730-731`), and
|
||
those are exactly the harness's clap defaults (`config.rs:344,356`) — a pod
|
||
that omits both is behaviorally identical, and adding rows for them would
|
||
imply a divergence that does not exist. `BUZZ_MANAGED_AGENT` is likewise
|
||
deliberately absent remotely: it brands local harness processes so the
|
||
desktop's orphan sweep and instance reaper can prove ownership by scanning
|
||
process env (`orphan_sweep.rs`, `instance_reaper.rs`) — there is no local
|
||
process to sweep.
|
||
|
||
**Environment precedence (normative) — three tiers, later wins:**
|
||
|
||
1. **Overridable behavior defaults** — `launch.policy_env`. These keys are
|
||
deliberately non-reserved (`env_vars.rs:54-57` says so outright: power
|
||
users may bypass the dedicated UI fields), and locally the user env is
|
||
written after them (`runtime.rs:860` and its comment). A policy-wins
|
||
order here would make remote agents ignore overrides local agents honor.
|
||
2. **User/layered env** — `launch.env`. User `env_vars` need no separate
|
||
slot: the descriptor's layering already merged them (global < persona <
|
||
agent), so a provider applies `launch.env` and MUST NOT re-merge the
|
||
legacy `env_vars` field on top.
|
||
3. **Authoritative** — unoverridable at every layer, written last and
|
||
backed by the reserved-key strip: the identity variables from top-level
|
||
payload fields (§Reserved-key rule), the respond-to gate values,
|
||
`BUZZ_ACP_AGENT_OWNER`, the inactivity bound, `BUZZ_ACP_MCP_COMMAND`,
|
||
and `BUZZ_MANAGED_AGENT_START_NONCE`. For the nonce, the provider MUST
|
||
set it to the attempt's **generation token** (§K8s Secrets): the harness
|
||
stamps it into every observer lifecycle frame (`buzz-acp/lib.rs:1501`),
|
||
so the Secret generation and the lifecycle correlator become one
|
||
identity instead of an empty string.
|
||
|
||
**Host-resolved values MUST NOT be forwarded and MUST be re-derived
|
||
in-image.** The local spawn sets several variables to absolute paths on the
|
||
desktop's filesystem; forwarding them into a container is a guaranteed
|
||
failure. The provider/image re-derives:
|
||
|
||
- the harness and agent binaries: `launch.command` is a *name*, resolved
|
||
against the image's own `PATH` (`BUZZ_ACP_AGENT_COMMAND`), and
|
||
`BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` likewise;
|
||
- `CLAUDE_CODE_EXECUTABLE` — a `resolve_command()` host path
|
||
(`configure_runtime_cli`, `runtime.rs:424-446`), same class as the
|
||
command paths: image-local resolution or unset;
|
||
- `PATH` itself (the desktop's augmented PATH is meaningless in the image);
|
||
- git credential/signing helper locations — the relay-URL *scoping* of the
|
||
credential config is normative (never a global helper), the helper *path*
|
||
is image-local (§Image);
|
||
- `BUZZ_ACP_SETUP_PAYLOAD` is desktop-computed readiness state and MUST NOT
|
||
appear in a remote pod.
|
||
|
||
**Owner resolution (normative):** the provider MUST have either a non-null
|
||
`auth_tag` (→ `BUZZ_AUTH_TAG`) or a non-null `launch.owner_pubkey`
|
||
(→ `BUZZ_ACP_AGENT_OWNER`) before any mutation; if both are null it MUST
|
||
refuse the deploy. Without an owner the harness cannot match `!shutdown`
|
||
(`buzz-acp/src/lib.rs: resolve_agent_owner`, main-loop owner check) and the
|
||
agent answers its own stop command conversationally — §Stop would be
|
||
describing a mechanism that does not work. `BUZZ_ACP_AGENT_OWNER` is a
|
||
reserved key, so this value can only arrive as authoritative launch data,
|
||
never through user env.
|
||
|
||
**Buzz shared compute (relay-mesh) is non-deployable, and this is forced,
|
||
not chosen.** The mesh rewrite resolves to an OpenAI-compatible transport at
|
||
`http://127.0.0.1:9337/v1` (`relay_mesh.rs: RELAY_MESH_API_BASE_URL`) — a
|
||
loopback proxy on the desktop. Serializing that policy into a pod points the
|
||
agent at its own localhost, where nothing listens. `D` already rejects
|
||
mesh-configured creates on non-local backends
|
||
(`agents.rs: normalize_relay_mesh`); the deploy path MUST equally fail
|
||
closed — before any mutation — when the effective provider resolves to
|
||
`relay-mesh`, rather than passing `relay-mesh` through as if it were a
|
||
runtime provider. Remote mesh transport is a possible v2 (an in-image mesh
|
||
client), not a v1 silent breakage.
|
||
|
||
**The governing invariant:** a remote agent's environment differs from the
|
||
same record's local spawn **only where the substrate forces it** (paths,
|
||
PATH, readiness). Anyone adding a local behavior knob adds it to the shared
|
||
resolver, and both spawn paths inherit it; there are not two derivations to
|
||
keep in sync.
|
||
|
||
### Deploy State Machine
|
||
|
||
`start` on any non-Local agent unconditionally issues `deploy` — the desktop
|
||
does not track substrate state (M1). Deploy is therefore **not** "create": it
|
||
is *converge to at-most-one-live-instance* (I4), implemented as a
|
||
**reconciliation loop** keyed on the agent's identity within the provider's
|
||
scope.
|
||
|
||
**Step 0 — derive and verify identity.** The payload carries the nsec, not
|
||
the pubkey. Before any substrate read or mutation, the provider MUST parse
|
||
`private_key_nsec` and derive the public key from it; a malformed or
|
||
undecodable key is an immediate in-band error. Every selector, name, and
|
||
comparison below uses the *derived* pubkey — never a caller-supplied one.
|
||
|
||
**Step 1 — select and authenticate candidates.** Candidate objects are
|
||
selected by the (truncated) identity label, then each candidate's
|
||
**full-pubkey annotation MUST be compared against the derived pubkey**
|
||
before it is treated as belonging to this agent. Truncated selectors are
|
||
collision-*resistant*, not collision-*free*: the annotation check is what
|
||
makes them safe. An object whose annotation does not match MUST NOT be
|
||
no-op'd against, deleted, GC'd, or have its Secret touched; the provider
|
||
MUST either ignore it or fail with an explicit collision error. Only
|
||
annotation-verified objects proceed.
|
||
|
||
**Auto-repair is fenced to Buzz-authored, positively identified residue
|
||
(normative).** The destructive rows below (delete residue, replace a
|
||
never-started body, GC a Secret) are legitimate *only because* every object
|
||
they touch carries positive **protocol ownership evidence** — and identity
|
||
evidence alone is not ownership evidence. The identity label, the
|
||
full-pubkey annotation, and the create-intent fingerprint prove "matches
|
||
our schema for this public identity"; all three are public, so any cluster
|
||
writer can reproduce them on an object this provider never created. Every
|
||
object this provider creates therefore also carries an explicit
|
||
management marker — `app.kubernetes.io/managed-by: buzz-backend-kubernetes`
|
||
plus a binding schema-version label (§Pod shape) — and **no destructive
|
||
repair or GC action fires unless the marker is present**, on top of the
|
||
annotation check and the UID+`resourceVersion` fence every delete already
|
||
requires. This is protocol evidence, not cryptographic proof: a cluster
|
||
writer can forge metadata by definition, and an actor with write access to
|
||
the namespace can already delete the pod outright — the marker's job is
|
||
making *accidental* schema collisions and third-party objects fail closed,
|
||
not defeating a hostile admin. The vision's rule that a never-started body
|
||
is substrate-operator residue survives with one qualifier: *Buzz-authored*
|
||
create-state (a Secret our provider wrote, a pod carrying our verified
|
||
annotations and marker) is the reconciler's to clear, because it is state
|
||
the user cannot reasonably clear themselves; *substrate* wreckage —
|
||
anything unowned, unmarked, unannotated, or ambiguously identified — still
|
||
fails closed to the operator. A provider that cannot positively identify an
|
||
object as its own output does not repair around it; it reports it.
|
||
|
||
**Step 2 — reconcile.** Ordered rules, evaluated against the verified
|
||
observation; on any conflict, *re-enter from step 1* rather than fail:
|
||
|
||
| observed | action | rationale |
|
||
|---|---|---|
|
||
| instance marked for deletion (`deletionTimestamp` set, any phase) | wait for actual disappearance, then re-enter | the user pressed Start and the old instance is unrecoverable; returning the dying instance's id records a success that evaporates. **Note: in Kubernetes there is no `Terminating` phase — a pod being gracefully deleted stays in phase `Running` for its whole grace period.** The deletion mark MUST be checked *before* phase, or this row is mistaken for the no-op row |
|
||
| no instance | create, then verify startup (below) | first deploy / after GC |
|
||
| terminated (Succeeded/Failed) | delete residue, wait for disappearance, re-enter (→ create) | the **normal restart path**: how a user revives a reaped or shut-down agent |
|
||
| live and **started** (harness container running) | **strict no-op; return existing `agent_id`** | Start must never silently kill a live agent mid-turn; "already running" is the honest answer, consistent with I3 |
|
||
| exists but **never started**, provably non-recoverable — referenced Secret confirmed absent (by a consistent read, below), or invalid image reference | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | a pod whose harness never ran is not a live agent: nothing can be killed mid-turn (I3), it never held the identity (I4), auto-stop cannot bound it (I5's reaper lives in the harness), and no-op'ing it would return a permanently inert instance as success on every future Start. "Provably" means the provider verified the referenced object's absence or the spec-level defect itself — never a reason string alone |
|
||
| exists, **never started**, recoverable, **fingerprint matches** current desired create intent (below) — self-healable startup states: `Unschedulable` (scale-from-zero autoscaling), image pull / `ImagePullBackOff`, transient `CreateContainerConfigError` | observe until started or the operation deadline expires, then return the latest redacted condition — **never delete, on this call or any later one** | these states routinely self-heal — an autoscaler provisions the node, the pull retries, the kubelet re-resolves the Secret (it retries a never-created container regardless of `restartPolicy`). And recoverable-timeout MUST stay observational *across calls*: any finite pod-age threshold can collide with the cluster's own pod-age thresholds (Cluster Autoscaler's `--new-pod-scale-up-delay` / per-pod `pod-scale-up-delay` annotation — the FAQ's example is `"600s"`), and delete-recreate resets exactly the age the autoscaler keys on, converting a slow cold start into a livelock in which every individual decision is correct. A later deploy re-reads: started → strict no-op; still recoverable and same intent → observe under the new call's deadline without resetting pod age; provably non-recoverable → the non-recoverable row. Repeated **identical** Starts can therefore never delete anything, whatever the pod's age — a genuinely slow cluster persists until it heals or an operator acts, and M1 already makes substrate residue the operator's boundary |
|
||
| exists, **never started**, recoverable, **fingerprint differs or absent** — the recorded create-intent fingerprint does not match what *this* deploy would create | delete (preconditioned, below), wait for disappearance, re-enter (→ create) | this is not the same generation the user is waiting on — it is a pod built from configuration the user has since *changed*, and without this row the change can never materialize: the pod name is deterministic, GC only reaps terminated pods, Stop needs a live harness, I5's reaper lives in the harness, and there is no `undeploy` — so a never-started pod wedged by its own config (a `memory_request` no node satisfies, a quota-blocked namespace) would swallow every future edit while reporting only "startup not confirmed", indistinguishable from a slow cluster. Divergence is evidence, not a clock — but it has **two** sources, not one: a user config change, and a provider upgrade that moves the baked default image digest (§K8s image; the default is compile-time provider state, so upgrading the provider changes the computed intent with no user action). Both are deliberate: the second is the *only* escape from a wedge caused by a bad baked default (unpullable digest, wrong arch) — a fingerprint blind to the default resolution would hand that wedge back to exactly the population that cannot override `image`. The accepted cost is that a provider upgrade mid-cold-pull discards in-flight startup progress; neither source is clocked to anything the cluster keys on, so no threshold exists to collide with the autoscaler. A **started** pod is never touched by this row: live → strict no-op regardless of divergence (edits reach it via the documented next-generation consequence) |
|
||
|
||
**Startup is part of create — phase is not readiness.** `Pending` (and even
|
||
`Running` at the pod level) does not mean the harness started: a pod can sit
|
||
in `ImagePullBackOff`, `CreateContainerConfigError` (e.g. a missing
|
||
`envFrom` Secret), or unschedulable `Pending` forever, and I5's inactivity
|
||
reaper cannot bound a harness that never began. Therefore `deploy` MUST NOT
|
||
report success at pod acceptance: it succeeds only when the harness
|
||
container has actually started (container `state.running`), bounded by the
|
||
operation deadline. On failure or deadline expiry it MUST return an in-band
|
||
error carrying the actionable condition (the container waiting `reason` /
|
||
pod condition), not a generic timeout. "Live" in the no-op row above means
|
||
**started**, for the same reason — this is the lesson ephemeral-runner
|
||
controllers learned upstream (inspect container state, not pod phase).
|
||
Classification MUST combine container state, pod conditions,
|
||
referenced-object existence, and the recorded create-intent fingerprint —
|
||
**reason strings alone are not a
|
||
stable fatality taxonomy**, and pod age is never one (age triggers nothing
|
||
destructive; see the recoverable rows and the controlled-view rule below).
|
||
In particular, `Unschedulable` is not fatal: a
|
||
scale-from-zero pod reports it while the autoscaler provisions capacity,
|
||
and the kubelet retries a container that never got a container status
|
||
regardless of `restartPolicy: Never` (`ShouldContainerBeRestarted` returns
|
||
true for a nil status *before* the restart-policy check —
|
||
`kubelet/container/helpers.go`), which is exactly why a briefly-missing
|
||
Secret self-heals. `restartPolicy: Never` suppresses restarting a container
|
||
that ran and died; it says nothing about one that never started.
|
||
A consequence to state plainly: once success includes container start, the
|
||
600s operation deadline **is** the cold-start budget — image pull on a
|
||
fresh node, scale-from-zero scheduling, all of it. But the deadline bounds
|
||
**how long one Start waits synchronously**, nothing more. Deadline expiry
|
||
on a still-progressing startup is reported as "startup not confirmed within
|
||
the deadline", and MUST NOT trigger cleanup or forced recycle — on this
|
||
call *or any later one* (the recoverable rows above — what replaces a
|
||
never-started pod is a *config change*, never a deadline): the next deploy's
|
||
reconciler observes whatever the startup became and takes the matching row,
|
||
preserving the pod's `creationTimestamp` for whatever cluster machinery
|
||
keys on it. Whether ten minutes fits the intended cluster class is a
|
||
product ruling,
|
||
not a correctness one.
|
||
|
||
**One create attempt per call (normative).** The replacement rows above —
|
||
terminated, never-started provably broken, never-started divergent — exist
|
||
to clear residue from a *previous* life. Once a deploy call has created its
|
||
own pod, a classification that would replace that pod means the attempt this
|
||
call just made has already failed: the harness started, rejected its
|
||
configuration, and exited (the deterministic startup failure), or the pod
|
||
was proven broken. Re-running the identical create against the same cluster
|
||
inside the same call cannot produce a different outcome; what it produces is
|
||
a hot delete/mint/create cycle every poll interval for the whole operation
|
||
deadline, one immutable Secret per cycle (measured live: 107 Secrets in a
|
||
single 600s call), every one younger than §K8s GC's orphan age gate — a
|
||
bounded-call resource DoS and nsec-bearing-Secret amplifier. A binding MUST
|
||
NOT delete-recreate a pod created by the same deploy call: it MUST return
|
||
the in-band error carrying the latest condition (for a terminated container,
|
||
the exit code and reason — never the terminated `message`, which is
|
||
process-composed output under the same redaction rule as pull messages).
|
||
The failed attempt's pod and Secret are deliberately left in place: the pod
|
||
is terminated, so the *next* Start's preflight GC collects the pod and its
|
||
referenced Secret together before that call's own single attempt — retry is
|
||
thereby gated on fresh owner intent, and litter is bounded at one pod plus
|
||
one Secret per press, not per poll. This bounds attempts, not observation:
|
||
the recoverable rows still observe a slow startup for the full deadline, and
|
||
residue from previous lives is still replaced exactly once on the way to
|
||
this call's attempt.
|
||
|
||
**Destructive decisions come from views you control — reads and writes
|
||
both (normative).** This is one rule with three instances, stated once so
|
||
nobody optimizes an instance away. §K8s GC's same-clock rule is the time
|
||
instance. The other two live here:
|
||
|
||
- *Reads*: every read whose result can authorize a deletion — the
|
||
Secret-absence confirmation above, and the candidate list the GC pass
|
||
filters — MUST use most-recent semantics (`resourceVersion` **unset**,
|
||
a quorum read). `resourceVersion: "0"` is served from the watch cache,
|
||
which the Kubernetes API contract explicitly allows to be much older
|
||
than anything the client has already observed; a stale
|
||
Secret-absence read would delete a pod whose Secret exists and whose
|
||
container was about to start — the GC race again, arriving through read
|
||
consistency instead of a clock.
|
||
- *Writes*: a fresh read is necessary but not sufficient — the kubelet can
|
||
start the container between observation and delete. Every DELETE
|
||
authorized by a classification MUST carry `preconditions.uid` **and**
|
||
`preconditions.resourceVersion` from that exact observation
|
||
(`metav1.Preconditions` supports both), making the edge a
|
||
compare-and-delete. A failed precondition is neither an error nor
|
||
permission to retry the delete: re-enter from step 1 and classify the
|
||
object that exists now. The full-pubkey annotation check remains — the
|
||
precondition pins *when*, the annotation pins *whose*.
|
||
|
||
**The 409 discriminator is `Status.reason`, never the status code
|
||
(normative).** Two rules in this section require *opposite* actions on
|
||
the same HTTP status: a failed delete precondition and a create-conflict
|
||
are **both 409** (`NewConflict` and `NewAlreadyExists` each carry
|
||
`Code: http.StatusConflict` — `apimachinery/pkg/api/errors/errors.go`).
|
||
The discriminator is the Kubernetes API `Status.reason` field:
|
||
`Conflict` → abandon the delete and re-enter from step 1;
|
||
`AlreadyExists` on create → the convergence rule below (clean up only the
|
||
losing attempt's Secret, re-read, adopt the winner). An implementation
|
||
that branches on the code alone will eventually take the adoption path on
|
||
a failed delete or vice versa. This does not contradict the
|
||
reason-strings warning above: API `Status.reason` is a machine-readable
|
||
contract token defined by `metav1.Status`; *container waiting* reasons
|
||
are kubelet-produced strings with no such contract — the spec distrusts
|
||
the latter, not the former.
|
||
|
||
**Create-intent fingerprint (normative).** The divergence discriminator
|
||
in the never-started rows is a recorded annotation,
|
||
`buzz.block.xyz/create-intent`, written at pod create — the same shape as
|
||
the image-reference and pubkey annotations the pod already carries. Its
|
||
value is an **unkeyed SHA-256** over a canonical serialization of the
|
||
provider's **non-secret create-intent template**, computed *before* the
|
||
create call. The scope rule that makes a plain hash safe: the input
|
||
covers exactly the provider-controlled fields that can affect scheduling
|
||
or container creation — resolved image reference, resource
|
||
requests/limits, service account, PodSpec command/args, volumes/mounts,
|
||
security context, and the provider's other pod-shape knobs — and **never
|
||
Secret data or attempt identity**. Secret *values* cannot cause the
|
||
never-started wedge this discriminator exists to clear (scheduling reads
|
||
pod fields, not Secret values; a bad launch value produces a started
|
||
container that fails at the relay — a different row), so hashing them
|
||
buys nothing and a plain hash over low-entropy secrets published in a
|
||
world-readable annotation would be a dictionary oracle; excluding them
|
||
removes the oracle and with it any need for an HMAC key or nsec-derived
|
||
key material. Two normalization requirements, or every attempt diverges
|
||
by construction: the per-attempt Secret *name* in `envFrom` MUST be
|
||
replaced by a fixed placeholder (or the pre-binding template serialized
|
||
instead of the concrete PodSpec), and API metadata / server- and
|
||
admission-produced output (UID, `resourceVersion`, timestamps, defaulted
|
||
fields, the fingerprint annotation itself) is excluded structurally —
|
||
the serializer never sees it, an invariant checkable by inspection.
|
||
Comparison is always recorded-annotation vs freshly-computed intent,
|
||
**never** a diff against the live pod spec: admission defaulting and
|
||
mutation would make every pod look divergent, which is why the
|
||
fingerprint is computed pre-create. A missing referenced Secret stays
|
||
handled by the most-recent absence check (the non-recoverable row), not
|
||
by fingerprint divergence; and divergence authorizes deletion only
|
||
through the never-started recoverable row — a started pod is strict
|
||
no-op whatever its fingerprint says.
|
||
|
||
**No-op means zero mutation.** The live-instance row MUST NOT replace or
|
||
patch the Secret, patch metadata, or delete anything belonging to the
|
||
observed live generation. Configuration and environment edits apply only to
|
||
the *next* fresh generation (see the documented consequence below).
|
||
|
||
**Conflicts converge, never fail.** Two provider processes can concurrently
|
||
observe "no instance" or "terminated" — the deterministic instance name
|
||
prevents two live instances, but one caller loses the race. The provider
|
||
MUST treat create-conflict (already exists) by re-reading and, if the winner
|
||
is an annotation-verified live instance, returning it as the no-op row
|
||
would — cleaning up only its own losing attempt's residue, never the
|
||
winner's (the Kubernetes binding makes this concrete via per-attempt Secret
|
||
names, §K8s Secrets); it MUST treat delete-not-found as success; and it
|
||
MUST loop until a
|
||
stable outcome or the operation deadline (600s) expires. One deliberate
|
||
asymmetry: the **create loser does not apply the fingerprint-divergence
|
||
row to the pod that just beat it**, even when the winner's fingerprint
|
||
differs from its own intent — it adopts or reconciles the elected winner.
|
||
Two contenders with different payloads would otherwise ping-pong deletes
|
||
through the conflict path. A *subsequent* deploy that walks in and
|
||
observes that never-started divergent winner replaces it normally.
|
||
Without this rule,
|
||
"two deploys return an `agent_id`" (the idempotency claim below) is false
|
||
under concurrency.
|
||
|
||
**Documented consequence.** Because live → no-op, configuration edits to a
|
||
running remote agent do not take effect until it next exits (unlike local
|
||
agents, which re-resolve on every spawn). This is an accepted v1 tradeoff;
|
||
a deliberate "recycle" affordance (stop-then-start) is the v2 path to
|
||
immediate application. [DECISION E, ruled: per-binding policy — this
|
||
binding keeps no-op; the universal property is that no sequence of Starts
|
||
yields two live instances in one scope.] Note the asymmetry is deliberate and points the
|
||
right way: an edit *cannot* reach a started pod until it exits, but it
|
||
*can* reach a never-started one immediately (fingerprint divergence) —
|
||
the never-started pod is the one the user is editing *because* it did not
|
||
start.
|
||
|
||
Idempotency in the protocol sense: any number of concurrent or sequential
|
||
`deploy`s with the same payload converge to one live instance, and every
|
||
non-erroring call returns an `agent_id` naming it; no sequence of `deploy`s
|
||
can yield two live instances in one scope.
|
||
|
||
### Stop and Delete
|
||
|
||
- **Stop** is not a provider operation. `D` publishes `!shutdown` mentioning
|
||
the agent on `R`; the harness verifies the sender is the owner and exits
|
||
through its graceful path: agent-pool shutdown, drain of in-flight turns,
|
||
publish presence `offline`, close relay connection. **The spec does not
|
||
derive an upper bound for this path from its segment timeouts, because
|
||
review proved that arithmetic wrong twice**: the visible constants (30s
|
||
drain, 2s presence, 5s relay close) omit terms that are *variable*, not
|
||
constant — at `28ae6cd21` the post-drain reap segment
|
||
(late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
|
||
drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
|
||
`:2636`, closed at `:2657`) and serially awaits a 5s post-SIGKILL wait
|
||
per occupied pool slot (`acp.rs:436`). **That segment alone can reach
|
||
`30 + 5×parallelism + 7` — ~87s at the desktop's default parallelism
|
||
of 10** (`DEFAULT_AGENT_PARALLELISM`, `types.rs:814`; lowered from 24 by
|
||
#3038), ~197s at the harness cap of 32 (`config.rs:293`) — already
|
||
exceeding a 60s grace. And it is a *lower* bound on the tail, not the
|
||
worst case: the same path runs earlier segments before the prompt drain
|
||
even opens — a separate 30s wake-task drain (`:2612`) followed by
|
||
serial shutdown of any awakened pools (`:2620-2624`), whose per-slot
|
||
`acp.shutdown()` loop (`:3747-3751`) has no timeout of its own. The
|
||
total tail is not bounded by today's segment timeouts at all.
|
||
The requirement is therefore stated as a budget, not a sum (Known
|
||
Defect 7): **the harness MUST bound its total shutdown tail — every
|
||
post-signal segment, including per-slot reaping — under one shared
|
||
deadline no greater than the declared grace budget**, and the budget
|
||
MUST include a **reserved finalization slice** held back for presence
|
||
`offline` publish and relay close, **no smaller than those finalizers'
|
||
declared bounds — currently 2s + 5s = 7s** — which child cleanup may
|
||
never consume: child reaping degrades first (skip remaining per-slot
|
||
waits, force-kill), because a shared deadline without the reservation
|
||
can legally spend all 60s reaping children and hit SIGKILL before the
|
||
one action the grace period exists to protect. The binding declares the
|
||
budget (§K8s Grace: 60s); anyone re-deriving "~37s" from the segment
|
||
constants is reading numbers without their variables. The desktop's
|
||
local stop command rejects remote agents.
|
||
- **Delete** with a live `backend_agent_id` requires `force_remote_delete:
|
||
true` from the UI's orphan-warning confirmation — a buggy IPC caller
|
||
cannot silently orphan substrate objects.
|
||
|
||
### Auto-Stop (Inactivity Self-Termination)
|
||
|
||
I5's enforcement point. A new harness knob:
|
||
|
||
```
|
||
--exit-after-inactivity <secs> / BUZZ_ACP_EXIT_AFTER_INACTIVITY
|
||
```
|
||
|
||
- **Default 0 = disabled.** The flag ships in the harness every *local*
|
||
agent also runs; a reaper bug must not be able to kill a laptop agent.
|
||
Remote providers opt in (the Kubernetes binding's `inactivity_seconds`
|
||
config field, schema default 7200 = 2h, feeds this env var directly).
|
||
**`inactivity_seconds: 0` is likewise a legal, blessed value meaning "no
|
||
inactivity bound"** — the explicit opt-in to an indefinitely-lived agent
|
||
(I5's lifetime-is-policy rule); it is not a misconfiguration and MUST NOT
|
||
be rejected by provider-side validation.
|
||
- **"Inactivity" is defined as**: no events dispatched to the agent and no
|
||
turns in flight. Raw relay traffic does not count — an agent lurking in a
|
||
busy channel it never answers is exactly the waste this bounds.
|
||
- **Mechanism**: on expiry of the bound, the harness fires the same shutdown
|
||
channel `!shutdown` uses — so inactivity exit gets in-flight drain,
|
||
presence→offline, and graceful relay close identically to an owner stop.
|
||
**The expiry check MUST NOT depend on pool readiness.** This is a design
|
||
constraint learned by inspection, not a transcription: the harness's
|
||
existing 30s maintenance tick is gated on `pool_ready` (`lib.rs:1743`),
|
||
which under `lazy_pool` starts false (`:1320`) and flips true only on a
|
||
wake (`:2570`) — and wakes require pending work (`pool_lifecycle.rs:42`).
|
||
A reaper riding that tick composes with the mandated
|
||
`BUZZ_ACP_LAZY_POOL=true` (§Launch data) into a deadlock in I5's single
|
||
most important case: a never-mentioned lazy pod never runs the tick, so
|
||
the idle agent the reaper exists to kill is exactly the one it can never
|
||
evaluate. The reaper therefore runs on its own timer, independent of pool
|
||
state (an idle-pool check needs no pool). Check granularity makes the
|
||
effective bound `t ∈ [T, T+interval)`, immaterial at T=7200.
|
||
- **Reserved keys**: `BUZZ_ACP_EXIT_AFTER_INACTIVITY` MUST join
|
||
`RESERVED_ENV_KEYS` (`env_vars.rs`) when it lands — it is tier-3
|
||
authoritative (§Launch data), and without reservation a user env var
|
||
could disable the reaper and reopen unbounded lifetime through the front
|
||
door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:378`) MUST join in the same
|
||
change, for the same shape of reason at I3 instead of I5: unreserved, it
|
||
lets user env silently defeat the 180s presence bound (I3). One knob
|
||
guards "knows when to leave", the other "you can see that it left";
|
||
both are promises users must not be able to un-make by typo.
|
||
- Distinctness note: this is a **fourth** timeout concept, deliberately named
|
||
away from the existing three (`--idle-timeout` = per-turn ACP wire silence,
|
||
900s; `turn_timeout`; `max_turn_duration` = 7200s — numerically equal to
|
||
the default inactivity bound and semantically unrelated). Sharing a flag or
|
||
env name with any of them is how the bug ships.
|
||
|
||
The harness exiting MUST terminate the substrate's unit of execution, and —
|
||
equally load-bearing — the substrate's termination signal MUST reach the
|
||
harness process itself; any wrapper MUST forward it. A wrapper that runs
|
||
the harness as a child without forwarding signals silently voids both I5's
|
||
substrate half *and* the graceful-shutdown budget: the termination signal
|
||
lands on the wrapper, the harness never learns to shut down, and the
|
||
force-kill leaves presence stale-online — exactly the staleness window the
|
||
grace period exists to close. This binding's realization — the harness as
|
||
the container's signal-receiving process (PID 1 or the signal target) — is
|
||
§K8s Entrypoint's `exec` rule and §Pod shape ([L3], L1 item 3 for the
|
||
universal form).
|
||
With the supervisor policy that matches the lifetime policy (this
|
||
binding's [L3] mapping — bounded → `Never`, indefinite → `OnFailure`
|
||
after both prerequisites, §Pod shape; the universal rule is I5's),
|
||
harness exit completes the pod on every intentional path — turning
|
||
agent-level I5 into substrate-level I5.
|
||
|
||
## The Kubernetes Binding (`buzz-backend-kubernetes`)
|
||
|
||
The first conforming provider: a Rust crate in `block/buzz`, distributed as a
|
||
standalone binary. Everything above is the contract; this section is its
|
||
realization.
|
||
|
||
### Cluster auth {#k8s-auth}
|
||
|
||
Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`) via
|
||
`kube-rs`. `provider_config` carries **`context`** and **`namespace`** only
|
||
(I2: credentials never transit config). Because kubeconfigs at Block
|
||
near-universally use `exec` credential plugins (`aws eks get-token`,
|
||
`gke-gcloud-auth-plugin`) that resolve via PATH, and the provider inherits a
|
||
Finder-launched desktop's minimal PATH, the provider MUST prepend
|
||
`/opt/homebrew/bin`, `/usr/local/bin`, and `~/.local/bin` to its own PATH
|
||
before building the client, and on exec-plugin failure MUST name the missing
|
||
plugin binary in the error rather than surfacing a kube-rs stack.
|
||
|
||
### Namespace {#k8s-namespace}
|
||
|
||
One stable namespace per user-visible choice; the provider emits a freshly
|
||
generated `buzz-agents-<rand6>` as the `namespace` field's schema *default*
|
||
on every `info` call, so the UI prefills a visible, editable random name with
|
||
zero UI changes ("random default" satisfied at the schema layer). If the
|
||
namespace does not exist the provider attempts to create it; on RBAC denial
|
||
it MUST fail with the literal `kubectl create namespace <name>` command to
|
||
run — it MUST NOT fall back to `default`.
|
||
|
||
### Image
|
||
|
||
`ghcr.io/block/buzz-sprig`: Alpine base + `bash` (required by the dev-MCP
|
||
shell tool) + `git` + CA certificates + the static musl `sprig` multicall
|
||
binary with its personality links (`buzz-acp`, `buzz-agent`, `buzz-dev-mcp`,
|
||
`rg`, `tree`, `buzz`, `git-credential-nostr`, `git-sign-nostr`) + a baked
|
||
system gitconfig wiring the nostr signing and credential helpers. The baked
|
||
credential-helper config MUST be scoped to the relay's git URL — mirroring
|
||
the local spawn's `credential.<relay-url>/git.helper` scoping — never a
|
||
global `credential.helper`: a global nostr helper would answer for every
|
||
remote, including github.com. ~15–25MB;
|
||
not FROM-scratch (bash and git preclude it). Sprig-only: alternate-harness
|
||
dependencies (node for Claude Code / Codex) come via the `image` override
|
||
field, not a fatter default. Tagging follows the relay image's matrix —
|
||
`sha-<short>` on main, semver on `sprig-v*` tags (the sprig tarball's
|
||
`+git.<sha>` version string is not a legal Docker tag). **The default image
|
||
reference MUST be pinned by digest, not tag**: the provider bakes, at
|
||
compile time, the multi-arch manifest digest of the image built from its
|
||
own commit and defaults `image` to
|
||
`ghcr.io/block/buzz-sprig@sha256:<that-digest>` — a `sha-<git-sha>` *tag*
|
||
is traceable but still movable (registry tags are mutable pointers;
|
||
Kubernetes distinguishes movable tags from immutable digests for exactly
|
||
this reason), and the object holding it runs with an nsec. The provider
|
||
records the reference it used in a pod annotation, and rejects `:latest`.
|
||
User `image` overrides accept tag, digest, or full custom registry
|
||
reference — visibly the user's trust decision, with the resolved image ID
|
||
recorded in the same annotation for post-hoc attribution.
|
||
**An image override MUST contain the runtime ABI** — the `buzz-acp`
|
||
entrypoint and everything §Entrypoint and launch ABI requires — not merely
|
||
alternate-harness dependencies. A conforming custom image is "buzz-sprig
|
||
plus your tools", never "your tools instead".
|
||
|
||
### Entrypoint and launch ABI {#k8s-entrypoint}
|
||
|
||
Two conforming implementations must produce interchangeable pods, so the
|
||
launch contract is normative.
|
||
|
||
**Entrypoint.** The container runs the harness as its signal-receiving
|
||
process. Sprig is a multicall binary with no supervisor personality —
|
||
nothing reaps children or forwards signals — so the entrypoint MUST end in
|
||
`exec`:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
# nest scaffolding, if DECISION A lands, goes here
|
||
exec buzz-acp # exec, not a call — buzz-acp must be PID 1
|
||
```
|
||
|
||
`bash -c "setup && buzz-acp"` (no `exec`) is non-conforming: bash becomes
|
||
PID 1, and a PID-1 bash with no trap never delivers SIGTERM to the harness
|
||
(PID 1 receives kernel-level default-handler signal immunity), so the pod
|
||
rides out the entire grace period and is SIGKILLed with presence still
|
||
online — voiding I5's substrate half and the very staleness window
|
||
`terminationGracePeriodSeconds: 60` was sized to close. The entrypoint
|
||
shape and the grace period are one requirement, not two.
|
||
|
||
**Payload → environment mapping.** The provider builds the pod environment
|
||
(via the per-agent Secret, §K8s Secrets) by applying the §Launch data
|
||
three-tier precedence — `launch.policy_env` (overridable defaults), then
|
||
`launch.env` (user/layered), then the authoritative tier from top-level
|
||
fields per the reserved-key rule. Only the
|
||
non-`launch` scalars and the substrate-forced re-derivations are mapped
|
||
individually:
|
||
|
||
| source | env var |
|
||
|---|---|
|
||
| `relay_url` | `BUZZ_RELAY_URL` |
|
||
| `private_key_nsec` | `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY` (the git helpers read the latter) |
|
||
| `auth_tag` | `BUZZ_AUTH_TAG` (omitted when null; then `launch.owner_pubkey` → `BUZZ_ACP_AGENT_OWNER` is REQUIRED — §Launch data owner rule) |
|
||
| `launch.command` | `BUZZ_ACP_AGENT_COMMAND` — the *name*, resolved against the image's own PATH; never a forwarded host path |
|
||
| `launch.args` | `BUZZ_ACP_AGENT_ARGS`, comma-joined |
|
||
| `launch.env`, `launch.policy_env` | verbatim, at their precedence tiers |
|
||
| generation token (§K8s Secrets) | `BUZZ_MANAGED_AGENT_START_NONCE` — the lifecycle-frame correlator and the Secret generation are one identity (§Launch data tier 3) |
|
||
| `system_prompt`, `idle_timeout_seconds`, `max_turn_duration_seconds`, `parallelism` | **not mapped by the provider** — the desktop resolves these into `launch.policy_env` (`BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`, `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS`), because they are tier-1 behavior knobs: locally they are written *before* the user env layer and none is reserved (`runtime.rs:716-729,763` vs `:860`; `env_vars.rs:54-57`), so user env beats them. A provider that mapped the top-level copies after `launch.env` would silently defeat an override that works locally. The top-level fields remain as display/bookkeeping inputs only |
|
||
| `turn_timeout_seconds` | not mapped — deprecated upstream and ignored; the local spawn also does not emit it |
|
||
| `respond_to` | `BUZZ_ACP_RESPOND_TO` |
|
||
| `respond_to_allowlist` | `BUZZ_ACP_RESPOND_TO_ALLOWLIST`, comma-joined |
|
||
| — | `BUZZ_ACP_MCP_COMMAND=buzz-dev-mcp` (image-local; the dev-MCP requirement) |
|
||
| `provider_config.inactivity_seconds` | `BUZZ_ACP_EXIT_AFTER_INACTIVITY` (schema default 7200; the I5 opt-in, §Auto-Stop — the config field and this env var are one knob, not two) |
|
||
|
||
The top-level `model`/`provider` payload fields are display/bookkeeping
|
||
inputs; the *environment* consequence of model and provider selection
|
||
(per-runtime vars, `provider_locked` suppression, `BUZZ_ACP_MODEL`) arrives
|
||
resolved inside `launch.env`/`launch.policy_env`. A provider MUST NOT map
|
||
`provider` to any env var itself — that mapping is per-runtime and lives in
|
||
the desktop's resolver (§Launch data).
|
||
|
||
**Encoding honesty note.** `BUZZ_ACP_AGENT_ARGS` is comma-delimited by the
|
||
harness's CLI parser, and the desktop's *local* spawn performs the same
|
||
comma-join — an argument containing a comma is unrepresentable in both
|
||
paths. This is a harness interface limitation the binding inherits and
|
||
matches, not one it introduces; a provider MUST NOT invent a private
|
||
escaping scheme the harness would not decode.
|
||
|
||
**Working directory.** `HOME` is set to a writable path backed by the
|
||
workspace `emptyDir` (e.g. `/home/agent`), and the harness runs with cwd =
|
||
`HOME` — mirroring the local spawn's agent-workdir convention. The baked
|
||
system gitconfig references the nostr helpers by absolute path so it works
|
||
regardless of `HOME`.
|
||
|
||
### Pod shape
|
||
|
||
- **Bare Pod; `restartPolicy` follows lifetime policy (I5).** No Job, no
|
||
controller — controller-grade restart machinery (`Restart=always`-shaped)
|
||
would resurrect what `!shutdown` and auto-stop terminate, violating I5.
|
||
Within the bare pod, the policy is selected from `inactivity_seconds`:
|
||
- **Bounded lifetime (`inactivity_seconds > 0`, the default): `Never`.**
|
||
The reaper's clean exit must complete the pod; any restart would undo
|
||
the reap. Accidental death is handled by *intent*, not machinery:
|
||
eviction → presence `offline` (I3) → user hits Start → the
|
||
reconciler's terminated arm re-creates. That sequence is
|
||
rescheduling-after-accident gated on a fresh owner intent — apt for an
|
||
agent whose owner already accepted "not running" as its default state.
|
||
- **Indefinite lifetime (`inactivity_seconds: 0`): `OnFailure`** — once
|
||
the harness exit-code contract is pinned (I5 ordering rule; until
|
||
then the provider MUST refuse the combination rather than ship
|
||
`OnFailure` against an undefended exit convention). `OnFailure`
|
||
restarts the *in-place* abnormal deaths — process crash, container
|
||
OOM-kill — and honors the intentional ones (clean exit completes the
|
||
pod): I5's intent-vs-accident distinction, realized. **Second
|
||
prerequisite — reconciler classification:** `OnFailure` introduces a
|
||
pod state the deploy state machine's rows do not cover — a
|
||
crash-looping harness sits in phase `Running` with
|
||
`state.waiting{reason: CrashLoopBackOff}`, `restartCount > 0`: not
|
||
deletion-marked, not terminated (the kubelet keeps restarting it),
|
||
not "live and started" (`state.running` is false), and not
|
||
never-started (it started, repeatedly) — and it fails the startup
|
||
success criterion while the kubelet is actively reviving it. Before
|
||
the binding ships `OnFailure`, the state machine MUST gain a
|
||
crash-loop classification row and the started-criterion's treatment
|
||
of `restartCount > 0` MUST be specified; the exit-code contract alone
|
||
is *not* the green light. **Honest
|
||
limit:** `restartPolicy` is
|
||
kubelet-level and cannot survive *node-level* loss — a drain or
|
||
API-initiated eviction deletes a bare pod outright, and no
|
||
restart policy reschedules a deleted pod. Full "continuous need"
|
||
across node loss requires controller-grade machinery this binding
|
||
deliberately does not use in v1 (the same machinery I5 distrusts);
|
||
the v1 promise for indefinite agents is restart-on-crash, with
|
||
node loss surfacing as presence `offline` awaiting a fresh Start.
|
||
- **Naming/labeling — the exact contract** (63-char label-value limit; a hex
|
||
pubkey is 64 chars, one over):
|
||
- pod name: `buzz-agent-<first-12-hex-of-pubkey>` — also the returned
|
||
`agent_id`
|
||
- label `buzz.block.xyz/agent-pubkey: <first-32-hex>` — the selector key
|
||
for reconciliation and GC. 128 bits is collision-*resistant*, not
|
||
collision-free, which is why the annotation check below is normative,
|
||
not decorative
|
||
- label `app.kubernetes.io/managed-by: buzz-backend-kubernetes` and label
|
||
`buzz.block.xyz/binding-version: <schema-version>` — the **management
|
||
marker** (§Deploy State Machine auto-repair fence): present on every
|
||
pod and Secret this provider creates, and **required before any
|
||
destructive repair or GC action**. Identity labels/annotations prove
|
||
identity; the marker asserts protocol ownership — without it, an object
|
||
that merely matches our schema fails closed to the operator
|
||
- annotation `buzz.block.xyz/agent-pubkey-full: <full-64-hex>` —
|
||
**load-bearing**: per §Deploy State Machine step 1, every label-selected
|
||
object's annotation MUST equal the derived pubkey before the provider
|
||
no-ops against it, deletes it, mutates its Secret, or returns its name
|
||
- annotation `buzz.block.xyz/create-intent: <sha256-of-intent-template>` — the
|
||
recorded create intent (§Deploy State Machine, create-intent
|
||
fingerprint), written at pod create; the divergence discriminator for
|
||
never-started pods
|
||
- Secret name: `buzz-agent-<first-12-hex>-<gen>`, where `<gen>` is a random
|
||
per-create-attempt **generation token** — unique, never reused, carrying
|
||
the same labels (identity + management marker) and annotation. The
|
||
pod's `envFrom` references this exact
|
||
Secret name. Deterministic pod name + unique Secret name is what makes
|
||
payload and Secret atomic at the pod-spec boundary (§K8s Secrets)
|
||
- **Deletion semantics the reconciler must respect.** A Kubernetes `DELETE`
|
||
returns success immediately while the object still exists; the name stays
|
||
taken until the kubelet finishes the grace period. Two consequences:
|
||
(a) a pod being gracefully deleted has `deletionTimestamp` set but remains
|
||
in phase `Running` — the reconciler MUST check the deletion mark before
|
||
phase (there is no `Terminating` phase to match on); (b) after deleting a
|
||
live pod, a naive immediate create gets AlreadyExists for up to the full
|
||
grace period — the reconciler MUST poll for actual disappearance (GET →
|
||
404) before creating. The delete call MUST use the object's own grace
|
||
period (kube-rs: `DeleteParams { grace_period_seconds: None, .. }`); the
|
||
tempting shortcut of passing `0` to skip the poll is a **force-kill** that
|
||
discards the 60s shutdown grace pinned below — the poll is mandatory
|
||
precisely because the fast path is wrong. For *terminal*
|
||
(Succeeded/Failed) pods — and for **unscheduled** pods (no assigned node:
|
||
unschedulable or quota-blocked `Pending`, a state users hit while setting
|
||
up a namespace) — the apiserver
|
||
zeroes the grace period and deletes immediately, so the normal restart
|
||
path needs no meaningful wait — do not add a fixed sleep, and do not use
|
||
zero-grace cleanup as a reason to skip the poll in the live-pod arm.
|
||
- **`terminationGracePeriodSeconds: 60` — a declared budget the harness
|
||
MUST honor, not a sum the spec derived.** Kubernetes' default 30s grace
|
||
would SIGKILL the harness mid-drain, leaving presence stale-online — the
|
||
avoidable half of I3's staleness window — so the binding declares 60s.
|
||
But the shutdown tail is *variable*, not constant (§Stop: the post-drain
|
||
reap segment alone reaches ~87s at default parallelism at `28ae6cd21`,
|
||
and earlier untimed segments precede it — the total is not bounded by
|
||
today's segment timeouts), so no fixed grace can be proven
|
||
sufficient by adding segment timeouts. The two halves of the requirement:
|
||
the binding *declares* the budget here, and the harness *enforces* it —
|
||
one shared deadline across the entire post-signal path, with a reserved
|
||
finalization slice (≥ the finalizers' declared bounds, currently 7s) for
|
||
presence `offline` and relay close, child cleanup
|
||
degrading first (§Stop, Known Defect 7). Until the harness enforcement
|
||
lands, 60s is an operational margin that the tail can exceed.
|
||
- **Hardening defaults (normative).** The workload is a prompted coding
|
||
agent running repository and tool code while holding an nsec; the pod MUST
|
||
NOT hand it ambient cluster credentials or kernel privilege on top:
|
||
`automountServiceAccountToken: false` (Kubernetes mounts a ServiceAccount
|
||
token unless told otherwise — an API-stealable credential the agent never
|
||
needs), `runAsNonRoot: true` with a fixed nonzero UID/GID,
|
||
`allowPrivilegeEscalation: false`, capabilities drop-all,
|
||
`seccompProfile.type: RuntimeDefault`; never privileged, `hostPID`,
|
||
`hostNetwork`, or `hostPath`. `readOnlyRootFilesystem` is *not* required
|
||
in v1 — the sprig toolchain writes outside the workspace mount — but is a
|
||
named candidate once the image's write surface is mapped. The
|
||
`service_account` config field selects an identity for scheduling/RBAC
|
||
purposes only; it MUST NOT silently re-enable token mounting — API-token
|
||
access, if ever wanted, is a separate explicit opt-in, not a side effect
|
||
of naming an SA.
|
||
- **Resources**: requests 1 cpu / 2Gi, limits 2 cpu / 4Gi, all four
|
||
configurable (`cargo build` in an agent workspace makes 500m/1Gi requests
|
||
unrealistic).
|
||
- **Workspace**: `emptyDir`. Checkouts and scratch die with the pod; agent
|
||
memory is relay-persisted (NIP-AE) and unaffected. PVC support is a
|
||
deferred knob. [DECISION A — how remote pods get the nest workspace
|
||
(AGENTS.md etc.) that local agents get from the desktop's `ensure_nest`;
|
||
current recommendation is a desktop-stated protocol field, not
|
||
image-side scaffolding — §Open Decisions.]
|
||
|
||
### Secrets {#k8s-secrets}
|
||
|
||
Per-agent `Secret` containing the identity variables (built from top-level
|
||
payload fields per the reserved-key rule) plus `env_vars`; consumed via
|
||
`envFrom`.
|
||
|
||
**Secret creation is per-attempt, immutable, and uniquely named**
|
||
(`buzz-agent-<first-12-hex>-<gen>`, §Pod shape). The rationale is a
|
||
concurrency race a deterministic shared Secret name cannot survive: two
|
||
concurrent deploys carrying *different* payloads would both write the shared
|
||
Secret, the loser's write could land last, and the winner's pod —
|
||
deterministic name, winner's spec — would resolve the **loser's**
|
||
identity/config through `envFrom`. The losing caller would have mutated the
|
||
winning generation despite strict no-op. Unique names close this: each
|
||
create attempt writes its own Secret first, then attempts the deterministic
|
||
pod create with a spec referencing exactly that Secret. Pod creation elects
|
||
the winner; payload and Secret are atomic at the pod-spec boundary, with no
|
||
Lease or CAS machinery.
|
||
|
||
Lifecycle rules that follow:
|
||
|
||
- **Winner**: pod + its referenced Secret live together; GC deletes them
|
||
together.
|
||
- **Losing contender** (create-conflict): annotation-verify the winning pod,
|
||
return its `agent_id` per the convergence rule, and delete **only its own
|
||
now-unreferenced Secret** — never the winner's, never any Secret
|
||
referenced by an *existing* pod. "Existing" deliberately includes
|
||
not-yet-started pods: an `envFrom` reference from a pod still pulling its
|
||
image is exactly as load-bearing as one from a running pod.
|
||
- **Live no-op arm**: no Secret is written at all (zero mutation).
|
||
- **GC**: also deletes annotation-verified **orphan Secrets** — those whose
|
||
generation token no existing pod references — covering contenders that
|
||
crashed between Secret create and their conflict cleanup. But only when
|
||
**age-eligible**: see the normative age gate in §K8s GC — "unreferenced"
|
||
is not "orphaned" while a concurrent attempt may still be between its
|
||
Secret create and its pod create.
|
||
|
||
Fresh configuration therefore materializes exactly when a fresh generation
|
||
does. Residual exposure, stated: any principal with
|
||
pod-exec or secret-read in the namespace can read the nsec. This is the
|
||
substrate-security boundary from §Non-Goals — the namespace is the isolation
|
||
unit, and users deploying to shared namespaces accept its ambient RBAC. The
|
||
in-pod narrowing that sprig's dev-MCP shim performs (strips the key from its
|
||
own env, re-materializes as a 0600 keyfile for the git helpers) limits
|
||
accidental leakage into subprocess environments, not hostile cluster access.
|
||
|
||
### Garbage collection {#k8s-gc}
|
||
|
||
A **generation** is one pod-create attempt and the uniquely-named Secret it
|
||
references; the Secret's generation token is the generation's identity, and
|
||
the *current* generation is the one referenced by the existing pod's
|
||
`envFrom`.
|
||
|
||
GC is a **preflight reconciliation pass**, not a post-deploy afterthought:
|
||
on every deploy, after identity derivation and before the state transition,
|
||
the provider deletes terminated pods (and their referenced Secrets) that
|
||
match the pubkey label, **pass the full-pubkey annotation check, and carry
|
||
the management marker** (§Pod shape; the auto-repair fence applies to GC
|
||
identically), plus
|
||
annotation-verified, marker-bearing orphan Secrets whose generation token
|
||
no existing pod
|
||
references (§K8s Secrets). It never touches the current generation.
|
||
Mismatched annotations are never GC'd (§Deploy State Machine step 1), and
|
||
an unmarked object is never GC'd regardless of its labels.
|
||
|
||
**Orphan-Secret age gate (normative).** An unreferenced Secret is
|
||
GC-eligible only when its server-assigned `creationTimestamp` is older than
|
||
**twice the deploy operation deadline** (2 × 600s). Rationale — without the
|
||
gate, GC composes with per-attempt Secrets into a legal interleaving that
|
||
strands a deploy: attempt A creates Secret A; concurrent attempt B runs its
|
||
preflight GC *before A creates its pod*, sees Secret A unreferenced, and
|
||
deletes it as an "orphan"; A's pod is then accepted referencing a missing
|
||
Secret and sits in `CreateContainerConfigError` until a later deploy
|
||
repairs it by delete-recreate (§Deploy State Machine never-started rows) —
|
||
a stranded deploy either way. Unique Secret
|
||
names made payload↔Secret atomic *at the pod-spec boundary*, but
|
||
Secret-create→pod-create is not atomic against an independent GC pass —
|
||
the standard controller lesson that observations may be stale and
|
||
reconciliation must tolerate in-flight peers. The age bound makes
|
||
"unreferenced" mean "provably abandoned": any attempt that could still
|
||
reference the Secret has exceeded its own deadline. A losing contender's
|
||
immediate cleanup of **its own** Secret is exempt — ownership, not age, is
|
||
its safety argument. (A Lease per agent identity would also close this
|
||
race; the age gate achieves the same with no extra machinery.)
|
||
|
||
**Same-clock rule (normative).** The age comparison has two operands and
|
||
both MUST come from the apiserver's clock. `creationTimestamp` is
|
||
server-assigned; the comparison instant MUST be derived from the HTTP
|
||
`Date` response header on the very list/get call the GC pass performs
|
||
(RFC 9110 §6.6.1 — origin-server message-origination time), never from the
|
||
provider's local `now()`. The provider runs on a user's desktop, and a
|
||
local clock fast by more than the margin doesn't *race* — it
|
||
deterministically computes every in-flight Secret as expired and deletes
|
||
them all, silently, on every pass, reopening exactly the interleaving the
|
||
gate exists to close. With both operands from one clock, skew cancels.
|
||
(`kube`'s `Client::send` returns the raw `http::Response` with headers, so
|
||
this costs one header read, not a departure from the typed API.) If the
|
||
`Date` header is absent or unparseable, the provider MUST **skip
|
||
orphan-Secret GC for that pass** — never fall back to local time. A
|
||
deferred cleanup is free; a wrong deletion is not.
|
||
|
||
**Alternative considered — `ownerReferences`, omitted in v1.** Kubernetes'
|
||
native GC (a Secret owned by its attempt's Pod is deleted when the owner is
|
||
verified absent) cannot *replace* the age gate: an ownerReference needs the
|
||
owner's UID, which exists only after pod create, so primary reliance on it
|
||
would flip the ordering to Pod-first-then-Secret. The reason that flip
|
||
loses is **diagnostics, not repairability**: a never-started winner is
|
||
recoverable (the kubelet retries a config-failed container indefinitely,
|
||
and the amended no-op rule lets a later deploy delete-and-recreate it with
|
||
its own payload), but Pod-first routes *every healthy deploy* through
|
||
`CreateContainerConfigError` — the exact condition the startup classifier
|
||
treats as an actionable failure signal — so the classifier could no longer
|
||
believe that reason without waiting out the deadline, on every deploy.
|
||
That trades away normative diagnostics for a cleanup the age gate already
|
||
provides. A *supplementary* post-create attachment (patch the Secret with
|
||
the winning pod's UID; Secret metadata stays patchable when `immutable` and
|
||
`data` are untouched) is sound but adds no required property: the pre-pod
|
||
crash window still needs the age-gated sweep as backstop, so v1 omits it
|
||
under the complexity budget. Any future implementation that adds it MUST
|
||
set `blockOwnerDeletion: false` explicitly (true requires `update` on
|
||
`pods/finalizers` — an RBAC verb nothing else here needs — and a Secret
|
||
should never delay its pod's deletion), MUST keep owner and dependent in
|
||
the same namespace (a cross-namespace owner is treated as *absent*, turning
|
||
the safety net into an immediate-delete instruction), and MUST treat
|
||
attachment failure as non-fatal cleanup, never a deploy error.
|
||
|
||
Running GC first
|
||
gives concurrency and Secret ownership one unambiguous order: reconcile
|
||
always observes a world with at most one candidate generation *older than
|
||
the gate*. Completed
|
||
pods from the *current* generation are left in place — their logs are the
|
||
only forensics M1 permits. That forensic window is deliberately fragile:
|
||
next-deploy GC, node loss, or namespace deletion erases it, and M1 means
|
||
there is no log operation to reach for. **Cluster-native log shipping is
|
||
therefore a production prerequisite, not an optional nicety** — the
|
||
ephemeral-runner lesson: disposable generations still need durable
|
||
diagnostics, forwarded off the pod by the cluster operator's stack. The
|
||
binding's contribution is correlation, not transport: the pod carries the
|
||
full-pubkey annotation, the generation token (doubling as
|
||
`BUZZ_MANAGED_AGENT_START_NONCE`, so lifecycle frames and pod logs share a
|
||
correlator), the provider version, and the resolved image reference
|
||
(§Image) — enough to attribute any shipped log line to an exact identity,
|
||
generation, and binary, with no secret in any of it. GC on next-deploy
|
||
also self-heals the missing
|
||
`undeploy`: delete-then-recreate converges, and a deleted-forever agent's
|
||
residue is one Completed pod that never restarts (I5) plus one Secret,
|
||
removable with `kubectl delete`.
|
||
|
||
### `provider_config` v1 fields
|
||
|
||
`context`, `namespace`, `image`, `cpu_request`, `memory_request`,
|
||
`cpu_limit`, `memory_limit`, `inactivity_seconds`, `service_account` —
|
||
9 of the 20-field validation cap. Node selectors, tolerations, and PVCs are
|
||
deliberately baked out of v1 to preserve budget.
|
||
|
||
### Distribution
|
||
|
||
Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's
|
||
ubuntu × musl matrix cannot produce the laptop-side binary), artifacts
|
||
attached to releases, installed to `~/.local/bin` (already on the discovery
|
||
path). v1 ships no Windows binary [DECISION B]; desktop bundling into the
|
||
.app (discovery already prepends the bundle dir) is deferred [DECISION D].
|
||
|
||
## Conformance
|
||
|
||
Obligations are split by layer per §Launchers: the **[L1] agent/harness
|
||
contract** binds every launcher; the **[L2] provider/deployer contract**
|
||
binds provider-managed launches; the **[L3] binding policy** here is the
|
||
Kubernetes binding's own. A non-provider launcher (bash script, systemd
|
||
unit) owes only the L1 items; a provider on a different substrate owes
|
||
L1 + L2 and writes its own L3 realization of the generic L3 property.
|
||
|
||
### [L1] Launcher conformance — every launcher
|
||
|
||
A launcher — desktop, provider-deployed pod, systemd unit, bash script —
|
||
is conforming iff:
|
||
|
||
1. It launches the harness with a **valid, nonempty identity**: a
|
||
parseable private key, a relay URL, and an auth tag or resolved owner
|
||
pubkey — refusing to launch rather than launching identityless (I1's
|
||
property, enforced wherever the env is assembled).
|
||
2. It does not suppress the harness's promises on a remote agent:
|
||
presence stays enabled (`BUZZ_ACP_NO_PRESENCE` never set — remotely,
|
||
presence is the only signal, I3), and the inactivity knob
|
||
(`BUZZ_ACP_EXIT_AFTER_INACTIVITY`) carries the owner's *deliberate*
|
||
lifetime policy, never an accidental passthrough of user env (I5; the
|
||
reserved-key rule is the provider path's realization of this).
|
||
3. The substrate's **termination signal reaches the harness process**,
|
||
with enough grace for its full graceful shutdown before force-kill (I3
|
||
staleness minimization). "Allows" is not enough — a wrapper that
|
||
swallows the signal conforms to nothing.
|
||
4. Intentional termination (owner `!shutdown`, inactivity reap) exits
|
||
through the harness's graceful path under the **pinned clean-exit
|
||
contract** (intentional exit ⇒ exit code 0 — Known Defect 6 until the
|
||
contract lands).
|
||
5. Any supervisor the launcher configures **never restarts an intentional
|
||
clean exit** (I5). `Restart=always` and equivalents are non-conforming
|
||
at this layer no matter what the substrate calls them.
|
||
|
||
### [L2] Provider conformance — provider-managed launches
|
||
|
||
A provider is conforming iff, in addition to deploying only L1-conforming
|
||
invocations:
|
||
|
||
1. `info` and `deploy` implement the wire contract (§Provider
|
||
Protocol), including one-JSON-in/one-JSON-out and in-band
|
||
`{"ok": false}` errors. **Exit codes carry exactly one bit** — zero =
|
||
the operation's output is trustworthy, nonzero = failure regardless of
|
||
stdout (§Invocation's rule restated from the provider's side): a
|
||
provider MUST exit nonzero on any crash path and MUST NOT encode
|
||
structured meaning in nonzero values, because `D` discards partial
|
||
output rather than interpreting codes.
|
||
2. It never requests or accepts credentials through
|
||
`provider_config` (I2).
|
||
3. It builds agent identity env from top-level payload fields, never
|
||
from `env_vars` (reserved-key rule), applies §Launch data mechanically —
|
||
three-tier precedence, host-resolved re-derivation, no re-merge of
|
||
legacy `env_vars`, no provider-side model/provider mapping — and refuses
|
||
a deploy that resolves neither `auth_tag` nor `launch.owner_pubkey`, or
|
||
whose provider is `relay-mesh`.
|
||
4. `deploy` implements the reconciliation loop (I4), stated
|
||
substrate-neutrally: identity derived from the nsec before any
|
||
mutation; candidates verified by **full-identity evidence** before any
|
||
action; live (= **started**: the harness process confirmed running, not
|
||
merely the body accepted) → strict no-op (zero mutation); never-started
|
||
states classified by evidence, not by substrate status strings
|
||
(provably-broken → fenced replace; recoverable + same recorded create
|
||
intent → observe, never delete, on this call or any later one;
|
||
recoverable + divergent intent → fenced replace); every read that can
|
||
authorize a destruction uses most-recent semantics; every destructive
|
||
write is **fenced to the exact observation that authorized it**
|
||
(compare-and-delete — the write fails if the object changed since the
|
||
read) and touches only objects carrying the provider's **management
|
||
marker** (the auto-repair fence, §Deploy State Machine);
|
||
same-status-code conflicts discriminated by a **machine-readable
|
||
conflict discriminator**, never the status code alone; success only on
|
||
confirmed harness start; conflicts converge by re-entry;
|
||
delete-of-absent is success.
|
||
5. It emits no secret material in any output (belt to `D`'s
|
||
redaction suspenders).
|
||
6. **Generic L3 obligation:** its binding *documents* how it realizes each
|
||
L2 term on its substrate, and how the owner's lifetime policy (bounded
|
||
vs indefinite) and clean-exit restart behavior are realized there —
|
||
stating the properties in its own vocabulary, not skipping them.
|
||
|
||
### [L3] Kubernetes binding conformance — this binding
|
||
|
||
The realization the two lists above require, in this binding's vocabulary:
|
||
|
||
1. Each L2 item-4 term maps to the mechanism in §Deploy State Machine:
|
||
full-pubkey annotation for identity evidence, container `state.running`
|
||
for "started", `resourceVersion`-unset quorum reads for most-recent
|
||
semantics, UID+`resourceVersion` delete preconditions for fencing,
|
||
`Status.reason` as the 409 discriminator, and the
|
||
`app.kubernetes.io/managed-by` + binding-version labels as the
|
||
management marker.
|
||
2. The deployed invocation realizes the lifetime policy the owner chose
|
||
(I5) through this binding's `inactivity_seconds` field: `> 0` →
|
||
a working inactivity bound and `restartPolicy: Never`; `0` (the
|
||
blessed indefinite opt-in) → no bound and `restartPolicy: OnFailure`,
|
||
**only after both prerequisites land** — the pinned exit-code contract
|
||
(I5 ordering rule) *and* the crash-loop classification row (§Pod
|
||
shape); until then the provider MUST refuse the combination.
|
||
3. The harness is the deployed container's **signal-receiving process**
|
||
(PID 1 or the target of the pod's termination signal — §K8s
|
||
Entrypoint's `exec` rule), and `terminationGracePeriodSeconds` carries
|
||
the declared grace budget (§Pod shape).
|
||
|
||
Conformance is testable without mechanization: a fake-provider harness can
|
||
exercise L2 items 1–3 and 5 over the wire contract — including the pre-secret
|
||
negotiation gate (§Discovery): an incompatible **or absent**
|
||
`protocol_version` MUST be rejected before any request carrying
|
||
`private_key_nsec` is sent; a **same-inode content rewrite** of the
|
||
resolved binary after resolution MUST NOT reach the deploy invocation
|
||
(the staged artifact still carries the bytes that answered `info`); and a
|
||
**pathname swap after validation** — the resolved path re-pointed at a
|
||
different file between the gate's checks and process spawn — likewise
|
||
MUST NOT redirect the nsec (both cases are exactly what path+metadata
|
||
comparison misses) — and an envtest/kind suite
|
||
can drive L2 item 4's reconciler against a real apiserver — concurrent
|
||
deploys, a deletion-marked pod, terminal restart, an annotation-mismatch
|
||
collision, and SIGTERM→presence-offline for the L3 items. Three families of
|
||
cases are mandatory because they were the review-found failure modes:
|
||
**startup discrimination** (slow-but-valid scheduling → poll-then-succeed;
|
||
`Unschedulable` during scale-from-zero → observed until the autoscaler
|
||
provisions capacity, then success — never delete, **including when
|
||
provisioning completes only after the 600s deadline**: the original pod
|
||
identity and `creationTimestamp` survive the expired call and become the
|
||
no-op winner on a later deploy, the case that pins the anti-livelock rule;
|
||
a label-and-annotation-matching object **without the management marker** →
|
||
never deleted, never GC'd, reported (the auto-repair fence under test);
|
||
referenced Secret *confirmed absent* → preconditioned delete-recreate or
|
||
actionable error, never silent success or no-op; a **never-started winner
|
||
is repairable** — pod exists, Secret absent, container never started: a
|
||
later deploy MUST delete-and-recreate rather than no-op, the test that pins
|
||
started-not-phase as the no-op criterion; and the **classification→DELETE
|
||
race** — the container transitions to running between the classifying read
|
||
and the delete: the UID+resourceVersion precondition MUST fail and the
|
||
live agent MUST be preserved) and the **GC/attempt interleaving** (attempt B's
|
||
preflight GC running between attempt A's Secret create and pod create MUST
|
||
NOT delete Secret A — the §K8s GC age gate under test; provider death after
|
||
Secret create → the age gate protects, then a later GC reaps; and a
|
||
**provider local clock fast beyond the margin** MUST NOT delete an
|
||
in-flight Secret — cheap with a fake clock, and the same-clock rule's
|
||
skip-on-absent-`Date` arm is exercised by stripping the header). A third
|
||
family pins the **divergence discriminator and the 409 split**: a failed
|
||
delete precondition (code 409, reason `Conflict`) → re-read and
|
||
re-classify, never the create-conflict cleanup/adoption path; a create
|
||
conflict (code 409, reason `AlreadyExists`) → loser-Secret cleanup and
|
||
winner adoption, never treated as a failed delete; identical desired
|
||
intent + permanently-Pending pod → no delete across arbitrarily many
|
||
Starts, regardless of age; a resource/image correction against a
|
||
never-started pod → fingerprint differs, preconditioned
|
||
delete-and-recreate (the wedge-escape case); same user config but the
|
||
provider's **baked default image digest** changed (provider upgrade)
|
||
against a never-started pod → divergence, replace (the second intent
|
||
source — the only escape from a bad-default-image wedge); the same correction against
|
||
a **started** pod → strict zero-mutation no-op; admission
|
||
defaulting/mutating the live pod → no false divergence (the comparison
|
||
uses the recorded annotation); the fingerprint serializer property,
|
||
asserted structurally — changing only Secret *values* or the generated
|
||
Secret *name* leaves the fingerprint unchanged, changing any
|
||
fingerprinted pod-create field changes it (equivalently: the serializer
|
||
has no access to Secret data or attempt identity); and the
|
||
conflict-path asymmetry — two no-instance contenders with different
|
||
payloads: the create loser adopts the elected winner rather than
|
||
deleting it for divergence, while a subsequent deploy observing that
|
||
never-started divergent winner replaces it. A model checker is
|
||
the wrong tool here: the failure modes found in review were wrong
|
||
*abstractions of Kubernetes* (a nonexistent `Terminating` phase, non-atomic
|
||
delete, phase-as-readiness, non-atomic Secret→pod against GC), which a
|
||
hand-written model would have reproduced convincingly.
|
||
|
||
## Known Defects (at `28ae6cd21`)
|
||
|
||
**Citation pin:** every `file:line` reference in this document was verified
|
||
against `28ae6cd21` — the commit at which this spec merged to `main`.
|
||
References are to that tree; a later commit may offset them.
|
||
|
||
Desktop- and harness-side, discovered during this design:
|
||
|
||
1. **Windows discovery id pollution**: the `.exe` suffix survives into the
|
||
provider id, which then fails id validation at deploy — dropdown-visible,
|
||
probe-fine, deploy-broken. Fix is a suffix strip in discovery. (v1
|
||
provider scope is macOS+Linux regardless — [DECISION B].)
|
||
2. **Provider env inheritance**: `invoke_provider` passes the desktop's
|
||
environment through unmodified; combined with launchd's minimal PATH this
|
||
breaks kubeconfig exec plugins. Mitigated provider-side (§K8s Auth);
|
||
a desktop-side PATH augmentation would fix the class.
|
||
3. **Deploy payload bypasses the launch resolver** (the prerequisite this
|
||
spec names for §Launch data — a desktop code change, not spec text).
|
||
At `28ae6cd21`, `deploy_payload_json` serializes raw record bytes and a
|
||
three-layer `merged_user_env` where the local spawn uses
|
||
`resolve_effective_harness_descriptor`'s six-layer resolution. Concrete
|
||
consequences, each verified in review: (a) no per-runtime model/provider
|
||
env — a remote goose agent silently ignores the user's model choice, and
|
||
`provider_locked` runtimes would receive vars the desktop deliberately
|
||
withholds; (b) persona-derived `agent_command` and definition-provided
|
||
`agent_args` serialize as blank/empty — a different command line than the
|
||
identical local agent; (c) no `owner_pubkey` — a null-`auth_tag` agent
|
||
cannot match `!shutdown` (it *answers* it), stranding §Stop; (d) spawn
|
||
policy (`BUZZ_ACP_RELAY_OBSERVER`, runtime `default_env` such as
|
||
`GOOSE_MODE=auto`, team instructions, session title, lazy-pool selection)
|
||
is absent — remote pods run different observer/approval semantics
|
||
(`BUZZ_ACP_DEDUP`/`BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are *not* on this
|
||
list: the local writes match the harness defaults, §Launch data); (e) a
|
||
mesh-provider agent deploys pointed at a loopback URL that cannot exist
|
||
in the pod instead of being refused. Until `deploy_payload_json` emits
|
||
the `launch` block, no provider can conform to §Launch data, and the
|
||
current payload MUST be treated as insufficient for a
|
||
semantics-preserving remote launch. **Security follow-through:** once
|
||
secrets can arrive via `launch.env`, desktop redaction MUST collect
|
||
candidate values from `launch.env` (and `launch.policy_env`) as well as
|
||
legacy `agent.env_vars` — at `28ae6cd21`, `env_secrets_from_request`
|
||
reads only `agent.env_vars` (`backend.rs`), leaving a
|
||
definition/persona-layer secret outside the literal-value scrub.
|
||
Conformance: a provider that echoes a launch-only secret into an error
|
||
must come back redacted.
|
||
4. **The I5 reaper does not exist, and its natural home is a trap**
|
||
(harness code prerequisite). `BUZZ_ACP_EXIT_AFTER_INACTIVITY` appears
|
||
nowhere in the harness at `28ae6cd21`; §Auto-Stop is a design, not a
|
||
description. Worse, the obvious attachment point — the existing 30s
|
||
maintenance tick — is gated on `pool_ready` (`lib.rs:1743`), which under
|
||
`lazy_pool` only becomes true when work arrives, so a never-mentioned
|
||
lazy pod would never evaluate the bound: I5 dead in its most important
|
||
case (§Auto-Stop mechanism rule). The implementation MUST run the expiry
|
||
check on a pool-independent timer and MUST add the env var to
|
||
`RESERVED_ENV_KEYS` in the same change.
|
||
5. **The deploy path never checks `protocol_version`** (desktop code
|
||
prerequisite). `provider_deploy` (`backend.rs`) sends the nsec-bearing
|
||
`deploy` request without any preceding `info` on the same resolved
|
||
executable; §Discovery's pre-secret negotiation gate is a design, not a
|
||
description, until the deploy command performs
|
||
resolve-once → stage-and-digest → `info` → explicit-version check →
|
||
`deploy`, both invocations running the staged bytes.
|
||
6. **The clean-exit contract is emergent, not defended** (harness code
|
||
prerequisite; gates `OnFailure`). At `28ae6cd21`: the graceful path
|
||
returns `Ok(())` (`lib.rs:2723`), and owner `!shutdown` (`:2045`),
|
||
Ctrl-C (`:1635`), and
|
||
SIGTERM (`:1644`) all route into the same shutdown channel — so clean
|
||
stops exit 0 *today*, but no distinguished exit code exists and no test
|
||
pins "intentional exit ⇒ 0"; every `process::exit(1)` in the crate is a
|
||
startup failure. Until a
|
||
pinned, tested exit-code contract lands, no supervisor restart policy
|
||
(`restartPolicy: OnFailure`, systemd `Restart=on-failure`) may be
|
||
deployed against the harness: a refactor returning `Err` from a drain
|
||
timeout would silently convert every clean stop into a restart loop —
|
||
I5 defeated with no failing test (I5 ordering rule).
|
||
7. **The shutdown tail overruns the declared grace budget at default
|
||
config** (harness code prerequisite). At `28ae6cd21`: the post-drain
|
||
reap segment
|
||
(`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
|
||
(`:2636,:2657`) and serially awaits a 5s post-SIGKILL wait per occupied
|
||
slot (`acp.rs:436`) — that segment alone reaches ~87s at the desktop's
|
||
default parallelism of 10 (`types.rs:814`; #3038 lowered it from 24),
|
||
~197s at the harness cap of 32 (`config.rs:293`), against the binding's
|
||
60s grace; and it is not the whole tail — the wake-task drain
|
||
(`:2612`) and awakened-pool shutdown (`:2620-2624`, per-slot loop
|
||
`:3747-3751`, no timeout) precede it (§Stop), so the total is
|
||
unbounded by today's segment timeouts. The fix is one shared deadline
|
||
across the entire post-signal
|
||
path with a reserved finalization slice (≥ the finalizers' declared
|
||
bounds, currently 2s presence + 5s relay close = 7s) for presence
|
||
`offline` and
|
||
relay close, child cleanup degrading first (§Stop); natural home is the
|
||
same harness change as the I5 reaper (defect 4).
|
||
8. **Cleared numeric config fields ship as strings** (desktop code
|
||
prerequisite, raised by blessing `0`). `coerceConfigValues`
|
||
(`desktop/src/features/agents/ui/ProviderConfigFields.tsx:6` at
|
||
`28ae6cd21`) skips numeric coercion when the value is `""`, so a
|
||
*cleared* numeric field reaches the provider as a JSON string instead
|
||
of a number. Blessing `inactivity_seconds: 0` makes clearing that
|
||
field a legitimate user action, so the empty-string arm now sits on a
|
||
documented path: the provider receives `""` where the schema says
|
||
integer, and "0 MUST NOT be rejected" cannot protect a value that
|
||
never parses as 0. Fix is desktop-side (map cleared numeric →
|
||
omit-or-default, never `""`); provider-side, a non-numeric value for a
|
||
numeric field is an in-band error, not a silent default.
|
||
|
||
## Implementation Correspondence
|
||
|
||
| spec concept | code |
|
||
|---|---|
|
||
| Discovery, resolution rule | `desktop/src-tauri/src/managed_agents/backend.rs` (`discover_provider_candidates`, `resolve_provider_binary`) |
|
||
| Invocation, output caps, exit rule | `backend.rs` (`invoke_provider`) |
|
||
| Pre-secret negotiation gate | *to be added*: `backend.rs` deploy path — resolve-once → stage-and-digest → `info` → explicit-version check → `deploy` on the staged bytes (Known Defect 5) |
|
||
| Redaction | `backend.rs` (`redact_secrets_with`) |
|
||
| I2 validation | `backend.rs` (`validate_provider_config`) |
|
||
| I1 refusal, payload | `desktop/src-tauri/src/commands/agents_deploy.rs` |
|
||
| Launch resolver (shared with local spawn) | `desktop/src-tauri/src/managed_agents/readiness.rs` (`resolve_effective_harness_descriptor`); `launch` block emission *to be added* to `agents_deploy.rs` (Known Defect 3) |
|
||
| Mesh rewrite (why relay-mesh is non-deployable) | `desktop/src-tauri/src/managed_agents/relay_mesh.rs`; create-time rejection in `commands/agents.rs` (`normalize_relay_mesh`) |
|
||
| Reserved-key strip | `desktop/src-tauri/src/managed_agents/env_vars.rs` (`RESERVED_ENV_KEYS`) |
|
||
| Unconditional deploy on Start | `desktop/src-tauri/src/commands/agents.rs` (`start_managed_agent`) |
|
||
| Presence publish / offline-on-exit | `crates/buzz-acp/src/lib.rs` (`publish_presence`, shutdown path) |
|
||
| `!shutdown` owner check | `crates/buzz-acp/src/lib.rs` (main loop) |
|
||
| Graceful shutdown path (budget enforcement *to be added* — Known Defect 7) | `crates/buzz-acp/src/lib.rs` (pool shutdown, then drain / reap / presence / relay close) |
|
||
| Clean-exit exit-code contract | *to be added*: `crates/buzz-acp` distinguished exit codes + pinning test (Known Defect 6; gates `OnFailure`) |
|
||
| Auto-stop flag | *to be added*: `crates/buzz-acp/src/config.rs` + a pool-independent timer (NOT the `pool_ready`-gated maintenance tick — Known Defect 4) + `RESERVED_ENV_KEYS` entry |
|
||
| Kubernetes binding | *to be added*: `crates/buzz-backend-kubernetes` |
|
||
| Sprig image | *to be added*: `Dockerfile.sprig` + workflow |
|
||
|
||
## Open Decisions
|
||
|
||
Marked `[DECISION]` inline; consolidated:
|
||
|
||
- **A. Nest scaffolding** — should the image entrypoint scaffold the agent
|
||
workspace (AGENTS.md, RESEARCH/, …) that the desktop's `ensure_nest`
|
||
provides locally? Recommendation (revised): **workspace becomes a
|
||
protocol field the desktop states**, not an image-baked behavior — the
|
||
desktop resolves the nest content it would have written locally and
|
||
carries it in the launch data, so every substrate materializes the same
|
||
workspace from the same source of truth and the image stays
|
||
scaffold-free. An image-side template crate was the earlier
|
||
recommendation; it loses because it forks the nest definition into a
|
||
second implementation that drifts from `ensure_nest`.
|
||
- **B. Windows scope** — fix the `.exe` discovery bug in the desktop now;
|
||
ship Windows provider binaries only on demand. Recommended as stated.
|
||
- **C. Config budget** — the 9-field v1 set above. Recommended as stated.
|
||
- **D. Desktop bundling** — `~/.local/bin` install only for v1. Recommended
|
||
as stated.
|
||
- **E. Running-pod semantics** — no-op (recommended, both reviewers) vs
|
||
forcible recycle on Start. Ruled: **per-binding policy**, with one
|
||
universal property every binding must preserve — no sequence of Starts
|
||
yields two live instances in one scope (I4). The Kubernetes binding
|
||
keeps strict no-op in v1; a recycle affordance, if a binding adds one,
|
||
is stop-then-start, never delete-under-a-live-agent.
|
||
- **F. Mesh deployability** — the spec refuses relay-mesh agents
|
||
pre-mutation in v1 (§Launch data: the transport is desktop loopback;
|
||
serializing it fails identically but invisibly). Reviewer consensus is
|
||
refusal; ratification requested because it makes a visible product cut
|
||
(shared-compute agents are local-only until an in-image mesh client
|
||
exists).
|
||
- **G. Remote override semantics** — the spec keeps local semantics: user
|
||
env continues to beat Buzz behavior defaults remotely (three-tier
|
||
precedence, §Launch data), because the alternative is a quiet behavior
|
||
fork between local and remote spawns of the same record. Flagged because
|
||
it is a policy statement about what power users may do to remote pods.
|
||
- **H. Startup budget** — with deploy success now requiring container start
|
||
(§Deploy State Machine), the 600s operation deadline is the de facto
|
||
cold-pull / scale-from-zero budget. The spec fixes the semantics
|
||
narrowly: the deadline bounds how long one Start waits synchronously —
|
||
never when anything is destroyed (recoverable startup is observational
|
||
across calls, so a cluster whose autoscaler `new-pod-scale-up-delay`
|
||
exceeds 600s degrades to "Start reports unconfirmed, a later Start
|
||
adopts the now-running pod", not a livelock). The remaining SLO ruling
|
||
is UX-only: is ten minutes of synchronous waiting the right ceiling for
|
||
the intended cluster class?
|
||
- **I. Never-started escape hatch** — the create-intent fingerprint
|
||
(§Deploy State Machine) lets a config *change* replace a never-started
|
||
pod, closing the config wedge. Ruled on the vision-consistency half:
|
||
Start-time auto-repair of never-started bodies is legitimate, **fenced
|
||
to Buzz-authored, positively identified residue** (§Deploy State Machine
|
||
auto-repair rule) — the vision's "never-started body is operator
|
||
residue" line gains that qualifier rather than being waived. The
|
||
remaining product question: does v1 owe users an explicit in-product
|
||
"clear this stuck deployment" affordance for a never-started pod whose
|
||
config they have *not* changed (a genuinely slow or broken cluster)?
|
||
Both reviewers agree on the mechanism; this is the remaining product
|
||
question layered on top of it.
|
||
|
||
## Summary
|
||
|
||
Remote agents extend Buzz's managed-agent model across a deliberately thin
|
||
boundary: one untrusted binary, two JSON operations, and a relay. The
|
||
desktop's obligations end at a well-formed, fail-closed deploy payload; the
|
||
provider's obligations are convergence and honesty about state; the agent's
|
||
obligation is to honor its owner's lifetime choice — bounded by default,
|
||
indefinite by declaration, and in either case final when told to stop.
|
||
Everything else — status, control,
|
||
memory — was already on the relay, which is why the design holds: the relay
|
||
was the management plane all along, and the desktop was only ever one of
|
||
its doors.
|