@dynamicagents/plugins 0.12.0 → 0.14.0

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

@@ -10,7 +10,7 @@
  *
  * ## Why this exists at all
  *
- * The alternative is a sentence in the subagent's soul — "install dependencies
+ * The alternative is a sentence in the sub-agent's soul — "install dependencies
  * before you do anything else" — and a standard with no command attached is one a
  * model satisfies with whichever check is cheapest: edit a README, run
  * `prettier --check` on that one file, report the change verified, and never run
@@ -36,16 +36,16 @@ export interface InstallProbe {
  * Where the install has got to, as the host reports it and the tools read it.
  *
  * Declared here rather than in the host because both sides depend on it and
- * neither owns the other: the Durable Object runs the job, and `sb_exec` refuses
+ * neither owns the other: the Durable Object runs the job, and `bash` refuses
  * to run against a tree that is still being built. A shape they agreed on
  * informally would drift, and the drift would show up as a shell command running
  * halfway through an `npm ci`.
  *
- * ## Why it is core's `JobState` with one field intersected in
+ * ## Why it is the host's `JobState` with one field intersected in
  *
- * Core owns the *choreography* around a job a Durable Object drives through its
- * alarm — arming, the single-flight guard, the staleness bound, the generation
- * marker a drain checks before it writes. This package owns what an install
+ * Core's `/job` owns the *choreography* around a job a Durable Object drives
+ * through its alarm — arming, the single-flight guard, the staleness bound, the
+ * generation a drain writes under. This package owns what an install
  * specifically **is**: which package manager, which lockfile, what counts as
  * skippable. Splitting them along that line is what lets a second job on the
  * same object — a coding-agent run, say — reuse every rule without inheriting
@@ -146,7 +146,7 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * from `pnpm@9` to `pnpm@10`, or add a dependency without regenerating the lock,
  * and every one of those changes what an install produces while leaving the
  * lockfile byte-identical. Hashing the lockfile alone calls that a match, skips
- * the install, and hands the subagent a `node_modules` that is quietly wrong —
+ * the install, and hands the agent a `node_modules` that is quietly wrong —
  * which surfaces as a missing module in a build, three tool calls later, with
  * nothing pointing back at the install that never ran.
  *
@@ -184,6 +184,15 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * A matching fingerprint means "the same install would produce the same tree".
  * It does **not** mean the tree is there: it is on the container's disk, and
  * goes with the container. The caller also needs a record that this container
- * finished it — see `./host/install-job.ts`.
+ * finished it — see `./install-job.ts`.
  */
 export declare function installFingerprint(fs: InstallProbe, dir: string, resolution: InstallResolution): Promise<string | null>;
+/**
+ * The same digest for a package root an install reached without being pointed
+ * at it — a submodule a bootstrap installs, say — where there is no command to
+ * fold in, and every lockfile the plan knows stands in for the one it would pick.
+ *
+ * For `./deps-snapshot.ts`, which restores every root's tree at once and so has
+ * to know none of them moved.
+ */
+export declare function rootFingerprint(fs: InstallProbe, dir: string, plan: InstallPlan): Promise<string | null>;

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

@@ -10,7 +10,7 @@
  *
  * ## Why this exists at all
  *
- * The alternative is a sentence in the subagent's soul — "install dependencies
+ * The alternative is a sentence in the sub-agent's soul — "install dependencies
  * before you do anything else" — and a standard with no command attached is one a
  * model satisfies with whichever check is cheapest: edit a README, run
  * `prettier --check` on that one file, report the change verified, and never run
@@ -96,6 +96,10 @@ function pinnedManager(packageJson) {
         return undefined;
     }
 }
