@sorenllm/opencode-forge 0.3.2 → 0.3.4

package/README.md

@@ -114,8 +114,8 @@ and the plugin's command of that name is not registered.
    (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
    files are yours; delete them yourself if you want.
 5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
-   job registry ledger, and the watchdog ledger — the file ledger table
-   above lists everything).
+   job registry ledger, the watchdog ledger, and the dispatch ledger — the
+   file ledger table above lists everything).
 
 ## File ledger
 
@@ -130,6 +130,8 @@ What this plugin touches, exhaustively:
 | `<tmp>/opencode-forge/jobs/ledger.jsonl` | job registry ledger (bounded: 1 MB reset, 200 entries) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/registry.json` | persistent survivor registry (bounded: 100 entries) | runtime debris — after uninstall, kill any still-running `survive` jobs yourself first |
 | `<tmp>/opencode-forge/watchdog/log.jsonl` | watchdog interventions ledger (bounded: 200 entries, oldest rotated) | runtime debris — delete freely, also after uninstall |
+| `<tmp>/opencode-forge/dispatch/ledger.jsonl` | dispatch ledger: resolved identity/depth, outcomes, tokens/cost, timeouts, transport interruptions, lost-on-exit, crew summaries (bounded, capped rotation) | runtime debris — delete freely, also after uninstall |
+| `<project>/.opencode/forge.json`, `~/.config/opencode/forge.json` | your dispatch agent definitions (JSONC). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, keep the global one out of sync tools if it holds machine-specific models |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
@@ -317,6 +319,156 @@ These are runtime debris, not data — with ONE caveat: **if you uninstall with
 /F /T`, or just reboot); deleting the directory afterwards is safe and
 complete.
 
