@dynamicagents/plugins 0.13.0 → 0.15.0

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

@@ -1,474 +0,0 @@
-import type { WorkspaceRuntimeExecHandle, WorkspaceRuntimeExecOptions, WorkspaceRuntimeGetOptions, WorkspaceRuntimeKillOptions } from "@cloudflare/computer";
-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 to its end.
- *
- * ## 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
- * 18.7-27k token cached prefix, and a ten-call burst billed **twenty** raw input
- * tokens against 187,130 cache reads. On anything short the prefix is the bill.
- *
- * ## Detached, then re-attached — never owned by a request
- *
- * 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. 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
- * {@link DrainCursor}.
- */
-/**
- * Just enough of a workspace runtime to drive one detached session.
- *
- * Structural rather than `@cloudflare/computer`'s `WorkspaceRuntime`, for the
- * reason `InstallProbe` is structural one folder over: the class is not exported
- * as a type, it carries a dozen members none of this needs, and a spec that has
- * to construct one cannot test a drain without a container. Three methods is the
- * whole dependency.
- */
-export interface SessionRuntime {
-    exec(source: string, options: WorkspaceRuntimeExecOptions<"utf8">): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
-    getExec(id: string, options: WorkspaceRuntimeGetOptions<"utf8">): Promise<WorkspaceRuntimeExecHandle<"utf8">>;
-    killExec(id: string, options?: WorkspaceRuntimeKillOptions): Promise<void>;
-}
-/** Namespace for every session exec id in a workspace. */
-export declare const CLAUDE_EXEC_PREFIX = "claude-code-run";
-/**
- * The exec id one session occupies.
- *
- * **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 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 drain re-attaches instead of starting a second one.
- */
-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: 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 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;
-    /**
-     * How hard the model thinks, per turn. Unset, the model's own default.
-     *
-     * 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;
-    /**
-     * How the session answers its own permission prompts.
-     *
-     * Defaults to {@link DEFAULT_PERMISSION_MODE}. See
-     * {@link file://./config.ts ClaudeCodeConfig.permissionMode} for why the
-     * default is the permissive one, and {@link buildLaunch} for the root guard
-     * that decides how it has to be passed.
-     */
-    permissionMode?: PermissionMode;
-    /**
-     * Merged last, so a host can add what a repository needs.
-     *
-     * **Never secrets**, and {@link RESERVED_ENV_KEY} is refused outright rather
-     * 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;
-    env: Record<string, string>;
-}
-/**
- * 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 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` 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
- * 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
- *
- * 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
- * root, and the CLI refuses to bypass its permission checks under uid 0 unless
- * that variable is set: it calls `process.exit(1)` **before the first JSON
- * line**, with the only explanation on stderr. The failure then surfaces as
- * "exited with code 1 without reporting a result" and names nothing. One branch
- * below writes both so they cannot drift, and the variable is applied *after* a
- * host's `env` so a host cannot unset the thing making its own mode work.
- *
- * `IS_SANDBOX` has one other documented effect in this client: a repeated API
- * `529` stops raising the custom overload error and keeps retrying instead.
- * Harmless here — the egress gateway is what decides when to give up.
- *
- * The alternative is an image that does not run as root, which is a real option
- * and a much larger one: the FUSE mount, the checkout and every install path
- * currently assume uid 0. If that ever changes, this variable is the line to
- * delete.
- */
-export declare function buildLaunch(options: LaunchOptions): Launch;
-/** 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 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; 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. */
-    emitted: number;
-    /**
-     * The `result` line, once seen.
-     *
-     * 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;
-    /**
-     * A bounded slice of the session's stderr, for the runs that explain
-     * themselves nowhere else.
-     *
-     * stderr is not the protocol stream and is never parsed as one — see
-     * `consume` below. It is kept for exactly one case: a process that exits
-     * **before** emitting a `result` line, where the JSON stream holds nothing and
-     * the only account of what happened is the text the CLI printed on its way
-     * out. A bad flag, a refused permission mode under root, a Node crash. Without
-     * 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 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: 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: 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;
-    /**
-     * What the process printed on stderr, bounded — only when there is no
-     * `result` to explain the exit. Present on the terminal outcome alone
-     * because that is the only place a caller has nothing else to report.
-     */
-    stderr?: string;
-};
-export interface DrainOptions {
-    /**
-     * 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.
-     *
-     * **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?: (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 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">>;
-/** 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;
-}
-/**
- * Re-attach to a session this isolate did not start.
- *
- * **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 containerLost(printed?: string): string;
-/**
- * Stop a session.
- *
- * `SIGTERM` rather than `SIGKILL`: Claude Code aborts the turn, kills its own
- * Bash process tree, runs its `SessionEnd` hooks and exits 143. A `SIGKILL`
- * leaves whatever the session had spawned still running in a container the
- * workspace will keep using.
- */
-export declare function killRun(runtime: SessionRuntime, execId: string): Promise<void>;