@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/repo/url.js

@@ -6,7 +6,7 @@
  * naming it": every pattern here turns away a string that resolves to something
  * other than what it appears to name.
  */
-/** The forges a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
+/** The hosts a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
 export const DEFAULT_ALLOWED_HOSTS = ["github.com"];
 /** Branch names a push must never target, whatever the model believes. */
 export const PROTECTED_BRANCHES = new Set([
@@ -88,7 +88,7 @@ export function sameRepoUrl(a, b) {
     return canonical(a) === canonical(b);
 }
 /**
- * A name a forge would actually issue — and one that is safe to use as a path
+ * A name GitHub would actually issue — and one that is safe to use as a path
  * segment and as a key.
  *
  * GitHub's rule for an owner and a repository alike is alphanumerics, `-`, `_`
@@ -101,17 +101,17 @@ export function sameRepoUrl(a, b) {
  * is a separator in somebody else's key format, which is how two callers end up
  * sharing one workspace.
  */
-const FORGE_NAME = /^[A-Za-z0-9._-]+$/;
-function isForgeName(name) {
+const GITHUB_NAME = /^[A-Za-z0-9._-]+$/;
+function isGitHubName(name) {
     // `.` and `..` pass the character class and are exactly the two that must not.
-    return name !== "." && name !== ".." && FORGE_NAME.test(name);
+    return name !== "." && name !== ".." && GITHUB_NAME.test(name);
 }
 /**
  * `owner/repo` out of a repository URL, or `undefined` if it is not one.
  *
  * Anchored on the **parsed host** rather than matched in the string, so
  * `https://evil.example.com/github.com/owner/repo` is not a github.com URL.
- * Both names are then checked against {@link isForgeName}, so a name that could
+ * Both names are then checked against {@link isGitHubName}, so a name that could
  * traverse a path or split somebody else's key never gets as far as being one.
  *
  * `undefined` is a refusal at every caller, never a reason to carry on with a
@@ -125,7 +125,7 @@ export function parseRepo(url, allowedHosts = DEFAULT_ALLOWED_HOSTS) {
     if (!match)
         return undefined;
     const [, owner, repo] = match;
-    if (!isForgeName(owner) || !isForgeName(repo))
+    if (!isGitHubName(owner) || !isGitHubName(repo))
         return undefined;
     return { owner, repo };
 }

package/dist/scratch/index.d.ts

@@ -42,7 +42,7 @@ import type { AgentPlugin } from "@dynamicagents/core";
 /** Where a scratchpad lives, unless the host says otherwise. */
 export declare const DEFAULT_SCRATCH_DIR = "/workspace/scratch";
 /**
- * Run one command in the host's container. Matches `computerExec`'s shape.
+ * Run one command in the host's container. Matches `workspaceExec`'s shape.
  *
  * Injected rather than imported, like `/repo`'s: `npm run verify:exports` fails
  * any subpath whose module graph reaches a sibling's, and a scratchpad that
@@ -54,7 +54,7 @@ export type ScratchExec = (command: string, options?: {
     env?: Record<string, string | undefined>;
     timeout?: number;
     /**
-     * The executing subtask's runtime state, forwarded **opaquely** — the same
+     * The running sub-agent's `runtime()`, forwarded **opaquely** — the same
      * pass-through `/repo` does, for the same reason. This plugin never looks
      * inside it.
      */
@@ -96,7 +96,7 @@ export interface ScratchConfig {
      * Runs commands in the container holding the workspace.
      *
      * Uncredentialed, and nothing here ever needs a credential: a scratchpad has
-     * no remote, so no operation in this plugin talks to a forge.
+     * no remote, so no operation in this plugin talks to GitHub.
      */
     exec: ScratchExec;
     /** Where the scratchpad lives. Defaults to {@link DEFAULT_SCRATCH_DIR}. */
@@ -153,6 +153,6 @@ export interface ScratchConfig {
  * carries the same copy for the same reason.
  */
 export declare function truncateOutput(text: string, max: number): string;
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export declare const SCRATCH_OPEN_TOOL = "scratch_open";
 export declare function scratch(config: ScratchConfig): AgentPlugin;

package/dist/scratch/index.js

@@ -68,10 +68,10 @@ export function truncateOutput(text, max) {
         return text.slice(0, Math.max(0, max));
     return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
 }
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export const SCRATCH_OPEN_TOOL = "scratch_open";
 /**
- * What the delegating agent is told.
+ * What the model is told.
  *
  * The mixing rule at the end is the line worth its tokens. A host that keys one
  * workspace selection per caller — which is what makes a scratchpad routable at
@@ -294,19 +294,20 @@ export function scratch(config) {
             .filter(Boolean)
             .join(" "), maxChars);
     };
+    const context = capabilityFor(dir);
     return definePlugin({
-        key: "scratch",
+        name: "scratch",
         /**
-         * The main agent's, and no tool family — which is a decision rather than an
-         * omission.
+         * For a parent, never a sub-agent — which the host decides by installing it
+         * on one and not the other.
          *
          * Opening a scratchpad *selects a workspace*, exactly as `repo_clone` does.
-         * A subagent holding this could re-point the workspace its parent prepared
+         * A sub-agent holding this could re-point the workspace its parent prepared
          * half-way through its own run, which is the hazard a host's per-caller
-         * selection already has to document. A delegated run works in whatever it
-         * was given.
+         * selection already has to document. A sub-agent works in whatever it was
+         * given.
          */
-        mainAgentTools: () => ({
+        tools: (ctx) => ({
             [SCRATCH_OPEN_TOOL]: tool({
                 description: "Open a scratchpad: a git repository with no remote, in your container, " +
                     "for work that does not need a cloned repository. Use it before " +
@@ -318,9 +319,9 @@ export function scratch(config) {
                         .optional()
                         .describe("Discard everything in the scratchpad first, including files an earlier task left")
                 }),
-                execute: ({ reset }) => open(reset, undefined)
+                execute: ({ reset }) => open(reset, ctx.runtime())
             })
         }),
-        capability: capabilityFor(dir)
+        context: [{ provider: { get: async () => context } }]
     });
 }

package/dist/{computer → workspace}/advisory.d.ts

@@ -17,9 +17,9 @@ import type { InstallState } from "./install.js";
  *   A ceiling is a hard wall about the Durable Object, and the two are then told
  *   apart only by reading prose.
  * - Capacity must not travel through a channel gated by
- *   {@link file://./gate.ts needsDependencies}, or a full workspace says nothing
+ *   {@link file://../computer/gate.ts needsDependencies}, or a full workspace says nothing
  *   at all to `echo hi > file.txt` — the command whose write is being lost.
- * - "The tree is fine now", after a subagent installed by hand, has no honest
+ * - "The tree is fine now", after an agent installed by hand, has no honest
  *   spelling as a job record: fabricating a `done` rests on the presence of a
  *   `node_modules` directory, which the wreckage of the very install being
  *   overridden already satisfies.
@@ -56,7 +56,7 @@ export type WorkspaceAdvisory = {
      * Reported rather than acted on, because its presence proves nothing in
      * either direction. A half-finished `npm ci` leaves the directory behind
      * with an incomplete tree, so treating existence as success hides the
-     * common failure outright; and a subagent that re-ran the install by hand
+     * common failure outright; and an agent that re-ran the install by hand
      * leaves a record the host cannot update, since the host cannot see an
      * install it did not start. Both look identical from here, so the reader
      * is told which way the ambiguity runs rather than being handed a guess.
@@ -181,7 +181,7 @@ export declare function deriveAdvisories(input: AdvisoryInput): readonly Workspa
 /**
  * Everything a session should know before it starts, or `undefined` for silence.
  *
- * The counterpart to {@link file://./gate.ts execGate}, for the reader that is a
+ * The counterpart to {@link file://../computer/gate.ts execGate}, for the reader that is a
  * whole run rather than one command. It cannot be blocked and does not need to
  * be: it can install dependencies itself, and the only thing it must not do is
  * work silently against a workspace that is not what it assumes.

package/dist/{computer → workspace}/advisory.js

@@ -1,4 +1,4 @@
-import { humanMs } from "./render.js";
+import { humanMs } from "./format.js";
 /** What each advisory *means*. The one exhaustive home for policy. */
 export function shapeOf(advisory) {
     switch (advisory.kind) {
@@ -188,7 +188,7 @@ export function deriveAdvisories(input) {
 /**
  * Everything a session should know before it starts, or `undefined` for silence.
  *
- * The counterpart to {@link file://./gate.ts execGate}, for the reader that is a
+ * The counterpart to {@link file://../computer/gate.ts execGate}, for the reader that is a
  * whole run rather than one command. It cannot be blocked and does not need to
  * be: it can install dependencies itself, and the only thing it must not do is
  * work silently against a workspace that is not what it assumes.

package/dist/{computer/host → workspace}/ca-trust.d.ts

@@ -70,7 +70,14 @@ export declare class ContainerTrust {
     #private;
     private readonly deps;
     constructor(deps: ContainerTrustDeps);
-    /** Forget that any container was trusted. */
+    /**
+     * Forget that any container was trusted.
+     *
+     * Drops the standing watch too, because this is also reached for a container
+     * that keeps running — a `running` read, a lost exec. The watch it leaves
+     * behind ignores that container's real exit, so without a fresh one nothing
+     * would clear the flag again and the replacement would be vouched for.
+     */
     forget(): void;
     /**
      * Trust the CA if this container has not been trusted yet.

package/dist/{computer/host → workspace}/ca-trust.js

@@ -127,7 +127,7 @@ export class ContainerTrust {
     #trusted = false;
     /** Whether an exit watch is standing for the container now running. */
     #watching = false;
-    /** Bumped by {@link forget}, so a watch settling after it is ignored. */
+    /** Bumped by {@link forget}, so a watch armed before it is ignored. */
     #generation = 0;
     /**
      * Whether this container's deployment fault has already been reported.
@@ -141,10 +141,18 @@ export class ContainerTrust {
     constructor(deps) {
         this.deps = deps;
     }
-    /** Forget that any container was trusted. */
+    /**
+     * Forget that any container was trusted.
+     *
+     * Drops the standing watch too, because this is also reached for a container
+     * that keeps running — a `running` read, a lost exec. The watch it leaves
+     * behind ignores that container's real exit, so without a fresh one nothing
+     * would clear the flag again and the replacement would be vouched for.
+     */
     forget() {
         this.#generation += 1;
         this.#trusted = false;
+        this.#watching = false;
         this.#faultReported = false;
     }
     /**
@@ -171,8 +179,9 @@ export class ContainerTrust {
             return;
         const generation = this.#generation;
         try {
+            // A stale watch returns before touching anything: `#watching` belongs to
+            // whichever watch was armed since.
             const done = () => {
-                this.#watching = false;
                 if (generation !== this.#generation)
                     return;
                 this.forget();

package/dist/{computer/host → workspace}/container-fault.d.ts

@@ -3,9 +3,9 @@
  *
  * 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 two 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.
+ * 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

package/dist/{computer/host → workspace}/container-fault.js

@@ -3,9 +3,9 @@
  *
  * 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 two 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.
+ * 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
@@ -21,14 +21,18 @@
 /**
  * Match on the shape the backend formats, not on the prose after it.
  *
- * `[stage=auth]` is the stage label `CloudflareContainerBackend` 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. Both are stabler than the explanations they introduce, and
- * neither has a `code` to key on the way a lost exec does.
+ * `[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.
  *
@@ -54,5 +58,16 @@ export function deploymentFault(err) {
                 "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;

package/dist/workspace/format.js

@@ -0,0 +1,57 @@
+/**
+ * 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 function truncateOutput(text, max) {
+    if (text.length <= max)
+        return text;
+    const marker = (dropped) => `\n\n… [${dropped} characters omitted from the middle] …\n\n`;
+    // No budget for two halves plus the marker: keep the head, which is where the
+    // first error is, and say nothing clever.
+    const half = Math.floor((max - marker(text.length).length) / 2);
+    if (half < 1)
+        return text.slice(0, Math.max(0, max));
+    return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
+}
+/** Elapsed time in the shape a sentence wants. */
+export function humanMs(ms) {
+    const s = Math.round(ms / 1000);
+    return s < 60
+        ? `${s}s`
+        : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}
+/**
+ * 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 function cancelledNote(status, exitCode, timeoutMs) {
+    if (status !== "cancelled")
+        return undefined;
+    return (`the command was killed rather than exiting on its own (exit ${exitCode}), so ` +
+        `anything it had not yet written is gone. The two usual causes are the ` +
+        `per-command time limit — ${humanMs(timeoutMs)} here — and the container ` +
+        `running out of memory.`);
+}