@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/claude-code/run.d.ts

@@ -1,11 +1,11 @@
 import type { WorkspaceRuntimeExecHandle, WorkspaceRuntimeExecOptions, WorkspaceRuntimeGetOptions, WorkspaceRuntimeKillOptions } from "@cloudflare/computer";
-import type { ProgressEvent } from "@dynamicagents/core/subtasks";
-import { type ClaudeCodeResult } from "./events.js";
-import { type PermissionMode } from "./config.js";
+import type { NoteData } from "@dynamicagents/core/subagent";
+import { type ClaudeCodeResult, type RateLimitInfo } from "./events.js";
+import { type EffortLevel, type PermissionMode } from "./config.js";
 /**
- * Launching Claude Code in the workspace container, and draining it in windows.
+ * Launching Claude Code in the workspace container, and draining it to its end.
  *
- * ## One Dynamic Agents subtask is one `claude -p` session
+ * ## One sub-agent run is one `claude -p` session
  *
  * Not one turn, and not one tool call. The unit has to be substantial because of
  * what an invocation costs before it does anything: the harness carries an
@@ -14,20 +14,21 @@ import { type PermissionMode } from "./config.js";
  *
  * ## Detached, then re-attached — never owned by a request
  *
- * The run is spawned under an exec id and left running. Each chunk re-attaches,
- * drains for a bounded window, and returns. That shape is not a preference: a
- * drain owned by an RPC that returns in milliseconds gets disposed mid-command,
- * which is exactly how the dependency install used to die halfway through
+ * The run is spawned under an exec id and left running, and a drain reads it to
+ * its exit. A drain cut short — an eviction, a deploy — does not take the
+ * session with it: the next one re-attaches under the same id. That shape is
+ * not a preference: a session owned by the request that started it dies with
+ * that request — the same way a dependency install dies halfway through
  * `npm ci`.
  *
  * ## The cursor
  *
  * `getExec(id, { resume })` accepts `"tail"`, `"full"` **or an event sequence
- * number**, and the number is what this uses. Each chunk records the last `seq`
- * it consumed, so the next one resumes exactly there instead of replaying an
- * arbitrary tail. Replay still happens when a chunk dies before it can
- * checkpoint, which is why the progress keys stay positional (see
- * `toProgress`); the cursor makes replay rare, the keys make it harmless.
+ * number**, and the number is what this uses. The caller stores the last `seq`
+ * consumed, so a resumed drain starts exactly there instead of replaying an
+ * arbitrary tail. Replay still happens when a drain dies before the cursor is
+ * stored, which is why the note keys stay positional (see `toProgress`); the
+ * cursor makes replay rare, the keys make it harmless.
  *
  * The cursor also carries the **exec id** and the **parsed result**, and both
  * are there for reasons that only show up under concurrency or retry — see
@@ -52,49 +53,79 @@ export declare const CLAUDE_EXEC_PREFIX = "claude-code-run";
 /**
  * The exec id one session occupies.
  *
- * **Per subtask, not fixed**, and the difference is load-bearing. A workspace is
- * one Durable Object and one container, but subtasks are a flat *concurrent*
- * fan-out — two `claude-code` subtasks for the same caller and repository run at
- * the same time, against the same workspace. Under a single shared id they
- * would spawn over one another, each drain would attach to whichever exec won,
- * and `killRun` would stop somebody else's session. That is the displacement bug
- * the coder's install guard exists to prevent, in a new place; here the answer
- * is simply not to share the id.
+ * **Per run, not fixed**, and the difference is load-bearing. A workspace is
+ * one Durable Object and one container, but runs are concurrent — sessions in a
+ * scratchpad share their parent's container — so under a single shared id they would spawn
+ * over one another, each drain would attach to whichever exec won, and
+ * `killRun` would stop somebody else's session. That is the displacement bug the
+ * coder's install guard exists to prevent, in a new place; here the answer is
+ * simply not to share the id.
  *
- * Fixed *per subtask*, though, because the point is still to find it again: an
+ * Fixed *per run*, though, because the point is still to find it again: an
  * isolate that dies mid-drain leaves the session running in the container, and
- * `getExec` is how the next chunk re-attaches instead of starting a second one.
+ * `getExec` is how the next drain re-attaches instead of starting a second one.
  */
