@dynamicagents/plugins 0.13.0 → 0.15.0

package/dist/workspace/container-fault.js

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-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

@@ -1,153 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,57 +0,0 @@
-/**
- * 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.`);
-}

package/dist/workspace/git-host.d.ts

@@ -1,79 +0,0 @@
-import type { RepoGitResult } from "../repo/index.js";
-import type { GitClient } from "@cloudflare/computer/git";
-/**
- * The git operations that need the GitHub token, run on this side.
- *
- * They are here rather than on the `WorkspaceStub` the plugin already holds
- * because `WorkspaceGitStub` exposes only `cli(argv)` across a Durable Object
- * boundary, and argv cannot carry an `onAuth` callback. Routed through here, the
- * credential is read from the workspace object's own `env` and never crosses an
- * RPC boundary, never appears in an argument list, and never enters the
- * container.
- *
- * That last clause is the point, and it is why running credentialed `git` in the
- * container is not an option however carefully it is sandboxed: git executes
- * whatever `.git/config` and `.git/hooks` name, the model has a root shell on
- * that filesystem, and even a disposable git dir leaves the token readable
- * through `/proc` for the life of the process. isomorphic-git runs here and has
- * no hooks, no `ext::` transport, no template directory and no credential
- * helpers.
- *
- * **The caller owns the preconditions.** Bringing the workspace up to date is
- * the workspace object's job and it must happen first: git here reads that
- * object's SQLite, so a commit made in the container that has not been pulled
- * yet is a commit this code cannot see. The workspace object's `gitClone`,
- * `gitFetch` and `gitPush` in `./object.ts` are where that is settled.
- */
-export interface GitHostDeps {
-    /** The workspace's own client — isomorphic-git over the local store. */
-    git: () => GitClient;
-    /** The GitHub credential, read at the moment it would be handed over. */
-    token: () => string | undefined;
-    tag: () => string;
-}
-export declare class WorkspaceGitHost {
-    #private;
-    private readonly deps;
-    constructor(deps: GitHostDeps);
-    /**
-     * Each operation takes `url` explicitly rather than a remote name: resolving
-     * `origin` would read `.git/config`, a workspace file a co-installed shell
-     * tool can write.
-     */
-    clone(req: {
-        url: string;
-        dir: string;
-        allowedHosts: string[];
-        branch?: string;
-        depth?: number;
-    }): Promise<RepoGitResult>;
-    fetch(req: {
-        url: string;
-        dir: string;
-        allowedHosts: string[];
-        depth?: number;
-    }): Promise<RepoGitResult>;
-    /**
-     * `remote.origin.url` from the local store, or `undefined` where there is no
-     * checkout or no origin. Reads only, and needs no credential.
-     */
-    origin(dir: string): Promise<string | undefined>;
-    push(req: {
-        url: string;
-        dir: string;
-        branch: string;
-        allowedHosts: string[];
-    }): Promise<RepoGitResult>;
-}
-/**
- * A git error's message with the chain of causes behind it.
- *
- * `@cloudflare/computer/git` wraps isomorphic-git's errors, and classifies some
- * by a heuristic: any failure whose message mentions `.git` beside a missing
- * path or a ref it could not find is reported as "not a git repository" — a
- * sentence that is wrong about a checkout that plainly is one, and names
- * neither the file nor the ref. What actually failed is only on `cause`, which
- * a Durable Object boundary does not carry, so it is folded into the message
- * here while the error is still itself.
- */
-export declare function describeGitError(err: unknown): string;