@dynamicagents/plugins 0.13.0 → 0.14.0

package/dist/workspace/object.d.ts

@@ -1,6 +1,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { type WorkspaceEgressPolicy, type WorkspaceStub } from "@cloudflare/computer";
 import { ContainerBackend, type ContainerInstanceSize } from "@cloudflare/computer/backends/container";
+import { type DepsSnapshotRecord } from "./deps-snapshot.js";
 import { type WorkspaceAdvisory } from "./advisory.js";
 import type { InstallPlan, InstallState } from "./install.js";
 import type { RepoGitResult } from "../repo/index.js";
@@ -49,6 +50,7 @@ import type { RepoGitResult } from "../repo/index.js";
  * and each carries the reasoning for its own decisions:
  *
  * - `./install-job.ts` — when a dependency install runs, and every guard on it.
+ * - `./deps-snapshot.ts` — starting a container from one that already installed.
  * - `./sync.ts` — the host's half of syncing, which nothing else will do.
  * - `./ca-trust.ts` — making a container able to speak TLS.
  * - `./git-identity.ts` — who a container's commits belong to.
@@ -337,15 +339,33 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
         dir: string;
         repo?: string;
     }): Promise<InstallState>;
+    /**
+     * This workspace's dependency snapshot, for another of the same class to start
+     * from — see {@link seedDepsSnapshot}. Starts no container and moves no
+     * deadline.
+     */
+    depsSnapshot(): Promise<DepsSnapshotRecord | undefined>;
+    /**
+     * Start this workspace's next container from `record`, another workspace's
+     * dependency snapshot, when it fits the checkout here — a worktree at the same
+     * path as the checkout it was cut from. Call it after the checkout and before
+     * the first command.
+     *
+     * A snapshot is that workspace's whole disk, so offer one only between
+     * workspaces of the same caller.
+     */
+    seedDepsSnapshot(record: DepsSnapshotRecord): Promise<{
+        seeded: boolean;
+        reason?: string;
+    }>;
     /**
      * Stop the container, and **keep everything on disk**.
      *
      * The counterpart to {@link reclaimIfIdle}, and the difference is the whole
      * reason both exist. A reclaim is for a workspace nobody wants again: it empties
-     * storage, so the checkout and the dependency tree go with the container. This is
-     * for a workspace that will be worked in again — the next task on the same
-     * repository has to skip the clone and the install, which is the cost the whole
-     * design is arranged around.
+     * storage, so the checkout and the dependency snapshot go with the container.
+     * This is for a workspace that will be worked in again — the next task on the
+     * same repository skips the clone, and the install by restoring the snapshot.
      *
      * **Why a caller needs this at all.** The idle deadline would eventually do it,
      * but it cannot be tuned down to meet a cost target: `containerIdleMs` must

package/dist/workspace/object.js

@@ -9,6 +9,7 @@ import { createGitClient } from "@cloudflare/computer/git";
 import { createCloudflareObserver } from "@cloudflare/computer/observe/cloudflare";
 import { ContainerTrust } from "./ca-trust.js";
 import { ContainerDeps } from "./container-deps.js";
+import { DepsSnapshot } from "./deps-snapshot.js";
 import { ContainerGitIdentity } from "./git-identity.js";
 import { InstallJob } from "./install-job.js";
 import { WorkspaceGitHost } from "./git-host.js";
@@ -62,6 +63,7 @@ import { pathExists } from "./read.js";
  * and each carries the reasoning for its own decisions:
  *
  * - `./install-job.ts` — when a dependency install runs, and every guard on it.
+ * - `./deps-snapshot.ts` — starting a container from one that already installed.
  * - `./sync.ts` — the host's half of syncing, which nothing else will do.
  * - `./ca-trust.ts` — making a container able to speak TLS.
  * - `./git-identity.ts` — who a container's commits belong to.
@@ -135,6 +137,8 @@ const HOLDS_KEY = "container-holds";
 const RELEASE_ASKED_KEY = "container-release-asked";
 /** Where the container-warm wake keeps its current schedule id. */
 const CONTAINER_WARM_ID = "container-warm-id";