-export declare function execIdFor(subtaskId: string | number): string;
+export declare function execIdFor(runId: string): string;
+/**
+ * The id a run's follow-up turn runs under — its own, because the session's exec
+ * has already finished under {@link execIdFor} and an id names one process.
+ */
+export declare function followUpExecIdFor(runId: string): string;
 /**
  * What the container is given instead of a credential.
  *
- * Claude Code does not validate it locally — proven in the Phase 0c spike, where
- * a run with this exact value succeeded and the proxy log confirmed the
- * container only ever sent the placeholder. The egress gateway swaps in the real
- * credential on the way out, so a `postinstall` script that dumps the
- * environment learns this and nothing else.
+ * Claude Code does not validate it locally: a run with this exact value
+ * succeeds, and the container only ever sends the placeholder. The egress
+ * gateway swaps in the real credential on the way out, so a `postinstall` script
+ * that dumps the environment learns this and nothing else.
  *
  * Shaped like a real token deliberately: something that looks obviously fake
  * invites a future reader to "fix" it by putting the real one there.
  */
 export declare const CREDENTIAL_PLACEHOLDER: string;
+/**
+ * Where every session keeps Claude Code's own state — its `CLAUDE_CONFIG_DIR`.
+ *
+ * The whole config directory moves, created if absent: the transcripts under
+ * `projects/<cwd-with-/-as-->/<session-id>.jsonl`, the session index,
+ * `.claude.json` and the auto-memory directory. None of it is a credential.
+ *
+ * This is what decides how long a session stays resumable. The CLI's own
+ * `$HOME/.claude` is on the container's disk, so a conversation there dies with
+ * the container — which a deploy, a rollout and the workspace's own idle timer
+ * all end. Under the workspace mount it is the Durable Object's storage, and the
+ * conversation outlives the container that held it; a later run can continue it
+ * from that same workspace object, and from no other.
+ *
+ * **Fixed, and never a host's to choose.** A transcript is found only where it
+ * was written, so every second place a session could write one is a resume that
+ * cannot find it. `env` cannot move it either: {@link buildLaunch} refuses the
+ * key.
+ *
+ * The directory is named {@link file://../computer/paths.ts SESSION_STATE_DIR},
+ * which is the name the file tools' walk steps over: a transcript records every
+ * line the session read, so a walk that descended into it would answer the
+ * parent's `grep` for a line of source with the session that quoted it. The
+ * name is written out here rather than imported, because `/claude-code` does
+ * not reach `/computer` — a spec holds the two to the same spelling.
+ */
+export declare const SESSION_CONFIG_DIR = "/workspace/.claude-sessions";
 export interface LaunchOptions {
-    /** The subtask's prompt — the whole of what this session is asked to do. */
+    /** The run's prompt — the whole of what this session is asked to do. */
     prompt: string;
     /** Where the checkout is. The session runs with this as its cwd. */
     dir: string;
     model?: string;
-    /** Ceiling on the *outer* session's turns. Advisory; the budget gate is not. */
-    maxTurns?: number;
     /**
-     * Caps on Claude Code's own subagent tree.
+     * How hard the model thinks, per turn. Unset, the model's own default.
      *
-     * These steer rather than enforce, and the distinction matters: the inner
-     * tree is invisible to Dynamic Agents' scheduler and unreachable by its
-     * cancellation sweep, so a cap it chooses to ignore has no backstop. What
-     * actually bounds the spend is the egress gateway, which every inner call
-     * also crosses.
+     * See {@link file://./config.ts ClaudeCodeConfig.effort} for what a level
+     * costs, and why an unrecognised one is worse here than a rejected one.
+     */
+    effort?: EffortLevel;
+    /**
+     * Caps on Claude Code's own subagent tree — advisory, for the reason
+     * {@link file://./config.ts ClaudeCodeConfig.maxSubagentDepth} gives.
      */
     maxSubagentDepth?: number;
     maxConcurrentSubagents?: number;
@@ -114,6 +145,63 @@ export interface LaunchOptions {
      * than trusted to the reader of that sentence.
      */
     env?: Record<string, string>;
+    /**
+     * Who this session's commits are attributed to — see
+     * {@link file://./config.ts ClaudeCodeConfig.author}.
+     */
+    author?: {
+        name: string;
+        email: string;
+    };
+    /**
+     * A JSON Schema the session's answer must match, as `--json-schema`. The CLI
+     * gives the model a `StructuredOutput` tool and holds the run until it is
+     * called, and the result line carries the call's input as
+     * `structured_output` — see {@link file://./events.ts ClaudeCodeResult}.
+     */
+    jsonSchema?: Record<string, unknown>;
+    /**
+     * A Claude Code session id to continue — the handle an earlier session left on
+     * its {@link DrainCursor}, or reported on its `result` line.
+     *
+     * {@link LaunchOptions.prompt} is then the **next user turn** rather than a new
+     * task: the conversation is already in the session's context, so a brief that
+     * restates it pays for it twice.
+     *
+     * Not scoped to the working directory — a session recorded against one cwd
+     * resumes under another and goes on appending to the original transcript — so
+     * what decides whether this works is where the transcript is, which is
+     * {@link SESSION_CONFIG_DIR} in the workspace the session ran in.
+     *
+     * **An id whose transcript is not there is not a failed session.** The CLI
+     * prints `No conversation found with session ID`, emits a `result` line
+     * carrying that as {@link file://./events.ts ClaudeCodeResult.errors}, and
+     * exits in milliseconds; its client still makes its own startup requests, but
+     * nothing is inferred and nothing is billed. The honest report is "not
+     * resumable", and the retry is the same delegation without this.
+     *
+     * **An empty id is refused rather than dropped.** That retry is launching
+     * without this option, not passing it empty.
+     */
+    resume?: string;
+    /**
+     * Fork the resumed conversation: continue it under a **new** session id,
+     * leaving the original transcript whole and resumable.
+     *
+     * What a change of mode wants — a planning session, run under `plan`,
+     * continued under the mode that writes — so that the plan's own conversation
+     * can still be resumed for an edit afterwards. Continuing in the same mode
+     * takes no fork: one conversation accumulating is what "continue" means.
+     *
+     * Refused without {@link LaunchOptions.resume}: on its own the flag has no
+     * conversation to fork, and a caller that set it meant to resume one.
+     */
+    fork?: boolean;
+    /**
+     * Present GitHub's placeholder as `GH_TOKEN` and as git's credential, for a
+     * gateway holding the real token — see {@link file://./github.ts}.
+     */
+    github?: boolean;
 }
 export interface Launch {
     command: string;
@@ -123,37 +211,32 @@ export interface Launch {
  * Build the command and environment for one session.
  *
  * `--output-format stream-json` with `--verbose`, because the stream is the only
- * way to report progress before the run ends and a run legitimately lasts longer
- * than any single chunk. `--verbose` is required: without it Claude Code emits
+ * way to report progress before the run ends, and a run lasts for minutes.
+ * `--verbose` is required: without it Claude Code emits
  * only the final result even in stream mode.
  *
- * Note what is **absent**. No `--bare`, no `--settings` override, no
- * `CLAUDE_CONFIG_DIR`: a cloned repository's `CLAUDE.md`, skills and hooks are
- * exactly the material that makes the agent good at that repository, and the
- * container is already an arbitrary-code-execution environment by design — the
- * install runs the repo's `postinstall`, the agent runs its test suite. Stripping
- * one door while the others stand open buys nothing and costs the agent its
- * context. (§4 of the design plan, cancelled 2026-08-21.)
+ * Note what is **absent**. No `--bare` and no `--settings` override: a cloned
+ * repository's `CLAUDE.md`, skills and hooks are exactly the material that makes
+ * the agent good at that repository, and the container is already an
+ * arbitrary-code-execution environment by design — the install runs the repo's
+ * `postinstall`, the agent runs its test suite. Stripping one door while the
+ * others stand open buys nothing and costs the agent its context.
+ * `CLAUDE_CONFIG_DIR` is not that kind of flag, and every session gets it: it
+ * moves where the *client* keeps its own state, touching nothing a repository
+ * ships — see {@link SESSION_CONFIG_DIR}.
  *
- * No `ANTHROPIC_BASE_URL` either, and that one is a genuine simplification over
- * the spike: `http-gateway` egress intercepts transparently, so the client talks
- * to the real hostname and the gateway sees it. Nothing has to be told to use a
- * proxy, which means nothing in the container can be told *not* to.
+ * No `ANTHROPIC_BASE_URL` either: `http-gateway` egress intercepts
+ * transparently, so the client talks to the real hostname and the gateway sees
+ * it. Nothing has to be told to use a proxy, which means nothing in the
+ * container can be told *not* to.
  *
  * ## `--permission-mode`, and the root guard behind it
  *
- * `-p` is headless. There is no terminal, so there is nobody to answer a
- * permission prompt — and Claude Code's headless path does not wait for one, it
- * **auto-denies**. Left unset the mode is `default`, and `default` gates Write,
- * Edit and every Bash command. A session in that state reads the repository
- * perfectly and cannot change one byte of it, while reporting prose that reads
- * like considered reluctance rather than a blocked tool. That cost this
- * deployment a day of "the container is fixed but nothing lands".
- *
- * So the mode is passed explicitly, and {@link DEFAULT_PERMISSION_MODE} is
- * `bypassPermissions` — see
- * {@link file://./config.ts ClaudeCodeConfig.permissionMode} for why the
- * permissive value is the correct default here rather than a concession.
+ * The mode is always passed explicitly, never left to the CLI's `default` — see
+ * {@link file://./config.ts ClaudeCodeConfig.permissionMode} for what an
+ * unset mode does to a headless session, and why
+ * {@link DEFAULT_PERMISSION_MODE} is the permissive value rather than a
+ * concession.
  *
  * **`IS_SANDBOX=1` ships in the same branch as the flag, and separating the two
  * breaks a session harder than passing no flag at all.** The container runs as
@@ -174,17 +257,32 @@ export interface Launch {
  * delete.
  */
 export declare function buildLaunch(options: LaunchOptions): Launch;
-/** Where a drain got to. Persisted between chunks by the caller. */
+/** Where a drain got to. Stored by the caller, so a cut-short drain resumes. */
 export interface DrainCursor {
     /**
      * The exec id this session occupies.
      *
      * Carried rather than derived so a re-attach cannot compute a different one
-     * from the subtask id it happens to have in hand.
+     * from the run id it happens to have in hand — and because a run's follow-up
+     * is a second exec, and the cursor says which of the two it names.
      */
     execId: string;
-    /** The last event sequence consumed; the next chunk resumes from here. */
+    /** The last event sequence consumed; a resumed drain starts here. */
     seq: number;
+    /**
+     * The Claude Code session id, from the `init` line — the handle that continues
+     * this conversation later.
+     *
+     * Carried here rather than read off the `result` line alone because the runs
+     * that most need continuing are the ones that never reach a result: a session
+     * stopped by its time limit, a cancel or a container rollout reports no result
+     * at all, and without this the conversation it got half-way through would be
+     * unreachable. The `init` line arrives in the first seconds, so a session has a
+     * handle almost from the start — which is why {@link drainRun} offers the
+     * cursor the moment the id appears instead of waiting out
+     * {@link CHECKPOINT_MIN_MS}.
+     */
+    sessionId?: string;
     /** Bytes after the last newline — an incomplete line the next read finishes. */
     carry: string;
     /** Progress notes emitted so far. The base for the positional keys. */
@@ -192,11 +290,11 @@ export interface DrainCursor {
     /**
      * The `result` line, once seen.
      *
-     * Carried because it and the `exit` event are two separate events and a window
-     * can end between them. Without this a run whose result arrived in the last
-     * moments of one chunk reports a terminal outcome with **no result** in the
-     * next — and `persistResult` converts an empty report into a failure, so a
-     * successful session would be recorded as a failed one.
+     * Carried because it and the `exit` event are two separate events and a
+     * drain can be cut short between them. Without this a run whose result
+     * arrived just before an eviction reports a terminal outcome with **no
+     * result** after it resumes — and a successful session would be reported as
+     * one that died without a word.
      */
     result?: ClaudeCodeResult;
     /**
@@ -211,20 +309,37 @@ export interface DrainCursor {
      * this the caller can only report an exit code.
      *
      * Carried on the cursor rather than kept local because the death and the exit
-     * event can land in different windows.
+     * event can land either side of an eviction.
      */
     stderr?: string;
+    /**
+     * When the pending thinking block began streaming, on this drain's clock —
+     * see `ParsedStream.thinkingFrom` in `./events.ts`.
+     */
+    thinkingFrom?: number;
 }
 /** A cursor for a session that has not started yet. */
 export declare function freshCursor(execId: string): DrainCursor;
 export type DrainOutcome = {
     done: false;
     cursor: DrainCursor;
-    progress: ProgressEvent[];
+    progress: NoteData[];
+    /**
+     * The bucket as the client reported it **during this drain**, if it did.
+     *
+     * Deliberately not carried on the cursor the way `result` is. A caller
+     * acts on this against whichever credential is leading *now*, so a reading
+     * replayed on every resumed drain would let one old observation retire a
+     * credential that was not even in use when it was taken. Absent means
+     * "this drain learned nothing", which is the honest answer.
+     */
+    rateLimit?: RateLimitInfo;
 } | {
     done: true;
     cursor: DrainCursor;
-    progress: ProgressEvent[];
+    progress: NoteData[];
+    /** The bucket as reported **in this drain**. See the `done: false` arm. */
+    rateLimit?: RateLimitInfo;
     exitCode: number;
     /** Absent when the process died without ever emitting a `result` line. */
     result?: ClaudeCodeResult;
@@ -237,41 +352,117 @@ export type DrainOutcome = {
 };
 export interface DrainOptions {
     /**
-     * How long this chunk may block before checkpointing and yielding.
+     * Called with each note as it is parsed, rather than with all of them when the
+     * drain ends — a session runs for minutes, and a caller with nothing but the
+     * outcome would learn everything at once, once the work is over.
+     *
+     * Notes are still returned on the outcome as well, so a caller that files them
+     * from here must drop what it is handed back, or the same note is filed twice.
+     * The keys are positional, so the transcript would dedupe it, but paying for
+     * the second one to be discarded is not a plan.
      *
-     * Must stay comfortably under the Workflow step timeout, and it is what stops
-     * a run burning its whole chunk allowance in seconds: a drain that returned
-     * the moment it had nothing to read would exhaust `MAX_CHUNKS_PER_BRANCH`
-     * before the session finished thinking.
+     * **Never awaited inside the read loop.** Calls are chained instead, so they
+     * stay in order without stalling the read of the container's stream for as
+     * long as the session is talkative, and the chain is settled before the drain
+     * returns.
      */
-    windowMs: number;
+    onProgress?: (note: NoteData) => void | Promise<void>;
+    /**
+     * Called with a cursor that is safe to store, no more often than
+     * {@link CHECKPOINT_MIN_MS}.
+     *
+     * **Only meaningful alongside `onProgress`, and that coupling is the whole
+     * point.** A cursor names a position whose notes have *already been handed to
+     * the sink* — it rides the same chain, after them — so resuming from it loses
+     * nothing the parent was sent. A note the sink **rejects** ends the
+     * checkpoints for the rest of the drain, so no stored cursor passes it: a
+     * drain cut after that resumes from before it, and files it again.
+     *
+     * Without it, a drain that dies mid-stream resumes from the start of the
+     * session. One production run lost six and a half minutes of a session that
+     * way and re-derived it by replaying the whole stream.
+     */
+    onCheckpoint?: (cursor: DrainCursor) => void | Promise<void>;
+    /**
+     * Stops the drain now: the cursor comes back as `done: false`, and the
+     * session goes on running — stopping *it* is the caller's, with
+     * {@link killRun}. Not honoured once the process has exited, because the read
+     * to the end carries the filesystem sync; see the loop in {@link drainRun}.
+     */
+    signal?: AbortSignal;
     now?: () => number;
 }
+/** Whether a thrown value is the runtime refusing to reuse a live exec id. */
+export declare function isExecBusy(err: unknown): boolean;
+/**
+ * Whether a thrown value means the session this cursor names is gone for good.
+ *
+ * `EEXEC_LOST` is the runtime saying the container that held the execution was
+ * replaced. The session died with it, and no attachment will ever find it — so
+ * unlike `EEXEC_BUSY`, which is a live session reached the wrong way, there is
+ * nothing to recover and retrying only discovers that again.
+ */
+export declare function isExecLost(err: unknown): boolean;
 /**
  * Start a session, detached.
  *
  * **Falls back to attaching when the id is already live**, which is not a
- * nicety. `start` spawns and then drains for minutes, so a chunk that fails
- * anywhere after the spawn is retried by the Workflow with no cursor to resume
- * from — and `@cloudflare/computer` refuses to reuse an id whose execution is
- * still running (`EEXEC_BUSY`). Without this the retry throws, every later retry
+ * nicety. `start` spawns and then drains for minutes, so a turn cut anywhere
+ * after the spawn is recovered with no cursor stored yet — and
+ * `@cloudflare/computer` refuses to reuse an id whose execution is still
+ * running (`EEXEC_BUSY`). Without this the recovery throws, every later one
  * throws the same way, and a perfectly healthy session in the container becomes
  * unreachable.
+ *
+ * **The sync stays on the default, and `defer` is not an option here.** A
+ * deferred exec skips the post-command pull entirely and settles the outcome
+ * from the cursor instead — and its `cancel` reads the stream to the end first,
+ * so stopping a drain would block until the session exits. Both halves are
+ * exactly what this drain is built not to do.
  */
 export declare function startRun(runtime: SessionRuntime, options: LaunchOptions & {
     execId: string;
     timeoutMs: number;
+    /** Stops the fallback's wait — see {@link AttachOptions.signal}. */
+    signal?: AbortSignal;
 }): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
-/** Re-attach to a session this isolate did not start. */
-export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
+/** The clock and the wait, injectable so a spec can drive the bound. */
+export interface AttachOptions {
+    now?: () => number;
+    wait?: (ms: number) => Promise<void>;
+    /** Stops the wait — see `DrainOptions.signal`. */
+    signal?: AbortSignal;
+}
 /**
- * Drain a session for one bounded window.
+ * Re-attach to a session this isolate did not start.
  *
- * Returns `done: false` when the window expired with the process still running —
- * the caller checkpoints the cursor and comes back — or `done: true` once the
- * stream has finished.
+ * **Waits out a subscriber the previous drain has not released yet**, and that
+ * wait is the point of this function rather than a refinement of it. The
+ * alternative is not "fail fast" — it is spending a recovery to discover a
+ * condition that clears on its own in a second, when recoveries are what a
+ * deploy, a severed stub and a network drop have to be covered out of. A
+ * deployment lost a twenty-one-minute session exactly that way — consecutive
+ * attach races used the retries up, and the redeploy that followed had no
+ * attempt left to be retried on. See {@link isExecSubscribed}.
+ *
+ * Everything else is rethrown on the first look, `EEXEC_LOST` above all: it is
+ * the runtime saying the container was replaced, `resume` turns it into a report
+ * for the model, and a retry loop would sit on it for {@link ATTACH_MAX_MS}
+ * learning nothing.
+ */
+export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor, options?: AttachOptions): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
+/**
+ * Drain a session to its end.
+ *
+ * Returns `done: true` once the stream has finished, or `done: false` when the
+ * caller's signal stopped the drain with the process still running.
+ */
+export declare function drainRun(handle: WorkspaceRuntimeExecHandle<"utf8">, cursor: DrainCursor, options?: DrainOptions): Promise<DrainOutcome>;
+/**
+ * What a session reports on `stderr` when its container went away under it:
+ * the stream ended with no `exit` event, or a re-attach found the exec gone.
  */
-export declare function drainRun(handle: WorkspaceRuntimeExecHandle<"utf8">, cursor: DrainCursor, options: DrainOptions): Promise<DrainOutcome>;
+export declare function containerLost(printed?: string): string;
 /**
  * Stop a session.
  *