+## Worker dispatch (scoped subagents on a chosen model + depth)
+
+`forge_dispatch {prompt, agent, depth}` spawns a child session that runs one
+scoped task on the agent's pinned model at the requested reasoning depth. The
+result is an honest report: the actual model/depth used, real token counts, a
+self-computed cost (`null` when the model is unpriced), the
+`depthTranslation` disclosure (`canonical high → native XHigh`, or
+`verbatim`), and the worker's concluding report.
+
+### forge.json — the dispatch configuration
+
+Agents live in a dedicated `forge.json` (JSONC — comments allowed), resolved
+by a three-level cascade with a single winning source (never merged):
+
+1. `<project>/.opencode/forge.json` — project-level, versionable, team-shared
+2. `~/.config/opencode/forge.json` — global
+3. the built-in seed — `research {depths: [low, medium]}` and
+   `review {depths: [medium, high, max]}`, both pinned to the placeholder
+   `Local/GPT Luna` (an identity that never resolves: an unconfigured install
+   fails every dispatch with the configuration recipe below)
+
+```jsonc
+{
+  // forge dispatch agents — save the file; changes apply on the next dispatch, no restart
+  "agents": {
+    "research": {
+      "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string
+      "depths": ["low", "medium"], // first entry is the default
+      // "prompt": "optional role prompt riding inside the discipline wrapper",
+      // "shape": "write", // default readonly denies mutating tools
+      // "permission": { "bash": "deny" } // optional override; "task" is always denied
+    }
+  }
+}
+```
+
+- **The plugin only ever reads this file.** It never creates, writes, or
+  migrates it. Unconfigured? The first `forge_dispatch` error carries a
+  machine-actionable recipe (detected identities, both file paths, the
+  template, a verify dispatch) — or just ask your session AI to configure
+  dispatch; `forge_dispatch_config` shows the exact live state.
+- **Hot-apply**: the file is re-read (mtime-cached) before every dispatch and
+  on every `forge_dispatch_config` call — edits take effect on the next
+  dispatch, no host restart. One boundary: newly added agents materialize
+  their hidden `forge-<agent>` entry only on the next config reload; the
+  dispatch itself still works (the body names the agent), but a brand-new
+  agent's first dispatch may need a host reload if the host validates agent
+  names on session create.
+- Each agent materializes as a hidden `mode: subagent` agent `forge-<agent>`
+  carrying the role prompt (explicit `prompt` > built-in research/review
+  defaults > generic worker) and a deny-style permission: `shape: "readonly"`
+  (the default) denies `write`/`edit`/`bash`, `shape: "write"` allows them,
+  an explicit `permission` map overrides the shape default — and `task` is
+  ALWAYS denied (recursive dispatch stays physically impossible). Agents
+  never carry a `model` field; the brain is bound per dispatch.
+
+### The depth metalanguage
+
+`depth` comes from the canonical five-word set `none | low | medium | high |
+max`, or the model's **native level names verbatim** (escape hatch — e.g.
+Qwen's `XHigh`). Translation to the provider's native parameter follows three
+hard rules:
+
+- **verbatim-first**: a meta word the model natively offers passes as-is
+- **no interpolation**: a meta word with no counterpart errors listing both
+  vocabularies — never a nearest guess
+- **full disclosure**: the report always shows `canonical → native`
+
+Per family: effort-style providers (OpenAI-compatible) receive
+`reasoningEffort = <word>`; budget-style (Anthropic-style) receive a
+published thinking tier — `low → 8192`, `medium → 16384`, `high → 24576`,
+`max → 32768` budget tokens, `none → thinking off`; toggle-style (zai/GLM)
+receive thinking on/off (that shape has no level slot — disclosed honestly).
+A provider whose option shape the plugin does not know gets nothing injected,
+disclosed as `not injected (unknown provider shape)`. The provider is the
+final judge of every depth word: its raw errors flow back unedited.
+
+### Legacy inline roster (advanced)
+
+The pre-forge.json inline form still works when configured (the plugin
+options `dispatch.roster` / `dispatch.tiers`): tier ids it defines keep their
+exact-match resolution, one-retry-excluding-a-failed-identity semantics, and
+startup dead-key warnings. Legacy tier ids win over forge.json agents of the
+same name while inline options exist. Zero-config auto-generation of roster
+entries was removed (configured ≠ usable) — dispatch without configuration is
+the seed + recipe path above.
+
+### Background dispatch and wake briefs
+
+`forge_dispatch` takes `background: true`: it returns
+`{dispatchId, agent, requested, resolved, depth, queuedAt}` immediately and
+the full result arrives later as a coalesced `[forge:dispatch-complete]`
+brief — debounced, never interrupting an active turn (delivery waits for an
+idle), each terminal delivered exactly once, and merged into a single
+combined re-prompt when a goal continuation fires on the same idle.
+`forge_dispatch_list` recovers in-flight and recent terminal state (with
+dispatchIds) after context compaction; `forge_dispatch_kill {dispatchId}`
+stops polling, suppresses the brief, and ledgers `killed`. On host exit,
+in-flight dispatches are ledgered `lost-on-exit` — sessions are host memory
+objects, there are no orphan processes and no survive semantics.
+
+**Transport-interruption recovery**: the child's prompt is delivered by a
+turn-synchronous HTTP POST that stays open for the whole first turn. If that
+POST dies at the transport layer (fetch abort / network failure — anything
+that is not an HTTP error response), the dispatch does **not** fail: the
+engine ledgers `transport-interrupted` (with the child sessionID) and falls
+back to completion polling under the same deadline — the child session is a
+host-side object and usually keeps running, so its result is still collected
+and delivered normally. The message is never re-POSTed (the prompt may
+already be delivering); a message that never arrived polls as waiting and
+ends in the honest deadline `timeout`. Terminal reports and terminal ledger
+rows carry the child sessionID, dispatchId, parentSessionID, and durationMs.
+
+### Crew workflow (`/crew`)
+
+`/crew <objective>` registers a crew: decompose the objective into
+evidence-checked subtasks, dispatch them as background waves paced on
+completion briefs (**never past the concurrency cap — launch the next batch
+only as briefs free capacity**), at most ONE retry per failed subtask, then
+`crew_close` with the full report. The close is a hard gate: every subtask
+needs a PASS/FAIL verdict with evidence, a FAIL needs both failure reports,
+and the report is cross-checked against the dispatch ledger — a dispatched
+subtask missing from the report refuses the close (refusals never bother you
+with a dialog). A valid close asks once, appends a crew summary to the
+ledger, and ends the crew. Crew state is in-memory by design: a host restart
+ends it honestly and the ledger keeps the history.
+
+### Known pitfalls
+
+- **Keyless endpoints × readonly agents**: free/keyless providers can return
+  a deterministic EMPTY response for any toolset-reduced (readonly) agent —
+  0 tokens, no parts. The plugin detects this and fails the dispatch honestly
+  (`empty-response`, never counted as success); use a `shape: "write"` agent
+  or a keyed provider for readonly work on such endpoints.
+- **`opencode run` and background**: a finished run-mode session cannot be
+  re-prompted, so completion briefs have nowhere to land — completions are
+  ledger-only (read them via `forge_dispatch_list`). Background mode targets
+  live TUI sessions; prefer sync under `opencode run`.
+- **Host tool ceiling (~262s observed on 1.18.32)**: the host may kill a
+  sync tool call that exceeds roughly 262 seconds even though the plugin's
+  own deadline is higher. A same-family transport abort (~281s observed,
+  2026-09-27 incident) can also kill the background dispatch's turn POST.
+  Transport-interruption recovery (above) absorbs both: the dispatch falls
+  back to polling and still delivers the child's result; keep `timeoutMs`
+  modest anyway for sync-heavy workflows.
+- **Child permission asks**: a worker that hits a permission ask surfaces the
+  ask on the CHILD's session in the TUI. An unanswered ask stalls the child
+  until the dispatch deadline — scope worker prompts to avoid permission
+  boundaries (readonly tiers and workspace-relative paths help).
+
 ## Hang watchdog (a stuck builtin shell unblocks itself)
 
 `forge_shell` is structurally immune to the stdio-EOF hang, but the builtin