Skip to content

[review] feat(spiron): speak spiron.headless/v2 and run local Spiron without a keeper - #280

Merged
shtse8 merged 14 commits into
mainfrom
w-protocol/spiron-v2-adapter
Nov 16, 2026
Merged

shtse8 merged 14 commits into
mainfrom
w-protocol/spiron-v2-adapter

Conversation

@shtse8

@shtse8 shtse8 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

The Spiron adapter speaks spiron.headless/v2 (ADR 0011, #276; Spiron side SylphxAI/spiron#5383) and local Spiron runs with no keeper: a process of its own behind its Unix socket that a restarted server reattaches to with after_seq. v1 stays.

How it runs

  • Where processes outlive the server (Linux, serve with keepers), a Spiron launch starts spiron --headless --json ... --listen <config dir>/spiron.sock in its own process group, output in <config dir>/spiron.log, connects and sends attach. It speaks v2 when the ready answering that attach says so. A binary that exits with a usage error naming --listen (v1 only) runs as before: v1 over stdio, in a keeper.
  • The launch record <data>/detached/<agent>.json (server-owned, 0600 in a 0700 directory, because it names a process the server may signal) holds the process identity (pid, start time, boot id, pid namespace), seat, socket, session and after_seq = the launch ready's seq minus one. It is written once per launch, and the supervisor's process note is kept in it.
  • Server shutdown (retain) closes the connection and leaves the process running. At startup the custody takes the agent's lock, proves the recorded process, and reattaches with after_seq; the replay of the process's frames rebuilds the adapter exactly (open turn, accepted/steer_consumed proofs, served usage), so the supervisor's note compares against the same totals. A process that is gone or will not attach is ended and replaced.
  • stop sends v2 stop (3 s grace, then the process group, inside the shared 5 s STOP_DEADLINE that delete, archive and pause wait); dropping an adapter that was neither stopped nor detached ends the process, as for a child. Every Spiron launch first ends a process a stale record still names. anyagents keepers stop also ends these processes, so a rollback to a binary without v2 support does not leave one behind.

Delivery

  • Mailbox cursors still move only on accepted / steer_consumed. A v2 receipt for an input an earlier connection wrote is taken as written by this one, so a re-offered message is answered from the replayed proof and never written again; one Spiron never answered is written again and Spiron drops it by request_id.
  • v2 inputs carry no aliases (prompt/steer/cancel with request_id). result.cost_micros is recorded as the turn's reported cost (also from a v1 Spiron that sends it).

Tests

  • anyagents-harness-stream v2_tests: replay rebuild and no rewrite, over a real socket with recorded frames; a refused attach.
  • anyagents-harness-spiron/tests/real_spiron_v2.rs: the adapter against the REAL Spiron binary (SPIRON_BIN): launch, deliver, steer mid-turn, detach (server gone, process alive), reattach with after_seq, rebuilt proofs, nothing written twice, turn end with usage and cost 78, stop. Without SPIRON_BIN it reports itself not run (ANYAGENTS_REQUIRE_SPIRON=1 makes that a failure); AnyAgents' public CI cannot build the private Spiron, so the binary-driven conformance suite runs in Spiron's CI (SylphxAI/spiron PR).
  • A binary without v2 is reported NotV2.

Docs: docs/delivery.md (v2 row), docs/architecture.md (Spiron reports cost).

Not merged, not deployed. Deploying needs a Spiron release with v2 first; until then every Spiron launch falls back to v1 in a keeper after one failed --listen exec.

Verified locally against a Spiron built from SylphxAI/spiron#5383 (SPIRON_BIN):

  • real_spiron_v2.rs (2 tests) and server_harnesses a_v2_spiron_needs_no_keeper_and_is_reattached_after_a_server_crash: server killed mid-turn with a steer in flight, the same Spiron pid survives a crash and a clean stop, the next server reattaches, both messages are committed once, Spiron's frame journal shows each consumed exactly once, one result with cost_micros 78, and the idle agent's process ends with its record. The keeper path for v1 binaries (a_spiron_adapter_in_its_keeper_never_writes_a_line_twice_across_a_restart, a_server_stops_at_once_while_a_keeper_is_still_starting) still passes.
  • cargo clippy --workspace --all-targets -D warnings clean. cargo test --workspace: 1674 passed; the failures (sandbox ... preserving_setgid, memory_backlog_follows_wakes..., three_tier_agent_authority..., supervisor profile_rotation_keeps_mail_flowing...) fail the same way on main on this host; host_retrieval ... multi_agent_refresh passed on rerun.

Independent review fixes

  • D2: a launch record beside a live keeper (rollback then roll forward, or a crash while switching from a kept harness) no longer returns Boot::Retry forever: the custody takes the lock from the keeper, retires it as older (proofs committed) and goes on with the v2 process. a_roll_forward_after_a_rollback_retires_the_keeper_and_keeps_one_spiron runs it against the real binaries (SPIRON_BIN, OLD_ANYAGENTS_BIN); it did not finish without the fix.
  • D3: a quota in a replayed frame no longer holds the agent (v2_tests::a_replayed_quota_holds_nothing_and_a_live_one_does).
  • D4: a spiron --help probe that times out is not cached as "not v2" (a_probe_that_runs_out_of_time_is_asked_again).
  • D5: delete, archive and pause wait anyagents_harness::STOP_DEADLINE (5 s); the v2 stop grace is 3 s.
  • Records live in <data>/detached/, and keepers --help names "detached harness processes" (CLI test): the release guardian reads both, and platform code must not name products.

Deploy order: SylphxAI/infra#5588 (the release guardian ends detached harness processes before a rollback away from them) must merge before this deploys, and a Spiron release with v2 must exist for it to matter.

… keeper

A Spiron that knows --listen runs as a process of its own behind
<config dir>/spiron.sock and outlives the server. The launch record
<data>/spiron/<agent>.json names its identity and the seq a new server
replays from; after a restart the custody takes the agent lock and
reattaches with after_seq, and the replay rebuilds the adapter (open
turn, proofs, served usage). A v2 receipt for an input an earlier
connection wrote is taken as written, so nothing is written twice.
stop ends the process; a server stop only closes the connection.
result.cost_micros is recorded. v1 (stdio, in a keeper) stays for
binaries without --listen. keepers stop also ends these processes.

Tests: replay rebuild over a socket; the adapter and a server crash/
reattach against the real Spiron binary (SPIRON_BIN).
The launch record is written as soon as the process is spawned (its
identity, socket, after_seq 0) and completed after its ready, so a
server that dies during the launch leaves a process its successor finds
and attaches to or ends, never one that holds the socket unrecorded.
…played quotas, re-ask a timed-out probe, stop within the delete wait

- D2: a launch record beside a live keeper (a rollback then a roll
  forward, or a crash during a switch from a kept harness) no longer
  retries forever on the agent lock: the keeper's lock is taken, the
  keeper is retired as an older process (its proofs committed) and the
  v2 process goes on. Roll-forward test against the real binaries.
- D3: a quota a replayed frame reports no longer holds the agent.
- D4: a spiron --help probe that runs out of time is not kept as v1.
- D5: a v2 stop gives the process 3 s before ending its group, inside a
  shared 5 s STOP_DEADLINE that delete, archive and pause now wait.
- Launch records move to <data>/detached and keepers --help names
  detached harness processes: the release guardian (infra) reads both and
  must not name products.
- ADR 0011 (merged): session_in_use, host tools on v1, the keeper beside
  a v2 process, the record's place; ADR 0007's rollback runbook covers
  detached harnesses.
…der the window policy

Spiron main added a context policy (fixed or window): ready names it, and
under window there is no compaction threshold (null).
A model can reuse a tool call id across turns, so host_tool_call's
call_id is now minted per invocation, and tool_call_id carries the
model's id.
@shtse8
shtse8 enabled auto-merge November 15, 2026 23:26
@shtse8
shtse8 disabled auto-merge November 15, 2026 23:57
@shtse8
shtse8 enabled auto-merge November 16, 2026 00:24
@shtse8
shtse8 added this pull request to the merge queue Nov 16, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 16, 2026
…adapter

# Conflicts:
#	crates/anyagents-harness-stream/src/lib.rs
@shtse8
shtse8 enabled auto-merge November 16, 2026 01:55
@shtse8
shtse8 added this pull request to the merge queue Nov 16, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 16, 2026
@shtse8
shtse8 added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit cd74611 Nov 16, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant