@excitedjs/agent-runtime-claude-code 0.7.0-alpha.gea3dc096ae44 → 0.7.0-beta.214

package/README.md

@@ -7,68 +7,116 @@ The built-in **Claude Code** Agent Runtime provider for
 It implements the public `AgentRuntimeProvider` contract from
 [`@excitedjs/dreamux-types`](../../dreamux-types) against a resident `claude`
 stream-json child: process supervision, the stream-json wire protocol (line
-framing, turn aggregation, control-request replies), per-turn idle-deadline
-handling, MCP config translation (`--mcp-config`), teammate completion delivery
+framing, result aggregation, control-request replies), pending-request idle
+deadlines, MCP config translation (`--mcp-config`), teammate completion delivery
 as a plain user turn, bounded native transcript pagination, and Claude Code
 doctor diagnostics.
 
 ## Boundary
 
-This package depends on `@excitedjs/dreamux-types` **only**. It never imports
+This package uses `@excitedjs/dreamux-types` and shared `@excitedjs/dreamux-utils`.
+It never imports
 `@excitedjs/dreamux` core. Everything host-specific — per-dispatcher paths, the
 durable state sink, the process `PATH` seeded from the host package bins — is
 supplied by the Dreamux host through the neutral `AgentRuntimeCreateContext` and
 the provider factory options. The package owns only Claude Code engine mechanics
 and its own runtime config parsing; it reconstructs no Dreamux host
-layout/path/log contracts. Generic OS/validation/turn helpers it needs are
-vendored under `src/internal/`.
+layout/path/log contracts. Shared process supervision and state-write fencing
+come from `@excitedjs/dreamux-utils`.
 
 ## Loading
 
-Dreamux core resolves `builtin:claude-code` to this package and constructs the
-provider through its own core-owned adapter, which maps core's host-shaped create
-context onto the neutral one and supplies the host contracts. The package also
-default-exports a generic provider-loader factory, so
+Dreamux core resolves `builtin:claude-code` through the generic provider loader
+and supplies host contracts through the neutral create context. The package
+default-exports that provider factory, so
 `loadExternalAgentRuntimeProviders({ refs: ['builtin:claude-code'] })` can load it
 through the same package-loader path as external `npm:` providers.
 
-## Turn lifecycle
+## Resident session and request settlement
 
 The public runtime boundary returns one `RuntimeSubmission` handle per accepted
-send, settled by an immutable provider-owned `RuntimeCompletion` created at each
-real native result boundary. Inputs merged before session creation and supported
-live steering settle with the same completion object; queued sends settle with
-distinct completions in native order. Command UUIDs are private wire aliases;
-when `msg_lifecycle_v1` is available, all aliases must reach a terminal command
-state and a final result must be captured before the object settles. Live steer
-fails loudly without that capability. Runtime stop fences queued session work,
-terminates the supervised process group with absence proof, and resolves every
-unsettled public object as stopped.
-
-Source deduplication is provider-private. A source is reserved while its native
-admission is in flight, committed only after acceptance or an ambiguous
-post-write failure, and released after a proven pre-write failure. Concurrent
-uses of the same reserved source share the same admission outcome. Accordingly,
-`failed` means the command was proven not written, while `ambiguous` means a
-native write may have been accepted and must not be retried automatically.
-Runtime stop synchronously fences new input, releases pending capability/write
-waiters, and drains all already-started admission calls before it resolves.
+send. Every input follows the same native write path; admission resolves after
+write acknowledgement or positive native evidence. RPC holds one table of
+unanswered requests and settles them directly from native results or command
+cancellation/refusal. There is no enclosing request window or aggregate drainage.
+
+A native result answering requests creates one immutable `RuntimeCompletion`
+shared by those requests. Folded inputs share that object; queued inputs wait
+for their own result. Consumption lifecycle and a matching submitted result UUID
+are positive attribution evidence. A completed lifecycle frame may precede or
+follow its result and does not decide when another input can be submitted.
+
+Background native turns may run without a submission. Their activity and result
+boundaries remain observable, but they settle no unrelated request and do not
+terminate the resident process. Explicit inputs steered into a background turn
+settle normally once they join it. Concurrent input requires lifecycle evidence;
+sessions without it retain single-input compatibility. Native `cancelled` can
+describe a hard failure; it does not imply a user stop. Consumed commands retain
+their result membership through terminal lifecycle frames. An unconsumed command
+that is cancelled, refused or discarded settles as failed. Every native error
+result remains observable, including UUID-less errors and the `success` arm with
+`is_error: true` carrying API error text.
+
+A setup error can precede `started` and omit the input UUID. It reports a failed
+native end with its error details but cannot identify a queued request. A later
+named `cancelled` fails that request with its protocol state; the adapter does not
+guess that a preceding unbound error belongs to it.
+
+Core owns source deduplication, captured recipients and completion-token delivery.
+The provider owns native admission: `failed` means the command was proven not
+written, while `ambiguous` means a native write may have been accepted and must
+not be retried automatically. Runtime stop synchronously fences new input,
+releases pending capability/write waiters, terminates the supervised process
+group with absence proof, resolves unsettled submissions as stopped, and drains
+already-started admission calls before it resolves.
 
 ## Native sessions and transcripts
 
-For a fresh runtime this package generates the native UUID before launch,
-passes it through Claude Code's `--session-id`, and deterministically derives
-the native transcript under
-`<CLAUDE_CONFIG_DIR-or-~/.claude>/projects/<project>/<session-id>.jsonl`.
-The validated canonical path is persisted with the checkpoint before admission
-can be reported. Resume keeps the authoritative native session id and can
-rediscover a moved transcript across Claude Code project directories. No
-SessionStart Hook, callback process, placeholder file, or auxiliary IPC bridge
-is used to discover `transcript_path`.
-
-`readTranscript` is a cold bounded read that never starts a Claude process. It
-applies native rewrite lineage, returns completed provider-neutral
-message/tool blocks in chronological order, and owns opaque cursors, query and
-rewrite mismatch detection, payload redaction/truncation, and the fixed host
-output budget. Native command/session IDs and filesystem paths never appear in
-transcript pages.
+For a fresh runtime this package generates the native UUID before launch and
+passes it through Claude Code's `--session-id`. The native identity is durably
+published before input is written. Resume uses that same authoritative session
+id. Recent activity reads locate Claude's native history independently of the
+live process; transcript discovery never controls request settlement.
+
+`readRecentActivity` is a cold bounded read that never starts a Claude process.
+It returns neutral assistant/tool activity records and provider-owned opaque
+cursors. It is not a completion source.
+
+## Custom session factories
+
+A custom `ClaudeCodeSessionFactory` now implements `submit()` returning
+`RuntimeAdmission`; accepted submissions carry their own settlement promises.
+The old `submitTurn()`/`steerTurn()` window interface is removed. Session specs
+provide the pinned `sessionId` and optional `outputSchemaEnabled` result contract;
+the exit handler receives its failure cause.
+
+Session implementations own result validation and settlement. Their
+`onProtocolEvent` callback reports native activity independently: result events
+retain `commandUuids` for observation, and the public `command_lifecycle` variant
+reports native command state without deciding settlement in runtime or Core.
+An `interrupted` event can report an independently known interruption boundary.
+Emitting a callback alone no longer settles a
+request. These are breaking changes to the Claude-specific extension seam;
+the neutral `AgentRuntime` and `RuntimeSubmission` contracts are unchanged.
+
+## Direct stream RPC consumers
+
+The exported `ClaudeCodeStreamRpc` has the same single `submit()` path, returning
+`Promise<RuntimeAdmission>` in place of `submitTurn()` and `steerTurn()`. Accepted
+handles own eventual settlement; callers no longer await an aggregate window.
+Replace `failPending(error)` with `fail(error)` for transport failure or `stop()`
+for deliberate teardown. A session retired after an unexpected exit retains
+that failure for subsequent admission, even after cleanup calls `stop()`.
+
+`ClaudeCodeStreamRpcOptions` now requires `sessionId` (a pinned native ID or
+`null`) and accepts optional `outputSchemaEnabled` for result validation.
+`reapOnTimeout(error)` receives the failure `Error`. Protocol callbacks are
+observation only, as described above. Parsed `ResultEnvelope` and `TurnOutcome`
+also expose `terminalReason`, a string or `null`, for native terminal diagnostics.
+These changes break direct RPC consumers as well as custom session factories.
+
+The default adapter uses consumption events because the observed background
+folds omit both result UUID echo fields. Claude Code 2.1.263 marks
+`command_lifecycle` as internal; it is not a documented stable SDK contract.
+Compatibility tests and real native captures are distinguished in the task's
+verification record.

package/dist/config.d.ts

