open-multi-agent-kit 0.98.4 → 0.98.5

package/docs/sdk.md

@@ -156,6 +156,199 @@ The CLI equivalent is `--model-contract <file>`. This is opt-in dispatch control
 not final-wire or billing attestation. See [Model dispatch contracts](model-contract.md)
 for the JSON shape, events, hook restrictions, and uncovered paths.
 
+### Isolated command runs (SDK, opt-in)
+
+`planVerifiedRun()` and `createRunCoordinator()` provide three experimental profiles:
+`linux-command-v1` executes an approved command, `linux-scripted-agent-v1` drives
+approved steps through the real `AgentSession` and the offline Faux adapter, and
+`linux-command-dag-v1` executes a bounded command DAG serially.
+Commands run in private sandboxes; native EvidenceReceipt v3 cores and a supervisor
+attestation bind the checked candidate before artifact retrieval.
+
+The high-level factory injects the closed session runtime through a host-only port;
+low-level `new RunCoordinator(root)` needs no session port for command execution or
+candidate-only recovery. `inspectRecovery(runId)` is read-only; `resume(command,
+approval)` acquires a new generation and rechecks the exact frozen candidate under
+the original boot-relative deadline. It never restarts the writer or model and
+refuses missing process identity, stale refs, unavailable clocks and expired budget.
+
+`inspectWriterRecovery(runId)` and `restartWriter(command, approval)` separately
+restart an interrupted local writer from its durable input checkpoint. They preserve
+spent requests and the original work deadline, use a fresh private directory, and
+never continue from partial output or a changed original workspace.
+
+For the command DAG, `inspectTaskRecovery(runId)` returns read-only readiness and
+`retryTasks(command, approval)` acquires a new generation for selected failed or
+interrupted tasks. `RunTaskRetryCommand` pins `baseDigest` and `taskIds` alongside the
+contract/revision/generation fields; an empty selection only continues pending work.
+Successful checkpoints are revalidated against their complete ancestor inputs before
+adoption. Final integration verification always uses fresh native receipts. The
+profile supports at most 16 tasks and two preapproved commands per task; it does not
+synthesize a repair or accept overlapping task write scopes. `RunProjection.tasks`
+exposes task attempts and checkpoint digests; a blocked DAG returns `execution: "paused"`.
+All recovery actions share the generation cap, original budget and command-id fence.
+
+This does not enable live-model task generation, opaque remote replay, parallel
+frontier scheduling, plan amendment, or host application. See [Verified Run](verified-run.md) for contracts and trust boundaries.
+
+### Shared run budgets (SDK, opt-in)
+
+Pass `runBudget` to `session.prompt()` to bound one prompt's logical model
+requests. The budget starts before prompt preflight and stays shared across
+provider retries, continuations, and first-party summaries using that session's
+`agent.streamFn` while the prompt is active.
+
+```typescript
+import { RunBudgetExceededError } from "open-multi-agent-kit";
+
+try {
+  await session.prompt("Implement the selected change and run its focused tests", {
+    runBudget: { timeoutMs: 120_000, maxRequests: 12, maxConcurrentRequests: 2 },
+  });
+} catch (error) {
+  if (!(error instanceof RunBudgetExceededError)) throw error;
+  console.log(error.code); // deadline, requests, concurrency, or closed
+}
+console.log(session.getRunBudgetSnapshot());
+```
+
+| Limit | Meaning |
+| --- | --- |
+| `timeoutMs` | One monotonic work deadline, including preflight and retry waiting; at most 2,147,483,647 ms. |
+| `maxRequests` | Total entries into the scoped stream-dispatch boundary. Failed requests also consume this allowance. |
+| `maxConcurrentRequests` | Outstanding logical streams. Returning a stream object does not release its reservation; terminal metadata does. |
+
+Limits must be non-negative safe integers. Zero denies the corresponding
+admission; omitted limits are unbounded. Supply at least one limit. Unknown
+fields, accessors, inherited fields, and malformed values raise
+`RunBudgetPolicyError`. The policy is copied before asynchronous work, so later
+caller mutation cannot enlarge it.
+
+Exhaustion latches, requests cancellation through the existing provider, tool,
+retry, compaction, and branch-summary paths, and rejects with
+`RunBudgetExceededError`. Termination records use `kind: "budget_exhausted"` and
+`causeCode: "budget.deadline"`, `"budget.requests"`, or `"budget.concurrency"`;
+these are not automatic-retry or model-failover instructions. A separate prompt
+cannot borrow or reset an active budget. Preflight ownership also applies when
+the first prompt has no budget, preventing a competing budgeted prompt from
+changing its stream or aborting it. Explicit steering/follow-up messages join the
+running prompt without receiving a new allowance; registered commands retain
+their existing streaming path.
+
+`getRunBudgetSnapshot()` returns the active or most recent budget's immutable
+limits, started-request count, outstanding-stream count, remaining time, closed
+state, and optional exhaustion reason. It returns `undefined` when no budget has
+been used. Missing terminal metadata retains an outstanding reservation; an
+abort request alone does not release it. Outstanding streams block admission of
+a new bounded or unbounded prompt even after the scope closes. Once terminal
+metadata arrives, that reservation drains and new work can proceed. The original
+stream and core credential resolver are restored unless another owner replaced
+them. Captured old wrappers reject further dispatch after closure.
+
+The core credential resolver and compaction-auth preflight now check admission
+before consulting credentials. This is a pre-check, not a reservation: logical
+request counts are still reserved at stream dispatch. Cancellation or expiry
+during credential lookup is checked again before continuing.
+
+**Limits of this slice:** request counts are not HTTP-attempt or billing counts.
+The wrapper requests `maxRetries: 0` to disable adapter retries, but cannot attest
+that every provider honors it. Independent context/auth hooks, remote work, detached
+children, direct `omk-ai` calls, and replacement of the stream wrapper remain
+outside that dispatch-count guarantee. In-process plugins are trusted. Deadline
+cancellation is cooperative: synchronous blocking code, an uncooperative hook,
+or a remote service can outlive the signal. This is not an OS kill/join boundary
+or a guaranteed wall-clock return time. There is no financial/output-token cap,
+verification/cleanup reserve, persisted budget recovery, CLI flag, or global
+setting in this slice. Restart does not reconstruct an in-flight budget.
+
+Regression tests: `test/run-budget.test.ts`, `test/run-budget-scope.test.ts`,
+`test/suite/agent-session-run-budget.test.ts`, and
+`test/suite/agent-session-admission.test.ts`.
+
+### Prompt settlement
+
+**Working-tree hardening:** a timeout/abort result is not proof that the tool stopped.
+
+| Signal | Meaning |
+| --- | --- |
+| `tool_execution_end` | A result was committed; a timeout/abort can win before the tool stops. |
+| `session_termination` | One agent-loop attempt ended; retries may follow. |
+| `prompt()` resolves | The outer loop returned. A timed-out or aborted tool may remain active. |
+| `prompt_settled` | The prompt producer closed, registered local tool promises ended, and streaming/queues no longer block settlement. |
+
+The session retains a per-prompt owner across retries and continuations. Tools
+selected through its registry receive unique runtime tokens, independent of
+model tool-call IDs. Actual promise completion removes only its own token;
+duplicate flushes and an earlier run's finish callback cannot settle another run.
+
+After timeout or cancellation, the session withholds `prompt_settled` and its
+resource-lease release while registered tool promises remain active. Another
+ordinary prompt is rejected before model dispatch. Clearing a leftover queue
+rechecks settlement, so a drained run can release its owner and accept new work.
+Default late-settlement handling triggers a fresh settlement check after the workspace-mutation audit.
+With explicit `lateSettlement: "ignore"`, actual completion triggers that check
+without inventing an audit. Durations and the core tool-timeout teardown window
+use a monotonic clock; wall-clock adjustments cannot extend or shorten that window.
+
+User cancellation during tool execution remains an abort even when the last
+assistant message says `toolUse`. Timeout text reports cancellation requested,
+not process termination confirmed. Late success never replaces the failed or
+aborted result. **`prompt_settled` is a UX signal, not semantic verification.**
+
+This safeguard is session-local. It does not persist ownership, join detached
+work, prove remote cancellation, or fence writers across replacement/disposal,
+restart, or workspace reuse. Direct `Agent` calls, replacing
+`session.agent.state.tools`, independent interactive bash, and plugin-created
+background work are not automatically enrolled. In-process plugins remain trusted.
+
+#### Independent bash commands
+
+`executeBash()` owns one cancellation controller per invocation, including permit
+waiting. Concurrent commands never share or overwrite that controller. Completion
+removes only its own entry, so `isBashRunning` remains true while another command
+is active. `abortBash()` signals every owned command and does not declare them
+terminated. Cancellation observed after permit admission prevents backend dispatch.
+
+These commands remain independent of prompt settlement and its model-request
+budget. Backend promises still own actual termination; detached processes and
+remote completion are not inferred from cancellation. Regression:
+`test/suite/agent-session-bash-ownership.test.ts`.
+
+#### Shared permits and internal lanes
+
+`WorkloadPermitPool` captures request identity, weight, and signal before waiting;
+caller mutation cannot alter a later release. Per-permit release latches replace
+the unbounded retired-ID set. Removing a cancelled/expired FIFO head immediately
+reconsiders the next request. Explicit pool `capacity: 0` denies grants and
+`maxQueue: 0` denies waiting; lowering capacity never revokes held permits.
+
+Internal `launchSubagentLanes()` preserves computed zero width as
+`admission-deferred`, observes run-specific heavy caps, defers marked heavy lanes
+under `defer-heavy`, and rechecks abort after acquiring a permit. It forwards the
+parent signal and awaits the callback before release. Parent cancellation reports
+`cancelled`; failures use a fixed diagnostic rather than arbitrary child error
+text. The existing configured lane setting `0 = unlimited` remains distinct from
+computed admission zero. `heavyLaneIds` is a trusted caller classification.
+This does not activate a live task DAG or a detached-process join adapter.
+
+Regression checks from the repository root:
+
+```bash
+LIVE_E2E=0 node node_modules/vitest/dist/cli.js --run \
+  packages/coding-agent/test/session-prompt-lifecycle.test.ts \
+  packages/coding-agent/test/suite/agent-session-owned-settlement.test.ts \
+  packages/coding-agent/test/suite/agent-session-child-settlement.test.ts \
+  packages/coding-agent/test/workload-permit-pool-admission.test.ts \
+  packages/coding-agent/test/subagent-lane-ownership.test.ts
+npm run check
+```
+
+The child test observes a local Node process closing before settlement and lease
+restoration. These are not paid-provider, crash-recovery, or coding-quality benchmarks.
+Shared logical request budgets are available through the opt-in SDK path above.
+Verification/cleanup reserves, protected candidate/verifier binding, effect recovery,
+and approval-bound application remain prerequisites for a durable verified run.
+
 ### AgentSession policy seams
 
 The package root exports focused policy helpers for custom runtimes and tests:

