@dynamicagents/plugins 0.11.0 → 0.12.0

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

@@ -0,0 +1,62 @@
+import type { RepoGitResult } from "../../repo/index.js";
+import type { GitClient } from "@cloudflare/computer/git";
+/**
+ * The git operations that need the forge 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 `./workspace.ts` are where that is settled.
+ */
+export interface GitHostDeps {
+    /** The workspace's own client — isomorphic-git over the local store. */
+    git: () => GitClient;
+    /** The forge 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>;
+    push(req: {
+        url: string;
+        dir: string;
+        branch: string;
+        allowedHosts: string[];
+    }): Promise<RepoGitResult>;
+}

package/dist/computer/host/git-host.js

@@ -0,0 +1,156 @@
+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 });
+            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 a subagent 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,
+                ...(req.depth ? { depth: req.depth } : {})
+            });
+            return `fetched ${req.url} (default branch ${result.defaultBranch ?? "unknown"})`;
+        });
+    }
+    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;
+            return {
+                ok: false,
+                ...(typeof code === "string" ? { code } : {}),
+                message: err instanceof Error ? err.message : String(err)
+            };
+        }
+    }
+}

package/dist/computer/host/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/computer/host/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)
+            });
+        }
+    }
+}

package/dist/computer/host/install-job.d.ts

@@ -0,0 +1,121 @@
+import { type Workspace } from "@cloudflare/computer";
+import type { Scheduler } from "@dynamicagents/core/alarm";
+import { type InstallPlan, type InstallState } from "../install.js";
+import type { WorkspaceWakeHandlers } from "./wake.js";
+export interface InstallJobDeps {
+    storage: DurableObjectStorage;
+    scheduler: Scheduler<WorkspaceWakeHandlers>;
+    workspace: () => Workspace;
+    /** How this deployment installs dependencies for this agent's checkouts. */
+    plan: () => InstallPlan;
+    /** How long an install may run before it is killed. */
+    timeoutMs: () => number;
+    /** Set only when the workspace is over its ceiling. */
+    headroom: () => {
+        bytes: number;
+        capBytes: number;
+    } | undefined;
+    /** The object's own entry-point bookkeeping, which an install still owes. */
+    touch: () => Promise<void>;
+    ready: () => Promise<void>;
+    /** Hand a drain to the invocation, for the caller that can hold one. */
+    waitUntil: (promise: Promise<unknown>) => void;
+    /** A container was replaced, so nothing believed about it still holds. */
+    containerGone: () => Promise<void>;
+    tag: () => string;
+    id: () => string;
+}
+export declare class InstallJob {
+    #private;
+    private readonly deps;
+    constructor(deps: InstallJobDeps);
+    /**
+     * Start a dependency install the moment we can see one will be needed.
+     *
+     * The signal is {@link CONTAINER_TREE_KEY}: a local read, true only while the
+     * container that ran the install is the one running.
+     *
+     * Armed as soon as a container is up or a command is about to start one,
+     * because the model's first minute is README-reading and `git status` — an
+     * install armed there runs *through* that minute, where one armed on the first
+     * `npm` command charges its full time to that command.
+     *
+     * It writes `running` before anything is running: the alarm has not fired yet,
+     * and a `done` record would let an `npm` command through against a tree that
+     * is not there. That also makes this self-limiting — the next call sees
+     * `running` and stops.
+     */
+    armIfTreeMissing(): Promise<void>;
+    /** Where the last install ran, for the container setup's marker read. */
+    dir(): Promise<string | undefined>;
+    /** The container went away, and its tree with it. */
+    containerGone(): Promise<void>;
+    /**
+     * Check the record against the marker a new isolate's setup read.
+     *
+     * The record can outlive its container in an isolate that did not watch it
+     * exit; the marker cannot.
+     */
+    reconcile(marker: string | null): Promise<void>;
+    /**
+     * The record exactly as the job wrote it, with no staleness bound applied.
+     *
+     * {@link state} is what almost everything wants. This is for the one caller
+     * that must not repair anything on the way past: the container-idle handler,
+     * which only needs to know whether something is running before it destroys the
+     * container underneath it.
+     */
+    read(): Promise<InstallState>;
+    /**
+     * Start installing this checkout's dependencies, and return without waiting.
+     *
+     * Called from `repo_clone` through the repo plugin's `afterCheckout` hook, so
+     * it runs inside a model turn and must not block on the install — 225 seconds
+     * for slack-gatekeeper, against a chunk step that dies at ten minutes.
+     *
+     * That caller is a model turn, which lives long enough to hold the drain handed
+     * to `ctx.waitUntil` below. **A short-lived caller cannot**, which is why an
+     * install the alarm drives is awaited inside that alarm rather than calling
+     * this.
+     */
+    start(req: {
+        dir: string;
+        repo?: string;
+    }): Promise<InstallState>;
+    /**
+     * Whether this container holds a finished tree, asked only when it qualifies a
+     * `deps-broken` advisory (see `deriveAdvisories`).
+     */
+    treePresentIfItMatters(install: InstallState): Promise<boolean>;
+    /**
+     * The install record itself, with its staleness bound and re-attach applied.
+     *
+     * Split from {@link advisories} so `startInstall` can consult the record
+     * without going through the `node_modules` probe, which needs a container and
+     * has nothing to say about whether an install may start.
+     *
+     * Re-attaches on the way past. An isolate reset leaves the record saying
+     * `running` with nothing draining it, and without this the state would say
+     * `running` forever while the command had long since finished.
+     */
+    state(): Promise<InstallState>;
+    /**
+     * When a reinstall was queued, if one is waiting to run.
+     *
+     * Read by {@link file://../advisory.ts deriveAdvisories}, which is the only
+     * caller that needs it: a `failed` record with a repair already queued is a
+     * transient condition wearing a permanent record's clothes.
+     */
+    reinstallArmedAt(): Promise<number | undefined>;
+    /**
+     * The armed reinstall came due.
+     *
+     * `clearArmed` first and unconditionally: this handler runs for minutes, and
+     * the stamp left in place is what a second arming would recognise as its own.
+     * `startInstall`'s in-flight guard would catch a double, but the cheaper
+     * answer is not to schedule one.
+     */
+    onRun(): Promise<void>;
+    /** The watchdog: an install still running that nobody is draining. */
+    onWatch(): Promise<void>;
+}