@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/repo/url.js

@@ -6,7 +6,7 @@
  * naming it": every pattern here turns away a string that resolves to something
  * other than what it appears to name.
  */
-/** The forges a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
+/** The hosts a clone URL may name. `RepoConfig.allowedHosts` overrides it. */
 export const DEFAULT_ALLOWED_HOSTS = ["github.com"];
 /** Branch names a push must never target, whatever the model believes. */
 export const PROTECTED_BRANCHES = new Set([
@@ -88,7 +88,7 @@ export function sameRepoUrl(a, b) {
     return canonical(a) === canonical(b);
 }
 /**
- * A name a forge would actually issue — and one that is safe to use as a path
+ * A name GitHub would actually issue — and one that is safe to use as a path
  * segment and as a key.
  *
  * GitHub's rule for an owner and a repository alike is alphanumerics, `-`, `_`
@@ -101,17 +101,17 @@ export function sameRepoUrl(a, b) {
  * is a separator in somebody else's key format, which is how two callers end up
  * sharing one workspace.
  */
-const FORGE_NAME = /^[A-Za-z0-9._-]+$/;
-function isForgeName(name) {
+const GITHUB_NAME = /^[A-Za-z0-9._-]+$/;
+function isGitHubName(name) {
     // `.` and `..` pass the character class and are exactly the two that must not.
-    return name !== "." && name !== ".." && FORGE_NAME.test(name);
+    return name !== "." && name !== ".." && GITHUB_NAME.test(name);
 }
 /**
  * `owner/repo` out of a repository URL, or `undefined` if it is not one.
  *
  * Anchored on the **parsed host** rather than matched in the string, so
  * `https://evil.example.com/github.com/owner/repo` is not a github.com URL.
- * Both names are then checked against {@link isForgeName}, so a name that could
+ * Both names are then checked against {@link isGitHubName}, so a name that could
  * traverse a path or split somebody else's key never gets as far as being one.
  *
  * `undefined` is a refusal at every caller, never a reason to carry on with a
@@ -125,7 +125,7 @@ export function parseRepo(url, allowedHosts = DEFAULT_ALLOWED_HOSTS) {
     if (!match)
         return undefined;
     const [, owner, repo] = match;
-    if (!isForgeName(owner) || !isForgeName(repo))
+    if (!isGitHubName(owner) || !isGitHubName(repo))
         return undefined;
     return { owner, repo };
 }

package/dist/scratch/index.d.ts

@@ -42,7 +42,7 @@ import type { AgentPlugin } from "@dynamicagents/core";
 /** Where a scratchpad lives, unless the host says otherwise. */
 export declare const DEFAULT_SCRATCH_DIR = "/workspace/scratch";
 /**
- * Run one command in the host's container. Matches `computerExec`'s shape.
+ * Run one command in the host's container. Matches `workspaceExec`'s shape.
  *
  * Injected rather than imported, like `/repo`'s: `npm run verify:exports` fails
  * any subpath whose module graph reaches a sibling's, and a scratchpad that
@@ -54,7 +54,7 @@ export type ScratchExec = (command: string, options?: {
     env?: Record<string, string | undefined>;
     timeout?: number;
     /**
-     * The executing subtask's runtime state, forwarded **opaquely** — the same
+     * The running sub-agent's `runtime()`, forwarded **opaquely** — the same
      * pass-through `/repo` does, for the same reason. This plugin never looks
      * inside it.
      */
@@ -96,7 +96,7 @@ export interface ScratchConfig {
      * Runs commands in the container holding the workspace.
      *
      * Uncredentialed, and nothing here ever needs a credential: a scratchpad has
-     * no remote, so no operation in this plugin talks to a forge.
+     * no remote, so no operation in this plugin talks to GitHub.
      */
     exec: ScratchExec;
     /** Where the scratchpad lives. Defaults to {@link DEFAULT_SCRATCH_DIR}. */
@@ -153,6 +153,6 @@ export interface ScratchConfig {
  * carries the same copy for the same reason.
  */
 export declare function truncateOutput(text: string, max: number): string;
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export declare const SCRATCH_OPEN_TOOL = "scratch_open";
 export declare function scratch(config: ScratchConfig): AgentPlugin;

package/dist/scratch/index.js

@@ -68,10 +68,10 @@ export function truncateOutput(text, max) {
         return text.slice(0, Math.max(0, max));
     return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
 }
-/** The tool name, exported so a host restricting its main agent can name it. */
+/** The tool name, exported so a host restricting the plugin can name it. */
 export const SCRATCH_OPEN_TOOL = "scratch_open";
 /**
- * What the delegating agent is told.
+ * What the model is told.
  *
  * The mixing rule at the end is the line worth its tokens. A host that keys one
  * workspace selection per caller — which is what makes a scratchpad routable at
@@ -294,19 +294,20 @@ export function scratch(config) {
             .filter(Boolean)
             .join(" "), maxChars);
     };
+    const context = capabilityFor(dir);
     return definePlugin({
-        key: "scratch",
+        name: "scratch",
         /**
-         * The main agent's, and no tool family — which is a decision rather than an
-         * omission.
+         * For a parent, never a sub-agent — which the host decides by installing it
+         * on one and not the other.
          *
          * Opening a scratchpad *selects a workspace*, exactly as `repo_clone` does.
-         * A subagent holding this could re-point the workspace its parent prepared
+         * A sub-agent holding this could re-point the workspace its parent prepared
          * half-way through its own run, which is the hazard a host's per-caller
-         * selection already has to document. A delegated run works in whatever it
-         * was given.
+         * selection already has to document. A sub-agent works in whatever it was
+         * given.
          */
-        mainAgentTools: () => ({
+        tools: (ctx) => ({
             [SCRATCH_OPEN_TOOL]: tool({
                 description: "Open a scratchpad: a git repository with no remote, in your container, " +
                     "for work that does not need a cloned repository. Use it before " +
@@ -318,9 +319,9 @@ export function scratch(config) {
                         .optional()
                         .describe("Discard everything in the scratchpad first, including files an earlier task left")
                 }),
-                execute: ({ reset }) => open(reset, undefined)
+                execute: ({ reset }) => open(reset, ctx.runtime())
             })
         }),
-        capability: capabilityFor(dir)
+        context: [{ provider: { get: async () => context } }]
     });
 }

package/dist/{computer → workspace}/advisory.d.ts

@@ -17,9 +17,9 @@ import type { InstallState } from "./install.js";
  *   A ceiling is a hard wall about the Durable Object, and the two are then told
  *   apart only by reading prose.
  * - Capacity must not travel through a channel gated by
- *   {@link file://./gate.ts needsDependencies}, or a full workspace says nothing
+ *   {@link file://../computer/gate.ts needsDependencies}, or a full workspace says nothing
  *   at all to `echo hi > file.txt` — the command whose write is being lost.
- * - "The tree is fine now", after a subagent installed by hand, has no honest
+ * - "The tree is fine now", after an agent installed by hand, has no honest
  *   spelling as a job record: fabricating a `done` rests on the presence of a
  *   `node_modules` directory, which the wreckage of the very install being
  *   overridden already satisfies.
@@ -56,7 +56,7 @@ export type WorkspaceAdvisory = {
      * Reported rather than acted on, because its presence proves nothing in
      * either direction. A half-finished `npm ci` leaves the directory behind
      * with an incomplete tree, so treating existence as success hides the
-     * common failure outright; and a subagent that re-ran the install by hand
+     * common failure outright; and an agent that re-ran the install by hand
      * leaves a record the host cannot update, since the host cannot see an
      * install it did not start. Both look identical from here, so the reader
      * is told which way the ambiguity runs rather than being handed a guess.
@@ -181,7 +181,7 @@ export declare function deriveAdvisories(input: AdvisoryInput): readonly Workspa
 /**
  * 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/{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) {
@@ -188,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/{computer/host → workspace}/ca-trust.d.ts

@@ -70,7 +70,14 @@ export declare class ContainerTrust {
     #private;
     private readonly deps;
     constructor(deps: ContainerTrustDeps);
-    /** Forget that any container was trusted. */
+    /**
+     * 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.

package/dist/{computer/host → workspace}/ca-trust.js

@@ -127,7 +127,7 @@ export class ContainerTrust {
     #trusted = false;
     /** Whether an exit watch is standing for the container now running. */
     #watching = false;
-    /** Bumped by {@link forget}, so a watch settling after it is ignored. */
+    /** Bumped by {@link forget}, so a watch armed before it is ignored. */
     #generation = 0;
     /**
      * Whether this container's deployment fault has already been reported.
@@ -141,10 +141,18 @@ export class ContainerTrust {
     constructor(deps) {
         this.deps = deps;
     }
-    /** Forget that any container was trusted. */
+    /**
+     * 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;
     }
     /**
@@ -171,8 +179,9 @@ export class ContainerTrust {
             return;
         const generation = this.#generation;
         try {
+            // A stale watch returns before touching anything: `#watching` belongs to
+            // whichever watch was armed since.
             const done = () => {
-                this.#watching = false;
                 if (generation !== this.#generation)
                     return;
                 this.forget();

package/dist/{computer/host → workspace}/container-deps.d.ts

@@ -1,6 +1,10 @@
 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";
+/** Every package root with a tree on this container's disk, one per line. */
+export declare const DEPS_ROOTS_COMMAND = "for f in /var/lib/workspace-deps/*.root; do [ -f \"$f\" ] && { cat \"$f\"; echo; }; done; true";
+/** {@link DEPS_ROOTS_COMMAND}'s output as paths, each once. */
+export declare function parseDepsRoots(stdout: string): string[];
 /**
  * The per-container setup, and a read of the marker under `dir`.
  *

package/dist/{computer/host → workspace}/container-deps.js

@@ -65,6 +65,11 @@ import { deploymentFault } from "./container-fault.js";
  * this installs ahead of the real binaries on `PATH`. Mounting earlier cannot
  * work: a bootstrap that initialises submodules and installs each of them in one
  * command creates the directories the mounts belong in.
+ *
+ * A container restored from a snapshot (see `./deps-snapshot.ts`) has the trees
+ * on its disk and none of the mounts, which are kernel state. So each mount
+ * records its package root beside its tree, and the setup mounts every recorded
+ * root again before it reads the marker through one.
  */
 /** Where the trees live on the container's disk. */
 const DEPS_DISK = "/var/lib/workspace-deps";
@@ -86,6 +91,23 @@ const WRAPPED = [
 ];
 /** Written into the tree by a successful host install; see `./install-job.ts`. */
 export const INSTALLED_MARKER = ".da-installed";
+/**
+ * The package root a tree belongs to, written beside it as `<tree>.root`.
+ *
+ * Beside rather than inside: `npm ci` empties the tree it installs into, and the
+ * hash a tree is named by cannot be turned back into the path.
+ */
+const ROOT_SUFFIX = ".root";
+/** Every package root with a tree on this container's disk, one per line. */
+export const DEPS_ROOTS_COMMAND = `for f in ${DEPS_DISK}/*${ROOT_SUFFIX}; do [ -f "$f" ] && { cat "$f"; echo; }; done; true`;
+/** {@link DEPS_ROOTS_COMMAND}'s output as paths, each once. */
+export function parseDepsRoots(stdout) {
+    const roots = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("/"));
+    return [...new Set(roots)];
+}
 /**
  * The per-container setup, and a read of the marker under `dir`.
  *
@@ -118,7 +140,7 @@ export function depsSetupCommand(workspaceDir, dir) {
         'nm="$dir/node_modules"',
         'mountpoint -q "$nm" && exit 0',
         `disk="${DEPS_DISK}/$(printf %s "$dir" | sha256sum | cut -c1-16)"`,
-        'mkdir -p "$disk" "$nm" && mount --bind "$disk" "$nm" && exit 0',
+        `mkdir -p "$disk" "$nm" && mount --bind "$disk" "$nm" && { printf %s "$dir" > "$disk${ROOT_SUFFIX}"; exit 0; }`,
         `echo "workspace-deps: could not put $nm on the container's disk" >&2`,
         "exit 1"
     ].join("\n");
@@ -139,6 +161,9 @@ export function depsSetupCommand(workspaceDir, dir) {
         `install -m 755 /tmp/workspace-deps-mount ${MOUNT_HELPER} || exit 1`,
         `printf '%s\\n' ${shellQuote(wrapper)} > /tmp/workspace-deps-wrap`,
         `for tool in ${WRAPPED.join(" ")}; do install -m 755 /tmp/workspace-deps-wrap "${WRAPPER_DIR}/$tool" || exit 1; done`,
+        // A root that is not in this checkout is left alone by the helper, and one
+        // that cannot be mounted reads as no marker below — an install, not a fault.
+        `for f in ${DEPS_DISK}/*${ROOT_SUFFIX}; do [ -f "$f" ] && ${MOUNT_HELPER} "$(cat "$f")"; done`,
         ...(dir
             ? [
                 `echo "MARKER $(cat ${shellQuote(`${dir}/node_modules/${INSTALLED_MARKER}`)} 2>/dev/null || echo -)"`

package/dist/{computer/host → workspace}/container-fault.d.ts

@@ -3,9 +3,9 @@
  *
  * 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 two 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.
+ * 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

package/dist/{computer/host → workspace}/container-fault.js

@@ -3,9 +3,9 @@
  *
  * 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 two 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.
+ * 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
@@ -21,14 +21,18 @@
 /**
  * Match on the shape the backend formats, not on the prose after it.
  *
- * `[stage=auth]` is the stage label `CloudflareContainerBackend` 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. Both are stabler than the explanations they introduce, and
- * neither has a `code` to key on the way a lost exec does.
+ * `[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.
  *
@@ -54,5 +58,16 @@ export function deploymentFault(err) {
                 "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/deps-snapshot.d.ts

@@ -0,0 +1,110 @@
+import type { Workspace } from "@cloudflare/computer";
+export interface DepsSnapshotRecord {
+    /** The platform's snapshot id. */
+    id: string;
+    /** In bytes, as the platform reported it. */
+    size: number;
+    /** The image reference it was taken on — see the file comment. */
+    image: string;
+    /** Where the install ran. */
+    dir: string;
+    /** The install fingerprint its marker holds. */
+    fingerprint: string;
+    /** Every package root with a tree on the disk, and its inputs' digest then. */
+    roots: {
+        dir: string;
+        fingerprint: string | null;
+    }[];
+    /** {@link packageRootSet} of the checkout then. */
+    rootSet: string;
+    at: number;
+}
+/** What a restore is checked against: the install a cold start would run. */
+export interface ExpectedTree {
+    dir: string;
+    fingerprint: string;
+}
+/** A tree an install finished, as its record names it — `at` tells two apart. */
+export interface InstalledTree extends ExpectedTree {
+    at: number;
+}
+export interface DepsSnapshotDeps {
+    storage: DurableObjectStorage;
+    container: () => Container | undefined;
+    /** The image a start from no snapshot would boot. */
+    image: () => string | undefined;
+    workspace: () => Workspace;
+    rootFingerprint: (dir: string) => Promise<string | null>;
+    /** The tree the install record says this container holds. */
+    tree: () => Promise<{
+        dir: string;
+        fingerprint: string | null;
+        at: number;
+    } | undefined>;
+    tag: () => string;
+    id: () => string;
+}
+/**
+ * Which package roots a checkout has, as one digest: every directory under
+ * `dir` with a `package.json`, and the submodules `.gitmodules` declares — one a
+ * bootstrap clones in the container has no `package.json` here until then.
+ */
+export declare function packageRootSet(fs: Workspace["fs"], dir: string): Promise<string>;
+export declare class DepsSnapshot {
+    #private;
+    private readonly deps;
+    readonly launch: {
+        readonly containerSnapshot: ContainerSnapshotRestoreParams | undefined;
+    };
+    constructor(deps: DepsSnapshotDeps);
+    /**
+     * Restore with the next start if the record fits it, and say which record.
+     *
+     * `expected` is a thunk because it reads the checkout, and a workspace with no
+     * snapshot or one from another image should not pay for that.
+     */
+    arm(expected: () => Promise<ExpectedTree | undefined>): Promise<DepsSnapshotRecord | undefined>;
+    /** Forget an armed restore, taken or not. */
+    disarm(): void;
+    /**
+     * Whether the container that came up holds `record`'s tree, judged by the
+     * marker the setup read in it.
+     *
+     * Drops the record when a start took it and the tree is not there; leaves it
+     * when no start did, since nothing was learned about it.
+     */
+    restored(record: DepsSnapshotRecord, marker: string | null | undefined): Promise<boolean>;
+    /**
+     * Snapshot the running container, which has just installed `tree`, after any
+     * snapshot already in flight — a later install's request is never dropped for
+     * an earlier one's.
+     *
+     * Never throws: a container that cannot be snapshotted installs again next
+     * time, which is today's cost and no worse.
+     */
+    take(tree: InstalledTree): Promise<void>;
+    /** Snapshots in flight, finished — for whatever is about to stop the container. */
+    settled(): Promise<void>;
+    /**
+     * The entries that ask for `tree`'s snapshot, for the install to write with
+     * its verdict — see the file comment, and {@link takeDue}.
+     */
+    dueEntries(tree: InstalledTree): Record<string, unknown>;
+    /** Take the snapshot an install asked for, if one is waiting. */
+    takeDue(): Promise<void>;
+    /** The container went, and the disk an asked-for snapshot was of with it. */
+    forgetDue(): Promise<void>;
+    get(): Promise<DepsSnapshotRecord | undefined>;
+    /**
+     * Start from another workspace's snapshot — one taken for the same checkout
+     * path on the same image, as a worktree shares with the checkout it was cut
+     * from.
+     *
+     * Kept out when this workspace's own snapshot already fits, and refused when
+     * the offered one does not.
+     */
+    seed(record: DepsSnapshotRecord, expected: () => Promise<ExpectedTree | undefined>): Promise<{
+        seeded: boolean;
+        reason?: string;
+    }>;
+}