@dynamicagents/plugins 0.12.0 → 0.13.0

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

@@ -1,7 +1,7 @@
-import type { RepoGitResult } from "../../repo/index.js";
+import type { RepoGitResult } from "../repo/index.js";
 import type { GitClient } from "@cloudflare/computer/git";
 /**
- * The git operations that need the forge token, run on this side.
+ * The git operations that need the GitHub token, run on this side.
  *
  * They are here rather than on the `WorkspaceStub` the plugin already holds
  * because `WorkspaceGitStub` exposes only `cli(argv)` across a Durable Object
@@ -22,12 +22,12 @@ import type { GitClient } from "@cloudflare/computer/git";
  * the workspace object's job and it must happen first: git here reads that
  * object's SQLite, so a commit made in the container that has not been pulled
  * yet is a commit this code cannot see. The workspace object's `gitClone`,
- * `gitFetch` and `gitPush` in `./workspace.ts` are where that is settled.
+ * `gitFetch` and `gitPush` in `./object.ts` are where that is settled.
  */
 export interface GitHostDeps {
     /** The workspace's own client — isomorphic-git over the local store. */
     git: () => GitClient;
-    /** The forge credential, read at the moment it would be handed over. */
+    /** The GitHub credential, read at the moment it would be handed over. */
     token: () => string | undefined;
     tag: () => string;
 }
@@ -53,6 +53,11 @@ export declare class WorkspaceGitHost {
         allowedHosts: string[];
         depth?: number;
     }): Promise<RepoGitResult>;
+    /**
+     * `remote.origin.url` from the local store, or `undefined` where there is no
+     * checkout or no origin. Reads only, and needs no credential.
+     */
+    origin(dir: string): Promise<string | undefined>;
     push(req: {
         url: string;
         dir: string;
@@ -60,3 +65,15 @@ export declare class WorkspaceGitHost {
         allowedHosts: string[];
     }): Promise<RepoGitResult>;
 }
+/**
+ * A git error's message with the chain of causes behind it.
+ *
+ * `@cloudflare/computer/git` wraps isomorphic-git's errors, and classifies some
+ * by a heuristic: any failure whose message mentions `.git` beside a missing
+ * path or a ref it could not find is reported as "not a git repository" — a
+ * sentence that is wrong about a checkout that plainly is one, and names
+ * neither the file nor the ref. What actually failed is only on `cause`, which
+ * a Durable Object boundary does not carry, so it is folded into the message
+ * here while the error is still itself.
+ */
+export declare function describeGitError(err: unknown): string;

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

