@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/workspace/deps-snapshot.js

@@ -0,0 +1,424 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { DEPS_ROOTS_COMMAND, parseDepsRoots } from "./container-deps.js";
+/**
+ * A snapshot of a container that has just installed, so the next container
+ * starts from it instead of installing again.
+ *
+ * Dependency trees live on the container's disk (see `./container-deps.ts`), so
+ * a new container reinstalls before its first command can use them — what that
+ * costs is in `./install-job.ts`. A Containers snapshot is that disk: restored,
+ * the trees are back. It holds nothing else worth having — the checkout is this
+ * object's storage, mounted over FUSE, and a mount is not in a snapshot.
+ *
+ * ## When a snapshot is restored
+ *
+ * Only into a start that would otherwise install the same thing, which takes
+ * all of:
+ *
+ * - **The image it was taken on.** A snapshot replaces the image rather than
+ *   layering on it, so one from before a deploy boots the old image's
+ *   `computerd`, which nothing downstream catches.
+ * - **The same checkout and install fingerprint**, so the marker it carries is
+ *   the one an install would write now.
+ * - **Every package root's inputs unchanged.** A bootstrap installs roots the
+ *   fingerprint does not cover — a submodule's lockfile — and a restore brings
+ *   all of them back at once.
+ * - **The same set of package roots.** A root added since — a new submodule —
+ *   has no tree in the snapshot, and restoring it would skip the install that
+ *   gives it one: see {@link packageRootSet}.
+ *
+ * What came up is then checked, not assumed: the setup mounts the restored trees
+ * and reads the marker, and only a match is adopted as installed. Anything else —
+ * an expired snapshot, which the platform reports as a failed start, after which
+ * the backend's restart takes the image — drops the record, and the install runs
+ * and snapshots again.
+ *
+ * ## Taken of the tree it was asked for, and nothing since
+ *
+ * An install asks for its snapshot in the same write as its verdict, so a stop
+ * that comes before the wake still sees the request. Snapshots run one at a
+ * time, and one is recorded only if the install record still names the tree it
+ * was taken of: a reinstall empties the tree before it rebuilds it, and a
+ * snapshot taken across that is of neither.
+ *
+ * ## The record outlives the container, and the snapshot outlives the record
+ *
+ * Unlike the tree record, which goes with its container, this is what a later
+ * container starts from. The platform keeps a snapshot for thirty days from its
+ * last restore and offers no way to delete one, so a dropped record leaves its
+ * snapshot to expire.
+ */
+/** Where the record lives. */
+const RECORD_KEY = "deps:snapshot";
+/** The tree a finished install asked to have snapshotted, until it is. */
+const DUE_KEY = "deps:snapshot-due";
+/**
+ * Which package roots a checkout has, as one digest: every directory under
+ * `dir` with a `package.json`, and the submodules `.gitmodules` declares — one a
+ * bootstrap clones in the container has no `package.json` here until then.
+ */
+export async function packageRootSet(fs, dir) {
+    const found = await fs
+        .find(dir, "**/package.json", { exclude: ["**/.git", "**/node_modules"] })
+        .catch((err) => {
+        if (err?.code === "ENOENT")
+            return [];
+        throw err;
+    });
+    const gitmodules = await fs
+        .readFile(`${dir}/.gitmodules`, "utf8")
+        .catch(() => "");
+    const input = [
+        ...found.map((entry) => entry.path).sort(),
+        "\0.gitmodules",
+        gitmodules
+    ].join("\n");
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * The launch options `ContainerBackend` spreads into every start, whose
+ * `containerSnapshot` is read at that moment.
+ *
+ * A getter, because the backend keeps this object for its lifetime and builds
+ * each start from it — the initial one and every restart after a failed health
+ * check — and only the first of those may restore: a restart is the backend
+ * recovering from a start that did not come up, which an expired snapshot is.
+ */
+function launchOptions(take) {
+    return {
+        get containerSnapshot() {
+            return take();
+        }
+    };
+}
+export class DepsSnapshot {
+    deps;
+    /** Restore with the next start, once. */
+    #pending;
+    /** Whether a start has taken {@link #pending} since it was armed. */
+    #launched = false;
+    #taking;
+    launch = launchOptions(() => {
+        const pending = this.#pending;
+        if (!pending)
+            return undefined;
+        this.#pending = undefined;
+        this.#launched = true;
+        return pending;
+    });
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Restore with the next start if the record fits it, and say which record.
+     *
+     * `expected` is a thunk because it reads the checkout, and a workspace with no
+     * snapshot or one from another image should not pay for that.
+     */
+    async arm(expected) {
+        this.disarm();
+        const record = await this.get();
+        if (!record)
+            return undefined;
+        const refused = await this.#refusal(record, expected);
+        if (refused) {
+            console.info(`[${this.deps.tag()}] not restoring the dependency snapshot`, {
+                id: this.deps.id(),
+                snapshot: record.id,
+                reason: refused
+            });
+            return undefined;
+        }
+        this.#pending = { id: record.id };
+        console.info(`[${this.deps.tag()}] restoring the dependency snapshot`, {
+            id: this.deps.id(),
+            snapshot: record.id,
+            bytes: record.size,
+            dir: record.dir
+        });
+        return record;
+    }
+    /** Forget an armed restore, taken or not. */
+    disarm() {
+        this.#pending = undefined;
+        this.#launched = false;
+    }
+    /**
+     * Whether the container that came up holds `record`'s tree, judged by the
+     * marker the setup read in it.
+     *
+     * Drops the record when a start took it and the tree is not there; leaves it
+     * when no start did, since nothing was learned about it.
+     */
+    async restored(record, marker) {
+        if (!this.#launched)
+            return false;
+        if (marker === record.fingerprint)
+            return true;
+        await this.#drop(record, marker === undefined
+            ? "the restored container could not be read"
+            : "the restored container does not hold the tree");
+        return false;
+    }
+    /**
+     * Snapshot the running container, which has just installed `tree`, after any
+     * snapshot already in flight — a later install's request is never dropped for
+     * an earlier one's.
+     *
+     * Never throws: a container that cannot be snapshotted installs again next
+     * time, which is today's cost and no worse.
+     */
+    async take(tree) {
+        const turn = (this.#taking ?? Promise.resolve()).then(() => this.#take(tree));
+        this.#taking = turn;
+        try {
+            await turn;
+        }
+        finally {
+            if (this.#taking === turn)
+                this.#taking = undefined;
+        }
+    }
+    /** Snapshots in flight, finished — for whatever is about to stop the container. */
+    async settled() {
+        await this.#taking;
+    }
+    /**
+     * The entries that ask for `tree`'s snapshot, for the install to write with
+     * its verdict — see the file comment, and {@link takeDue}.
+     */
+    dueEntries(tree) {
+        return { [DUE_KEY]: tree };
+    }
+    /** Take the snapshot an install asked for, if one is waiting. */
+    async takeDue() {
+        const due = await this.deps.storage.get(DUE_KEY);
+        if (!due)
+            return;
+        await this.deps.storage.delete(DUE_KEY);
+        await this.take(due);
+    }
+    /** The container went, and the disk an asked-for snapshot was of with it. */
+    async forgetDue() {
+        await this.deps.storage.delete(DUE_KEY);
+    }
+    async get() {
+        return await this.deps.storage.get(RECORD_KEY);
+    }
+    /**
+     * Start from another workspace's snapshot — one taken for the same checkout
+     * path on the same image, as a worktree shares with the checkout it was cut
+     * from.
+     *
+     * Kept out when this workspace's own snapshot already fits, and refused when
+     * the offered one does not.
+     */
+    async seed(record, expected) {
+        if (!isRecord(record))
+            return { seeded: false, reason: "not a snapshot" };
+        const now = await expected();
+        const fits = async () => now;
+        const own = await this.get();
+        if (own && !(await this.#refusal(own, fits)))
+            return { seeded: false, reason: "this workspace's own snapshot fits" };
+        const refused = await this.#refusal(record, fits);
+        if (refused)
+            return { seeded: false, reason: refused };
+        await this.deps.storage.put(RECORD_KEY, record);
+        console.info(`[${this.deps.tag()}] seeded a dependency snapshot`, {
+            id: this.deps.id(),
+            snapshot: record.id,
+            dir: record.dir
+        });
+        return { seeded: true };
+    }
+    /**
+     * Why `record` must not be restored now, or `undefined` if it may. A check
+     * that throws refuses: a start must not fail for a snapshot it can go without.
+     */
+    async #refusal(record, expected) {
+        if (record.image !== this.deps.image())
+            return "taken on another image";
+        try {
+            const tree = await expected();
+            if (!tree)
+                return "there is nothing to install here";
+            if (record.dir !== tree.dir)
+                return "taken for another checkout";
+            if (record.fingerprint !== tree.fingerprint)
+                return "the install's inputs have changed";
+            for (const root of record.roots) {
+                if ((await this.deps.rootFingerprint(root.dir)) !== root.fingerprint)
+                    return `${root.dir} has changed`;
+            }
+            if ((await packageRootSet(this.deps.workspace().fs, tree.dir)) !==
+                record.rootSet)
+                return "the checkout's package roots have changed";
+            return undefined;
+        }
+        catch (err) {
+            return `it could not be checked: ${String(err)}`;
+        }
+    }
+    /** Whether the install record still names `tree`. */
+    async #holds(tree) {
+        const now = await this.deps.tree();
+        return (now?.dir === tree.dir &&
+            now.fingerprint === tree.fingerprint &&
+            now.at === tree.at);
+    }
+    async #drop(record, reason) {
+        // Only this record: a later install may have put a newer one there.
+        if ((await this.get())?.id === record.id)
+            await this.deps.storage.delete(RECORD_KEY);
+        console.warn(`[${this.deps.tag()}] dropped the dependency snapshot`, {
+            id: this.deps.id(),
+            snapshot: record.id,
+            reason
+        });
+    }
+    async #take(tree) {
+        const container = this.deps.container();
+        const image = this.deps.image();
+        if (!container?.running || image === undefined)
+            return;
+        // Replaced, or reinstalling, since the install asked.
+        if (!(await this.#holds(tree)))
+            return;
+        const startedAt = Date.now();
+        try {
+            const roots = await this.#roots();
+            // Without a root to mount, a restore would read no marker and be dropped.
+            if (roots.length === 0) {
+                console.warn(`[${this.deps.tag()}] no dependency tree to snapshot on this disk`, { id: this.deps.id(), dir: tree.dir });
+                return;
+            }
+            const fingerprinted = [];
+            for (const dir of roots)
+                fingerprinted.push({
+                    dir,
+                    fingerprint: await this.deps.rootFingerprint(dir)
+                });
+            const rootSet = await packageRootSet(this.deps.workspace().fs, tree.dir);
+            const snapshot = await container.snapshotContainer({
+                name: `deps-${tree.fingerprint.slice(0, 16)}`
+            });
+            if (!(await this.#holds(tree))) {
+                console.warn(`[${this.deps.tag()}] discarded a dependency snapshot taken while the tree changed`, { id: this.deps.id(), snapshot: snapshot.id, dir: tree.dir });
+                return;
+            }
+            await this.deps.storage.put(RECORD_KEY, {
+                id: snapshot.id,
+                size: snapshot.size,
+                image,
+                dir: tree.dir,
+                fingerprint: tree.fingerprint,
+                roots: fingerprinted,
+                rootSet,
+                at: Date.now()
+            });
+            console.info(`[${this.deps.tag()}] took a dependency snapshot`, {
+                id: this.deps.id(),
+                snapshot: snapshot.id,
+                bytes: snapshot.size,
+                roots,
+                ms: Date.now() - startedAt
+            });
+        }
+        catch (err) {
+            console.warn(`[${this.deps.tag()}] could not take a dependency snapshot`, {
+                id: this.deps.id(),
+                err: String(err)
+            });
+        }
+    }
+    /** The package roots whose trees are on this container's disk. */
+    async #roots() {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const handle = __addDisposableResource(env_1, await this.deps
+                .workspace()
+                .runtime.exec(DEPS_ROOTS_COMMAND, {
+                cwd: "/",
+                encoding: "utf8",
+                timeoutMs: 30_000
+            }), false);
+            const result = await handle.result();
+            if (result.exitCode !== 0)
+                throw new Error(`could not list the dependency trees: ${result.stderr || `exit ${result.exitCode}`}`);
+            return parseDepsRoots(result.stdout ?? "");
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+}
+/** Enough of a record's shape to restore from — it arrives over RPC. */
+function isRecord(value) {
+    const r = value;
+    return (typeof r?.id === "string" &&
+        typeof r.image === "string" &&
+        typeof r.dir === "string" &&
+        typeof r.fingerprint === "string" &&
+        typeof r.rootSet === "string" &&
+        Array.isArray(r.roots) &&
+        r.roots.every((root) => typeof root?.dir === "string"));
+}

package/dist/workspace/exec.d.ts

@@ -0,0 +1,94 @@
+import { type WorkspaceHost } from "./open.js";
+/**
+ * Running a command in a workspace's container, from outside the workspace
+ * object: what `/computer`'s tools and `/repo`'s git share, and how a host
+ * reaches its own container.
+ */
+/** A command that has not finished in this long is a hung command. */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Where checkouts live, in the container and in the workspace alike. */
+export declare const DEFAULT_CWD = "/workspace";
+/** Which workspace a caller reaches, and how its commands run there. */
+export interface WorkspaceClientConfig {
+    /**
+     * The Durable Object namespace holding workspaces, closed over at
+     * instantiation so it is never model input.
+     */
+    binding: DurableObjectNamespace<WorkspaceHost>;
+    /**
+     * Which workspace this agent gets, by name. A thunk because the useful name —
+     * caller plus repository — does not exist when the plugin list is built.
+     *
+     * One workspace is one container is one repository: `@cloudflare/computer`
+     * pairs a Durable Object with exactly one container, so "never mix two
+     * repositories" is structural here rather than a convention to maintain.
+     */
+    workspaceName: () => string;
+    /** Working directory for every command. Defaults to `/workspace`. */
+    cwd?: string;
+    /**
+     * Run every command through this shell, e.g. `"bash"`. Unset, the command
+     * string goes to the runtime as-is and lands on whatever `/bin/sh` is.
+     *
+     * Worth setting, because "whatever `/bin/sh` is" is **dash** on Debian and
+     * Ubuntu, and a model writing shell writes *bash*. `${PIPESTATUS[0]}` is the
+     * one that costs most — a bash builtin a model reaches for to read a piped exit
+     * code, which dash fails with exit 2, after the command it wrapped has already
+     * run. It is one member of a family (`[[ ]]`, arrays, `set -o pipefail`,
+     * process substitution), so the fix is the shell rather than a note in a prompt
+     * telling the model to write POSIX.
+     *
+     * Set it only if the image actually has that shell: a missing one fails *every*
+     * command rather than the bash-flavoured ones.
+     */
+    shell?: string;
+    /** Per-command timeout. Defaults to ten minutes. */
+    timeoutMs?: number;
+}
+/**
+ * An `exec` bound to this workspace, for plugins that need a shell but should
+ * not own a container.
+ *
+ * `@dynamicagents/plugins/repo` is the reason this exists: it needs `git` on a real
+ * shell, but depending on this module would weld the two together and stop a
+ * host from pointing it at its own container. Structurally typed for the same
+ * reason — the two plugins compose without either importing the other.
+ *
+ * ## The agent tools' `env` is deliberately **not** merged here
+ *
+ * `/computer`'s `ComputerConfig.env` is merged into every command its tools
+ * run; this takes no environment of its own.
+ *
+ * What this hands out is a raw shell to *another plugin*, whose commands this
+ * module neither writes nor sees. `/repo` runs its unauthenticated git through
+ * it and pins the environment those need — `GIT_TERMINAL_PROMPT=0` plus the
+ * model-authored values it passes as variables. A host environment merged
+ * underneath lets through every key it does *not* pin: `http_proxy`,
+ * `GIT_PROXY_COMMAND`, `GIT_SSL_CAINFO`, `GIT_CONFIG_GLOBAL`, `GIT_EXEC_PATH` —
+ * the last two redirect the config git reads and relocate its helper binaries.
+ *
+ * No token is at stake, since the credentialed operations do not run here at
+ * all. The point is that changing what git does inside another plugin's commands
+ * should not be something a tools plugin's config field does by accident,
+ * from a host that only meant to set a registry. A host that wants it composes
+ * it where the merge is visible:
+ *
+ * ```ts
+ * exec: (command, options) =>
+ *   workspaceExec(config)(command, {
+ *     ...options,
+ *     env: { ...mine, ...options?.env }
+ *   });
+ * ```
+ */
+export declare function workspaceExec(config: WorkspaceClientConfig): (command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeout?: number;
+    runtime?: unknown;
+}) => Promise<{
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/workspace/exec.js

@@ -0,0 +1,153 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { cancelledNote } from "./format.js";
+import { openWorkspace, workspaceNameFromRuntime } from "./open.js";
+import { withShell } from "./shell.js";
+/**
+ * Running a command in a workspace's container, from outside the workspace
+ * object: what `/computer`'s tools and `/repo`'s git share, and how a host
+ * reaches its own container.
+ */
+/** A command that has not finished in this long is a hung command. */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/** Where checkouts live, in the container and in the workspace alike. */
+export const DEFAULT_CWD = "/workspace";
+/**
+ * An `exec` bound to this workspace, for plugins that need a shell but should
+ * not own a container.
+ *
+ * `@dynamicagents/plugins/repo` is the reason this exists: it needs `git` on a real
+ * shell, but depending on this module would weld the two together and stop a
+ * host from pointing it at its own container. Structurally typed for the same
+ * reason — the two plugins compose without either importing the other.
+ *
+ * ## The agent tools' `env` is deliberately **not** merged here
+ *
+ * `/computer`'s `ComputerConfig.env` is merged into every command its tools
+ * run; this takes no environment of its own.
+ *
+ * What this hands out is a raw shell to *another plugin*, whose commands this
+ * module neither writes nor sees. `/repo` runs its unauthenticated git through
+ * it and pins the environment those need — `GIT_TERMINAL_PROMPT=0` plus the
+ * model-authored values it passes as variables. A host environment merged
+ * underneath lets through every key it does *not* pin: `http_proxy`,
+ * `GIT_PROXY_COMMAND`, `GIT_SSL_CAINFO`, `GIT_CONFIG_GLOBAL`, `GIT_EXEC_PATH` —
+ * the last two redirect the config git reads and relocate its helper binaries.
+ *
+ * No token is at stake, since the credentialed operations do not run here at
+ * all. The point is that changing what git does inside another plugin's commands
+ * should not be something a tools plugin's config field does by accident,
+ * from a host that only meant to set a registry. A host that wants it composes
+ * it where the merge is visible:
+ *
+ * ```ts
+ * exec: (command, options) =>
+ *   workspaceExec(config)(command, {
+ *     ...options,
+ *     env: { ...mine, ...options?.env }
+ *   });
+ * ```
+ */
+export function workspaceExec(config) {
+    return async (command, options) => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // The caller forwards its sub-agent's runtime opaquely; only this side
+            // knows the key it might carry. That is what lets `/repo` reach a sub-agent's
+            // shared workspace without importing anything from here.
+            const name = workspaceNameFromRuntime(options?.runtime) ?? config.workspaceName();
+            const ws = __addDisposableResource(env_1, await openWorkspace(config.binding.get(config.binding.idFromName(name))), false);
+            const env = options?.env
+                ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== undefined))
+                : undefined;
+            // Named rather than inlined, because the note below has to state it: a
+            // ceiling the model cannot see is one it cannot work within.
+            const timeoutMs = options?.timeout ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            // `withShell`, never `withShellTranscript`: the caller reads this result in
+            // code. `/repo` compares `stdout` against a URL, tests it for emptiness to
+            // decide a tree is clean, and reads a sha out of it to push — all of which
+            // need `stdout` to carry the answer alone, with git's diagnostics on the
+            // channel git put them on.
+            const handle = __addDisposableResource(env_1, await ws.runtime.exec(withShell(command, config.shell), {
+                cwd: options?.cwd ?? config.cwd ?? DEFAULT_CWD,
+                encoding: "utf8",
+                timeoutMs,
+                ...(env ? { env } : {})
+            }), false);
+            const result = await handle.result();
+            const killed = cancelledNote(result.status, result.exitCode, timeoutMs);
+            return {
+                // `/repo` branches on `success`, which this runtime does not report — it
+                // has `status` and `exitCode`. Derived from the exit code rather than the
+                // status, because a command that runs and fails is `completed` here.
+                success: result.exitCode === 0,
+                stdout: result.stdout,
+                // Appended rather than substituted: a command killed at the ceiling may
+                // well have written plenty first, and that output is the more useful half.
+                // This is the only field the note can travel on — `stdout` is a data
+                // channel the caller parses, and the four fields are the whole contract.
+                stderr: killed
+                    ? [result.stderr, killed].filter(Boolean).join("\n")
+                    : result.stderr,
+                exitCode: result.exitCode
+            };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    };
+}