+/** Where the dependency-snapshot wake keeps its current schedule id. */
+const DEPS_SNAPSHOT_ID = "deps-snapshot-id";
 /**
  * How long a container stays up after the last command **started**.
  *
@@ -301,6 +305,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             idleReclaim: () => this.#onIdleReclaim(),
             containerIdle: (payload) => this.#onContainerIdle(payload),
             containerWarm: () => this.#onContainerWarm(),
+            depsSnapshot: () => this.#onDepsSnapshot(),
             syncRetry: (payload) => this.#onSyncDrain(payload)
         },
         onError: (err) => {
@@ -337,6 +342,18 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         key: CONTAINER_WARM_ID,
         callback: "containerWarm"
     });
+    /**
+     * Snapshot a container that just installed — see `./deps-snapshot.ts`.
+     *
+     * From the alarm rather than the install's drain, which a model turn's
+     * `waitUntil` may own.
+     */
+    #snapshotDue = namedDeadline({
+        storage: this.ctx.storage,
+        scheduler: this.#wake.scheduler,
+        key: DEPS_SNAPSHOT_ID,
+        callback: "depsSnapshot"
+    });
     /**
      * Come back and move the next block of an outstanding pull.
      *
@@ -369,6 +386,19 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         ready: () => this.#ready(),
         waitUntil: (promise) => this.ctx.waitUntil(promise),
         containerGone: () => this.#containerGone(),
+        installedRecords: (tree) => this.#snapshot.dueEntries(tree),
+        installed: async () => void (await this.#snapshotDue.set(new Date())),
+        tag: () => this.#tag,
+        id: () => this.ctx.id.toString()
+    });
+    /** The next container's dependency trees — see `./deps-snapshot.ts`. */
+    #snapshot = new DepsSnapshot({
+        storage: this.ctx.storage,
+        container: () => this.ctx.container,
+        image: () => this.#image,
+        workspace: () => this.#workspace,
+        rootFingerprint: (dir) => this.#install.rootFingerprint(dir),
+        tree: () => this.#install.tree(),
         tag: () => this.#tag,
         id: () => this.ctx.id.toString()
     });
@@ -426,13 +456,21 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      * The binding name, the egress policy and the instance size are the
      * subclass's — see {@link WorkspaceObjectConfig}, which carries the warnings
      * on each.
+     *
+     * `launch` is how a start restores a dependency snapshot instead of booting
+     * the image — see `./deps-snapshot.ts`. Never in the env: the env is part of
+     * what a running container is matched against.
      */
     #backendMemo;
     get backend() {
         return (this.#backendMemo ??= this.#newBackend());
     }
+    /** The image a start boots, as the deploy prepared it. */
+    get #image() {
+        return this.ctx.container?.images?.[IMAGE_NAME];
+    }
     #newBackend() {
-        const image = this.ctx.container?.images?.[IMAGE_NAME];
+        const image = this.#image;
         return new ContainerBackend({
             container: () => this,
             workspace: {
@@ -442,7 +480,8 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             egress: this.#cfg.egress,
             name: IMAGE_NAME,
             instance: this.#cfg.instance,
-            containerEnv: image === undefined ? {} : { [IMAGE_ENV]: image }
+            containerEnv: image === undefined ? {} : { [IMAGE_ENV]: image },
+            launch: this.#snapshot.launch
         });
     }
     #workspaceMemo;
@@ -486,6 +525,7 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         this.#gitIdentity.forget();
         this.#deps.forget();
         await this.#install.containerGone();
+        await this.#snapshot.forgetDue();
     }
     /**
      * Set once {@link reclaimIfIdle} has emptied storage, until the alarm it armed
@@ -538,19 +578,53 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
         });
         return this.#readying;
     }
-    /** One start, run for whoever got there first — see {@link #ready}. */
+    /**
+     * One start, run for whoever got there first — see {@link #ready}.
+     *
+     * A cold start restores the dependency snapshot when one fits, and the marker
+     * the setup reads decides whether what came up is adopted as installed — see
+     * `./deps-snapshot.ts`.
+     */
     async #readyNow() {
         // Read **before** `ready()`, which starts a stopped container.
