bullswarm 0.28.7 → 0.29.0

package/AGENTS.md

@@ -14,7 +14,9 @@ content. Published as `bullswarm` on npm.
 2. Pace by meter surplus = elapsed% (from provider resets_at) − used%.
    Weekly/monthly windows pace; 5h windows are burst gates only (M1–M5 in
    `src/meters/framework.js`).
-3. Connector quirks live in `connectors/*.json`, never in core logic.
+3. Provider quirks live in the provider's directory (`src/providers/<name>/`,
+   `providers/contrib/<name>/`, or `~/.bullswarm/providers/<name>/`), never in
+   core logic (see `docs/guide/providers.md`).
 4. Quarantine always auto-releases; recursion depth is core-owned via env
    (`BULLSWARM_DEPTH`).
 5. Workflow dispatches must honor the same guarantees as single runs:
@@ -61,7 +63,8 @@ author (`bullswarm workflow plan contract` returns the schema). There is no
 classifier or preview step. The skill is published alongside the package and
 is the canonical reference for the CLI surface.
 
-- Zero runtime dependencies. Node >= 18. Tests must never require network:
+- Zero runtime dependencies. Node >= 22.12 (providers load synchronously
+  through `require` of ES modules). Tests must never require network:
   prime `~/.bullswarm/meters/*.json` caches with fresh timestamps if needed.
 - Every verb must work non-interactively (no TTY). The interactive wizard is
   a human convenience, never a requirement.
@@ -70,14 +73,19 @@ is the canonical reference for the CLI surface.
   `git push --tags`
   — CI publishes through npm trusted publishing (OIDC), no tokens.
 
-## Adding a connector
+## Adding a provider
 
-Copy an existing file in `connectors/`, set: bin name, configDirs for
-discovery, spawn argv template (`{taskFile}` `{cwd}` `{bullswarmDir}`
-substitutions), authSignatures (output strings meaning auth/throttle
-failure), outputExtraction strategy, meter type, costRank, lanes. Add a
-meter reader in `src/meters/` only if the provider exposes a usage API —
-declared meters are the fallback, never the goal.
+A provider is a directory holding `connector.json` (a pool template checked
+against `src/providers/_schema.json`) and/or `provider.mjs`. First-class
+providers live in `src/providers/<name>/`, contrib providers in
+`providers/contrib/<name>/` (enabled per machine through
+`~/.bullswarm/providers.json`), and a user's own in
+`~/.bullswarm/providers/<name>/`. Start from
+`bullswarm provider scaffold <name> [--from <template>]`, then
+`bullswarm provider validate` and `bullswarm provider probe <pool>`. Write a
+`readUsage` export only if the vendor exposes a usage API — declared meters
+are the fallback, never the goal. The contract is `docs/guide/providers.md`;
+the authoring method is `skill/references/providers.md`.
 
 ## Releasing
 

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # bullswarm changelog
 
