@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/{computer → workspace}/advisory.js

@@ -1,4 +1,4 @@
-import { humanMs } from "./render.js";
+import { humanMs } from "./format.js";
 /** What each advisory *means*. The one exhaustive home for policy. */
 export function shapeOf(advisory) {
     switch (advisory.kind) {
@@ -129,9 +129,34 @@ export function deriveAdvisories(input) {
             });
             break;
         case "failed":
-            // Always reported. The record is durable evidence that an install failed,
-            // and nothing available here is evidence that a later one succeeded — so
-            // the presence of a tree qualifies the advisory instead of deleting it.
+            /**
+             * A queued reinstall changes the *kind*, not the severity of the facts.
+             *
+             * `deps-broken` is permanent by definition — nothing clears that record
+             * except another checkout — and that permanence is what the reader acts
+             * on: a session told this installs for itself. When a reinstall is
+             * already armed that is the wrong instruction and the wrong shape, because
+             * the condition does clear with nobody acting. `deps-building` is the one
+             * that says so, and its wording for a session already asks the reader to
+             * wait rather than start a second install on top of the first.
+             *
+             * Counted from when the reinstall was armed rather than when it starts:
+             * arming is the moment the repair became certain, and the alarm that runs
+             * it owns no clock this can read.
+             */
+            if (input.reinstallArmedAt !== undefined) {
+                advisories.push({
+                    kind: "deps-building",
+                    command: install.command,
+                    startedAt: input.reinstallArmedAt,
+                    ...(install.tail ? { tail: install.tail } : {})
+                });
+                break;
+            }
+            // Otherwise always reported. The record is durable evidence that an
+            // install failed, and nothing available here is evidence that a later one
+            // succeeded — so the presence of a tree qualifies the advisory instead of
+            // deleting it.
             advisories.push({
                 kind: "deps-broken",
                 command: install.command,
@@ -147,8 +172,8 @@ export function deriveAdvisories(input) {
             advisories.push({ kind: "deps-absent", reason: install.reason });
             break;
         // Nothing to say. `idle` means no install has been armed yet, which the
-        // host's cold-container check resolves on its own, and `done` is the
-        // ordinary case — a caller told its dependencies are fine has been told
+        // host resolves on its own when it finds no tree in the workspace, and
+        // `done` is the ordinary case — a caller told its dependencies are fine has been told
         // nothing, at the cost of prefix tokens on every run.
         case "idle":
         case "done":
@@ -163,7 +188,7 @@ export function deriveAdvisories(input) {
 /**
  * Everything a session should know before it starts, or `undefined` for silence.
  *
- * The counterpart to {@link file://./gate.ts execGate}, for the reader that is a
+ * The counterpart to {@link file://../computer/gate.ts execGate}, for the reader that is a
  * whole run rather than one command. It cannot be blocked and does not need to
  * be: it can install dependencies itself, and the only thing it must not do is
  * work silently against a workspace that is not what it assumes.

package/dist/workspace/ca-trust.d.ts

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

package/dist/workspace/ca-trust.js

@@ -0,0 +1,312 @@
+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 { deploymentFault } from "./container-fault.js";
+/**
+ * Making a container able to speak TLS, once there is a CA to trust.
+ *
+ * Only `egress: { mode: "http-gateway" }` needs this, but it lives on every
+ * workspace because the cost of getting it wrong is asymmetric: the trust
+ * install against a container with no CA prints one line and exits 0, while a
+ * container that missed it fails every later HTTPS connection with an error
+ * that names no cause.
+ */
+/**
+ * Install the egress interception CA, and say what was there to install.
+ *
+ * One shell string rather than a script in the image, because **the image cannot
+ * run this at all**, and the reason is ordering rather than preference.
+ * Cloudflare's own recipe assumes interception is declared as container
+ * configuration, so the runtime mounts the CA before the container starts.
+ * `@cloudflare/computer` uses the raw container API, where the only interception
+ * hooks are methods called *after* `start()` — so an entrypoint runs strictly
+ * before the CA can exist, finds nothing, and reports the container
+ * un-intercepted while every later TLS connection fails.
+ *
+ * The listing comes first and runs unconditionally: when the CA is missing,
+ * *what else is in that directory* is the only evidence distinguishing "mounted
+ * somewhere else" from "never provisioned", and it costs one line.
+ */
+export const TRUST_CA_COMMAND = [
+    'ls -A /etc/cloudflare/certs 2>&1 || echo "(no /etc/cloudflare/certs)"',
+    "CA=/etc/cloudflare/certs/cloudflare-containers-ca.crt",
+    'if [ -r "$CA" ]; then',
+    // Trailing operators, not leading ones: a newline ends a command in sh, so an
+    // `&&` opening the next line is a syntax error rather than a continuation.
+    '  install -m 644 "$CA" /usr/local/share/ca-certificates/cloudflare-containers-ca.crt &&',
+    "  update-ca-certificates > /dev/null 2>&1 &&",
+    '  echo TRUSTED || echo "TRUST FAILED"',
+    "else",
+    '  echo "NO CA AT $CA"',
+    "fi"
+].join("\n");
+/** How long the trust install may take before it is not going to happen. */
+const TRUST_TIMEOUT_MS = 30_000;
+/**
+ * Whether the container this object is talking to has had the CA installed.
+ *
+ * ## Why the answer is in memory
+ *
+ * What it describes is a *container*, which does not outlive the isolate in any
+ * way worth persisting. A stored `true` would be the exact bug this exists to
+ * prevent — a flag surviving the container it describes, and vouching for its
+ * replacement.
+ *
+ * It is wrong only in the safe direction. An isolate that lost it re-runs an
+ * idempotent `install -m 644`.
+ *
+ * ## What clears it
+ *
+ * **The container's own exit**, watched through `monitor()`. This is the signal
+ * that does not depend on anyone noticing: a container replaced underneath a
+ * running command — by a reconnect, a relaunch, a crash — exits, and the watch
+ * fires whoever caused it. Nothing else here is in a position to know, because
+ * most commands run through the stub this object hands out and report their
+ * failures to their own caller, not to it.
+ *
+ * The watch lives in memory beside the flag it clears, which is the right
+ * lifetime: an isolate that loses one loses the other, and the replacement
+ * starts out untrusted. It is deliberately not held open with `waitUntil` —
+ * that would keep an invocation alive for the life of the container.
+ *
+ * A container seen not running, and a command reporting `EEXEC_LOST`, both call
+ * {@link forget} as well. They are cheap, they are strictly earlier in some
+ * orderings, and neither is load-bearing on its own.
+ */
+export class ContainerTrust {
+    deps;
+    #trusted = false;
+    /** Whether an exit watch is standing for the container now running. */
+    #watching = false;
+    /** Bumped by {@link forget}, so a watch armed before it is ignored. */
+    #generation = 0;
+    /**
+     * Whether this container's deployment fault has already been reported.
+     *
+     * Same lifetime as {@link ContainerTrust.forget}'s other flag, and for the
+     * same reason: what it describes is one container. A fault that outlived it
+     * would silence the report for the replacement, which is the container an
+     * operator is waiting to hear about.
+     */
+    #faultReported = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Forget that any container was trusted.
+     *
+     * Drops the standing watch too, because this is also reached for a container
+     * that keeps running — a `running` read, a lost exec. The watch it leaves
+     * behind ignores that container's real exit, so without a fresh one nothing
+     * would clear the flag again and the replacement would be vouched for.
+     */
+    forget() {
+        this.#generation += 1;
+        this.#trusted = false;
+        this.#watching = false;
+        this.#faultReported = false;
+    }
+    /**
+     * Watch this container's exit, so its replacement is not trusted on its
+     * behalf.
+     *
+     * Re-armed rather than kept: the promise settles once, for the container it
+     * was taken from, so the next {@link ensure} takes a fresh one for whatever is
+     * running then.
+     *
+     * A rejection is an exit too — the runtime reporting the container went away
+     * badly — so both settlements clear the flag, and neither is allowed to
+     * surface as an unhandled rejection.
+     *
+     * An exit already accounted for — the container was forgotten since — is not
+     * reported: a replacement may be running by then, and it is not the one that
+     * exited.
+     */
+    #watch() {
+        if (this.#watching)
+            return;
+        const container = this.deps.container();
+        if (!container)
+            return;
+        const generation = this.#generation;
+        try {
+            // A stale watch returns before touching anything: `#watching` belongs to
+            // whichever watch was armed since.
+            const done = () => {
+                if (generation !== this.#generation)
+                    return;
+                this.forget();
+                this.deps.onExit?.();
+            };
+            container.monitor().then(done, done);
+            this.#watching = true;
+        }
+        catch (err) {
+            // No watch, so the flag keeps its other two ways of being cleared. Worth a
+            // line because it silently widens the window this class exists to close.
+            console.warn(`[${this.deps.tag()}] could not watch the container`, {
+                id: this.deps.id(),
+                err: String(err)
+            });
+        }
+    }
+    /**
+     * Trust the CA if this container has not been trusted yet.
+     *
+     * Called from the workspace's `ready()` path, which is the earliest point that
+     * is not too early: the backend's `connect()` has completed, so start and
+     * interception have both happened.
+     *
+     * **Never throws.** A workspace that cannot trust the CA still has a checkout,
+     * a shell and a git history, and whatever runs next will say plainly what went
+     * wrong — refusing to proceed here would replace a legible TLS error with an
+     * opaque one.
+     */
+    async ensure() {
+        this.#watch();
+        if (this.#trusted)
+            return;
+        // An exec pushes the workspace before it spawns, and a new container is
+        // empty, so this one — the first in every container — carries the whole
+        // tree. {@link TRUST_TIMEOUT_MS} bounds the process, not any of that.
+        const startedAt = Date.now();
+        try {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const handle = __addDisposableResource(env_1, await this.deps
+                    .workspace()
+                    .runtime.exec(TRUST_CA_COMMAND, {
+                    cwd: "/",
+                    encoding: "utf8",
+                    timeoutMs: TRUST_TIMEOUT_MS
+                }), false);
+                const result = await handle.result();
+                const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+                // Marked only when the command reported an outcome that will not change
+                // inside this container. `TRUSTED` is the success; `NO CA AT …` is the
+                // intentional terminal case, since interception is configured by the
+                // `connect()` already awaited and a CA absent now stays absent until the
+                // container is replaced — retrying that on the object's hottest path would
+                // buy nothing.
+                //
+                // `TRUST FAILED` is neither. The command exits 0 whatever happens, so
+                // treating "it ran" as "it worked" would mark a container trusted whose
+                // `install` or `update-ca-certificates` failed — and every later HTTPS
+                // connection in it fails with nothing naming the cause, permanently,
+                // because nothing tries again.
+                //
+                // A throw leaves this false too, so an unreachable container is retried.
+                this.#trusted = !output.includes("TRUST FAILED");
+                // Logged at info once per container, deliberately. The container's own
+                // stdout does not reach Workers Observability, so this line is the only
+                // place an operator can see whether the container can speak TLS at all —
+                // and its absence is itself the answer when a workspace never got this far.
+                //
+                // Once per container rather than per call is also what makes it readable:
+                // on the busiest entry point in the object, a line per call would bury the
+                // one that matters under thousands that say the same thing.
+                console.info(`[${this.deps.tag()}] container TLS trust`, {
+                    id: this.deps.id(),
+                    exitCode: result.exitCode,
+                    trusted: this.#trusted,
+                    // Where a cold workspace's time went, on the line already logged once
+                    // per container.
+                    pushed: result.pushed,
+                    ms: Date.now() - startedAt,
+                    output
+                });
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        catch (err) {
+            // A deployment fault is reported as itself, at error, once per container.
+            // The generic line below is the right one for a container that is merely
+            // unreachable — a retry is what clears that. It is the wrong one for a
+            // Worker whose image or container application cannot work at all:
+            // retrying logs the same symptom until something else gives up, and the
+            // sentence naming the cause is the one an operator needs.
+            //
+            // Only the *log* stops. The trust command is still sent on the next call,
+            // because the classification is a string match and this is the direction
+            // that is safe to be wrong in: a misread costs a line nobody needed, where
+            // refusing to retry would leave a container permanently untrusted on the
+            // strength of a message the library is free to reword. What actually ends
+            // the reporting is the container going away, which clears the flag through
+            // the same watch that clears the trust.
+            const fault = deploymentFault(err);
+            if (fault) {
+                if (!this.#faultReported) {
+                    this.#faultReported = true;
+                    console.error(`[${this.deps.tag()}] ${fault.summary}`, {
+                        id: this.deps.id(),
+                        remedy: fault.remedy,
+                        err: String(err)
+                    });
+                }
+                return;
+            }
+            console.warn(`[${this.deps.tag()}] could not trust the interception CA`, {
+                id: this.deps.id(),
+                // Separates a container that refused at once from one that was pushed
+                // to and then dropped.
+                ms: Date.now() - startedAt,
+                err: String(err)
+            });
+        }
+    }
+}

package/dist/workspace/container-deps.d.ts

@@ -0,0 +1,54 @@
+import { type Workspace } from "@cloudflare/computer";
+/** Written into the tree by a successful host install; see `./install-job.ts`. */
+export declare const INSTALLED_MARKER = ".da-installed";
+/**
+ * The per-container setup, and a read of the marker under `dir`.
+ *
+ * The helper mounts the package root the command targets — its directory, or
+ * `--prefix`, `--cwd`, `--dir`, `-C` — only under the workspace, never inside
+ * another tree. Workspace members are not mounted: a mount point cannot be
+ * removed, so one guessed into `dist/` breaks `rm -rf dist`, and an install at
+ * the root puts the bulk of the tree there.
+ *
+ * Wrappers are written with `install`, never through the path: `npm` is
+ * commonly a symlink to `npm-cli.js`, and writing through it replaces npm with a
+ * wrapper that execs itself. For the same reason a wrapper finds its tool on
+ * `PATH` with `WRAPPER_DIR` skipped, when it runs. `corepack enable` puts its
+ * shims beside the `corepack` on `PATH` — the wrapper — so it is pointed at the
+ * real one's directory instead.
+ */
+export declare function depsSetupCommand(workspaceDir: string, dir?: string): string;
+/** What a setup run found in the container. */
+export interface DepsFound {
+    /** The marker's contents, or `null` when no host install completed here. */
+    marker: string | null;
+}
+export interface ContainerDepsDeps {
+    workspace: () => Workspace;
+    workspaceDir: string;
+    tag: () => string;
+    id: () => string;
+}
+/**
+ * The setup 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 ContainerDeps {
+    #private;
+    private readonly deps;
+    constructor(deps: ContainerDepsDeps);
+    forget(): void;
+    /**
+     * Run the setup if this container has not had it, and report the marker under
+     * `dir`. `undefined` when it had, or with no `dir`.
+     *
+     * Throws when the container answered and the setup did not finish: nothing
+     * would say so later, since an unwrapped install succeeds, into the workspace.
+     * An unreachable container is only logged, like the CA install: the command
+     * after it fails the same way.
+     */
+    ensure(dir?: string): Promise<DepsFound | undefined>;
+}