@@ -28,8 +28,8 @@
  * is reset on every inbound stream line, so it bounds the max time the
  * still-alive child may emit *no* stream activity — not the total turn duration.
  * A child silent for the whole window is failed and reaped/re-spawned (rather
- * than wedging the serial turn queue and, behind it, TeamMate completion
- * delivery), while a long but actively-streaming turn never trips it.
+ * than blocking request settlement and TeamMate completion delivery), while a
+ * long but actively-streaming turn never trips it.
  */
 export interface DispatcherClaudeCodeConfig {
     bin: string;

package/dist/rpc.d.ts

@@ -1,125 +1,51 @@
-/**
- * Claude Code stream-json turn RPC.
- *
- * The supervisor owns the child process. This class owns one in-flight command
- * group, stdout line demux, command drainage, and defensive control replies.
- *
- * One resident CLI execution window can span several submitted commands: a
- * live steer is written while the CLI is already running. How the CLI answers them is
- * not fixed, which is what makes settlement subtle (probed against a live
- * 2.1.231 resident session):
- *
- *  - **Commands fold.** A message that arrives while the in-flight turn is
- *    inside a tool call is absorbed into that turn at the next query-loop
- *    boundary. Several commands then share ONE `result` (3 → 1 observed), and
- *    a folded command's uuid never appears on any `result`.
- *  - **Or they do not.** A command that arrives between turns runs on its own
- *    and gets its own `result`.
- *  - **`result.user_message_uuid` is not a completion ledger.** It is present
- *    only sometimes and is not reliably the first-submitted uuid of a fold. It
- *    is present on the artifact an accepted interrupt produces (measured
- *    against claude 2.1.263), so presence does not mean "this is an answer".
- *  - **`command_lifecycle` is the attribution signal.** Started commands identify
- *    the submissions represented by the next native `result`; terminal states
- *    drain the resident execution window. Its ordering against `result` is not
- *    stable.
- *
- * Every valid `result` is forwarded immediately as its own native completion
- * boundary. Lifecycle terminality only decides when the command group has
- * drained and the resident session may accept a new initial command; it never
- * aggregates several results into one completion.
- */
+/** Resident Claude input admission, request settlement and native stream handling. */
 import type { Writable } from 'node:stream';
 import type { TurnSubmitOptions } from './types.js';
-/** Provider-private admission classification; never crosses the neutral API. */
-export declare class ClaudeSteerAdmissionError extends Error {
-    readonly admission: 'failed' | 'ambiguous';
-    constructor(admission: 'failed' | 'ambiguous', message: string, options?: ErrorOptions);
-}
+import type { RuntimeAdmission } from '@excitedjs/dreamux-types';
 export interface ClaudeCodeStreamRpcOptions {
+    sessionId: string | null;
+    outputSchemaEnabled?: boolean;
     turnTimeoutMs: number;
     log?: (level: 'info' | 'warn' | 'error', msg: string, err?: unknown) => void;
-    reapOnTimeout: () => void;
+    reapOnTimeout: (error: Error) => void;
     onRemoteControlUrl?: (url: string) => void;
     onProtocolEvent?: import('./types.js').ClaudeCodeSessionSpec['onProtocolEvent'];
 }
+/**
+ * One resident transport, one association from UUID to unanswered request.
+ * Native results consume requests directly; no aggregate execution window waits
+ * for terminal lifecycle frames. The consumed set also includes native internal
+ * commands so cancellation is scoped to work that actually entered a turn.
+ */
 export declare class ClaudeCodeStreamRpc {
     private readonly stdin;
     private readonly options;
     private readonly lineBuf;
-    private pending;
+    private readonly aggregator;
+    private readonly requests;
+    private readonly consumed;
     private lifecycleSupported;
-    private readonly control;
+    private timer;
+    private closed;
+    private remoteControlRequestId;
     constructor(stdin: Writable, options: ClaudeCodeStreamRpcOptions);
-    submitTurn(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<void>;
-    steerTurn(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<void>;
-    private writeSteer;
+    submit(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<RuntimeAdmission>;
+    private acceptRequest;
+    private failWrite;
     onStdoutChunk(chunk: string): void;
-    failPending(err: Error): void;
-    interruptTurn(reason: string): Promise<boolean>;
+    /** Actual transport loss fails each outstanding request, without a completion. */
+    fail(error: Error): void;
+    /** Explicit teardown stops requests and converges unconfirmed admissions. */
+    stop(): void;
+    private close;
     enableRemoteControl(): void;
-    /**
-     * Detach the in-flight turn: clear its deadline timer and null `pending`,
-     * returning it so the caller can resolve or reject it exactly once.
-     */
-    private settlePending;
-    /**
-     * End the execution window on the artifact of an accepted interrupt. This is
-     * the only settlement an interrupt has, deliberately: a lifecycle
-     * `cancelled` for the same command arrives *after* the artifact and is then
-     * a no-op, so no path can settle the turn early and leave the artifact to
-     * arrive against an empty `pending` — which the `result` case reads as an
-     * unattributable envelope and answers by reaping the resident child.
-     */
-    private settleInterrupted;
-    /**
-     * Mark a submitted command as producing nothing further, then re-check
-     * settlement. `abnormalReason` is `null` for the normal ending (`completed`)
-     * and a short phrase for a command that never ran — those are logged,
-     * because the CLI gives no other trace of a command it declined.
-     *
-     * A command ending abnormally never fails the turn by itself: the probe
-     * shows a `cancelled` command coexisting with another that answers normally
-     * (that is exactly what an interrupt looks like), so
-     * rejecting on `cancelled` — as the pre-#342 code did — is wrong.
-     */
-    private markCommandTerminal;
-    /**
-     * The drainage gate: every submitted command has reached a terminal
-     * lifecycle state AND at least one valid `result` has been seen. Result
-     * identity and settlement have already been forwarded one-by-one.
-     *
-     * Two escapes, both anti-hang:
-     *
-     *  - no lifecycle signal at all (`msg_lifecycle_v1` absent, so no
-     *    `command_lifecycle` will ever arrive) — the `result` is then the only
-     *    terminal event there is, so settle on it;
-     *  - every command terminal, none of them ever ran, and no result — nothing
-     *    can answer this turn, so fail it loudly. The idle deadline is not an
-     *    acceptable backstop here: it reaps the resident child, and any inbound
-     *    line re-arms it, so a healthy session could be killed long after the
-     *    turn became unanswerable.
-     *
-     * When a command *did* run but no result has arrived yet, this waits: the
-     * probe shows terminal lifecycle states arriving both before and after the
-     * result they belong to, so "terminal, therefore no result is coming" is not
-     * a sound inference.
-     */
-    private settleIfReady;
-    /**
-     * (Re)arm the per-turn idle deadline. `turnTimeoutMs` is a *max-idle* window,
-     * not a total-turn cap: any inbound stream line for this turn pushes it out
-     * (see `onLine`). A genuinely wedged child (no stream activity for the whole
-     * window) is still reaped — preserving the #120 anti-hang intent — but a long
-     * but continuously-streaming turn never trips the deadline (#156).
-     */
+    private clearIdleIfEmpty;
+    /** Outstanding work has a max-idle deadline; pure background work has none. */
     private armIdleTimer;
     private onLine;
     private decideLifecycleSupport;
-    private flushCapabilityWaiters;
-    private rejectCapabilityWaiters;
-    private resolveWriteWaiter;
-    private rejectWriteWaiter;
-    private rejectWriteWaiters;
+    private rejectWaitingRequests;
+    private onControlRequest;
+    private onControlResponse;
 }
 //# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAU5C,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAqDhE,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,WAAW;gBAAjC,SAAS,EAAE,QAAQ,GAAG,WAAW,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAED,qBAAa,mBAAmB;IAO5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,kBAAkB,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;gBAG5B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,0BAA0B;IAKhD,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,IAAI,CAAC;IA+CV,SAAS,CACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,IAAI,CAAC;IAuBhB,OAAO,CAAC,UAAU;IA6ClB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI;IAI7B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C,mBAAmB,IAAI,IAAI;IAI3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,aAAa;IAwBrB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,MAAM;IA6Id,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,kBAAkB;CAU3B"}
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa5C,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,0BAA0B,CAAC;AAWlC,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAW5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,kBAAkB,CAAwB;IAClD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,sBAAsB,CAAuB;gBAGlC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,0BAA0B;IAGtD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,gBAAgB,CAAC;IAwC5B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;IAUjB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQlC,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxB,6EAA6E;IAC7E,IAAI,IAAI,IAAI;IAIZ,OAAO,CAAC,KAAK;IAkBb,mBAAmB,IAAI,IAAI;IAM3B,OAAO,CAAC,gBAAgB;IAOxB,+EAA+E;IAC/E,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,MAAM;IAsFd,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,iBAAiB;CAyB1B"}