@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/workspace/index.d.ts

@@ -1,53 +1,49 @@
-import type { ToolSet } from "ai";
-import type { AgentPlugin, WorkspaceBacking, WorkspaceHandle } from "@dynamicagents/core";
 /**
- * `@dynamicagents/plugins/workspace` — a durable file store for long subagent runs,
- * and the model-facing tools over it.
- *
- * Core already owns the *interface*: `WorkspaceHandle`, `WorkspaceBacking`, the
- * per-file and file-count caps, and `makeWorkspaceHandle` which enforces them.
- * What core deliberately does not own is a **backend**, because the only good
- * one is `@cloudflare/shell` and shell is experimental ("expect breaking
- * changes"). An agent that never delegates file work should not carry that
- * dependency, so it ships here and is an optional peer.
- *
- * This is the only `@cloudflare/shell` import surface in the package — the same
- * discipline the predecessor kept, for the same reason: everything else codes
- * against core's stable wrapper rather than shell's large, churning API.
- *
- * Two halves, and they are independent:
- *
- * - `workspaceBacking` gives every subagent execution a real file store. An
- *   agent that installs this plugin and nothing else still benefits, because the
- *   tool families that persist session state to the workspace now have somewhere
- *   durable to put it.
- * - the `workspace` tool family puts `ws_read`/`ws_write`/`ws_list` in front of
- *   the *model*, so it can keep notes across a context window it will outlive.
- *
- * A recipe opts into the second by naming `workspace` in its `toolFamilies`;
- * the first applies to every execution regardless.
+ * `@dynamicagents/plugins/workspace` — the Durable Object a container workspace
+ * lives in, and the client side every other plugin reaches it through.
+ *
+ * The filesystem **is** a Durable Object's SQLite, mounted into the container
+ * over FUSE by `computerd`. Commands see a normal `/workspace`; the Worker reads
+ * the same tree over RPC; and when the container is replaced the tree is pushed
+ * back into the new one — so a checkout outlives the container that held it.
+ *
+ * `WorkspaceObjectBase` is the object: container backend, egress, CA trust,
+ * credentialed git, the dependency install, the sync drain and idle reclaim. A
+ * host subclasses it and answers a short config. Everything else here is what
+ * reaches it from outside: `openWorkspace`, `workspaceExec`, and the advisory
+ * vocabulary it reports its state in.
+ *
+ * `@dynamicagents/plugins/computer` is the agent's tools over it; `/repo` and
+ * `/scratch` take `workspaceExec` injected.
+ *
+ * Requires the Workers **Paid** plan (containers) and a Durable Object binding
+ * whose class extends `WorkspaceObjectBase` — see the README for the wrangler
+ * block.
  */
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export declare const WORKSPACE_FAMILY = "workspace";
+/** How a repository installs its dependencies — the mechanical half. */
+export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand, type InstallPlan, type InstallProbe, type InstallResolution, type InstallRule, type InstallState } from "./install.js";
 /**
- * The model-facing workspace tools: read/write/list over the execution's durable
- * file store.
- *
- * Long recipes keep a small rolling context window, so these are how a model
- * persists anything it must remember after older turns scroll out. Exported
- * separately from the plugin so they unit-test without a runtime, and so a host
- * with its own tool assembly can reuse them.
+ * The workspace-advisory vocabulary, which a host needs all of: the type to
+ * return over RPC, `deriveAdvisories` to build it from what it already knows,
+ * and `sessionAdvisory` for a host driving a whole session rather than one
+ * command. `shapeOf` and `renderAdvisory` are exported for the specs that hold
+ * their exhaustiveness — a host has no reason to call either, since calling them
+ * would mean writing policy or wording that has one home already.
  */
-export declare function buildWorkspaceTools(workspace: WorkspaceHandle): ToolSet;
+export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf, type AdvisoryAudience, type AdvisoryInput, type AdvisoryShape, type WorkspaceAdvisory } from "./advisory.js";
+export { pathExists } from "./read.js";
+export { cancelledNote, truncateOutput } from "./format.js";
+export { openWorkspace, openWorkspaceFs, workspaceNameFromRuntime, WORKSPACE_RUNTIME_KEY, type WorkspaceHost } from "./open.js";
+export { withShell, withShellTranscript } from "./shell.js";
+export { workspaceExec, DEFAULT_CWD, DEFAULT_TIMEOUT_MS, type WorkspaceClientConfig } from "./exec.js";
 /**
- * Build a shell {@link Workspace} over a Durable Object's SQLite storage.
- *
- * The executing facet passes its *own* `ctx.storage.sql`, so per-execution
- * isolation is free and deleting the child wipes the workspace with the rest of
- * its storage. `name` is lazy because a facet's name is set after construction.
- *
- * Exported because a host that assembles its own `SubagentRuntime` by hand may
- * want it directly; the plugin's `workspaceBacking` is this same function.
+ * The object itself. The modules below import the client-side leaves beside
+ * them, never this barrel: a cycle through a module that builds a class at
+ * import time is a base that evaluates `undefined`.
  */