-        if (!this.ctx.container?.running)
+        let restoring;
+        if (!this.ctx.container?.running) {
             await this.#containerGone();
-        await this.#workspace.ready();
-        // Before the first exec, which pushes the whole tree into a new container.
-        await this.#purgeSyncedTrees();
-        await this.#trust.ensure();
-        await this.#gitIdentity.ensure();
-        const found = await this.#deps.ensure(await this.#install.dir());
-        if (found)
-            await this.#install.reconcile(found.marker);
+            restoring = await this.#snapshot.arm(() => this.#expectedTree());
+        }
+        try {
+            await this.#workspace.ready();
+            // Before the first exec, which pushes the whole tree into a new container.
+            await this.#purgeSyncedTrees();
+            await this.#trust.ensure();
+            await this.#gitIdentity.ensure();
+            const found = await this.#deps.ensure(restoring?.dir ?? (await this.#install.dir()));
+            if (found)
+                await this.#install.reconcile(found.marker);
+            if (restoring &&
+                (await this.#snapshot.restored(restoring, found?.marker)))
+                await this.#install.adopt(restoring);
+        }
+        finally {
+            this.#snapshot.disarm();
+        }
+    }
+    /**
+     * The install a cold start would owe: where the last one ran, or the checkout
+     * when none has — a worktree seeded before its first install.
+     */
+    async #expectedTree() {
+        const target = (await this.#install.target()) ?? (await this.#checkoutTarget());
+        if (!target)
+            return undefined;
+        const fingerprint = await this.#install.fingerprintFor(target);
+        return fingerprint ? { dir: target.dir, fingerprint } : undefined;
+    }
+    async #checkoutTarget() {
+        const record = await this.ctx.storage.get(CHECKOUT_KEY);
+        if (!record?.dir)
+            return undefined;
+        return { dir: record.dir, ...(record.repo ? { repo: record.repo } : {}) };
     }
     /**
      * Delete every `node_modules` that was synced into this object, once.
@@ -834,6 +908,26 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
     async startInstall(req) {
         return await this.#install.start(req);
     }
+    /**
+     * This workspace's dependency snapshot, for another of the same class to start
+     * from — see {@link seedDepsSnapshot}. Starts no container and moves no
+     * deadline.
+     */
+    async depsSnapshot() {
+        return await this.#snapshot.get();
+    }
+    /**
+     * Start this workspace's next container from `record`, another workspace's
+     * dependency snapshot, when it fits the checkout here — a worktree at the same
+     * path as the checkout it was cut from. Call it after the checkout and before
+     * the first command.
+     *
+     * A snapshot is that workspace's whole disk, so offer one only between
+     * workspaces of the same caller.
+     */
+    async seedDepsSnapshot(record) {
+        return await this.#snapshot.seed(record, () => this.#expectedTree());
+    }
     // --- lifecycle ---------------------------------------------------------------
     /**
      * Mark this workspace as in use, and push its reclamation back.
@@ -868,10 +962,9 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
      *
      * The counterpart to {@link reclaimIfIdle}, and the difference is the whole
      * reason both exist. A reclaim is for a workspace nobody wants again: it empties
-     * storage, so the checkout and the dependency tree go with the container. This is
-     * for a workspace that will be worked in again — the next task on the same
-     * repository has to skip the clone and the install, which is the cost the whole
-     * design is arranged around.
+     * storage, so the checkout and the dependency snapshot go with the container.
+     * This is for a workspace that will be worked in again — the next task on the
+     * same repository skips the clone, and the install by restoring the snapshot.
      *
      * **Why a caller needs this at all.** The idle deadline would eventually do it,
      * but it cannot be tuned down to meet a cost target: `containerIdleMs` must
@@ -1041,6 +1134,12 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             reason,
             running: this.ctx.container?.running ?? false
         });
+        // An install's snapshot the wake has not taken yet would go with the disk
+        // it is of, so it is taken here first. Not for a reclaim, which keeps
+        // nothing. Either way, one in flight needs the container running.
+        if (reason === "idle")
+            await this.#snapshot.takeDue();
+        await this.#snapshot.settled();
         // Hang up the session to computerd first: a destroy that cuts it live
         // surfaces as an uncaught `Network connection lost`. The workspace
         // reconnects on its next use, and `close()` swallows its own failures.
@@ -1305,6 +1404,21 @@ export class WorkspaceObjectBase extends WorkspaceContainerBase {
             await this.#sync.arm((payload?.attempt ?? 0) + 1);
         }
     }
+    /** An install finished in this container — see `./deps-snapshot.ts`. */
+    async #onDepsSnapshot() {
+        // The record is read from this object's storage — each root's inputs, and
+        // which roots there are — so the install's own pull has to have landed: it
+        // carries the submodules a bootstrap cloned. One still moving comes back;
+        // one that failed is left to the stop, which drains before it takes.
+        const synced = await this.#sync.drain(SYNC_DRAIN_BUDGET_MS);
+        if (synced === "incomplete") {
+            await this.#snapshotDue.set(new Date(Date.now() + SYNC_DRAIN_RESUME_MS));
+            return;
+        }
+        if (synced === "failed")
+            return;
+        await this.#snapshot.takeDue();
+    }
     /** The idle-reclaim deadline came due. */
     async #onIdleReclaim() {
         const { reclaimed, idleMs } = await this.reclaimIfIdle();

