@dynamicagents/plugins 0.11.1 → 0.13.0

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

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

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

package/dist/workspace/git-host.js

@@ -0,0 +1,226 @@
+/**
+ * What the container's own `git init` would write, over isomorphic-git's.
+ *
+ * isomorphic-git's `init` writes `core.*` for a filesystem without symlinks or
+ * an executable bit that ignores case, and the container's git obeys it. With
+ * `symlinks = false`, a command there that rewrites the tree — starter puts a
+ * worktree on its branch with `checkout -f` — writes each link as a file holding
+ * its target, and `status` calls that clean. With `filemode = false`, a script
+ * made executable is committed as 100644. The store models all three.
+ */
+const CONTAINER_CORE_CONFIG = {
+    "core.symlinks": true,
+    "core.filemode": true,
+    "core.ignorecase": false
+};
+export class WorkspaceGitHost {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 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.
+     */
+    async clone(req) {
+        return this.#run(req.allowedHosts, async (git, onAuth) => {
+            // Spelled out rather than `git.clone`, and the reason is the credential.
+            //
+            // `clone` is the one network operation the client does not give an
+            // `onAuth` callback — it authenticates only through a `headers` option,
+            // which means attaching the token to the very first request to a URL the
+            // *model* chose. Composing the same work out of `fetch` puts every
+            // credentialed request on this side of `onAuth` instead, where the host is
+            // checked at the moment the token would be handed over. The cost is four
+            // calls instead of one; `clone` is these four.
+            await git.init({ dir: req.dir });
+            // Straight after `init`, so a clone that fails part-way leaves nothing
+            // behind that the container's git would misread.
+            for (const [path, value] of Object.entries(CONTAINER_CORE_CONFIG))
+                await git.configSet({ dir: req.dir, path, value });
+            await git.remoteAdd({
+                dir: req.dir,
+                name: "origin",
+                url: req.url,
+                force: true
+            });
+            const fetched = await git.fetch({
+                url: req.url,
+                dir: req.dir,
+                onAuth,
+                // Omission is passed through as omission, because the tool the model
+                // reads says so: `repo_clone` describes `depth` as "omit for full
+                // history; needed if you must rebase", and `/repo` deliberately leaves
+                // the key off when it is unset. Defaulting to 1 here made every such
+                // clone shallow, so the one thing the model was told to omit it for —
+                // rebasing — failed on a repository it had asked for in full.
+                ...(req.depth === undefined ? {} : { depth: req.depth }),
+                singleBranch: true,
+                tags: false,
+                ...(req.branch ? { ref: req.branch } : {})
+            });
+            const landed = req.branch ?? fetched.defaultBranch?.replace(/^refs\/heads\//, "");
+            if (!landed)
+                throw new Error(`cloned ${req.url} but the remote named no default branch to check out`);
+            await git.checkout({ dir: req.dir, ref: landed });
+            // What a real `git clone` writes and the container's git will look for:
+            // without it the branch tracks nothing, and an agent reaching for a bare
+            // `git status` in the shell sees a branch with no upstream.
+            await git.configSet({
+                dir: req.dir,
+                path: `branch.${landed}.remote`,
+                value: "origin"
+            });
+            await git.configSet({
+                dir: req.dir,
+                path: `branch.${landed}.merge`,
+                value: `refs/heads/${landed}`
+            });
+            return landed;
+        });
+    }
+    async fetch(req) {
+        return this.#run(req.allowedHosts, async (git, onAuth) => {
+            const result = await git.fetch({
+                url: req.url,
+                dir: req.dir,
+                onAuth,
+                prune: true,
+                tags: false,
+                singleBranch: false,
+                // Every branch is fetched, but isomorphic-git still resolves one ref
+                // against the remote's list, and left to itself it picks the current
+                // branch's upstream. A checkout left on a branch whose pull request
+                // merged — and whose remote branch went with it — then fails every
+                // fetch with `Could not find refs/heads/<branch>`. The remote's HEAD
+                // is always listed.
+                remoteRef: "HEAD",
+                ...(req.depth ? { depth: req.depth } : {})
+            });
+            return `fetched ${req.url} (default branch ${result.defaultBranch ?? "unknown"})`;
+        });
+    }
+    /**
+     * `remote.origin.url` from the local store, or `undefined` where there is no
+     * checkout or no origin. Reads only, and needs no credential.
+     */
+    async origin(dir) {
+        try {
+            const url = await this.deps
+                .git()
+                .configGet({ dir, path: "remote.origin.url" });
+            return typeof url === "string" && url ? url : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async push(req) {
+        return this.#run(req.allowedHosts, async (git, onAuth) => {
+            const result = await git.push({
+                url: req.url,
+                dir: req.dir,
+                ref: req.branch,
+                remoteRef: req.branch,
+                onAuth
+                // No `force`, ever, and not a knob: `/repo` refuses anything but a plain
+                // branch name precisely so that a push cannot be turned into a force
+                // push, and this is the other end of that promise.
+            });
+            // isomorphic-git reports a rejected push in the *result* rather than by
+            // throwing — a non-fast-forward comes back `ok: false` with the reason on
+            // the ref. Reading only the absence of an exception would report every
+            // rejected push as a success, in the one plugin whose entire theme is that
+            // a failed command is not a completed operation.
+            if (!result.ok) {
+                const perRef = Object.entries(result.refs)
+                    .filter(([, status]) => !status.ok)
+                    .map(([ref, status]) => `${ref}: ${status.error ?? "rejected"}`)
+                    .join("; ");
+                // `||`, not `??`, on the second rung: `perRef` is a joined string, so
+                // "no failing ref carried a reason" is `""` rather than nullish — and
+                // `??` would hand that through as the error message. A rejected push
+                // reporting a blank reason is the one outcome worse than a generic one.
+                throw new Error(result.error ?? (perRef || "the remote rejected the push"));
+            }
+            return `pushed ${req.branch} to ${req.url}`;
+        });
+    }
+    /**
+     * The shared body: entry-point bookkeeping, the credential, and the translation
+     * back into something that survives RPC.
+     *
+     * A thrown `GitError` loses its prototype crossing a Durable Object boundary,
+     * so `instanceof` on the far side is not available and the caller would be left
+     * pattern-matching a string. The `code` is lifted here, while the error is
+     * still itself, and travels as data.
+     */
+    async #run(allowedHosts, body) {
+        // Bound to the credential rather than checked before the call, which is
+        // strictly stronger: this is the moment the token would be handed over, and
+        // it sees the URL git actually authenticated against — including one it
+        // reached by redirect. A host nobody allowed gets no credential and the
+        // request fails unauthenticated, rather than the token being offered to it
+        // and *then* the mistake being noticed.
+        const onAuth = (url) => {
+            let host;
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol !== "https:")
+                    return {};
+                host = parsed.hostname;
+            }
+            catch {
+                return {};
+            }
+            if (!allowedHosts.includes(host)) {
+                console.warn(`[${this.deps.tag()}] refused to authenticate to a host`, {
+                    host
+                });
+                return {};
+            }
+            return { username: "x-access-token", password: this.deps.token() };
+        };
+        try {
+            return { ok: true, detail: await body(this.deps.git(), onAuth) };
+        }
+        catch (err) {
+            const code = err?.code;
+            const message = describeGitError(err);
+            console.error(`[${this.deps.tag()}] git failed`, { code, message });
+            return {
+                ok: false,
+                ...(typeof code === "string" ? { code } : {}),
+                message
+            };
+        }
+    }
+}
+/**
+ * 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 function describeGitError(err) {
+    const parts = [];
+    const seen = new Set();
+    let at = err;
+    for (let depth = 0; at !== undefined && at !== null && depth < 4; depth++) {
+        const e = at;
+        const text = typeof e.message === "string" ? e.message : String(at);
+        if (!seen.has(text)) {
+            seen.add(text);
+            const name = typeof e.name === "string" ? e.name : "";
+            parts.push(name && depth > 0 ? `${name}: ${text}` : text);
+        }
+        at = e.cause;
+    }
+    return parts.join(" ← ");
+}

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

@@ -0,0 +1,57 @@
+import type { Workspace } from "@cloudflare/computer";
+/**
+ * The identity a commit made in this container carries when nothing nearer
+ * answers for it.
+ *
+ * `/repo` configures the checkouts it clones and names the identity on every
+ * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
+ * Neither reaches a repository the container made for itself: a submodule
+ * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
+ * have no identity at all, and git refuses to commit without one — so whatever
+ * is driving the shell has to invent a name to get past the refusal, and that
+ * invention is what ends up in the history.
+ *
+ * This is the layer underneath, so there is nothing to invent: every repository
+ * in the container starts out attributed to the deployment.
+ *
+ * **System scope, not global.** `--global` writes `$HOME/.gitconfig`, and a
+ * command run through the runtime cannot count on `HOME` being set to anything
+ * in particular — nor is the identity a property of one user of the container.
+ * `--system` is also the *lowest* precedence git has, which is the right place
+ * for it: a checkout's own config still wins, and so does the environment
+ * `/repo` and the session's launch put on a commit.
+ */
+/** Written to `/etc/gitconfig`; the values arrive as variables, never inline. */
+export declare const GIT_IDENTITY_COMMAND: string;
+export interface ContainerGitIdentityDeps {
+    workspace: () => Workspace;
+    author: () => {
+        name: string;
+        email: string;
+    };
+    /** Log prefix and object id, for the one line an operator can see. */
+    tag: () => string;
+    id: () => string;
+}
+/**
+ * The write above, once per container.
+ *
+ * In memory, with {@link file://./ca-trust.ts}'s lifetime and for its reason: it
+ * describes one container, and an isolate that lost it re-runs an idempotent
+ * command.
+ */
+export declare class ContainerGitIdentity {
+    #private;
+    private readonly deps;
+    constructor(deps: ContainerGitIdentityDeps);
+    forget(): void;
+    /**
+     * Configure this container if it has not been configured yet.
+     *
+     * **Never throws**, like the CA install and unlike the dependency setup. What
+     * a failure costs is an attribution, and every later commit says plainly that
+     * it has no identity to use — where a throw here would fail a workspace that
+     * is otherwise entirely usable.
+     */
+    ensure(): Promise<void>;
+}

