Skip to content

feat: kontext dispatch gives a ready epic its own sandbox (core) - #55

Merged
OmarAlex24 merged 1 commit into
mainfrom
dispatch/core
Nov 17, 2026
Merged

OmarAlex24 merged 1 commit into
mainfrom
dispatch/core

Conversation

@OmarAlex24

@OmarAlex24 OmarAlex24 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Bottom of the kontext dispatch stack (4 PRs): the core, against a fake Boat. kontext dispatch <epic> gives an epic of a ready wave a sandbox of its own, with a coordinator token that reaches it only as a file.

What changed and why

  • kontext dispatch <epic> (src/dispatch/mod.rs)
    • Checks, each a refusal with exit 2 and one line saying why: the project syncs through a server (with a token); the plan is signed; the epic exists, is in force and open; it is in a wave and that wave is ready ("epic payments is in wave 2, which is not ready: it waits for …"); it has no sandbox yet; fewer than the cap (default 3) are running. The last two are checked again under the state lock, so two dispatches at once cannot both pass.
    • An epic with a single open task gets a warning and dispatch goes on.
    • Token: a coordinator token for the epic, actor agent:epic:<name>, valid for the time limit plus 2 hours. Its id is saved; the token itself is written to a 0600 file made with create_new in the dispatch folder, handed to boat new --file .kontext-dispatch-token=<file>, and removed as soon as boat new returns (and on drop). It is never in argv, -e, stdout, stderr or a log.
    • boat new: --name kontext-<project>-<epic>, --environment (if configured), --type, --ttl (time limit + 1 h), --setup-file, and -e for KONTEXT_SERVER, KONTEXT_PROJECT, KONTEXT_ACTOR=agent:epic:, KONTEXT_ROLE=coordinator and KONTEXT_EPIC. In this layer --setup-file is wired in the adapter but dispatch passes no script yet (feat: the Boat adapter's start script and the coordinator's first turn #56 adds it).
    • A failed dispatch stops whatever sandbox it made, revokes the token, and leaves the run stuck with the reason, so status shows it.
    • The ledger gets a journal entry (an existing kind) when an epic is dispatched and when its sandbox ends: fields.dispatch = start|end, the epic id, the service, the sandbox id and the outcome, from agent:dispatcher. kontext tree shows "in a sandbox since " from it.
  • kontext dispatch status [--json]: per epic its sandbox, since when, progress (tasks closed of total), state (starting, running, resumed, stuck, closed, stopped). Whether the watcher is alive comes with feat: the dispatch watcher closes, resumes and stops sandboxes by the ledger #57.
  • kontext dispatch stop <epic>: boat stop (never delete) and revoke the token.
  • State (src/dispatch/state.rs): machine-local, in <config>/dispatch/<project>/state.json under a file lock.
  • Provider (src/dispatch/provider.rs): one trait per service, Boat its only impl ($KONTEXT_BOAT or boat, run with BOAT_NO_UPDATE=1 and stdin from null).
  • Config (src/config.rs): an optional [dispatch] table in project.toml: max_sandboxes, hours, environment, provider, model, machine, repo_dir, kontext_version, service.
  • Tests (tests/dispatch.rs, tests/fixtures/fake-boat.sh): a fake boat that logs every call, and a local server (server/dev.mjs through Miniflare).

Departures from the brief

  • KONTEXT_EPIC goes with the other -e variables (not secret; the agent can read its epic from it).
  • A stopped state besides the five named: what dispatch stop leaves.
  • --ttl is set to the time limit + 1 h, since Boat's default (1 h) would end the sandbox long before 8 h; the token lives 1 h longer than that.
  • A failed dispatch is left stuck rather than removed, so the owner sees why.
  • KONTEXT_BOAT (the binary) and KONTEXT_DISPATCH_POLL_MS (the wait between checks) exist for the tests.

Test plan

  • cargo fmt --check, cargo clippy --all-targets -- -D warnings and the full cargo test passed at this commit
  • Refusals with exit 2: no server, unsigned plan, unknown epic, epic in a wave that is not ready (one line on stderr, and nothing reached the fake boat); epic that already has a sandbox, cap reached (in the dispatch test). A closed epic's refusal is in the code but no test asserts it
  • The token travels only as a file: no kxt1. in the fake's calls log, the state file or the command's output; the token file is gone after boat new
  • An epic with one open task warns and goes on
  • dispatch stop stops the sandbox and the token is revoked on the server
  • A boat new that fails after making a sandbox: the sandbox is stopped, the token revoked, the run left stuck

🤖 Generated with Claude Code

@OmarAlex24
OmarAlex24 added this pull request to stack #59 November 16, 2026 22:42
`kontext dispatch <epic>` checks that the project syncs through a server,
the plan is signed, the epic is open in a ready wave, it has no sandbox yet
and the cap is not reached (exit 2 with one line otherwise), reserves the
epic under a state lock, makes a coordinator token for it and a sandbox
that gets the token as a 0600 file. Anything that fails after the token
stops the sandbox and revokes the token. `dispatch status` and `dispatch
stop` follow it; `[dispatch]` in project.toml configures it; the state is
machine-local in the config folder; the ledger gets a journal entry at the
start and the end, and `kontext tree` says "in a sandbox since".

Everything Boat-specific is behind the `Provider` trait; the tests use a
fake boat and the local server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@OmarAlex24
OmarAlex24 marked this pull request as ready for review November 17, 2026 14:30
@OmarAlex24
OmarAlex24 merged commit 27b7d92 into main Nov 17, 2026
1 check passed
@OmarAlex24 OmarAlex24 mentioned this pull request Nov 17, 2026
4 tasks done
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