@@ -1,3 +1,18 @@
+/**
+ * What the container's own `git init` would write, over isomorphic-git's.
+ *
+ * isomorphic-git's `init` writes `core.*` for a filesystem without symlinks or
+ * an executable bit that ignores case, and the container's git obeys it. With
+ * `symlinks = false`, a command there that rewrites the tree — starter puts a
+ * worktree on its branch with `checkout -f` — writes each link as a file holding
+ * its target, and `status` calls that clean. With `filemode = false`, a script
+ * made executable is committed as 100644. The store models all three.
+ */
+const CONTAINER_CORE_CONFIG = {
+    "core.symlinks": true,
+    "core.filemode": true,
+    "core.ignorecase": false
+};
 export class WorkspaceGitHost {
     deps;
     constructor(deps) {
@@ -20,6 +35,10 @@ export class WorkspaceGitHost {
             // checked at the moment the token would be handed over. The cost is four
             // calls instead of one; `clone` is these four.
             await git.init({ dir: req.dir });
+            // Straight after `init`, so a clone that fails part-way leaves nothing
+            // behind that the container's git would misread.
+            for (const [path, value] of Object.entries(CONTAINER_CORE_CONFIG))
+                await git.configSet({ dir: req.dir, path, value });
             await git.remoteAdd({
                 dir: req.dir,
                 name: "origin",
@@ -46,7 +65,7 @@ export class WorkspaceGitHost {
                 throw new Error(`cloned ${req.url} but the remote named no default branch to check out`);
             await git.checkout({ dir: req.dir, ref: landed });
             // What a real `git clone` writes and the container's git will look for:
-            // without it the branch tracks nothing, and a subagent reaching for a bare
+            // without it the branch tracks nothing, and an agent reaching for a bare
             // `git status` in the shell sees a branch with no upstream.
             await git.configSet({
                 dir: req.dir,
@@ -70,11 +89,33 @@ export class WorkspaceGitHost {
                 prune: true,
                 tags: false,
                 singleBranch: false,
+                // Every branch is fetched, but isomorphic-git still resolves one ref
+                // against the remote's list, and left to itself it picks the current
+                // branch's upstream. A checkout left on a branch whose pull request
+                // merged — and whose remote branch went with it — then fails every
+                // fetch with `Could not find refs/heads/<branch>`. The remote's HEAD
+                // is always listed.
+                remoteRef: "HEAD",
                 ...(req.depth ? { depth: req.depth } : {})
             });
             return `fetched ${req.url} (default branch ${result.defaultBranch ?? "unknown"})`;
         });
     }
+    /**
+     * `remote.origin.url` from the local store, or `undefined` where there is no
+     * checkout or no origin. Reads only, and needs no credential.
+     */
+    async origin(dir) {
+        try {
+            const url = await this.deps
+                .git()
+                .configGet({ dir, path: "remote.origin.url" });
+            return typeof url === "string" && url ? url : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async push(req) {
         return this.#run(req.allowedHosts, async (git, onAuth) => {
             const result = await git.push({
@@ -146,11 +187,40 @@ export class WorkspaceGitHost {
         }
         catch (err) {
             const code = err?.code;
+            const message = describeGitError(err);
+            console.error(`[${this.deps.tag()}] git failed`, { code, message });
             return {
                 ok: false,
                 ...(typeof code === "string" ? { code } : {}),
-                message: err instanceof Error ? err.message : String(err)
+                message
             };
         }
     }
 }
+/**
+ * A git error's message with the chain of causes behind it.
+ *
+ * `@cloudflare/computer/git` wraps isomorphic-git's errors, and classifies some
+ * by a heuristic: any failure whose message mentions `.git` beside a missing
+ * path or a ref it could not find is reported as "not a git repository" — a
+ * sentence that is wrong about a checkout that plainly is one, and names
+ * neither the file nor the ref. What actually failed is only on `cause`, which
+ * a Durable Object boundary does not carry, so it is folded into the message
+ * here while the error is still itself.
+ */
+export function describeGitError(err) {
+    const parts = [];
+    const seen = new Set();
+    let at = err;
+    for (let depth = 0; at !== undefined && at !== null && depth < 4; depth++) {
+        const e = at;
+        const text = typeof e.message === "string" ? e.message : String(at);
+        if (!seen.has(text)) {
+            seen.add(text);
+            const name = typeof e.name === "string" ? e.name : "";
+            parts.push(name && depth > 0 ? `${name}: ${text}` : text);
+        }
+        at = e.cause;
+    }
+    return parts.join(" ← ");
+}

package/dist/{computer/host → workspace}/git-identity.d.ts

@@ -4,7 +4,7 @@ import type { Workspace } from "@cloudflare/computer";
  * answers for it.
  *
  * `/repo` configures the checkouts it clones and names the identity on every
- * commit it makes — see {@link file://../../repo/checkout.ts writeGitIdentity}.
+ * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
  * Neither reaches a repository the container made for itself: a submodule
  * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
  * have no identity at all, and git refuses to commit without one — so whatever

package/dist/{computer/host → workspace}/git-identity.js

@@ -55,7 +55,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * answers for it.
  *
  * `/repo` configures the checkouts it clones and names the identity on every
- * commit it makes — see {@link file://../../repo/checkout.ts writeGitIdentity}.
+ * commit it makes — see {@link file://../repo/checkout.ts writeGitIdentity}.
  * Neither reaches a repository the container made for itself: a submodule
  * checked out by a bootstrap, a `git init`, a second clone from the shell. Those
  * have no identity at all, and git refuses to commit without one — so whatever

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, and stays
- * that way: 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, and stays
- * that way: 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/{computer/host → workspace}/install-job.d.ts

@@ -1,6 +1,6 @@
 import { type Workspace } from "@cloudflare/computer";
 import type { Scheduler } from "@dynamicagents/core/alarm";
-import { type InstallPlan, type InstallState } from "../install.js";
+import { type InstallPlan, type InstallState } from "./install.js";
 import type { WorkspaceWakeHandlers } from "./wake.js";
 export interface InstallJobDeps {
     storage: DurableObjectStorage;
@@ -71,7 +71,7 @@ export declare class InstallJob {
      *
      * 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 chunk step that dies at ten minutes.
+     * 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
@@ -102,7 +102,7 @@ export declare class InstallJob {
     /**
      * When a reinstall was queued, if one is waiting to run.
      *
-     * Read by {@link file://../advisory.ts deriveAdvisories}, which is the only
+     * 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.
      */
@@ -112,7 +112,7 @@ export declare class InstallJob {
      *
      * `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.
-     * `startInstall`'s in-flight guard would catch a double, but the cheaper
+     * The reservation in `#beginInstall` would catch a double, but the cheaper
      * answer is not to schedule one.
      */
     onRun(): Promise<void>;