@dynamicagents/plugins 0.14.0 → 0.15.0

package/dist/claude-code/run.js

@@ -1,913 +0,0 @@
-import { shellQuote } from "@cloudflare/computer";
-import { GITHUB_ENV_KEYS, githubEnv } from "./github.js";
-import { parseStream, toProgress, RATE_LIMIT_OK } from "./events.js";
-import { DEFAULT_PERMISSION_MODE } from "./config.js";
-/** Namespace for every session exec id in a workspace. */
-export 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 function execIdFor(runId) {
-    return `${CLAUDE_EXEC_PREFIX}:${runId}`;
-}
-/**
- * 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 function followUpExecIdFor(runId) {
-    return `${execIdFor(runId)}:follow-up`;
-}
-/**
- * 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 const CREDENTIAL_PLACEHOLDER = "sk-ant-oat01-" + "0".repeat(24);
-/**
- * The environment key a host may not set.
- *
- * `LaunchOptions.env` is merged last so a deployment can add what a repository
- * needs, and that merge is exactly how the placeholder could be replaced by a
- * real credential — silently, and in every container from then on. The whole
- * design rests on the container holding nothing worth stealing, so this one key
- * is refused rather than overridden.
- */
-const RESERVED_ENV_KEY = "CLAUDE_CODE_OAUTH_TOKEN";
-/**
- * The workspace mount, `/workspace` in every image this plugin runs in.
- * Whatever a session writes under it is synced into the workspace's Durable
- * Object; whatever it writes anywhere else dies with the container.
- */
-const WORKSPACE_MOUNT = "/workspace";
-/**
- * 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 const SESSION_CONFIG_DIR = `${WORKSPACE_MOUNT}/.claude-sessions`;
-/** The environment key {@link SESSION_CONFIG_DIR} travels as. */
-const CONFIG_DIR_ENV_KEY = "CLAUDE_CONFIG_DIR";
-/**
- * Git's identity as an *environment*, not a `git config`.
- *
- * The session's cwd is one checkout, and what it commits in is not: a
- * superproject's submodules, a scratch clone, anything it initialises are all
- * separate repositories with separate configs, and `/repo` only ever configured
- * the one it cloned. A config write would have to find each of them; the
- * environment is inherited by every git the session starts, and it outranks all
- * four config levels — so a checkout carrying a name from whenever it was
- * created no longer decides who commits today.
- *
- * Both pairs, because they answer different questions: an amend or a rebase
- * keeps the original author and stamps a fresh committer, and with only
- * `GIT_AUTHOR_*` set that commit ends up half attributed.
- */
-function gitIdentityEnv(author) {
-    if (!author)
-        return {};
-    return {
-        GIT_AUTHOR_NAME: author.name,
-        GIT_AUTHOR_EMAIL: author.email,
-        GIT_COMMITTER_NAME: author.name,
-        GIT_COMMITTER_EMAIL: author.email
-    };
-}
-/**
- * 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 function buildLaunch(options) {
-    /**
-     * Refused rather than silently dropped.
-     *
-     * A host that set this meant something by it, and the something is always
-     * wrong — the placeholder is what makes the container safe to run a
-     * stranger's `postinstall` in. The config is static, so this fails on the
-     * first run in development rather than surprising a live task.
-     */
-    if (options.env && RESERVED_ENV_KEY in options.env) {
-        throw new Error(`claude-code: ${RESERVED_ENV_KEY} cannot be set through \`env\`. The ` +
-            "container is launched with a placeholder and the egress gateway swaps " +
-            "in the real credential on the way out; putting a real one here would " +
-            "hand it to every process in the container, including a cloned " +
-            "repository's install scripts. Pass it as `credential` instead.");
-    }
-    /**
-     * Refused for the same reason: a host that set it meant its sessions to keep
-     * their state somewhere else, and a transcript written anywhere but the one
-     * place is a conversation no later run will find.
-     */
-    if (options.env && CONFIG_DIR_ENV_KEY in options.env) {
-        throw new Error(`claude-code: ${CONFIG_DIR_ENV_KEY} cannot be set through \`env\`. Every ` +
-            `session keeps its state in ${SESSION_CONFIG_DIR}, which is where a ` +
-            "later run looks for the conversation it continues.");
-    }
-    /**
-     * Refused rather than dropped, both of them: dropped, a caller that asked to
-     * continue or fork a conversation gets a session that started one of its own,
-     * and reports it as the continuation of whatever it was told to continue. An
-     * empty id is the same state {@link file://./session.ts followUp} refuses,
-     * and refusing it here covers every caller of this option rather than that
-     * one path.
-     */
-    if (options.resume === "") {
-        throw new Error("claude-code: `resume` is the session id of the conversation to " +
-            "continue, so it cannot be empty. Launch without it to start one.");
-    }
-    if (options.fork && !options.resume) {
-        throw new Error("claude-code: `fork` forks a resumed conversation, so it needs the " +
-            "`resume` session id it is forking.");
-    }
-    /**
-     * Refused beside `github`: a host value would either hand the session a real
-     * token or point git's credential at something other than the placeholder.
-     */
-    const githubKey = options.github
-        ? GITHUB_ENV_KEYS.find((key) => options.env && key in options.env)
-        : undefined;
-    if (githubKey) {
-        throw new Error(`claude-code: ${githubKey} cannot be set through \`env\` when \`githubToken\` ` +
-            "is configured. The session presents a placeholder and the egress " +
-            "gateway swaps in the GitHub token on the way out.");
-    }
-    const permissionMode = options.permissionMode ?? DEFAULT_PERMISSION_MODE;
-    const argv = ["claude", "-p", shellQuote(options.prompt)];
-    if (options.resume)
-        argv.push("--resume", shellQuote(options.resume));
-    if (options.fork)
-        argv.push("--fork-session");
-    argv.push("--output-format", "stream-json", "--verbose");
-    argv.push("--permission-mode", permissionMode);
-    if (options.model)
-        argv.push("--model", shellQuote(options.model));
-    if (options.effort)
-        argv.push("--effort", options.effort);
-    if (options.jsonSchema) {
-        argv.push("--json-schema", shellQuote(JSON.stringify(options.jsonSchema)));
-    }
-    const env = {
-        // Pinned image; an autoupdate would move the wire shape the gateway and the
-        // parser are both written against, mid-run and without a deploy.
-        DISABLE_AUTOUPDATER: "1",
-        // Telemetry and feature-flag fetches. Turned off at the source so an
-        // egress-restricted deployment does not fill its logs with 403s that mean
-        // nothing.
-        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
-    };
-    if (options.maxSubagentDepth !== undefined)
-        env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = String(options.maxSubagentDepth);
-    if (options.maxConcurrentSubagents !== undefined)
-        env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS = String(options.maxConcurrentSubagents);
-    return {
-        command: argv.join(" "),
-        // Everything below `options.env` is applied **after** the host's environment
-        // rather than before it. For the placeholder and the config directory that
-        // makes the guards above a second line rather than the only one; for
-        // `IS_SANDBOX` it means a host cannot unset
-        // the variable its own permission mode depends on — see the note above.
-        //
-        // For the identity it is what keeps the four keys one answer. Spread before
-        // `env`, a host that set `GIT_AUTHOR_NAME` there and `author` here would
-        // get the author from one and the committer from the other — a commit
-        // attributed to two people, which is the exact failure `author` exists to
-        // end. Last, `author` is simply the answer whenever a host gives one.
-        env: {
-            ...env,
-            ...options.env,
-            ...(permissionMode === "bypassPermissions"
-                ? { IS_SANDBOX: "1" }
-                : undefined),
-            ...gitIdentityEnv(options.author),
-            ...(options.github ? githubEnv() : undefined),
-            [CONFIG_DIR_ENV_KEY]: SESSION_CONFIG_DIR,
-            [RESERVED_ENV_KEY]: CREDENTIAL_PLACEHOLDER
-        }
-    };
-}
-/** A cursor for a session that has not started yet. */
-export function freshCursor(execId) {
-    return { execId, seq: 0, carry: "", emitted: 0 };
-}
-/**
- * Whether a bucket reading says anything the last one did not.
- *
- * Every field, because each is separately actionable: the status decides whether
- * a credential is worth using, `resetsAt` is when it recovers, the type says
- * which bucket is talking, and the overage pair says whether spending past it is
- * allowed and why not. Comparing only the status would hold a rollover — a new
- * `resetsAt` under an unchanged `allowed` — out of the logs entirely.
- *
- * **Over the keys rather than a written-out list**, which is the difference
- * between one bug and a class of them: a field added to
- * {@link RateLimitInfo} and forgotten here does not make a smaller log, it makes
- * a change to the reading that never reaches a log at all — the one failure this
- * function exists to prevent, and a silent one. Shallow is exact because the
- * reading is flat and every value on it is a primitive; a nested field would
- * need this revisited, and the parser is where that would be decided.
- */
-function changedReading(previous, next) {
-    if (previous === undefined)
-        return true;
-    const before = { ...previous };
-    const after = { ...next };
-    return [...new Set([...Object.keys(before), ...Object.keys(after)])].some((key) => before[key] !== after[key]);
-}
-/** Distinguishes "the caller stopped the drain" from a stream event in the race below. */
-const STOPPED = Symbol("stopped");
-/**
- * How rarely a drain offers a cursor to persist.
- *
- * A checkpoint is a Durable Object storage write, and the stream can carry many
- * events a second while a session reads files — so this is a floor on the writes,
- * not a schedule for them. Sized against what it is protecting: the loss it
- * bounds is re-drained in seconds, so buying a smaller bound with a write per
- * event would cost more than the bound is worth.
- */
-const CHECKPOINT_MIN_MS = 30_000;
-/** Whether a thrown value is the runtime refusing to reuse a live exec id. */
-export function isExecBusy(err) {
-    return err?.code === "EEXEC_BUSY";
-}
-/**
- * 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 function isExecLost(err) {
-    return err?.code === "EEXEC_LOST";
-}
-/**
- * Whether a thrown value is the *previous* drain's attachment, not yet released.
- *
- * An exec's event stream admits one subscriber at a time. A drain resumed after
- * an eviction, or a follow-up asked for the moment a session ends, can ask for
- * the next one while the last is still being released — and the release on the
- * far side is asynchronous and unobservable from here: the workspace client
- * carries `Symbol.dispose`, not `Symbol.asyncDispose`, so there is nothing a
- * caller can await to know the attachment is gone. {@link attachRun} answers by
- * waiting rather than by failing.
- *
- * A workspace object reset by the platform leaves its dead connection's
- * attachment held far longer: past thirty seconds, with the session mid-call
- * and printing nothing.
- *
- * **Matched on the message, not on a code, and that is not laziness.** This one
- * is raised inside the container image rather than by the runtime client: the
- * string appears nowhere in the Worker bundle, and it arrives here as a plain
- * `Error` with no `code` — unlike `EEXEC_BUSY` and `EEXEC_LOST`
- * above, which the client throws and codes. The code is checked first anyway, so
- * the day the container starts sending one this keeps working and the string
- * test becomes the fallback it should have been.
- */
-function isExecSubscribed(err) {
-    const e = err;
-    if (e?.code === "EEXEC_SUBSCRIBED")
-        return true;
-    return (typeof e?.message === "string" &&
-        e.message.includes("already has a live subscriber"));
-}
-/**
- * {@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 class AttachGivenUpError extends Error {
-    name = "AttachGivenUpError";
-}
-/** The first gap between attach attempts, doubled up to {@link ATTACH_CAP_MS}. */
-const ATTACH_BACKOFF_MS = 250;
-/**
- * The ceiling on that doubling, so the wait ends soon after the release rather
- * than at the next power of two.
- */
-const ATTACH_CAP_MS = 2_000;
-/**
- * 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 async function startRun(runtime, options) {
-    const { command, env } = buildLaunch(options);
-    try {
-        return await runtime.exec(command, {
-            id: options.execId,
-            cwd: options.dir,
-            encoding: "utf8",
-            env,
-            timeoutMs: options.timeoutMs
-        });
-    }
-    catch (err) {
-        if (!isExecBusy(err))
-            throw err;
-        console.info("[claude-code] a session is already running under this id — attaching", { execId: options.execId });
-        return await attachRun(runtime, freshCursor(options.execId), {
-            signal: options.signal,
-            maxWaitMs: options.timeoutMs
-        });
-    }
-}
-/**
- * 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 learning nothing.
- */
-export async function attachRun(runtime, cursor, options) {
-    const now = options.now ?? Date.now;
-    const wait = options.wait ?? sleep;
-    const started = now();
-    const deadline = started + options.maxWaitMs;
-    let backoff = ATTACH_BACKOFF_MS;
-    let waited = false;
-    for (;;) {
-        let handle;
-        try {
-            handle = await runtime.getExec(cursor.execId, {
-                encoding: "utf8",
-                // `0` is a legal seq and also the beginning, so a fresh cursor resumes
-                // from the start either way. A stored cursor names its own place.
-                resume: cursor.seq
-            });
-        }
-        catch (err) {
-            if (!isExecSubscribed(err) || options.signal?.aborted)
-                throw err;
-            if (now() >= deadline) {
-                const waitedMs = now() - started;
-                console.warn("[claude-code] gave up waiting out the previous drain", {
-                    execId: cursor.execId,
-                    waitedMs
-                });
-                throw new AttachGivenUpError("claude-code: the session's stream to its container was cut, and the " +
-                    "container held on to the old connection for the whole of the " +
-                    "session's time limit, so it could not be re-attached. The cut is " +
-                    "the platform's, not the session's; what the session did so far is " +
-                    "in its workspace and on the transcript.", { cause: err });
-            }
-            // Logged once each way rather than per look: how long a release takes
-            // is the number worth reading, and over a session-long bound a line per
-            // look would bury it.
-            if (!waited) {
-                waited = true;
-                console.info("[claude-code] the previous drain is still attached — waiting", { execId: cursor.execId, maxWaitMs: options.maxWaitMs });
-            }
-            // Clamped to what is left, so the last gap lands *on* the deadline rather
-            // than past it, and the bound is one the code keeps.
-            await wait(Math.min(backoff, deadline - now()));
-            backoff = Math.min(backoff * 2, ATTACH_CAP_MS);
-            continue;
-        }
-        if (waited) {
-            console.info("[claude-code] attached after waiting out the previous drain", {
-                execId: cursor.execId,
-                waitedMs: now() - started
-            });
-        }
-        return handle;
-    }
-}
-/**
- * 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 async function drainRun(handle, cursor, options = {}) {
-    const now = options.now ?? Date.now;
-    const reader = handle.getReader();
-    /**
-     * The drain's notes, in order — built as the stream is parsed rather than
-     * from a list of events at the end, so there is one place a note is numbered
-     * and the sink below cannot disagree with what is returned.
-     */
-    const progress = [];
-    let emitted = cursor.emitted;
-    let buffer = cursor.carry;
-    let thinkingFrom = cursor.thinkingFrom;
-    let seq = cursor.seq;
-    let result = cursor.result;
-    // This drain's reading only — see `DrainOutcome`. Starting undefined also
-    // means the first reading of each drain reaches the log, which is what keeps
-    // a resumed session's bucket visible without carrying a stale one forward.
-    let rateLimit;
-    let stderr = cursor.stderr ?? "";
-    let sessionId = cursor.sessionId;
-    /**
-     * Set when this drain is the one that learned the session id, and cleared by
-     * the checkpoint it lets through. See {@link DrainCursor.sessionId}.
-     */
-    let newHandle = false;
-    let exitCode;
-    let checkpointedAt = now();
-    /**
-     * The sink's calls, chained rather than awaited.
-     *
-     * Ordering matters — these are sentences in a conversation — and awaiting
-     * one inside the read loop would stall the drain for as long as the session
-     * keeps talking. A rejected note does not stop the drain — a note is
-     * best-effort — but it is logged, and it ends the checkpoints: see
-     * `DrainOptions.onCheckpoint`. Settled before the drain returns or throws, so
-     * nothing is cut short when it unwinds, and nothing lands behind a drain that
-     * re-attaches after it.
-     */
-    let sunk = Promise.resolve();
-    /** Set once a note is rejected — see `DrainOptions.onCheckpoint`. */
-    let rejected = false;
-    /**
-     * The last position every note behind which reached the sink: where this
-     * drain began, then each checkpoint the chain reaches unrejected.
-     */
-    let safe = cursor;
-    /**
-     * Parse whatever complete lines the buffer now holds.
-     *
-     * Called after **every** stdout event rather than once at the end. Claude
-     * Code's stream carries whole tool results, so a drain that only parsed on
-     * the way out would hold a whole session's transcript of a noisy build in a
-     * Durable Object's memory; parsing eagerly keeps only `carry`, which is at
-     * most one incomplete line.
-     */
-    const absorb = () => {
-        const parsed = parseStream(buffer, {
-            now: now(),
-            ...(thinkingFrom === undefined ? {} : { thinkingFrom })
-        });
-        buffer = parsed.carry;
-        thinkingFrom = parsed.thinkingFrom;
-        for (const event of parsed.events) {
-            if (event.kind === "result")
-                result = event.result;
-            // The first one only, and it is the id of whatever this drain is actually
-            // draining: a resumed conversation's own, or the new one a fork starts.
-            if (event.kind === "init" && !sessionId) {
-                sessionId = event.sessionId;
-                newHandle = true;
-            }
-            if (event.kind === "rateLimit") {
-                /**
-                 * Logged when the reading **changes**, not per line — and a change is
-                 * any field of it, not just the status: a bucket rolling over moves
-                 * `resetsAt` while saying `allowed` throughout, and the new reset is
-                 * the useful half of that line.
-                 *
-                 * The client repeats itself for as long as a session runs, so a log per
-                 * event would be the noisiest thing this package writes and every copy
-                 * after the first would say the same thing. A change is the whole signal:
-                 * the first reading names the bucket and when it refills, and the only
-                 * other one that can happen is the bucket saying no — which is the line
-                 * nobody has captured yet, and the one the pool needs before it can be
-                 * trusted to act on a status rather than on a refused request.
-                 */
-                if (changedReading(rateLimit, event.info)) {
-                    const at = { execId: cursor.execId, ...event.info };
-                    // An unrecognised status is **not** reported as a refusal. Nothing
-                    // here knows what one means, and a log that calls it exhaustion is
-                    // how a healthy credential gets retired by the next person to read
-                    // it. See `RATE_LIMIT_OK`.
-                    if (event.info.status === RATE_LIMIT_OK)
-                        console.info("[claude-code] subscription bucket", at);
-                    else
-                        console.warn("[claude-code] unrecognised subscription status", at);
-                }
-                rateLimit = event.info;
-            }
-        }
-        // Numbered from the running total, so a note has the same key whether it is
-        // filed from here or returned on the outcome — and the same key again when
-        // a resumed drain replays this part of the stream, which is what makes the
-        // duplicate harmless. See `toProgress`.
-        for (const note of toProgress(parsed.events, emitted)) {
-            progress.push(note);
-            emitted++;
-            const sink = options.onProgress;
-            if (sink)
-                sunk = sunk
-                    .then(() => sink(note))
-                    .catch((err) => {
-                    rejected = true;
-                    console.warn("[claude-code] a note did not reach the parent", {
-                        execId: cursor.execId,
-                        key: note.key,
-                        err: String(err)
-                    });
-                });
-        }
-        if (parsed.skipped > 0) {
-            // Not fatal, and deliberately not silent: a systematic schema change
-            // shows up here as a rising count long before it shows up as a run that
-            // reports nothing.
-            //
-            // **The sample is the half that makes this actionable.** For a release
-            // this warning fired on every session in the deployment with
-            // `skipped: 1`, which told an operator that something was being dropped
-            // and nothing whatever about what — so it was read as background noise
-            // while it was in fact the only trace of a real fault. A count says a
-            // schema moved; the line says which way.
-            console.warn("[claude-code] unparsed lines in the session stream", {
-                skipped: parsed.skipped,
-                ...(parsed.sample ? { sample: parsed.sample } : {})
-            });
-        }
-    };
-    /**
-     * Where the drain has got to, as something safe to persist.
-     *
-     * One object, so `seq`, `carry` and `emitted` are written together — a cursor
-     * that advanced its position without its note count would renumber every key
-     * after it, and a replay would then post the whole tail again under keys the
-     * transcript has never seen.
-     */
-    const checkpoint = () => ({
-        execId: cursor.execId,
-        seq,
-        carry: buffer,
-        emitted,
-        ...(thinkingFrom === undefined ? {} : { thinkingFrom }),
-        ...(sessionId ? { sessionId } : {}),
-        ...(result ? { result } : {}),
-        ...(stderr ? { stderr } : {})
-    });
-    /**
-     * Offer the caller a cursor to store, at most every
-     * {@link CHECKPOINT_MIN_MS} — and once more the moment the session id appears.
-     *
-     * Fire-and-forget onto the same chain the notes ride, so a storage write
-     * cannot stall the read loop and cannot land before the notes it claims are
-     * already posted.
-     *
-     * **The id does not wait for the interval.** It is the handle to everything
-     * that follows — the one thing that lets a later run continue this
-     * conversation — and a session killed inside the first interval would
-     * otherwise leave none. One extra write per session buys that.
-     */
-    const offerCheckpoint = () => {
-        const sink = options.onCheckpoint;
-        // **Refused without `onProgress`, not merely discouraged.** A checkpoint is
-        // only safe because the notes behind it have been filed; offered to a
-        // caller that files nothing, it advances a cursor past notes that were never
-        // delivered, and a drain dying after it loses them permanently. The
-        // documented unsafe combination is one nothing can reach.
-        if (!sink || !options.onProgress || rejected)
-            return;
-        if (newHandle)
-            newHandle = false;
-        else if (now() - checkpointedAt < CHECKPOINT_MIN_MS)
-            return;
-        checkpointedAt = now();
-        const at = checkpoint();
-        // Checked again on the chain: a note queued ahead of this one may yet be
-        // rejected, and this cursor names it.
-        sunk = sunk
-            .then(() => {
-            if (rejected)
-                return;
-            safe = at;
-            return sink(at);
-        })
-            .catch(() => { });
-    };
-    const finish = async (code) => {
-        // Everything the sink was given has been delivered before the outcome
-        // naming it is returned, so a caller cannot store a cursor that claims
-        // notes nobody filed. After a rejected note it is the last cursor behind
-        // it: the caller stores it, and a drain resumed from there files the note
-        // again, while the notes after it replay under keys the transcript dedupes.
-        await sunk;
-        const next = rejected ? safe : checkpoint();
-        return code === undefined
-            ? {
-                done: false,
-                cursor: next,
-                progress,
-                ...(rateLimit ? { rateLimit } : {})
-            }
-            : {
-                done: true,
-                cursor: next,
-                progress,
-                ...(rateLimit ? { rateLimit } : {}),
-                exitCode: code,
-                ...(result ? { result } : {}),
-                // Only when there is no result. A session that reported for itself has
-                // said everything worth saying, and its stderr is the CLI's own
-                // diagnostic chatter — surfacing that beside a perfectly good report
-                // would bury the report.
-                ...(!result && (SIGNALS[code] || stderr)
-                    ? { stderr: explainExit(code, stderr) }
-                    : {})
-            };
-    };
-    try {
-        for (;;) {
-            /**
-             * Once the process has exited, stop racing the clock and read to the end.
-             *
-             * This is the single most important branch in the file. The stream
-             * `@cloudflare/computer` hands back is wrapped by `withPostPull`, and that
-             * wrapper runs **the container-to-workspace filesystem sync** when — and
-             * only when — the underlying stream reaches `done`. Returning on the
-             * `exit` event instead would leave it unread, so a session's edits would
-             * never reach the durable checkout: the run reports success, the files are
-             * simply not there.
-             *
-             * Reading on is also how the sync gets *awaited*: the wrapper resolves its
-             * pull before it closes the stream, so observing `done` means the pull was
-             * attempted. Attempted, not guaranteed — a pull that fails leaves the
-             * stream closing normally and reports itself on the result the host does
-             * not see here, and nothing retries it on its own. The host drives any
-             * outstanding pull; see this plugin's README.
-             *
-             * It is also unbounded, deliberately: the pull carries whatever the
-             * session wrote, an install's dependency tree included. Cutting it short
-             * would trade a late report for edits that never land, and that trade is
-             * not close: a drain cut with the pull still in flight is resumed, and
-             * the sync resumes from the blocks it has already committed. A pull that
-             * *fails* is the case above, and nothing retries that.
-             */
-            if (exitCode !== undefined) {
-                const next = await reader.read();
-                if (next.done)
-                    return await finish(exitCode);
-                consume(next.value);
-                continue;
-            }
-            if (options.signal?.aborted)
-                return await stop();
-            const stopping = stopped(options.signal);
-            const next = await Promise.race([
-                reader.read(),
-                stopping.promise
-            ]).finally(stopping.clear);
-            if (next === STOPPED)
-                return await stop();
-            if (next.done) {
-                // The stream ended without an `exit` event — the container went away
-                // under the run. Report it as a failure rather than as still-running,
-                // or the caller would wait on a dead process.
-                stderr = containerLost(stderr);
-                return await finish(-1);
-            }
-            consume(next.value);
-        }
-    }
-    catch (err) {
-        // See `sunk`. It never rejects: each link catches its own.
-        await sunk;
-        throw err;
-    }
-    finally {
-        reader.releaseLock();
-    }
-    function consume(event) {
-        seq = event.seq;
-        if (event.name === "stdout" && event.value !== undefined) {
-            buffer += event.value;
-            absorb();
-            // After absorbing, never before: the position offered has to be one whose
-            // notes are already on the sink's queue.
-            offerCheckpoint();
-        }
-        // stderr is Claude Code's own diagnostics, not the protocol stream. Kept out
-        // of the parser so a warning line cannot be mistaken for an event — but
-        // **kept**, which it was not, because a process that dies before its first
-        // JSON line leaves nothing else behind. See `DrainCursor.stderr`.
-        if (event.name === "stderr" && event.value !== undefined) {
-            stderr = boundStderr(stderr + event.value);
-        }
-        if (event.name === "exit")
-            exitCode = event.code ?? -1;
-    }
-    /**
-     * End the drain with the session still running.
-     *
-     * **Cancels rather than merely releasing the lock.** Releasing leaves the
-     * attachment and its pending read alive on the far side, and the next drain
-     * would find it still subscribed. `cancel` is the wrapper's own designed exit
-     * — it settles the pending read, resolves the sync outcome as `pending`, and
-     * lets the next `getExec` open a fresh attachment that will run the real sync
-     * when the session finally ends.
-     *
-     * **Cancels before settling the sinks, not after**, so the attachment is not
-     * held open across notes still being filed. Safe in this order because
-     * `finish` reads only what `consume` already put in local state, and takes
-     * nothing off the stream.
-     */
-    async function stop() {
-        absorb();
-        await reader.cancel("drain stopped").catch(() => { });
-        return await finish();
-    }
-}
-/**
- * The signal behind each exit code `computerd` maps one to — the ones a process
- * is stopped from outside with.
- */
-const SIGNALS = { 143: "SIGTERM", 137: "SIGKILL" };
-/** A resultless session's `stderr`, explained when a signal ended it. */
-function explainExit(code, stderr) {
-    const signal = SIGNALS[code];
-    if (!signal)
-        return stderr;
-    return endedFromOutside(`the process was stopped by ${signal} before it reported a result — its ` +
-        "container stopping, its time limit or a cancel does this.", stderr);
-}
-/**
- * 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 function containerLost(printed = "") {
-    return endedFromOutside("the container holding this session was stopped or replaced before the " +
-        "session finished — a deploy or a container rollout does this — so the " +
-        "process was ended from outside and reported no result.", printed);
-}
-/**
- * The report for a process that did not end on its own: why, what that leaves,
- * then what it had printed.
- *
- * **The cause comes first.** What the process printed is not why it ended, and
- * without this it is all a report shows — so whatever came last, a startup
- * warning included, reads as the cause.
- *
- * **What it must not say is that starting over is safe.** A session is an
- * agent: by the time it was stopped, it may have written files that reached the
- * workspace, committed, pushed, or called something outside altogether. None of
- * that is visible from here — only that the process is gone — so the honest
- * report is what is known plus where to look, and the decision belongs to
- * whoever can read the durable state.
- */
-function endedFromOutside(cause, printed) {
-    const said = printed.trim();
-    return (`${cause} What it had already written to the workspace is still there, ` +
-        "and anything it did outside the workspace — a commit, a push, a request — " +
-        "has already happened. Check the workspace and the branch before starting " +
-        "this work again, since a rerun repeats from the beginning." +
-        (said
-            ? `\n\nWhat it had printed by then, which is not why it ended:\n${said}`
-            : ""));
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * The caller's signal, as a race a read can win.
- *
- * Cleared by the caller whichever side wins: one listener is added per read,
- * and a session is many reads.
- */
-function stopped(signal) {
-    let onAbort = () => { };
-    const promise = new Promise((resolve) => {
-        onAbort = () => resolve(STOPPED);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-    return {
-        promise,
-        clear: () => signal?.removeEventListener("abort", onAbort)
-    };
-}
-/** How much stderr is worth carrying, in characters. */
-const STDERR_MAX = 2_000;
-/**
- * Keep stderr bounded, from both ends.
- *
- * Applied on every append rather than once at the end, so a session that prints
- * megabytes to stderr — a verbose build, a runaway loop — cannot grow a Durable
- * Object's memory while it does it.
- *
- * Head *and* tail because which end carries the answer depends on how the
- * process died, and the caller cannot know in advance: a Node crash puts its
- * error first and a stack after it, while a CLI that validates its arguments and
- * gives up prints one line and exits, making that line the last thing there is.
- * Keeping both ends costs a few hundred characters and removes the guess.
- *
- * Not `truncateOutput`, and the difference is the marker: this runs on every
- * append, so the cut has to stay a single character rather than a sentence that
- * would be re-cut and nested on the next one.
- */
-function boundStderr(text) {
-    if (text.length <= STDERR_MAX)
-        return text;
-    const half = Math.floor((STDERR_MAX - 1) / 2);
-    return `${text.slice(0, half)}…${text.slice(-half)}`;
-}
-/**
- * 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 async function killRun(runtime, execId) {
-    await runtime.killExec(execId, { signal: "SIGTERM" });
-}