package/dist/workspace/git-identity.js

@@ -0,0 +1,147 @@
+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;
+});
+/**
+ * The identity a commit made in this container carries when nothing nearer
+ * answers for it.
+ *
+ * `/repo` configures the checkouts it clones and names the identity on every
+ * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
+ * Neither reaches a repository the container made for itself: a submodule
+ * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
+ * have no identity at all, and git refuses to commit without one — so whatever
+ * is driving the shell has to invent a name to get past the refusal, and that
+ * invention is what ends up in the history.
+ *
+ * This is the layer underneath, so there is nothing to invent: every repository
+ * in the container starts out attributed to the deployment.
+ *
+ * **System scope, not global.** `--global` writes `$HOME/.gitconfig`, and a
+ * command run through the runtime cannot count on `HOME` being set to anything
+ * in particular — nor is the identity a property of one user of the container.
+ * `--system` is also the *lowest* precedence git has, which is the right place
+ * for it: a checkout's own config still wins, and so does the environment
+ * `/repo` and the session's launch put on a commit.
+ */
+/** Written to `/etc/gitconfig`; the values arrive as variables, never inline. */
+export const GIT_IDENTITY_COMMAND = [
+    'git config --system user.name "$GIT_NAME"',
+    'git config --system user.email "$GIT_EMAIL"',
+    "echo IDENTITY OK"
+].join(" && ");
+/** How long the write may take before it is not going to happen. */
+const IDENTITY_TIMEOUT_MS = 30_000;
+/**
+ * The write above, once per container.
+ *
+ * In memory, with {@link file://./ca-trust.ts}'s lifetime and for its reason: it
+ * describes one container, and an isolate that lost it re-runs an idempotent
+ * command.
+ */
+export class ContainerGitIdentity {
+    deps;
+    #done = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    forget() {
+        this.#done = false;
+    }
+    /**
+     * Configure this container if it has not been configured yet.
+     *
+     * **Never throws**, like the CA install and unlike the dependency setup. What
+     * a failure costs is an attribution, and every later commit says plainly that
+     * it has no identity to use — where a throw here would fail a workspace that
+     * is otherwise entirely usable.
+     */
+    async ensure() {
+        if (this.#done)
+            return;
+        const author = this.deps.author();
+        try {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const handle = __addDisposableResource(env_1, await this.deps
+                    .workspace()
+                    .runtime.exec(GIT_IDENTITY_COMMAND, {
+                    cwd: "/",
+                    encoding: "utf8",
+                    timeoutMs: IDENTITY_TIMEOUT_MS,
+                    env: { GIT_NAME: author.name, GIT_EMAIL: author.email }
+                }), false);
+                const result = await handle.result();
+                const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+                this.#done = result.exitCode === 0 && output.includes("IDENTITY OK");
+                if (this.#done)
+                    return;
+                console.warn(`[${this.deps.tag()}] could not set the container's git identity`, {
+                    id: this.deps.id(),
+                    output: output.trim()
+                });
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        catch (err) {
+            console.warn(`[${this.deps.tag()}] could not set the container's git identity`, {
+                id: this.deps.id(),
+                err: String(err)
+            });
+        }
+    }
+}