-export declare function durableWorkspaceBacking(sql: SqlStorage, name: () => string | undefined): WorkspaceBacking;
-export declare function workspace(): AgentPlugin;
+export { WorkspaceObjectBase, IDLE_RECLAIM_MS, WORKSPACE_DIR, workspaceName, type WorkspaceObjectConfig, type WorkspaceGitConfig } from "./object.js";
+export { InstallJob, type InstallJobDeps } from "./install-job.js";
+export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs, type DrainOutcome, type SyncDrainIntent, type WorkspaceSyncDeps } from "./sync.js";
+export { ContainerTrust, TRUST_CA_COMMAND, type ContainerTrustDeps } from "./ca-trust.js";
+export { WorkspaceGitHost, type GitHostDeps } from "./git-host.js";
+export type { WorkspaceWakeHandlers } from "./wake.js";

package/dist/workspace/index.js

@@ -1,118 +1,58 @@
-import { tool } from "ai";
-import { z } from "zod";
-import { definePlugin } from "@dynamicagents/core";
-import { Workspace } from "@cloudflare/shell";
 /**
- * `@dynamicagents/plugins/workspace` — a durable file store for long subagent runs,
- * and the model-facing tools over it.
- *
- * Core already owns the *interface*: `WorkspaceHandle`, `WorkspaceBacking`, the
- * per-file and file-count caps, and `makeWorkspaceHandle` which enforces them.
- * What core deliberately does not own is a **backend**, because the only good
- * one is `@cloudflare/shell` and shell is experimental ("expect breaking
- * changes"). An agent that never delegates file work should not carry that
- * dependency, so it ships here and is an optional peer.
- *
- * This is the only `@cloudflare/shell` import surface in the package — the same
- * discipline the predecessor kept, for the same reason: everything else codes
- * against core's stable wrapper rather than shell's large, churning API.
- *
- * Two halves, and they are independent:
- *
- * - `workspaceBacking` gives every subagent execution a real file store. An
- *   agent that installs this plugin and nothing else still benefits, because the
- *   tool families that persist session state to the workspace now have somewhere
- *   durable to put it.
- * - the `workspace` tool family puts `ws_read`/`ws_write`/`ws_list` in front of
- *   the *model*, so it can keep notes across a context window it will outlive.
- *
- * A recipe opts into the second by naming `workspace` in its `toolFamilies`;
- * the first applies to every execution regardless.
+ * `@dynamicagents/plugins/workspace` — the Durable Object a container workspace
+ * lives in, and the client side every other plugin reaches it through.
+ *
+ * The filesystem **is** a Durable Object's SQLite, mounted into the container
+ * over FUSE by `computerd`. Commands see a normal `/workspace`; the Worker reads
+ * the same tree over RPC; and when the container is replaced the tree is pushed
+ * back into the new one — so a checkout outlives the container that held it.
+ *
+ * `WorkspaceObjectBase` is the object: container backend, egress, CA trust,
+ * credentialed git, the dependency install, the sync drain and idle reclaim. A
+ * host subclasses it and answers a short config. Everything else here is what
+ * reaches it from outside: `openWorkspace`, `workspaceExec`, and the advisory
+ * vocabulary it reports its state in.
+ *
+ * `@dynamicagents/plugins/computer` is the agent's tools over it; `/repo` and
+ * `/scratch` take `workspaceExec` injected.
+ *
+ * Requires the Workers **Paid** plan (containers) and a Durable Object binding
+ * whose class extends `WorkspaceObjectBase` — see the README for the wrangler
+ * block.
  */
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export const WORKSPACE_FAMILY = "workspace";
+/** How a repository installs its dependencies — the mechanical half. */
+export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand } from "./install.js";
 /**
- * The model-facing workspace tools: read/write/list over the execution's durable
- * file store.
- *
- * Long recipes keep a small rolling context window, so these are how a model
- * persists anything it must remember after older turns scroll out. Exported
- * separately from the plugin so they unit-test without a runtime, and so a host
- * with its own tool assembly can reuse them.
+ * The workspace-advisory vocabulary, which a host needs all of: the type to
+ * return over RPC, `deriveAdvisories` to build it from what it already knows,
+ * and `sessionAdvisory` for a host driving a whole session rather than one
+ * command. `shapeOf` and `renderAdvisory` are exported for the specs that hold
+ * their exhaustiveness — a host has no reason to call either, since calling them
+ * would mean writing policy or wording that has one home already.
  */