package/docs/usage.md

@@ -46,6 +46,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |
 | `/resource [probe\|policy]` | Show resource pressure and effective concurrency for this run |
+| `/debug [save]` | Preview runtime diagnostics; explicitly save a metadata-only local report |
 | `/goal [objective]` | Show or set the durable goal for the current working directory |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
@@ -61,6 +62,59 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/star` | Open the OMK GitHub repository |
 | `/quit` | Quit omk |
 
+### Diagnostics and failure details
+
+`/debug` previews runtime identity, terminal state and the latest typed outcome
+without saving or contacting a provider. The existing TUI debug shortcut opens
+the same preview instead of dumping the transcript.
+
+`/debug save` explicitly creates a new `omk-debug-*/diagnostics.json` under the OS
+temporary directory and prints its path. It does not upload or overwrite a report.
+POSIX directory/file permissions are `0700`/`0600`; Windows access follows the
+temporary directory's ACLs. Delete that directory when it is no longer needed.
+
+The version-1 JSON report contains approved metadata fields only. It excludes
+messages, prompts, images, tool output, rendered screen text, raw errors,
+configuration, environment values, credentials, local paths, session/run IDs and
+provider/model/tool names. Launch and UI module paths are visible locally, not
+saved. Metadata such as timestamps and message counts can still describe your
+workload; review a report before sharing it.
+
+There is no raw-transcript option in this command. Old `omk-debug.log` files are
+not deleted or rewritten and may contain private transcripts. Explicit raw ANSI
+capture via `OMK_TUI_WRITE_LOG` remains a separate, sensitive debugging facility;
+see [TUI components](tui.md#debug-logging).
+
+**Runtime identity:** The UI entry file's SHA-256 is observed at module initialization
+and compared with the same file during inspection. Missing, oversized, virtual or
+unreadable files are `unavailable`, not healthy. This is a single-file observation,
+not a fingerprint of all dependencies or proof of the exact executed bytes.
+An unchanged entry does not establish that a build includes current source changes.
+The package has no embedded build-to-commit binding, so build revision is reported
+as unavailable rather than inferred from checkout `HEAD`.
+
+`/reload` refreshes resources, not core JavaScript modules. Its last completion time
+is shown separately. Core changes need an authorized build where applicable and a
+restarted process. Source-mode QA does not update an installed launcher.
+
+**Failure cards:** Cause, impact and next action appear before technical fields.
+Ctrl+O (or the configured `app.tools.expand` binding) expands kind/phase/cause code,
+observation source, retry flags, run ID, timestamp and route. Credential-shaped
+values are masked even when input redaction is disabled; terminal controls are
+removed. These local details are not the saved report.
+
+Cards never retry, repair or approve effects. Retryability and automatic-retry
+safety stay separate; possible/confirmed side effects require inspection before
+repeating work. Duplicate delivery of the same termination is coalesced; separate
+failed attempts remain visible. Completed runs stay quiet, and compaction
+cancellation retains its concise status. Journal, print, JSON and RPC termination
+contracts are unchanged.
+
+Focused regression tests: `test/interactive-mode-diagnostics.test.ts` and
+`test/tui-diagnostics.test.ts` in `packages/coding-agent`. These cover the real
+command adapter, sensitive-field exclusion, private report creation, runtime file
+changes/unavailability, forced masking, narrow-terminal wrapping and theme changes.
+
 ### Durable Goals
 
 Use `/goal <objective>` to create or update the durable goal for the current working directory; `/goal` without arguments shows its status. See [Run Protocol](run-protocol.md#durable-goal-lifecycle) for the authoritative persistence, round-limit, continuation, and SDK lifecycle rules.