+## 0.29.0 — steer a running workflow, providers become directories, a declared reset date
+
+- workflow: the plan of a caller-planned program run can be changed at any
+  time. `bullswarm workflow plan export <id>` writes the live plan as an
+  editable revision document, and `bullswarm workflow plan revise <id>
+  --program plan.json` replaces it: the kernel matches actions by id and
+  applies the difference within about a second while agents keep running. A
+  new id is added; an unchanged action keeps its result and its running agent;
+  a changed action is stopped if running and starts over with the new
+  definition; an id in `rerun` discards its result and runs again; a missing id
+  is removed (stopped, never run, reported as `removed` and not counted against
+  the result); and every step downstream of a changed or rerun step runs again.
+  Evidence from a removed or rerun check stops counting until judged again.
+  Revisions carry `baseRevision`, so a revision written against an outdated
+  export is rejected instead of silently undoing another change, and an
+  invalid revision changes nothing. Revising a finished run reopens it and
+  archives the earlier result as `result-before-revision-<n>.json`.
+- workflow: `bullswarm workflow pause <id>` stops new work while running agents
+  finish (`--now` stops them too and requeues their steps). The kernel exits
+  with `outcome: paused`; revisions apply while paused, and `workflow resume`
+  is the only way to continue.
+- workflow: steering a caller-planned program run no longer halts it at the
+  next boundary. Watchers print `steering received`, the export lists the
+  pending messages, and a revision delivers them; only a run about to finish
+  with steering still unread pauses for the caller.
+- watch: new lines for `plan revised`, `plan revision rejected`, pause
+  requested/lifted, run reopened, steering received, and steps stopped by a
+  revision or a pause.
+- skill: SKILL.md gains "Steer a running workflow" and treats every watch
+  wake-up as a point to decide whether the plan still fits; operations.md
+  documents revision semantics, pause and resume, and steering.
+
+- providers: every coding-agent CLI is now a provider directory holding
+  `connector.json`, `provider.mjs`, or both, loaded by one synchronous loader
+  (`src/lib/providers.js`) from three tiers. First-class (`src/providers/`)
+  always loads and holds claude-code, codex, grok and echo. Contrib
+  (`providers/contrib/`) ships in the package but loads only where
+  `~/.bullswarm/providers.json` lists it, and holds command-code and the
+  generic opencode2 connector. Local (`~/.bullswarm/providers/`) is the
+  operator's own and never appears in this repository. A module exports at most
+  `name`, `displayName`, `connectors(ctx)`, `readUsage(pool, ctx)` and
+  `doctor(ctx)`; everything else stays the connector JSON four CLIs already
+  ran through. Echo ships JSON-only and grok keeps its OAuth-refreshing meter
+  as real code, so both paths stay exercised.
+- providers: `bullswarm provider list|enable|disable|validate|scaffold|probe`.
+  `probe` spawns one pool through the dispatcher's own runner with a one-word
+  task and then reads its meter once, which is the only evidence that a new
+  provider's model flag, event parsing and meter all actually work.
+- core: the per-vendor branching is gone. The meter registry resolves a pool's
+  reader through its owning provider instead of a name-prefix map, connector
+  loading is one call into the loader, setup discovery and the strategy labels
+  come from provider entries, and both hard-coded connector expanders are
+  deleted. `credentialGroup` is the honest name for `upstreamGroup`, which is
+  still read.
+- requires Node >= 22.12: the loader reads `provider.mjs` through
+  `require(esm)` so `loadConnectors` and `buildPools` stay synchronous for
+  their twenty-odd call sites.
+- providers: built-in support for one specific reseller was removed entirely.
+  It is expressible as a local provider with no repository changes at all,
+  which was the point of the tiers.
+- setup: `BULLSWARM_NO_PACKAGED_PROVIDERS=1` forces the packaged tiers off, for
+  tests that spawn the real CLI against a fixture home and assert an exact pool
+  list. Never set it in production.
+- workflow: evidence actions are routed like any other action. They used to be
+  steered away from the pools that did the work, which bought little
+  independence (the judging model is chosen by tier, not by pool) and overrode
+  pacing. The `avoidPools` dispatch option is gone.
+- codex: the connector runs `codex exec -s danger-full-access`. Codex sandboxes
+  writes to its workspace, so a workflow evidence action could do the work and
+  still fail with EPERM writing its candidate file into the run's state
+  directory under the bullswarm home.
+- command-code: the connector passes `--max-turns 10000`. command-code's print
+  mode stops after 100 turns by default and exits 8 mid-task, which bullswarm
+  could only report as a non-zero exit and retry from scratch on another pool.
+
+- routing: an upstream auth failure reported inside a provider's event stream
+  is now the `auth` failure kind with a quarantine hint, and it benches every
+  pool that shares the same upstream credential. On 2026-09-11 the pooled Codex
+  OAuth account behind `https://relay.example` was invalidated at 12:24 UTC and
+  answered every request with
+  `{"error":{"message":"Encountered invalidated oauth token for user, failing
+  request","type":"authentication_error","code":"auth_unavailable"}}` (401) or
+  `auth_unavailable: no auth available (providers=codex, model=gpt-5.6-luna; …)`
+  (503); non-GPT models on the same host answered `No available channel for
+  model <name> under group default`. `src/lib/watch.js` turned any stream
+  `error` event into a bare `provider` verdict before the auth gate ran, so no
+  pool was ever benched: a failed action's retry walked
+  `opencode2:relay-3` → `opencode2:relay-2` → `opencode2` — three names for the
+  one dead credential — and runs m4xiva and ytdsii ended `partial` with their
+  integrate/verify actions blocked (failures at 12:24, 12:25, 12:52, 12:53,
+  12:54; last good dispatch 11:22). Four upstream phrases now ship as
+  `DEFAULT_AUTH_SIGNATURES` (`src/lib/auth-signatures.js`), matched only on a
+  stream that already declared a failure and only on an error-shaped line or
+  the raw JSON error event itself, so an agent that merely reads auth code is
+  still never quarantined. Connectors may declare `upstreamGroup`;
+  `src/lib/opencode-relay.js` sets `relay:<host>` on every expanded Relay pool,
+  and an auth quarantine now spreads to that group on one shared 10-minute
+  deadline in both dispatch paths. Claude account pools get no group — separate
+  seats are separate credentials — and a `quota` quarantine never spreads,
+  because a sibling's own window still has work in it.
+
+- cli: `bullswarm update [--check] [--json]` upgrades the installation in
+  place — the verb a teammate reached for and found missing (2026-09-11). It
+  reads the latest version from the npm registry, tells the install shape
+  from the running package's real path rather than from `which` or `npm root
+  -g` (which can name a different Node install), and acts accordingly: a
+  global install gets `npm install -g bullswarm@<latest> --prefix <its own
+  prefix>`; a source checkout, including a global `npm link` into one, gets
+  `git pull --ff-only` and is refused while it has local changes; anything
+  else prints the manual command and exits 1. Success is verified by
+  re-reading package.json on disk, never by npm's exit code, and a shell
+  whose `bullswarm` resolves elsewhere is called out. `--check` compares
+  without changing anything.
+- routing: the reasoning level now reaches every model a Relay pool can run,
+  not only `gpt-5.6-luna`. opencode forwards `--variant <level>` only when its
+  config declares that variant for that exact model, and the config
+  `src/lib/opencode-relay.js` injects declared the five levels for luna alone,
+  so moving a tier onto `<id>/gpt-5.6-sol` (2026-09-12, when luna had no
+  upstream channel left but sol did) would have sent a `--variant medium` that
+  opencode silently dropped while `strategy rungs` kept reporting medium.
+  Discovery now records each provider's model list from opencode.json and the
+  variants are declared on all of them; a provider that lists none keeps the
+  luna default.
+- meters: a Relay pool's used% is read against its own declared plan total
+  (`strategy set-subscription <pool> --included-usd <n>`) before the host-wide
+  `RELAY_PLAN_USD` and the $50 default. The wallets differ — relay-4 is a $20
+  newcomer plan — and one shared number would have shown a $10 spend on it as
+  20% used.
+- meters: a pool whose provider reports usage but no reset date can be paced
+  from a reset the operator declares —
+  `bullswarm strategy set-subscription <pool> --resets-at <iso|unknown>`.
+  The Relay token API stopped returning `expires_at` for the `1` and `Moham`
+  wallets on 2026-09-03 (the fleetlens log holds 28 dated snapshots between
+  2026-08-31 and 2026-09-03, then only nulls), so `opencode2` and
+  `opencode2:relay-3` printed `unmetered` at 73.8% and 10.7% of their $50
+  wallets and ranked as neutral. With a declared reset the used% stays the
+  provider's, elapsed% runs to the declared date, the date rolls forward one
+  calendar month (or week) at a time once it passes, and `bullswarm pools`
+  labels the row `[live declared-reset]`; `pools --json` and
+  `strategy show` carry `resetSource` (`provider` | `declared`). A window
+  the provider does date is never overridden. Doctrine M2 in
+  `src/meters/framework.js` and the guide's rule 2 record the operator path.
+
+## 0.28.8 — a README for visitors and a documentation site
+
+- docs: README rewritten for external visitors landing on the GitHub page —
+  pitch, why it exists, install, quick start, how routing picks a pool, and
+  what a run gives back — with the detailed reference material moved to a
+  GitHub Pages site under `docs/`: `guide/entry-points`, `guide/doctrine`,
+  `guide/getting-started`, `guide/strategy`, `guide/workflows`,
+  `guide/operations`, `guide/dashboard`, `guide/repository-operations`, and
+  `guide/routing`. Terms a newcomer would trip on (pool, lane, kernel,
+  envelope, rung) are defined on first use; the 5-hour gate is documented as
+  clock-relative. The site needs the repository owner to enable Pages
+  (Settings → Pages → deploy from branch `main`, folder `/docs`) before
+  `https://cowcow02.github.io/bullswarm/` serves it; until then the same pages
+  are readable directly under `docs/guide/` in the repository.
+
 ## 0.28.7 — pools about to reset spend their leftover first
 
 - routing: quota that expires sooner is worth more. A pool whose pacing window