+/** Every lockfile the plan names, each once. */
+function planLockfiles(plan) {
+    return [...new Set(plan.rules.flatMap((r) => [...r.lockfiles]))];
+}
 /**
  * Every lockfile the plan knows of that is present in `dir`.
  *
@@ -103,9 +107,8 @@ function pinnedManager(packageJson) {
  * about which manager it drives.
  */
 async function knownLockfiles(fs, dir, plan) {
-    const names = [...new Set(plan.rules.flatMap((r) => [...r.lockfiles]))];
     const present = [];
-    for (const name of names) {
+    for (const name of planLockfiles(plan)) {
         if (await fs.exists(`${dir}/${name}`))
             present.push(name);
     }
@@ -221,7 +224,7 @@ async function firstPresent(fs, dir, names) {
  * from `pnpm@9` to `pnpm@10`, or add a dependency without regenerating the lock,
  * and every one of those changes what an install produces while leaving the
  * lockfile byte-identical. Hashing the lockfile alone calls that a match, skips
- * the install, and hands the subagent a `node_modules` that is quietly wrong —
+ * the install, and hands the agent a `node_modules` that is quietly wrong —
  * which surfaces as a missing module in a build, three tool calls later, with
  * nothing pointing back at the install that never ran.
  *
@@ -259,7 +262,7 @@ async function firstPresent(fs, dir, names) {
  * A matching fingerprint means "the same install would produce the same tree".
  * It does **not** mean the tree is there: it is on the container's disk, and
  * goes with the container. The caller also needs a record that this container
- * finished it — see `./host/install-job.ts`.
+ * finished it — see `./install-job.ts`.
  */
 export async function installFingerprint(fs, dir, resolution) {
     if (resolution.kind !== "run")
@@ -273,10 +276,25 @@ export async function installFingerprint(fs, dir, resolution) {
         ...resolution.lockfiles,
         ...INSTALL_CONFIG_FILES
     ];
+    return await digestFiles(fs, dir, names, resolution.command);
+}
+/**
+ * The same digest for a package root an install reached without being pointed
+ * at it — a submodule a bootstrap installs, say — where there is no command to
+ * fold in, and every lockfile the plan knows stands in for the one it would pick.
+ *
+ * For `./deps-snapshot.ts`, which restores every root's tree at once and so has
+ * to know none of them moved.
+ */
+export async function rootFingerprint(fs, dir, plan) {
+    return await digestFiles(fs, dir, ["package.json", ...planLockfiles(plan), ...INSTALL_CONFIG_FILES], "");
+}
+/** `prefix`, then every file of `names` present in `dir`; null when none is. */
+async function digestFiles(fs, dir, names, prefix) {
     // Names as well as contents. Two lockfiles will not collide on content in
     // practice, but a digest that cannot say *which* file it read is one that
     // silently depends on the caller resolving them in the same order forever.
-    let input = resolution.command;
+    let input = prefix;
     let found = false;
     for (const name of names) {
         if (!(await fs.exists(`${dir}/${name}`)))

package/dist/{computer/host/workspace.d.ts → workspace/object.d.ts}

@@ -1,9 +1,10 @@
 import { DurableObject } from "cloudflare:workers";
 import { type WorkspaceEgressPolicy, type WorkspaceStub } from "@cloudflare/computer";
-import { CloudflareContainerBackend } from "@cloudflare/computer/backends/container";
-import { type WorkspaceAdvisory } from "../advisory.js";
-import type { InstallPlan, InstallState } from "../install.js";
-import type { RepoGitResult } from "../../repo/index.js";
+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";
 /**
  * A workspace: one Durable Object, one container, one repository.
  *
@@ -16,7 +17,7 @@ import type { RepoGitResult } from "../../repo/index.js";
  * A directory inside the plugin rather than a subpath beside it, so that one
  * capability stays one import path and a consumer cannot take the tools without
  * the object they address. The bundle cost of that is nothing: `sideEffects` is
- * false, so an agent that only calls `sb_exec` carries no container backend and
+ * false, so an agent that only calls `bash` carries no container backend and
  * no isomorphic-git.
  *
  * What this file must not do is import the plugin barrel. The barrel re-exports
@@ -29,7 +30,7 @@ import type { RepoGitResult } from "../../repo/index.js";
  * FUSE at `/workspace`. Commands run against the same tree the Worker reads over
  * RPC, and the tree outlives the container.
  *
- * **One repository per object**, because `computer` is strictly 1 DO ↔ 1
+ * **One repository per object**, because `@cloudflare/computer` is strictly 1 DO ↔ 1
  * container: the id derives from caller *and* repository (see `workspaceName`),
  * so two repositories for one caller are two objects and two containers.
  *
@@ -49,10 +50,11 @@ 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.
- * - `./git-host.ts` — the operations that hold the forge credential.
+ * - `./git-host.ts` — the operations that hold the GitHub credential.
  *
  * Each takes a small explicit seam, and that is the test: a module that needed
  * the whole object back would be a module that did not want extracting.
@@ -63,7 +65,7 @@ export declare const WORKSPACE_DIR = "/workspace";
  * The Durable Object name for one caller's checkout of one repository.
  *
  * Exported because several places must agree on it and none can see the others:
- * the plugin that resolves the stub, the agent that hands it down to subagents,
+ * the plugin that resolves the stub, the agent that hands it down to sub-agents,
  * and the cancellation path. A pipe rather than a slash, so the caller half
  * cannot forge a repository boundary by containing one.
  *
@@ -76,10 +78,23 @@ export declare const WORKSPACE_DIR = "/workspace";
  *
  * `repo` is not always a repository. A host may pass a sentinel through here as
  * one — a scratchpad is modelled that way, which is what keys it to its own
- * object and its own container. Anything that is not a forge name works, as long
+ * object and its own container. Anything that is not a GitHub name works, as long
  * as no caller could clone something that collides with it.
  */
 export declare function workspaceName(callerKey: string, repo?: string): string;
+/**
+ * How long a workspace survives without being used.
+ *
+ * A Durable Object is **never** reclaimed by the platform, and a namespace
+ * cannot be enumerated from a Worker, so nothing else is coming to clean up.
+ * Source-only workspaces are small (6.3 MB for slack-gatekeeper), which makes
+ * this hygiene rather than cost control — but unbounded hygiene is still
+ * unbounded.
+ *
+ * Exported because a host keeping work in a workspace has to say how long that
+ * work survives untouched.
+ */
+export declare const IDLE_RECLAIM_MS: number;
 /**
  * `work`, refused once `ms` pass without it settling. The work itself goes on;
  * only the wait for it ends — see {@link READY_DEADLINE_MS}.
@@ -97,16 +112,15 @@ declare class WorkspaceContainerHost extends DurableObject<Cloudflare.Env> {
 }
 /**
  * `withWorkspaceContainer` adds one method, `getWorkspaceContainer()`, over
- * `this.ctx.container` — the runtime's own container handle. There is no
- * `@cloudflare/containers` `Container` subclass here and so no `sleepAfter`:
- * idle shutdown is this object's job, and it lands on the wake map with
- * everything else.
+ * `this.ctx.container` — the runtime's own container handle, started with the
+ * image and instance size this object asks for. Stopping it is this object's
+ * job — see {@link CONTAINER_IDLE_MS}.
  */
 declare const WorkspaceContainerBase: typeof WorkspaceContainerHost & (new (...args: any[]) => WorkspaceContainerHost & {
     getWorkspaceContainer(): import("@cloudflare/computer/backends/container").WorkspaceContainerAPI;
 });
 /**
- * The forge credential, and who a commit made on this side is attributed to.
+ * The GitHub credential, and who a commit made on this side is attributed to.
  *
  * Config rather than an env read, because this class cannot name a consumer's
  * ambient `Env` — it is an interface `wrangler types` generates into *their*
@@ -120,7 +134,7 @@ declare const WorkspaceContainerBase: typeof WorkspaceContainerHost & (new (...a
  */
 export interface WorkspaceGitConfig {
     /**
-     * The **name** of the binding holding the forge credential — never the
+     * The **name** of the binding holding the GitHub credential — never the
      * credential itself.
      *
      * `workspaceConfig()` is an ordinary method on the prototype, and on a Durable
@@ -196,7 +210,7 @@ export interface WorkspaceObjectConfig {
     egress: WorkspaceEgressPolicy;
     /** How this deployment installs dependencies for this agent's checkouts. */
     installPlan: InstallPlan;
-    /** Log prefix — `coder-workspace`, `claude-coder-workspace`. */
+    /** Log prefix — `coding-workspace`, `claude-coordinator-workspace`. */
     label: string;
     /**
      * How long this agent's container stays up after the last command **started**.
@@ -204,14 +218,23 @@ export interface WorkspaceObjectConfig {
      * A per-agent value because the invariant on {@link CONTAINER_IDLE_MS} — it
      * must exceed the longest command the shell allows — is an invariant about the
      * *agent*, and the two differ by a factor of four. The coder's longest command
-     * is a tool call; `claude-coder`'s is a whole `claude -p` session that runs
+     * is a tool call; `claude-coordinator`'s is a whole `claude -p` session that runs
      * detached for its entire timeout.
      *
      * Omit it for the default. Raise it, never lower it, and raise it whenever the
      * agent's longest command grows.
      */
     containerIdleMs?: number;
-    /** The forge credential and commit identity — see {@link WorkspaceGitConfig}. */
+    /**
+     * The size this agent's container starts at — a tier such as `standard-2`, or
+     * `{ vcpu, memoryMib, diskMb }`.
+     *
+     * Requested on every start, and part of what a running container is matched
+     * against: change it and the next connect replaces a container started at the
+     * old size. Which size, and why there is no default: {@link file://./README.md}.
+     */
+    instance: ContainerInstanceSize;
+    /** The GitHub credential and commit identity — see {@link WorkspaceGitConfig}. */
     git: WorkspaceGitConfig;
 }
 /**
@@ -219,14 +242,13 @@ export interface WorkspaceObjectConfig {
  *
  * Abstract because a Durable Object class takes no constructor arguments, so
  * per-agent configuration cannot arrive that way. {@link workspaceConfig} is the
- * seam, and it is the shape core's own `RecipeSubagentBase.subagentRuntime`
- * uses for exactly the same reason.
+ * seam, for the same reason Think's own hooks are methods rather than options.
  *
  * ## Why `backend` and `#workspace` are lazy
  *
  * **Base class fields run before subclass fields**, so as plain fields they
  * would read `undefined` from any `workspaceConfig()` that touches a subclass
- * field — which `ClaudeCoderWorkspaceDO`'s does, for its credential store.
+ * field — which `ClaudeCoordinatorWorkspace`'s does, for its credential store.
  * Memoised getters remove the hazard rather than documenting it, which is what
  * lets a subclass implement the seam however it likes.
  */
@@ -236,7 +258,7 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
      * This Worker's bindings, as the host's own generated `Env` spells them.
      *
      * Re-declared rather than inherited so a subclass reading a binding of its own
-     * — `claude-coder`'s reaches for its credential pool — gets its real type
+     * — `claude-coordinator`'s reaches for its credential pool — gets its real type
      * instead of the base's. `declare` because the field is the runtime's; this
      * only narrows what TypeScript believes about it.
      */
@@ -245,11 +267,11 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
      * Everything this agent's workspace does differently. Called once, lazily.
      *
      * Read through {@link #cfg}, never directly: an implementation may build
-     * something real — `claude-coder`'s constructs its egress gateway — and this
+     * something real — `claude-coordinator`'s constructs its egress gateway — and this
      * is consulted on the busiest path in the object.
      */
     protected abstract workspaceConfig(): WorkspaceObjectConfig;
-    get backend(): CloudflareContainerBackend;
+    get backend(): ContainerBackend;
     /**
      * What `getWorkspace(stub)` calls from outside this object.
      *
@@ -270,11 +292,11 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
      *
      * A stub cannot enforce what the caller does with it: `runtime.exec` on this
      * one would run against a container with no CA. The exec paths take the other
-     * method — see `openWorkspaceFs` in `@dynamicagents/plugins/computer`.
+     * method — see `openWorkspaceFs` in `./open.ts`.
      */
     __getWorkspaceFsStub(): Promise<WorkspaceStub>;
     /**
-     * Clone, fetch and push — the operations that need the forge token.
+     * Clone, fetch and push — the operations that need the GitHub token.
      *
      * The work is `./git-host.ts`, which owns why the credential stays on this
      * side of the boundary. What stays here is what only this object can do: the
@@ -300,6 +322,12 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
         branch: string;
         allowedHosts: string[];
     }): Promise<RepoGitResult>;
+    /**
+     * A checkout's `origin`, from this object's storage. Starts no container and
+     * moves no deadline, like {@link checkoutDir}: a pull request polled for its
+     * review is not the workspace in use.
+     */
+    gitOrigin(dir: string): Promise<string | undefined>;
     /**
      * Start this checkout's dependency install, and return without waiting.
      *
@@ -311,6 +339,76 @@ 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 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
+     * exceed the longest command the agent allows, and a container that outlives its
+     * work by that much bills for the difference. So a host that knows the work is
+     * finished says so, and the deadline goes back to being a backstop for the case
+     * where nothing got to say anything.
+     *
+     * Deliberately does **not** touch: `#touch()` would push the very deadline this
+     * is standing in for.
+     *
+     * `released: false` means the container is still up and the standing deadline
+     * still owns it — an install is running, or a pull is still moving blocks. Both
+     * resolve themselves: the drain re-arms the deadline to come back and finish,
+     * which is the same path `#onContainerIdle` takes. Under a {@link hold} the
+     * release is deferred instead, to the last `unhold`.
+     */
+    releaseContainer(): Promise<{
+        released: boolean;
+    }>;
+    /**
+     * Keep the container up for work this object cannot see, until `untilMs` or
+     * {@link unhold}.
+     *
+     * A Claude Code session a host starts here runs detached: nothing calls in
+     * while it works, and the runtime cannot list
+     * what is running. So a host done with the workspace cannot tell that the
+     * container is not, and {@link releaseContainer} would stop the session with
+     * it. A hold is the host saying so. It defers a release; it is not use, so it
+     * does not touch, and the idle deadline already outlasts a session.
+     *
+     * `untilMs` bounds a hold whose `unhold` never comes — a run cut between its
+     * start and its end. Past it the hold is ignored.
+     */
+    hold(key: string, untilMs: number): Promise<void>;
+    /**
+     * The work a {@link hold} stood for is over. When it was the last hold, a
+     * release asked for while it stood happens now — unless the workspace was
+     * used since, in which case the next release is asked for by whoever used it.
+     */
+    unhold(key: string): Promise<{
+        released: boolean;
+    }>;
     /**
      * Throw this workspace away if nothing has touched it for `maxIdleMs`.
      *
@@ -375,7 +473,7 @@ export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env =
     checkoutDir(): Promise<string | undefined>;
     /**
      * Everything currently true about this workspace that a caller must not assume
-     * away — the array `sb_exec`, `sb_write` and `sb_edit` all consult.
+     * away — the array `bash`, `edit` and the workspace's writes all consult.
      *
      * The policy is not here. `deriveAdvisories` decides which facts matter and
      * how they are worded; this method gathers what only the object can see and