@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/computer/context.js

@@ -0,0 +1,222 @@
+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 { DEFAULT_CWD, DEFAULT_TIMEOUT_MS } from "../workspace/exec.js";
+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;
+/**
+ * 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
+        // agent.
+        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.
+     *
+     * Lines every file tool would otherwise repeat with only the verb changed,
+     * and a chance for the next one 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.
+     *
+     * `bash` 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 context block's
+     * 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,40 @@
+/**
+ * One mutation per file at a time, across every tool set in this isolate.
+ *
+ * `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. The workspace's `writeFile` takes the
+ * same lock, so Think's `write` never lands between an edit's read and its
+ * write. Module-level because a parent and a sub-agent 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

@@ -1,8 +1,8 @@
-import { type WorkspaceAdvisory } from "./advisory.js";
+import { type WorkspaceAdvisory } from "../workspace/advisory.js";
 /**
  * What one shell command has to wait for, and what to say when it never ran.
  *
- * {@link file://./advisory.ts} decides what is true about the workspace and how
+ * {@link file://../workspace/advisory.ts} decides what is true about the workspace and how
  * to word it; this file decides what that means for a command about to run.
  * {@link needsDependencies} is the part that cannot move there — it is a
  * question about the *command*, and it is what stops `cat README.md` queueing
@@ -12,16 +12,16 @@ import { type WorkspaceAdvisory } from "./advisory.js";
  * replaced underneath a command that was running.
  */
 /**
- * The one `sb_exec` failure that is not the command's fault.
+ * The one `bash` failure that is not the command's fault.
  *
  * An execution running when the container is replaced throws `EEXEC_LOST`.
  * 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. */
@@ -75,7 +75,7 @@ export declare function execGate(advisories: readonly WorkspaceAdvisory[], comma
 /**
  * Whether a write should happen at all, and what to say when it should not.
  *
- * `sb_write` and `sb_edit` do not go through {@link execGate}: they run no
+ * `write`, `edit` and `delete` do not go through {@link execGate}: they run no
  * command, and a dependency install has nothing to do with writing source. One
  * thing does reach them, and it is the worst of the set — a workspace that
  * accepts no further writes takes an edit, reports the character count, and

package/dist/computer/gate.js

@@ -1,8 +1,8 @@
-import { renderAdvisory, shapeOf } from "./advisory.js";
+import { renderAdvisory, shapeOf } from "../workspace/advisory.js";
 /**
  * What one shell command has to wait for, and what to say when it never ran.
  *
- * {@link file://./advisory.ts} decides what is true about the workspace and how
+ * {@link file://../workspace/advisory.ts} decides what is true about the workspace and how
  * to word it; this file decides what that means for a command about to run.
  * {@link needsDependencies} is the part that cannot move there — it is a
  * question about the *command*, and it is what stops `cat README.md` queueing
@@ -12,16 +12,16 @@ import { renderAdvisory, shapeOf } from "./advisory.js";
  * replaced underneath a command that was running.
  */
 /**
- * The one `sb_exec` failure that is not the command's fault.
+ * The one `bash` failure that is not the command's fault.
  *
  * An execution running when the container is replaced throws `EEXEC_LOST`.
  * 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) {
@@ -76,7 +76,7 @@ export function execGate(advisories, command) {
 /**
  * Whether a write should happen at all, and what to say when it should not.
  *
- * `sb_write` and `sb_edit` do not go through {@link execGate}: they run no
+ * `write`, `edit` and `delete` do not go through {@link execGate}: they run no
  * command, and a dependency install has nothing to do with writing source. One
  * thing does reach them, and it is the worst of the set — a workspace that
  * accepts no further writes takes an edit, reports the character count, and
@@ -108,7 +108,7 @@ export function writeGate(advisories) {
  * Position is what makes this usable rather than merely cautious. Matching these
  * anywhere in the string looks equivalent and is not: `\bvitest\b` also fires on
  * `cat vitest.config.ts`, and `next.config.js`, `eslint.config.js` and
- * `vite.config.ts` are exactly the files a subagent reads while orienting itself.
+ * `vite.config.ts` are exactly the files an agent reads while orienting itself.
  * Every one of those reads would then queue behind an `npm ci` it has no use for,
  * which is the cost this whole check exists to remove.
  */