package/dist/workspace/wake.d.ts

@@ -14,6 +14,8 @@ export type WorkspaceWakeHandlers = {
     idleReclaim: () => Promise<void>;
     /** Start a cold container before a command needs it — see `./object.ts`. */
     containerWarm: () => Promise<void>;
+    /** Snapshot a container that just installed — see `./deps-snapshot.ts`. */
+    depsSnapshot: () => Promise<void>;
     containerIdle: (payload?: SyncDrainIntent) => Promise<void>;
     syncRetry: (payload?: SyncDrainIntent) => Promise<void>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamicagents/plugins",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Optional, composable capabilities for a Dynamic Agent: browser rendering, a Linux container, git and pull requests, a scratchpad, and Claude Code sessions. One subpath per plugin, so a bundle grows only with what it imports.",
   "keywords": [
     "ai-agents",
@@ -75,11 +75,11 @@
     "prepare": "husky || true && npm run build"
   },
   "peerDependencies": {
-    "@cloudflare/computer": "^0.4.0",
-    "@cloudflare/think": ">=0.20.0 <0.21.0",
-    "@dynamicagents/core": ">=0.13.0 <0.14.0",
-    "@platformatic/vfs": "^0.4.0",
-    "agents": ">=0.26.0 <0.27.0",
+    "@cloudflare/computer": "^0.5.0",
+    "@cloudflare/think": ">=0.20.2 <0.21.0",
+    "@dynamicagents/core": ">=0.14.0 <0.15.0",
+    "@platformatic/vfs": "^0.5.0",
+    "agents": ">=0.28.0 <0.29.0",
     "ai": "^7.0.88",
     "zod": "^4.4.3"
   },
@@ -92,13 +92,13 @@
     }
   },
   "devDependencies": {
-    "@cloudflare/computer": "^0.4.0",
-    "@cloudflare/think": "^0.20.0",
+    "@cloudflare/computer": "^0.5.0",
+    "@cloudflare/think": "^0.20.2",
     "@cloudflare/vitest-plugin": "^1.1.9",
-    "@dynamicagents/core": "^0.13.1",
-    "@platformatic/vfs": "^0.4.0",
+    "@dynamicagents/core": "^0.14.0",
+    "@platformatic/vfs": "^0.5.0",
     "@types/node": "^26.5.1",
-    "agents": "^0.26.0",
+    "agents": "^0.28.0",
     "ai": "^7.0.101",
     "eslint": "^10.10.0",
     "husky": "^9.1.7",