@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/workspace/container-deps.js

@@ -0,0 +1,224 @@
+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 { shellQuote } from "@cloudflare/computer";
+import { deploymentFault } from "./container-fault.js";
+/**
+ * Dependency trees live on the container's disk, never in the workspace.
+ *
+ * A tree in the workspace is written through FUSE into computerd's in-memory
+ * store, pulled into this object's SQLite, and pushed back into every fresh
+ * container before its first command — measured at 76,740 entries and nine
+ * minutes for one cold container. So a package root's `node_modules` is a bind
+ * mount of container disk, and a new container reinstalls.
+ *
+ * The mount is made by the package manager's own invocation, through wrappers
+ * this installs ahead of the real binaries on `PATH`. Mounting earlier cannot
+ * work: a bootstrap that initialises submodules and installs each of them in one
+ * command creates the directories the mounts belong in.
+ */
+/** Where the trees live on the container's disk. */
+const DEPS_DISK = "/var/lib/workspace-deps";
+/** First on Debian's default `PATH`, so a wrapper here shadows the real tool. */
+const WRAPPER_DIR = "/usr/local/sbin";
+const MOUNT_HELPER = `${WRAPPER_DIR}/workspace-deps-mount`;
+/**
+ * Every entry point that can write a `node_modules`, wrapped whether or not it
+ * is installed yet: `corepack enable` or `npm i -g pnpm` adds one later.
+ */
+const WRAPPED = [
+    "npm",
+    "npx",
+    "pnpm",
+    "yarn",
+    "corepack",
+    "bun",
+    "bunx"
+];
+/** Written into the tree by a successful host install; see `./install-job.ts`. */
+export const INSTALLED_MARKER = ".da-installed";
+/**
+ * The per-container setup, and a read of the marker under `dir`.
+ *
+ * The helper mounts the package root the command targets — its directory, or
+ * `--prefix`, `--cwd`, `--dir`, `-C` — only under the workspace, never inside
+ * another tree. Workspace members are not mounted: a mount point cannot be
+ * removed, so one guessed into `dist/` breaks `rm -rf dist`, and an install at
+ * the root puts the bulk of the tree there.
+ *
+ * Wrappers are written with `install`, never through the path: `npm` is
+ * commonly a symlink to `npm-cli.js`, and writing through it replaces npm with a
+ * wrapper that execs itself. For the same reason a wrapper finds its tool on
+ * `PATH` with `WRAPPER_DIR` skipped, when it runs. `corepack enable` puts its
+ * shims beside the `corepack` on `PATH` — the wrapper — so it is pointed at the
+ * real one's directory instead.
+ */
+export function depsSetupCommand(workspaceDir, dir) {
+    const helper = [
+        "#!/bin/sh",
+        'cwd="$1"; dir="$1"; shift',
+        'while [ $# -gt 0 ]; do case "$1" in',
+        "  --) break;;",
+        '  --prefix=*|--cwd=*|--dir=*) dir="${1#*=}";;',
+        '  --prefix|--cwd|--dir|-C) [ $# -gt 1 ] && { dir="$2"; shift; };;',
+        "esac; shift; done",
+        'case "$dir" in /*) ;; *) dir="$cwd/$dir";; esac',
+        'dir=$(cd "$dir" 2>/dev/null && pwd -P) || exit 0',
+        'while [ "$dir" != / ] && [ ! -f "$dir/package.json" ]; do dir=$(dirname "$dir"); done',
+        `case "$dir" in */node_modules/*) exit 0;; ${workspaceDir}|${workspaceDir}/*) ;; *) exit 0;; esac`,
+        'nm="$dir/node_modules"',
+        'mountpoint -q "$nm" && exit 0',
+        `disk="${DEPS_DISK}/$(printf %s "$dir" | sha256sum | cut -c1-16)"`,
+        'mkdir -p "$disk" "$nm" && mount --bind "$disk" "$nm" && exit 0',
+        `echo "workspace-deps: could not put $nm on the container's disk" >&2`,
+        "exit 1"
+    ].join("\n");
+    const wrapper = [
+        "#!/bin/sh",
+        `${MOUNT_HELPER} "$PWD" "$@" || exit 1`,
+        'tool=$(basename "$0"); real=',
+        `IFS=:; for d in $PATH; do [ "$d" = ${WRAPPER_DIR} ] && continue; [ -x "$d/$tool" ] && { real="$d"; break; }; done; unset IFS`,
+        '[ -n "$real" ] || { echo "$tool: not found" >&2; exit 127; }',
+        'case "$tool:${1:-}:$*" in',
+        "  *--install-directory*) ;;",
+        '  corepack:enable:*|corepack:disable:*) cmd="$1"; shift; set -- "$cmd" --install-directory "$real" "$@";;',
+        "esac",
+        'exec "$real/$tool" "$@"'
+    ].join("\n");
+    return [
+        `printf '%s\\n' ${shellQuote(helper)} > /tmp/workspace-deps-mount`,
+        `install -m 755 /tmp/workspace-deps-mount ${MOUNT_HELPER} || exit 1`,
+        `printf '%s\\n' ${shellQuote(wrapper)} > /tmp/workspace-deps-wrap`,
+        `for tool in ${WRAPPED.join(" ")}; do install -m 755 /tmp/workspace-deps-wrap "${WRAPPER_DIR}/$tool" || exit 1; done`,
+        ...(dir
+            ? [
+                `echo "MARKER $(cat ${shellQuote(`${dir}/node_modules/${INSTALLED_MARKER}`)} 2>/dev/null || echo -)"`
+            ]
+            : []),
+        "echo SETUP OK"
+    ].join("\n");
+}
+/**
+ * The setup above, once per container.
+ *
+ * In memory, with {@link file://./ca-trust.ts}'s lifetime and for its reason: it
+ * describes one container, and an isolate that lost it re-runs an idempotent
+ * command.
+ */
+export class ContainerDeps {
+    deps;
+    #done = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    forget() {
+        this.#done = false;
+    }
+    /**
+     * Run the setup if this container has not had it, and report the marker under
+     * `dir`. `undefined` when it had, or with no `dir`.
+     *
+     * Throws when the container answered and the setup did not finish: nothing
+     * would say so later, since an unwrapped install succeeds, into the workspace.
+     * An unreachable container is only logged, like the CA install: the command
+     * after it fails the same way.
+     */
+    async ensure(dir) {
+        if (this.#done)
+            return undefined;
+        const startedAt = Date.now();
+        let output;
+        try {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const handle = __addDisposableResource(env_1, await this.deps
+                    .workspace()
+                    .runtime.exec(depsSetupCommand(this.deps.workspaceDir, dir), {
+                    cwd: "/",
+                    encoding: "utf8",
+                    timeoutMs: 30_000
+                }), false);
+                const result = await handle.result();
+                output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+                this.#done = result.exitCode === 0 && output.includes("SETUP OK");
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        catch (err) {
+            const fault = deploymentFault(err);
+            console.warn(`[${this.deps.tag()}] ${fault?.summary ?? "could not set up container dependencies"}`, {
+                id: this.deps.id(),
+                ...(fault ? { remedy: fault.remedy } : {}),
+                err: String(err)
+            });
+            return undefined;
+        }
+        console.info(`[${this.deps.tag()}] container dependency setup`, {
+            id: this.deps.id(),
+            ok: this.#done,
+            ms: Date.now() - startedAt,
+            ...(this.#done ? {} : { output })
+        });
+        if (!this.#done)
+            throw new Error(`could not put node_modules on the container's disk: ${output.trim() || "the setup exited without output"}`);
+        const marker = /^MARKER (.*)$/m.exec(output)?.[1]?.trim();
+        if (marker === undefined)
+            return undefined;
+        return { marker: marker === "-" ? null : marker };
+    }
+}

package/dist/workspace/container-fault.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The container failures that are the deployment's fault, not the workspace's.
+ *
+ * Everything else this host catches is the kind of thing a retry clears: a
+ * container that is starting, a connection that dropped, a command that died
+ * with it. These are not. They describe a Worker and a container application
+ * that cannot work together no matter how many times they are asked, and they
+ * end only when an operator deploys.
+ *
+ * **This changes what is said, not what is done.** No caller branches its
+ * control flow on the answer, and none should start: the match is on a string
+ * the library is free to reword, so a misread has to cost a misleading sentence
+ * rather than a workspace that stopped trying. What it earns is the log line.
+ * The cause is already in the thrown message, but a caller logs its own
+ * sentence and the cause travels in a detail field a log digest truncates — so
+ * an operator scanning for what broke reads the symptom ("could not trust the
+ * interception CA") and not the reason. {@link deploymentFault} is how a caller
+ * puts the reason in the message instead, and how the install record stops
+ * offering advice that cannot work.
+ */
+/**
+ * A failure no retry can clear, in the two registers a caller needs.
+ *
+ * `summary` is the log message: what is wrong, short enough to scan. `remedy`
+ * goes to whoever is blocked by it — it reaches a model through the install
+ * record, so it says what a person has to do rather than what a tool should try.
+ */
+export interface DeploymentFault {
+    readonly summary: string;
+    readonly remedy: string;
+}
+/**
+ * Whether this error says the deployment is wrong, and what to say about it.
+ *
+ * `undefined` for everything else, which is the answer that keeps the existing
+ * behaviour: a caller that gets it logs and retries exactly as before.
+ */
+export declare function deploymentFault(err: unknown): DeploymentFault | undefined;

package/dist/workspace/container-fault.js

@@ -0,0 +1,73 @@
+/**
+ * The container failures that are the deployment's fault, not the workspace's.
+ *
+ * Everything else this host catches is the kind of thing a retry clears: a
+ * container that is starting, a connection that dropped, a command that died
+ * with it. These are not. They describe a Worker and a container application
+ * that cannot work together no matter how many times they are asked, and they
+ * end only when an operator deploys.
+ *
+ * **This changes what is said, not what is done.** No caller branches its
+ * control flow on the answer, and none should start: the match is on a string
+ * the library is free to reword, so a misread has to cost a misleading sentence
+ * rather than a workspace that stopped trying. What it earns is the log line.
+ * The cause is already in the thrown message, but a caller logs its own
+ * sentence and the cause travels in a detail field a log digest truncates — so
+ * an operator scanning for what broke reads the symptom ("could not trust the
+ * interception CA") and not the reason. {@link deploymentFault} is how a caller
+ * puts the reason in the message instead, and how the install record stops
+ * offering advice that cannot work.
+ */
+/**
+ * Match on the shape the backend formats, not on the prose after it.
+ *
+ * `[stage=auth]` is the stage label `ContainerBackend` writes into every
+ * message it throws from that stage, and the container-application sentence is
+ * the runtime's own, surfaced verbatim through the backend's `priorExit=` field.
+ * `prepared images` is in both of the backend's refusals to start without an
+ * image — none prepared at all, and none under the key it was asked for — and
+ * survives the reconnect wrapper's truncation of either. All are stabler than
+ * the explanations they introduce, and none has a `code` to key on the way a
+ * lost exec does.
+ */
+const AUTH_STAGE = "[stage=auth]";
+const NO_APPLICATION = "no container application";
+const NO_IMAGE = "prepared images";
+/**
+ * Whether this error says the deployment is wrong, and what to say about it.
+ *
+ * `undefined` for everything else, which is the answer that keeps the existing
+ * behaviour: a caller that gets it logs and retries exactly as before.
+ */
+export function deploymentFault(err) {
+    const text = String(err);
+    if (text.includes(AUTH_STAGE))
+        return {
+            summary: "the container image is older than this Worker",
+            remedy: "the container is running an image that predates this Worker, so the " +
+                "two cannot authenticate and nothing can reach it. The image and the " +
+                "Worker are released as a pair and have to be deployed together, so " +
+                "this clears when an operator redeploys the Worker with its container " +
+                "image — no command here can recover it."
+        };
+    if (text.includes(NO_APPLICATION))
+        return {
+            summary: "this Worker has no container application",
+            remedy: "the container application this workspace starts containers from does " +
+                "not exist, so no container can start. Deploying the Worker is what " +
+                "creates it — deleting it does not cause it to be rebuilt — so this " +
+                "clears when an operator redeploys, and not before."
+        };
+    if (text.includes(NO_IMAGE))
+        return {
+            summary: "this Worker prepared no image for the workspace container",
+            remedy: "the container application has no image under the name this workspace " +
+                "starts, so no container can start. The workspace schedules its own " +
+                'containers, which takes `scheduling_policy: "durable_object"` and an ' +
+                "`images` entry for that name in the Worker's containers block, and an " +
+                "application created under another policy is deleted before that " +
+                "deploy rather than switched. This clears when an operator redeploys " +
+                "with both in place, and not before."
+        };
+    return undefined;
+}

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);
+        }
+    };
+}

