@dynamicagents/plugins 0.12.0 → 0.14.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 { 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,19 +14,21 @@ import { type EffortLevel, 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
- * — the same way a dependency install dies halfway through `npm ci`.
+ * 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
@@ -51,20 +53,24 @@ 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.
  *
@@ -77,8 +83,35 @@ export declare function execIdFor(subtaskId: string | number): string;
  * 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;
@@ -120,6 +153,55 @@ export interface LaunchOptions {
         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;
@@ -129,17 +211,19 @@ 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.
+ * 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: `http-gateway` egress intercepts
  * transparently, so the client talks to the real hostname and the gateway sees
@@ -173,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. */
@@ -191,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;
     /**
@@ -210,31 +309,36 @@ 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 window**, if it did.
+     * 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 later chunk would let one window's observation retire
-     * a credential that was not even in use when it was taken. Absent means
-     * "this window learned nothing", which is the honest answer.
+     * 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[];
-    /** The bucket as reported **in this window**. See the `done: false` arm. */
+    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. */
@@ -247,125 +351,135 @@ export type DrainOutcome = {
     stderr?: string;
 };
 export interface DrainOptions {
-    /**
-     * How long this chunk may block before checkpointing and yielding.
-     *
-     * **This is the coder path's soft limit**, justified the same way core's
-     * `CHUNK_SOFT_MS` is — by the step timeout — but checked as a deadline on
-     * reading the session's stdout stream rather than between turns, because a
-     * `claude -p` session runs its own loop inside the container and there are no
-     * core-visible turns to stop between. The stream is the only synchronisation
-     * point there is. {@link file://./config.ts ClaudeCodeConfig.windowMs} holds
-     * how the default is sized against that timeout, what the headroom it leaves
-     * is for, and why that headroom is an expectation rather than a guarantee.
-     *
-     * It is also 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.
-     *
-     * **It is not the reporting interval**, and reading it as one is the mistake
-     * {@link DrainOptions.onProgress} exists to remove: a session that finishes
-     * inside a single window reaches no boundary at all, so a caller with nothing
-     * but the outcome learns everything at once, once the work is over.
-     */
-    windowMs: number;
     /**
      * Called with each note as it is parsed, rather than with all of them when the
-     * window ends.
+     * 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 posts from
-     * here must drop what it is handed back, or the same note is posted twice. The
-     * keys are positional, so the gatekeeper would dedupe it, but paying for the
-     * second post to be discarded is not a plan.
+     * 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.
      *
-     * **Never awaited inside the read loop.** A post is a signed round trip to the
-     * gatekeeper — measured at ~700 ms — and awaiting one per note would stall
-     * reading the container's stream for as long as the session is talkative.
-     * Calls are chained instead, so they stay in order, and the chain is settled
-     * before the drain returns.
+     * **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.
      */
-    onProgress?: (event: ProgressEvent) => void | Promise<void>;
+    onProgress?: (note: NoteData) => void | Promise<void>;
     /**
-     * Called with a cursor that is safe to persist, no more often than
+     * 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 caller normally commits the cursor after the drain returns,
-     * because a cursor written ahead of consuming events would skip events a retry
-     * never saw. A cursor offered here names a position whose notes have *already
-     * been handed to the sink*, so resuming from it loses nothing a person saw —
-     * which is only true because the sink posted them.
+     * 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 chunk that dies mid-window resumes from the last committed
-     * position, which is wherever the previous window ended. One production run
-     * lost six and a half minutes of a session that way and re-derived it by
-     * replaying the whole stream.
+     * 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 spends chunks discovering that again.
+ * nothing to recover and retrying only discovers that again.
  */
 export declare function isExecLost(err: unknown): boolean;
+/**
+ * {@link attachRun} giving up on a subscriber that was never released. Unlike
+ * a transient failure, nothing retries it: the run fails, and its host stops
+ * the session.
+ */
+export declare class AttachGivenUpError extends Error {
+    name: string;
+}
 /**
  * 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 ending a window would block until the session exits rather than yielding
- * the chunk. Both halves are exactly what this drain is built not to do.
+ * 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">>;
-/** The clock and the wait, injectable so a spec can drive the bound. */
 export interface AttachOptions {
+    /**
+     * How long to wait out a subscriber that has not been released: the
+     * session's own `timeoutMs`.
+     *
+     * Giving up fails the run, and a failed run is stopped by its host — so a
+     * shorter bound kills a healthy session, and past this one the session is
+     * over anyway. How long a release actually took is logged when the attach
+     * lands.
+     */
+    maxWaitMs: number;
+    /** The clock and the wait, injectable so a spec can drive the bound. */
     now?: () => number;
     wait?: (ms: number) => Promise<void>;
+    /** Stops the wait — see `DrainOptions.signal`. */
+    signal?: AbortSignal;
 }
 /**
  * Re-attach to a session this isolate did not start.
  *
- * **Waits out a subscriber the previous window has not released yet**, and that
+ * **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 Workflow retry to discover a
- * condition that clears on its own in a second, when a chunk step's retries are
- * what a deploy, a severed stub and a network drop have to be covered out of.
- * Core sizes that budget and says why; what matters here is that this must not
- * be charged to it. 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}.
+ * 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.
+ * for the model, and a retry loop would sit on it learning nothing.
  */
-export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor, options?: AttachOptions): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
+export declare function attachRun(runtime: SessionRuntime, cursor: DrainCursor, options: AttachOptions): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
 /**
- * Drain a session for one bounded window.
+ * Drain a session to its end.
  *
- * 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.
+ * 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.
  *