@@ -197,7 +355,7 @@
   `elapsedPct`, `pace` and `paceResetsAt` off `reading.windows`, so cache,
   stale and live readings are paced identically; the pool view carries
   `pacingWindow`. The 5h gate is untouched: `command-code` still gates on 5h
-  `25.2%`. Connectors already declared this — `command-code` and the kaihk
+  `25.2%`. Connectors already declared this — `command-code` and the relay
   pools `monthly`, `claude-code`/`codex`/`grok` `weekly`; nothing read it for
   pacing before.
 - The spend model follows the pacing window. `WINDOW_KEYS` (framework.js)
@@ -357,7 +515,7 @@
   no planner has to reason about. No shipped connector's routing changes
   either way — all six declare all three lanes.
 
-- The three KaiHK-backed OpenCode pools can now run gpt-5.6-luna at a
+- The three Relay-backed OpenCode pools can now run gpt-5.6-luna at a
   chosen reasoning level. `connectors/opencode2.json` declares
   `reasoning: { flag: "--variant", levels: [low, medium, high, xhigh,
   max], defaults: { high: high, medium: medium, low: low } }` — the same
@@ -365,25 +523,25 @@
   backend — so rungs for these pools stop printing `— (unsupported)`.
   opencode only forwards a `--variant` its config declares for that
   model, so the flag alone would be silently dropped;