package/dist/workspace/format.d.ts

@@ -0,0 +1,36 @@
+import type { WorkspaceRuntimeStatus } from "@cloudflare/computer";
+/**
+ * Text shared by the workspace and the tools over it: the output bound, the
+ * elapsed-time phrase, and what a killed command is told.
+ */
+/**
+ * Middle-out truncation, so both the first error and the final summary survive.
+ *
+ * The guard is not defensive padding. Without it a `max` at or below the marker's
+ * own length makes `half` zero or negative, and `slice(-0)` is `slice(0)` — the
+ * *whole* string — so the function returns more than it was given: 500 characters
+ * in, 543 out at `max: 80`. A silent inversion of the one thing it does,
+ * reachable from a public config field.
+ */
+export declare function truncateOutput(text: string, max: number): string;
+/** Elapsed time in the shape a sentence wants. */
+export declare function humanMs(ms: number): string;
+/**
+ * Why a command has nothing to show for itself.
+ *
+ * {@link renderResult} states a non-`completed` status on its verdict line;
+ * {@link file://./exec.ts workspaceExec} has no verdict line, only the four fields its caller
+ * branches on. A *killed* process writes nothing, so without this a `git clone`
+ * that hit the ten-minute ceiling reaches the model through
+ * `@dynamicagents/plugins/repo` as `clone failed:` with an empty reason — which reads
+ * like a bug in the plugin rather than a limit it can work within.
+ *
+ * Only `cancelled`. A `failed` status is an ordinary non-zero exit, where the
+ * command's own stderr is the better explanation and this would be noise on top
+ * of it.
+ *
+ * Both plausible causes are named because the exit code cannot separate them:
+ * 137 is SIGKILL, which is what the timeout sends *and* what the kernel sends a
+ * container that ran out of memory.
+ */
+export declare function cancelledNote(status: WorkspaceRuntimeStatus | undefined, exitCode: number, timeoutMs: number): string | undefined;