@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/computer/advisory.d.ts

@@ -9,21 +9,20 @@ import type { InstallState } from "./install.js";
  * and the generation marker. It is right for that and unchanged by this file.
  *
  * Every *reader*, though, is asking a different question: **can I rely on this
- * workspace right now?** The two diverge, and where they did the old code either
- * overloaded a variant or invented a record:
+ * workspace right now?** The two diverge, and expressing the second through the
+ * first goes wrong in ways that are each easy to reintroduce:
  *
- * - A workspace at its storage ceiling was written as `skipped` — the same
- *   variant that means "this checkout has nothing to install". One is a hard
- *   wall about the Durable Object, the other is routine and about the
- *   repository, and they were told apart only by reading prose. Both readers
- *   missed the first.
- * - Capacity therefore travelled through a channel gated by
- *   {@link file://./gate.ts needsDependencies}, so a full workspace said nothing
+ * - A workspace at its storage ceiling is not `skipped`. That variant means
+ *   "this checkout has nothing to install" — routine, and about the repository.
+ *   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
  *   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, had no way to be
- *   said except by fabricating a `done` with an invented exit code — and the
- *   probe it rested on, a bare `test -d node_modules`, is satisfied by the
- *   wreckage of the very install it was overriding.
+ * - "The tree is fine now", after a subagent 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.
  *
  * So an advisory is **derived at read time** and describes the workspace, not a
  * job. Its absence is the good case, which is what removes the need to invent
@@ -139,11 +138,11 @@ export interface AdvisoryInput {
     /**
      * Whether a `node_modules` directory exists — **existence only, not health**.
      *
-     * Named for what it can actually observe. A host probes this with the
-     * equivalent of `test -d`, and that answers a narrower question than
-     * "are the dependencies fine": a `npm ci` that died partway leaves the
-     * directory behind holding an incomplete tree, so a `true` here is entirely
-     * consistent with the install having failed for real.
+     * Named for what it can actually observe. A host answers it by looking for the
+     * directory in the workspace, and that is a narrower question than "are the
+     * dependencies fine": an `npm ci` that died partway leaves the directory
+     * behind holding an incomplete tree, so a `true` here is entirely consistent
+     * with the install having failed for real.
      *
      * So it never suppresses a proven failure. It travels onto the advisory as
      * {@link WorkspaceAdvisory} `treePresent` and the reader is told which way the
@@ -152,6 +151,20 @@ export interface AdvisoryInput {
      * mode it was recording.
      */
     dependencyTreePresent: boolean;
+    /**
+     * A reinstall the host has already queued, as the moment it was queued.
+     *
+     * The difference between "your dependencies are broken" and "your
+     * dependencies are being rebuilt", and the two read identically from the
+     * durable record alone — an install whose container was replaced writes
+     * `failed`, and the arming that will repair it is a separate fact the record
+     * does not carry.
+     *
+     * A production session was briefed `deps-broken` six seconds before the
+     * armed reinstall it did not know about finished, and spent its own turns
+     * re-running `npm ci` on top of a tree that was already landing.
+     */
+    reinstallArmedAt?: number;
 }
 /**
  * Everything currently true about a workspace, from what the host can see.

package/dist/computer/advisory.js

@@ -129,9 +129,34 @@ export function deriveAdvisories(input) {
             });
             break;
         case "failed":
-            // Always reported. The record is durable evidence that an install failed,
-            // and nothing available here is evidence that a later one succeeded — so
-            // the presence of a tree qualifies the advisory instead of deleting it.
+            /**
+             * A queued reinstall changes the *kind*, not the severity of the facts.
+             *
+             * `deps-broken` is permanent by definition — nothing clears that record
+             * except another checkout — and that permanence is what the reader acts
+             * on: a session told this installs for itself. When a reinstall is
+             * already armed that is the wrong instruction and the wrong shape, because
+             * the condition does clear with nobody acting. `deps-building` is the one
+             * that says so, and its wording for a session already asks the reader to
+             * wait rather than start a second install on top of the first.
+             *
+             * Counted from when the reinstall was armed rather than when it starts:
+             * arming is the moment the repair became certain, and the alarm that runs
+             * it owns no clock this can read.
+             */
+            if (input.reinstallArmedAt !== undefined) {
+                advisories.push({
+                    kind: "deps-building",
+                    command: install.command,
+                    startedAt: input.reinstallArmedAt,
+                    ...(install.tail ? { tail: install.tail } : {})
+                });
+                break;
+            }
+            // Otherwise always reported. The record is durable evidence that an
+            // install failed, and nothing available here is evidence that a later one
+            // succeeded — so the presence of a tree qualifies the advisory instead of
+            // deleting it.
             advisories.push({
                 kind: "deps-broken",
                 command: install.command,
@@ -147,8 +172,8 @@ export function deriveAdvisories(input) {
             advisories.push({ kind: "deps-absent", reason: install.reason });
             break;
         // Nothing to say. `idle` means no install has been armed yet, which the
-        // host's cold-container check resolves on its own, and `done` is the
-        // ordinary case — a caller told its dependencies are fine has been told
+        // host resolves on its own when it finds no tree in the workspace, and
+        // `done` is the ordinary case — a caller told its dependencies are fine has been told
         // nothing, at the cost of prefix tokens on every run.
         case "idle":
         case "done":

package/dist/computer/context.d.ts

@@ -0,0 +1,23 @@
+import type { WorkspaceClient } from "@cloudflare/computer";
+import { type ExecGate } from "./gate.js";
+import type { WorkspaceAdvisory } from "./advisory.js";
+import type { ComputerConfig } from "./index.js";
+/** 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";
+/** What {@link computerContext} hands each group of tools. */
+export interface ComputerContext {
+    config: ComputerConfig;
+    cwd: string;
+    timeoutMs: number;
+    maxChars: number;
+    workspace: () => Promise<WorkspaceClient>;
+    awaitAdvisories: (command: string, signal?: AbortSignal) => Promise<ExecGate>;
+    definedEnv: () => Record<string, string> | undefined;
+    inWorkspace: (gerund: string, subject: string, body: (fs: WorkspaceClient["fs"]) => Promise<string>) => Promise<string>;
+    refuseWrite: () => Promise<string | undefined>;
+    scope: () => string;
+}
+/** Takes what {@link file://./index.ts buildComputerTools} takes. */
+export declare function computerContext(workspace: () => Promise<WorkspaceClient>, config: ComputerConfig, advisories?: () => Promise<readonly WorkspaceAdvisory[]>, fsWorkspace?: () => Promise<WorkspaceClient>, lockScope?: () => string): ComputerContext;

package/dist/computer/context.js

@@ -0,0 +1,225 @@
+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 { withAbort } from "@dynamicagents/core";
+import { execGate, writeGate } from "./gate.js";
+/**
+ * The machinery every container tool closes over: the resolved config, the
+ * advisory gates, and the workspace opener the file tools share.
+ */
+/**
+ * How much command output the model is allowed to see, in characters.
+ *
+ * One `npm install` prints more than a small context window holds, and the
+ * interesting part of a failing build is the first error and the last summary —
+ * never the middle. So output is truncated from the middle rather than the end,
+ * which is what a naive `slice` would do and would drop the exit summary that
+ * says what actually failed.
+ */
+const DEFAULT_MAX_OUTPUT_CHARS = 16_000;
+/** 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";
+/**
+ * How often the install gate re-reads the install's status.
+ *
+ * An interval rather than a subscription because the status lives in another
+ * Durable Object with no event to wait on. Never slept past the gate itself —
+ * see `awaitAdvisories` in {@link computerContext}.
+ */
+const INSTALL_POLL_MS = 3_000;
+/** Takes what {@link file://./index.ts buildComputerTools} takes. */
+export function computerContext(workspace, config, advisories, fsWorkspace = workspace, lockScope) {
+    const cwd = config.cwd ?? DEFAULT_CWD;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxChars = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+    const gateMs = config.installGateMs ?? 90_000;
+    const env = config.env;
+    const ownScope = crypto.randomUUID();
+    const scope = () => lockScope?.() ?? ownScope;
+    /**
+     * Wait out anything transient, up to the gate, and report whatever is left.
+     *
+     * Polled rather than subscribed: the state lives in another Durable Object,
+     * there is no event to wait on, and the whole window is under two minutes.
+     *
+     * **Read for every command, including the ones that need no dependencies.**
+     * The filter that spares `cat README.md` from queueing behind an `npm ci`
+     * lives in `execGate`, where it applies per advisory — because a dependency
+     * install and a full workspace are not relevant to the same commands, and one
+     * filter over both leaves a workspace at its ceiling silent for exactly the
+     * commands whose writes it is dropping. The cost is one same-colo RPC per
+     * command, against a class of silent data loss.
+     */
+    const awaitAdvisories = async (command, signal) => {
+        if (!advisories)
+            return {};
+        // Fails **open**, and that belongs here rather than at the call site: this
+        // is a read of another Durable Object's state. An error must not take out a
+        // working shell — running the command is exactly what would have happened
+        // before the gate existed, and a spurious blockage would strand the
+        // subagent.
+        const read = async () => {
+            try {
+                signal?.throwIfAborted();
+                return await withAbort(signal, advisories());
+            }
+            catch (err) {
+                // Open on a failed read, never on a cancel: failing open here would go on
+                // to run the command the caller just gave up on.
+                if (signal?.aborted)
+                    throw err;
+                return [];
+            }
+        };
+        // Clamped to whatever is left of the gate, not the bare interval. A fixed
+        // sleep makes `installGateMs` a floor rather than the ceiling it is
+        // documented to be: at a 100 ms gate the loop still slept the full three
+        // seconds before looking again, so a public timeout overshot by 30×.
+        const deadline = Date.now() + gateMs;
+        let current = await read();
+        // Keyed on the gate's own verdict rather than on a state name, so "what is
+        // worth waiting for" has one definition and it is the one that will decide
+        // the outcome.
+        while (execGate(current, command).block && Date.now() < deadline) {
+            const wait = Math.min(INSTALL_POLL_MS, deadline - Date.now());
+            // Throws on a cancel rather than returning the verdict so far: a gate that
+            // outlived its caller would otherwise go on to run the command it was holding.
+            await withAbort(signal, new Promise((resolve) => setTimeout(resolve, wait)));
+            current = await read();
+        }
+        return execGate(current, command);
+    };
+    /**
+     * Whether a write can succeed at all, asked once and not polled.
+     *
+     * Separate from {@link awaitAdvisories} because the question is different:
+     * there is no command to classify and nothing worth waiting for. An install in
+     * flight does not stop a file being written, and the one thing that does —
+     * a workspace that no longer accepts writes — never resolves on its own.
+     *
+     * Fails **open** for the same reason the exec gate does: a read of another
+     * Durable Object's state must not take out a working tool.
+     */
+    const refuseWrite = async () => {
+        if (!advisories)
+            return undefined;
+        try {
+            return writeGate(await advisories());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * Host-supplied environment, with the undefined entries dropped.
+     *
+     * `RuntimeExecOptions.env` is `Record<string, string>`, and a config thunk
+     * that reads straight off `env` will hand back `undefined` for anything
+     * unset — which would otherwise arrive in the container as the string
+     * "undefined".
+     */
+    const definedEnv = () => {
+        if (!env)
+            return undefined;
+        const entries = Object.entries(env()).filter((entry) => entry[1] !== undefined);
+        return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+    };
+    /**
+     * Open the workspace, run one file operation in it, and own the failure.
+     *
+     * Five lines every file tool would otherwise repeat with only the verb changed
+     * — five chances for the seventh to be written without them. The catch is the
+     * point: a failed file operation is the model's to recover from, and it can
+     * only recover from what it is told, so this returns the sentence rather than
+     * throwing it.
+     *
+     * `sb_exec` deliberately does not use it. That one recognises `EEXEC_LOST`,
+     * logs, and carries an install warning through the failure path — a bespoke
+     * catch saying something this cannot.
+     *
+     * It opens through `fsWorkspace`, which is what makes the capability sentence
+     * about these tools true: they answer while the container is down.
+     */
+    const inWorkspace = async (gerund, subject, body) => {
+        try {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const ws = __addDisposableResource(env_1, await fsWorkspace(), false);
+                return await body(ws.fs);
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        catch (err) {
+            return `error ${gerund} ${subject}: ${String(err)}`;
+        }
+    };
+    return {
+        config,
+        cwd,
+        timeoutMs,
+        maxChars,
+        workspace,
+        awaitAdvisories,
+        definedEnv,
+        inWorkspace,
+        refuseWrite,
+        scope
+    };
+}

package/dist/computer/file-lock.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `path` is canonicalised the way the filesystem resolves it, so spellings with
+ * `.`, `..` or doubled slashes share one lock.
+ */
+export declare function withFileLock<T>(scope: string, path: string, body: () => Promise<T>): Promise<T>;

package/dist/computer/file-lock.js

@@ -0,0 +1,39 @@
+/**
+ * One mutation per file at a time, across every tool set in this isolate.
+ *
+ * `sb_edit` reads, replaces and writes back over RPC, and the AI SDK runs one
+ * step's tool calls concurrently — so two edits to one file would both report
+ * success and the first would be lost. Module-level because a parent and a
+ * subagent can hold separate tool sets over one workspace; another isolate is
+ * out of reach.
+ */
+const tails = new Map();
+/**
+ * `path` is canonicalised the way the filesystem resolves it, so spellings with
+ * `.`, `..` or doubled slashes share one lock.
+ */
+export async function withFileLock(scope, path, body) {
+    const key = `${scope}\0${canonical(path)}`;
+    const run = (tails.get(key) ?? Promise.resolve()).then(body);
+    const tail = run.catch(() => { });
+    tails.set(key, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (tails.get(key) === tail)
+            tails.delete(key);
+    }
+}
+function canonical(path) {
+    const out = [];
+    for (const segment of path.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return `/${out.join("/")}`;
+}

package/dist/computer/gate.d.ts

@@ -18,10 +18,10 @@ import { type WorkspaceAdvisory } from "./advisory.js";
  * Unexplained, the model receives `Execution "…" was lost when its container
  * runtime was replaced`, reads it as a crash, and goes looking at its command.
  *
- * What it needs is three facts: nothing ran to completion, the checkout survived
- * because the filesystem is the Durable Object's rather than the container's, and
- * `node_modules` did not because it never was. So re-run, and expect the install
- * to be rebuilding underneath.
+ * What it needs is two facts: nothing ran to completion, and the workspace
+ * survived because the filesystem is the Durable Object's rather than the
+ * container's. So re-run it. `node_modules` is the container's, so the note
+ * says the replacement reinstalls it.
  *
  * Matched on `code` rather than the message — the property the package sets
  * deliberately, and the one that survives a reworded string.
@@ -52,10 +52,10 @@ export declare function execLostNote(err: unknown): string | undefined;
  * ## What a command is told depends on the command
  *
  * A dependency advisory reaches only commands that read `node_modules`; a
- * universal one reaches everything. That asymmetry is the reason a full
- * workspace used to say nothing at all to `echo hi > file.txt` — the write being
- * lost is usually not a dependency's, and the filter that was right for installs
- * was silently applied to capacity too.
+ * universal one reaches everything. Applying the dependency filter to capacity
+ * too is the mistake that asymmetry invites: a full workspace then says nothing
+ * at all to `echo hi > file.txt`, and the write being lost is usually not a
+ * dependency's.
  */
 export interface ExecGate {
     /** Set only for something transient: the command did not run. */

package/dist/computer/gate.js

@@ -18,10 +18,10 @@ import { renderAdvisory, shapeOf } from "./advisory.js";
  * Unexplained, the model receives `Execution "…" was lost when its container
  * runtime was replaced`, reads it as a crash, and goes looking at its command.
  *
- * What it needs is three facts: nothing ran to completion, the checkout survived
- * because the filesystem is the Durable Object's rather than the container's, and
- * `node_modules` did not because it never was. So re-run, and expect the install
- * to be rebuilding underneath.
+ * What it needs is two facts: nothing ran to completion, and the workspace
+ * survived because the filesystem is the Durable Object's rather than the
+ * container's. So re-run it. `node_modules` is the container's, so the note
+ * says the replacement reinstalls it.
  *
  * Matched on `code` rather than the message — the property the package sets
  * deliberately, and the one that survives a reworded string.
@@ -31,9 +31,9 @@ export function execLostNote(err) {
         return undefined;
     return ("the container was replaced while this command was running, so it was lost — " +
         "nothing ran to completion and no output survived. This is infrastructure, " +
-        "not your command: re-run it. The checkout is durable and is exactly as you " +
-        "left it, but `node_modules` lived in the old container and is being rebuilt, " +
-        "so anything that needs dependencies may have to wait for that install.");
+        "not your command: re-run it. The workspace is durable and is exactly as you " +
+        "left it. `node_modules` is not: the replacement reinstalls it, and a " +
+        "command that needs it waits for that.");
 }
 /** Which advisories this particular command needs to hear about. */
 function relevantTo(advisories, command) {

package/dist/computer/host/ca-trust.d.ts

@@ -0,0 +1,88 @@
+import type { Workspace } from "@cloudflare/computer";
+/**
+ * Making a container able to speak TLS, once there is a CA to trust.
+ *
+ * Only `egress: { mode: "http-gateway" }` needs this, but it lives on every
+ * workspace because the cost of getting it wrong is asymmetric: the trust
+ * install against a container with no CA prints one line and exits 0, while a
+ * container that missed it fails every later HTTPS connection with an error
+ * that names no cause.
+ */
+/**
+ * Install the egress interception CA, and say what was there to install.
+ *
+ * One shell string rather than a script in the image, because **the image cannot
+ * run this at all**, and the reason is ordering rather than preference.
+ * Cloudflare's own recipe assumes interception is declared as container
+ * configuration, so the runtime mounts the CA before the container starts.
+ * `@cloudflare/computer` uses the raw container API, where the only interception
+ * hooks are methods called *after* `start()` — so an entrypoint runs strictly
+ * before the CA can exist, finds nothing, and reports the container
+ * un-intercepted while every later TLS connection fails.
+ *
+ * The listing comes first and runs unconditionally: when the CA is missing,
+ * *what else is in that directory* is the only evidence distinguishing "mounted
+ * somewhere else" from "never provisioned", and it costs one line.
+ */
+export declare const TRUST_CA_COMMAND: string;
+export interface ContainerTrustDeps {
+    workspace: () => Workspace;
+    /** The runtime's own container handle, for the exit this has to hear about. */
+    container: () => Container | undefined;
+    /** Log prefix and object id, for the one line an operator can see. */
+    tag: () => string;
+    id: () => string;
+    /** Told when the watched container exits, for what else it described. */
+    onExit?: () => void;
+}
+/**
+ * Whether the container this object is talking to has had the CA installed.
+ *
+ * ## Why the answer is in memory
+ *
+ * What it describes is a *container*, which does not outlive the isolate in any
+ * way worth persisting. A stored `true` would be the exact bug this exists to
+ * prevent — a flag surviving the container it describes, and vouching for its
+ * replacement.
+ *
+ * It is wrong only in the safe direction. An isolate that lost it re-runs an
+ * idempotent `install -m 644`.
+ *
+ * ## What clears it
+ *
+ * **The container's own exit**, watched through `monitor()`. This is the signal
+ * that does not depend on anyone noticing: a container replaced underneath a
+ * running command — by a reconnect, a relaunch, a crash — exits, and the watch
+ * fires whoever caused it. Nothing else here is in a position to know, because
+ * most commands run through the stub this object hands out and report their
+ * failures to their own caller, not to it.
+ *
+ * The watch lives in memory beside the flag it clears, which is the right
+ * lifetime: an isolate that loses one loses the other, and the replacement
+ * starts out untrusted. It is deliberately not held open with `waitUntil` —
+ * that would keep an invocation alive for the life of the container.
+ *
+ * A container seen not running, and a command reporting `EEXEC_LOST`, both call
+ * {@link forget} as well. They are cheap, they are strictly earlier in some
+ * orderings, and neither is load-bearing on its own.
+ */
+export declare class ContainerTrust {
+    #private;
+    private readonly deps;
+    constructor(deps: ContainerTrustDeps);
+    /** Forget that any container was trusted. */
+    forget(): void;
+    /**
+     * Trust the CA if this container has not been trusted yet.
+     *
+     * Called from the workspace's `ready()` path, which is the earliest point that
+     * is not too early: the backend's `connect()` has completed, so start and
+     * interception have both happened.
+     *
+     * **Never throws.** A workspace that cannot trust the CA still has a checkout,
+     * a shell and a git history, and whatever runs next will say plainly what went
+     * wrong — refusing to proceed here would replace a legible TLS error with an
+     * opaque one.
+     */
+    ensure(): Promise<void>;
+}