-  `expandOpenCodeKaihkConnectors` (`src/lib/opencode-kaihk.js`) therefore
+  `expandOpenCodeRelayConnectors` (`src/lib/opencode-relay.js`) therefore
   sets `env.OPENCODE_CONFIG_CONTENT` on the base pool and on every clone
   to the variants for that pool's OWN provider id, via the new pure
-  helper `kaihkVariantsConfig(providerId, model = KAIHK_OPENCODE_MODEL)`:
-  `{"provider":{"kaihk-2":{"models":{"gpt-5.6-luna":{"variants":{"low":{"reasoningEffort":"low"},"medium":{"reasoningEffort":"medium"},"high":{"reasoningEffort":"high"},"xhigh":{"reasoningEffort":"xhigh"},"max":{"reasoningEffort":"max"}}}}}}}`.
+  helper `relayVariantsConfig(providerId, model = RELAY_OPENCODE_MODEL)`:
+  `{"provider":{"relay-2":{"models":{"gpt-5.6-luna":{"variants":{"low":{"reasoningEffort":"low"},"medium":{"reasoningEffort":"medium"},"high":{"reasoningEffort":"high"},"xhigh":{"reasoningEffort":"xhigh"},"max":{"reasoningEffort":"max"}}}}}}}`.
   opencode merges that JSON string over the config file, so the API key
   and everything else in `~/.config/opencode/opencode.json` stays in
   force. An `OPENCODE_CONFIG_CONTENT` the operator set by hand in the
   installed connector is never overwritten, on the base pool or on the