-export function buildWorkspaceTools(workspace) {
-    return {
-        ws_read: tool({
-            description: "Read a file from your workspace. Returns the file's text, or a note if it does not exist.",
-            inputSchema: z.object({
-                path: z.string().describe("File path, e.g. 'notes.md'")
-            }),
-            execute: async ({ path }) => {
-                const content = await workspace.read(path);
-                return content === null ? `(no file at ${path})` : content;
-            }
-        }),
-        ws_write: tool({
-            description: "Create or overwrite a workspace file. Use this to persist notes, hypotheses, and plans so you remember them after older turns scroll out of context.",
-            inputSchema: z.object({
-                path: z.string().describe("File path, e.g. 'notes.md'"),
-                content: z
-                    .string()
-                    .describe("Full file content (overwrites any existing file)")
-            }),
-            execute: async ({ path, content }) => {
-                // Returned rather than thrown: a write over the size cap is the model's
-                // mistake to correct, and it can only correct what it is told. The SDK
-                // would surface a throw as a tool error too, but this reads better and
-                // keeps the limit itself in the message.
-                try {
-                    await workspace.write(path, content);
-                    return `wrote ${path}`;
-                }
-                catch (err) {
-                    return `error writing ${path}: ${String(err)}`;
-                }
-            }
-        }),
-        ws_list: tool({
-            description: "List the files currently in your workspace.",
-            inputSchema: z.object({
-                dir: z.string().optional().describe("Directory to list (default: root)")
-            }),
-            execute: async ({ dir }) => {
-                const entries = await workspace.list(dir);
-                if (entries.length === 0)
-                    return "(workspace is empty)";
-                return entries
-                    .map((e) => `${e.path}${e.type === "directory" ? "/" : ""} (${e.size} bytes)`)
-                    .join("\n");
-            }
-        })
-    };
-}
+export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf } from "./advisory.js";
+// A host implementing `InstallProbe` needs exactly this, and hand-rolling it
+// loses the fast path: across a Durable Object boundary `fs` is a stub carrying
+// `exists`, which a `stat`-only probe never asks for.
+export { pathExists } from "./read.js";
+export { cancelledNote, truncateOutput } from "./format.js";
+export { openWorkspace, openWorkspaceFs, workspaceNameFromRuntime, WORKSPACE_RUNTIME_KEY } from "./open.js";
+export { withShell, withShellTranscript } from "./shell.js";
+export { workspaceExec, DEFAULT_CWD, DEFAULT_TIMEOUT_MS } from "./exec.js";
 /**
- * Build a shell {@link Workspace} over a Durable Object's SQLite storage.
- *
- * The executing facet passes its *own* `ctx.storage.sql`, so per-execution
- * isolation is free and deleting the child wipes the workspace with the rest of
- * its storage. `name` is lazy because a facet's name is set after construction.
- *
- * Exported because a host that assembles its own `SubagentRuntime` by hand may
- * want it directly; the plugin's `workspaceBacking` is this same function.
+ * The object itself. The modules below import the client-side leaves beside
+ * them, never this barrel: a cycle through a module that builds a class at
+ * import time is a base that evaluates `undefined`.
  */
-export function durableWorkspaceBacking(sql, name) {
-    return new Workspace({ sql, name });
-}
-export function workspace() {
-    return definePlugin({
-        key: "workspace",
-        workspaceBacking: durableWorkspaceBacking,
-        toolFamilies: {
-            [WORKSPACE_FAMILY]: (ctx) => ({
-                tools: buildWorkspaceTools(ctx.workspace)
-            })
-        }
-        // No `requires`: shell backs the workspace with the Durable Object's own
-        // SQLite, which every DO already has. Nothing for the host to declare.
-    });
-}
+export { WorkspaceObjectBase, IDLE_RECLAIM_MS, WORKSPACE_DIR, workspaceName } from "./object.js";
+// The dependency install, exported because a host that wants to report on one —
+// or a spec that drives it — needs the type, not because anything but
+// `./object.ts` constructs it.
+export { InstallJob } from "./install-job.js";
+// The pull the library owns no alarm for. Its constants are exported because a
+// host deferring to a drain has to back off at the same rate this does.
+export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs } from "./sync.js";
+// `TRUST_CA_COMMAND` is exported so a host can assert what its image will be
+// asked to run — see the file for why this cannot live in an entrypoint.
+export { ContainerTrust, TRUST_CA_COMMAND } from "./ca-trust.js";
+export { WorkspaceGitHost } from "./git-host.js";

package/dist/workspace/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 turn that is cut at fifteen 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.
+     * The reservation in `#beginInstall` 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>;
+}