-  clones. A medium/max dispatch on `opencode2:kaihk-2` composes
-  `opencode run --auto --model kaihk-2/gpt-5.6-luna <taskFile> --variant
+  clones. A medium/max dispatch on `opencode2:relay-2` composes
+  `opencode run --auto --model relay-2/gpt-5.6-luna <taskFile> --variant
   max --format json`; a level already pinned in the template is replaced,
   not duplicated. Per pool:
-  `bullswarm strategy set-rung opencode2 medium --model kaihk/gpt-5.6-luna --reasoning max`,
-  `bullswarm strategy set-rung opencode2:kaihk-2 medium --model kaihk-2/gpt-5.6-luna --reasoning max`,
-  `bullswarm strategy set-rung opencode2:kaihk-3 medium --model kaihk-3/gpt-5.6-luna --reasoning max`.
+  `bullswarm strategy set-rung opencode2 medium --model relay/gpt-5.6-luna --reasoning max`,
+  `bullswarm strategy set-rung opencode2:relay-2 medium --model relay-2/gpt-5.6-luna --reasoning max`,
+  `bullswarm strategy set-rung opencode2:relay-3 medium --model relay-3/gpt-5.6-luna --reasoning max`.
   Existing installations pick the block up through
   `upgradeConnectorMetadata` (`src/setup.js`), which backfills a missing
-  `reasoning` block and leaves a customised one alone. Non-KaiHK opencode
+  `reasoning` block and leaves a customised one alone. Non-Relay opencode
   installations get no injected variants, so `--variant` is a no-op there
   rather than an error — recorded in the connector's
   `$comment-reasoning`.
@@ -1124,11 +1282,11 @@ behaviour, or pass the program you authored with `--program <file.json>`.
   automatic LLM classification.
 
 - OpenCode connector portability: `connectors/opencode2.json` no longer
-  hardcodes `--model kaihk/gpt-5.6-luna` in `spawn.cmd`. A plain OpenCode
-  install with no KaiHK provider configured now dispatches with OpenCode's
-  own default model instead of failing to resolve a KaiHK-only model.
-  `src/lib/opencode-kaihk.js` still injects the explicit
-  `--model <providerId>/gpt-5.6-luna` for each discovered KaiHK provider, so
+  hardcodes `--model relay/gpt-5.6-luna` in `spawn.cmd`. A plain OpenCode
+  install with no Relay provider configured now dispatches with OpenCode's
+  own default model instead of failing to resolve a Relay-only model.
+  `src/lib/opencode-relay.js` still injects the explicit
+  `--model <providerId>/gpt-5.6-luna` for each discovered Relay provider, so
   the primary `opencode2` pool and any extra `opencode2:<id>` pools keep
   dispatching with their pinned per-provider model exactly as before.
 
@@ -1163,7 +1321,7 @@ behaviour, or pass the program you authored with `--program <file.json>`.
 - Historical workflow design documents now identify themselves as dated
   implementation records and list the current `verify`, `decide`, and
   `outputSchema` surfaces instead of presenting resolved gaps as current.
-- Extra KaiHK providers in `~/.config/opencode/opencode.json` (`kaihk-2`, …)
+- Extra Relay providers in `~/.config/opencode/opencode.json` (`relay-2`, …)
   become `opencode2:<id>` pools, spawned with `--model <id>/gpt-5.6-luna`.
   Spend is read from `GET /api/usage/token` plus
   `/v1/dashboard/billing/usage` (USD = `total_usage / 100`). The HTML wallet
@@ -1288,7 +1446,7 @@ behaviour, or pass the program you authored with `--program <file.json>`.
   spent a 97 s correction turn on it).
 - Goal-4 rerun on `7724da1` (`8ebi8a`, rule 7 + PR #5): 42 min 03 s, three
   planner turns (775 s, 31 %), parallelism 1.34, 23 dispatches (20 on
-  `kaihk/gpt-5.6-luna`), three repair rounds each rejected on re-verify for
+  `relay/gpt-5.6-luna`), three repair rounds each rejected on re-verify for
   reasons the prompts caused, tail of five actions blocked, recovery program
   auto-completed, 315/315, existing tests +179/−1. Goal-4 line:
   44 → 72 → 37 → 25 → 36 → 42 min.
@@ -1324,7 +1482,7 @@ behaviour, or pass the program you authored with `--program <file.json>`.
   re-verify rejected the mandated extension, and a planner turn recovered.
 - Goal-4 rerun on v0.16.0 (`euh622`): 36 min 00 s, four stage phases in the TUI
   (implement, tests, verify, report) instead of sixteen one-action rows, 22/24
-  dispatches on `kaihk/gpt-5.6-luna`, auto-completed, 319/319; two planner
+  dispatches on `relay/gpt-5.6-luna`, auto-completed, 319/319; two planner
   turns because of the false rejection above (planner turn 2: "an append-only
   rule that the goal itself makes unsatisfiable").
 
@@ -1345,7 +1503,7 @@ behaviour, or pass the program you authored with `--program <file.json>`.
   wrote sixteen one-action phases — no scheduling cost (phases never gate;
   `dependsOn` does), but a TUI phase list carrying no information.
 - Goal-4 rerun on this release (`bizp4s`, runtime `9af8fdf`, workers on
-  `kaihk/gpt-5.6-luna`): **25 min 13 s** (attempt 3: 44 min; 0.15.0: 72 min;
+  `relay/gpt-5.6-luna`): **25 min 13 s** (attempt 3: 44 min; 0.15.0: 72 min;
   audited contract alone: 37 min), one planner turn (247 s, 16 % of wall),
   parallelism 1.77, 3 repair rounds each fixing a real defect, 0 schema
   retries, 0 corrections, auto-completed, 319/319, existing tests +174/−0.