@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/workspace/open.d.ts

@@ -0,0 +1,95 @@
+import type { WorkspaceClient, WorkspaceStub } from "@cloudflare/computer";
+import type { WorkspaceAdvisory } from "./advisory.js";
+/**
+ * Reaching a workspace: which one a call names, and the two ways to open it.
+ *
+ * A leaf, so the object, `/computer`'s tools and its proxy in
+ * `../computer/proxy.ts` can import it without
+ * going through the barrel that re-exports them.
+ */
+/**
+ * Where a parent puts the workspace name so its sub-agents reach the same one.
+ *
+ * A sub-agent cannot compute this itself. The name is derived from the caller
+ * and the repository, and the checkout it should work in is one its parent
+ * chose — so a sub-agent that named its own would land beside the parent's
+ * checkout, in a workspace with nothing in it.
+ *
+ * A spec's `prepare` runs on the parent, where the name resolves, and its
+ * return value reaches the sub-agent's plugins as `runtime()`. That is the
+ * channel core built for exactly this, and it is emphatically *not* the
+ * sub-agent's input, which the parent's model writes — a workspace name there
+ * would be model-authored, and a model naming another caller's workspace would
+ * get that caller's files.
+ */
+export declare const WORKSPACE_RUNTIME_KEY = "workspaceName";
+/**
+ * Read a parent-resolved workspace name off a sub-agent's `runtime()`.
+ *
+ * Returns `undefined` rather than throwing on anything unexpected: a parent has
+ * no runtime at all, and falling back to the configured thunk is right there.
+ */
+export declare function workspaceNameFromRuntime(runtime: unknown): string | undefined;
+/**
+ * The Durable Object the workspace lives in, as this plugin needs to see it.
+ *
+ * Structural rather than imported: the class is the host's — it owns the
+ * container binding, the alarm and the install job — and a plugin that imported
+ * it would stop a second host from bringing its own. `__getWorkspaceStub` is the
+ * one method `getWorkspace()` calls across the boundary, and it is what
+ * `withWorkspace` installs (or what a host that constructs `Workspace` itself
+ * reimplements, which is the same three lines).
+ */
+export interface WorkspaceHost extends Rpc.DurableObjectBranded {
+    __getWorkspaceStub(): Promise<WorkspaceStub>;
+    /**
+     * The same workspace for filesystem-only work, which the host must serve
+     * **without starting a container**.
+     *
+     * The filesystem is the Durable Object's own SQLite, while the first command
+     * in a fresh container waits for the whole tree to be pushed into it — so a
+     * file tool served the other way waits minutes for a local `readdir`. See
+     * `WorkspaceObjectBase.__getWorkspaceFsStub` in `./object.ts`.
+     *
+     * Required rather than optional, for the reason {@link advisories} gives. A
+     * host with nothing to distinguish returns its own `__getWorkspaceStub()`.
+     */
+    __getWorkspaceFsStub(): Promise<WorkspaceStub>;
+    /**
+     * Everything currently true about the workspace that a caller must not assume
+     * away — see {@link file://./advisory.ts}. An empty array is the good case.
+     *
+     * Required rather than optional, and not only because Workers RPC types an
+     * optional method as a union nothing can call. A host with nothing to report
+     * returns `[]` in one line; a host that forgot to expose it gets a compile
+     * error instead of a `bash` that silently runs against a half-built
+     * `node_modules`, or against a workspace whose writes are being dropped.
+     *
+     * `deriveAdvisories` builds the array from what the host already knows, so
+     * implementing this is gathering what the host has rather than writing policy.
+     */
+    advisories(): Promise<readonly WorkspaceAdvisory[]>;
+}
+/**
+ * Open the workspace behind a Durable Object stub.
+ *
+ * The cast is unavoidable, and narrow enough to be worth isolating here rather
+ * than repeating. `getWorkspace` wants a handle whose `__getWorkspaceStub()`
+ * resolves to a `WorkspaceStub` — the concrete class, private fields and all.
+ * Across a Durable Object boundary Workers RPC hands back a structural
+ * `Stub<WorkspaceStub>`, which forwards every method faithfully but carries none
+ * of the class's private brand: runtime-compatible, type-incompatible. This is
+ * the only place in the plugin that gap is crossed.
+ */
+export declare function openWorkspace(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;
+/**
+ * The same workspace, opened for filesystem work alone.
+ *
+ * `getWorkspace` calls exactly one method on what it is handed, so the host is
+ * wrapped in an object answering it from the other side of the seam — see
+ * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
+ *
+ * **Only the file tools take this.** `bash` and `workspaceExec` need the
+ * container started and its CA installed, so they open it the other way.
+ */
+export declare function openWorkspaceFs(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;

package/dist/workspace/open.js

@@ -0,0 +1,63 @@
+import { getWorkspace } from "@cloudflare/computer";
+/**
+ * Reaching a workspace: which one a call names, and the two ways to open it.
+ *
+ * A leaf, so the object, `/computer`'s tools and its proxy in
+ * `../computer/proxy.ts` can import it without
+ * going through the barrel that re-exports them.
+ */
+/**
+ * Where a parent puts the workspace name so its sub-agents reach the same one.
+ *
+ * A sub-agent cannot compute this itself. The name is derived from the caller
+ * and the repository, and the checkout it should work in is one its parent
+ * chose — so a sub-agent that named its own would land beside the parent's
+ * checkout, in a workspace with nothing in it.
+ *
+ * A spec's `prepare` runs on the parent, where the name resolves, and its
+ * return value reaches the sub-agent's plugins as `runtime()`. That is the
+ * channel core built for exactly this, and it is emphatically *not* the
+ * sub-agent's input, which the parent's model writes — a workspace name there
+ * would be model-authored, and a model naming another caller's workspace would
+ * get that caller's files.
+ */
+export const WORKSPACE_RUNTIME_KEY = "workspaceName";
+/**
+ * Read a parent-resolved workspace name off a sub-agent's `runtime()`.
+ *
+ * Returns `undefined` rather than throwing on anything unexpected: a parent has
+ * no runtime at all, and falling back to the configured thunk is right there.
+ */
+export function workspaceNameFromRuntime(runtime) {
+    const value = runtime?.[WORKSPACE_RUNTIME_KEY];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Open the workspace behind a Durable Object stub.
+ *
+ * The cast is unavoidable, and narrow enough to be worth isolating here rather
+ * than repeating. `getWorkspace` wants a handle whose `__getWorkspaceStub()`
+ * resolves to a `WorkspaceStub` — the concrete class, private fields and all.
+ * Across a Durable Object boundary Workers RPC hands back a structural
+ * `Stub<WorkspaceStub>`, which forwards every method faithfully but carries none
+ * of the class's private brand: runtime-compatible, type-incompatible. This is
+ * the only place in the plugin that gap is crossed.
+ */
+export function openWorkspace(host) {
+    return getWorkspace(host);
+}
+/**
+ * The same workspace, opened for filesystem work alone.
+ *
+ * `getWorkspace` calls exactly one method on what it is handed, so the host is
+ * wrapped in an object answering it from the other side of the seam — see
+ * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
+ *
+ * **Only the file tools take this.** `bash` and `workspaceExec` need the
+ * container started and its CA installed, so they open it the other way.
+ */
+export function openWorkspaceFs(host) {
+    return getWorkspace({
+        __getWorkspaceStub: () => host.__getWorkspaceFsStub()
+    });
+}

package/dist/workspace/read.d.ts

@@ -0,0 +1,16 @@
+import type { WorkspaceClient } from "@cloudflare/computer";
+/**
+ * Does this path exist?
+ *
+ * `getWorkspace()` types `fs` as the in-process `WorkspaceFilesystem`, but the
+ * value on the far side of a Durable Object boundary is a
+ * `WorkspaceFilesystemStub`, which carries a few methods the local class does
+ * not — `exists` among them. So the fast path is asked for rather than cast to,
+ * and `stat` is the fallback for a host that hands back a local workspace.
+ *
+ * The fallback treats *any* `stat` failure as absence, which is the honest
+ * reading for a tool whose entire answer is a boolean: there is no error channel
+ * to distinguish "missing" from "unreadable", and the caller's next move — look
+ * somewhere else — is the same either way.
+ */
+export declare function pathExists(fs: WorkspaceClient["fs"], path: string): Promise<boolean>;

package/dist/workspace/read.js

@@ -0,0 +1,22 @@
+/**
+ * Does this path exist?
+ *
+ * `getWorkspace()` types `fs` as the in-process `WorkspaceFilesystem`, but the
+ * value on the far side of a Durable Object boundary is a
+ * `WorkspaceFilesystemStub`, which carries a few methods the local class does
+ * not — `exists` among them. So the fast path is asked for rather than cast to,
+ * and `stat` is the fallback for a host that hands back a local workspace.
+ *
+ * The fallback treats *any* `stat` failure as absence, which is the honest
+ * reading for a tool whose entire answer is a boolean: there is no error channel
+ * to distinguish "missing" from "unreadable", and the caller's next move — look
+ * somewhere else — is the same either way.
+ */
+export async function pathExists(fs, path) {
+    // Called as a method, never through `.call`: on an RPC stub `.call` is read as
+    // a remote method, and the stub it would pass as `this` cannot be serialised.
+    const remote = fs;
+    if (typeof remote.exists === "function")
+        return remote.exists(path);
+    return fs.stat(path).then(() => true, () => false);
+}

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

@@ -1,11 +1,11 @@
 /**
- * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * Run a command under {@link file://./exec.ts WorkspaceClientConfig.shell} with its
  * two output streams left as they are, or hand it back untouched when no shell
  * is configured.
  *
  * This is the variant for a caller that **reads the result in code**: `stdout` is
  * a data channel it compares or parses, and `stderr` is a separate diagnostic.
- * {@link file://./index.ts computerExec} is that caller, on behalf of
+ * {@link file://./exec.ts workspaceExec} is that caller, on behalf of
  * `@dynamicagents/plugins/repo`, which asks git questions like
  * `symbolic-ref --short refs/remotes/origin/HEAD` and `rev-list --count` and
  * needs the answer alone.
@@ -19,12 +19,12 @@
  */
 export declare function withShell(command: string, shell: string | undefined): string;
 /**
- * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * Run a command under {@link file://./exec.ts WorkspaceClientConfig.shell} with its
  * two output streams merged into one transcript, in the order they were
  * written.
  *
  * This is the variant for a caller whose consumer is **a model reading output**.
- * `sb_exec` is that caller. A project's check is a chain — `wrangler types &&
+ * `bash` is that caller. A project's check is a chain — `wrangler types &&
  * prettier && eslint && tsc` — and *which tool spoke last* is how you know which
  * one failed. A stdout block and a separate stderr block destroy that ordering,
  * and a model that wants it back re-runs the whole gate as
@@ -38,7 +38,7 @@ export declare function withShell(command: string, shell: string | undefined): s
  *
  * With no shell configured there is no wrapper process to redirect, so the
  * command goes to the runtime untouched and the two streams arrive separate.
- * That is not a gap: {@link file://./render.ts renderResult} renders them as a
+ * That is not a gap: {@link file://../computer/render.ts renderResult} renders them as a
  * labelled `--- stderr ---` block for exactly this case. The transcript is the
  * better answer, not the only supported one.
  */

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

@@ -23,20 +23,20 @@ import { shellQuote } from "@cloudflare/computer";
  * truncated with both ends kept.
  *
  * Requires a shell that implements it — `bash`, `zsh`, `ksh`, not `sh`/dash. A
- * host setting {@link file://./index.ts ComputerConfig.shell} is choosing that
+ * host setting {@link file://./exec.ts WorkspaceClientConfig.shell} is choosing that
  * shell explicitly.
  */
 function wrapped(command, shell) {
     return `${shell} -o pipefail -c ${shellQuote(command)}`;
 }
 /**
- * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * Run a command under {@link file://./exec.ts WorkspaceClientConfig.shell} with its
  * two output streams left as they are, or hand it back untouched when no shell
  * is configured.
  *
  * This is the variant for a caller that **reads the result in code**: `stdout` is
  * a data channel it compares or parses, and `stderr` is a separate diagnostic.
- * {@link file://./index.ts computerExec} is that caller, on behalf of
+ * {@link file://./exec.ts workspaceExec} is that caller, on behalf of
  * `@dynamicagents/plugins/repo`, which asks git questions like
  * `symbolic-ref --short refs/remotes/origin/HEAD` and `rev-list --count` and
  * needs the answer alone.
@@ -52,12 +52,12 @@ export function withShell(command, shell) {
     return shell ? wrapped(command, shell) : command;
 }
 /**
- * Run a command under {@link file://./index.ts ComputerConfig.shell} with its
+ * Run a command under {@link file://./exec.ts WorkspaceClientConfig.shell} with its
  * two output streams merged into one transcript, in the order they were
  * written.
  *
  * This is the variant for a caller whose consumer is **a model reading output**.
- * `sb_exec` is that caller. A project's check is a chain — `wrangler types &&
+ * `bash` is that caller. A project's check is a chain — `wrangler types &&
  * prettier && eslint && tsc` — and *which tool spoke last* is how you know which
  * one failed. A stdout block and a separate stderr block destroy that ordering,
  * and a model that wants it back re-runs the whole gate as
@@ -71,7 +71,7 @@ export function withShell(command, shell) {
  *
  * With no shell configured there is no wrapper process to redirect, so the
  * command goes to the runtime untouched and the two streams arrive separate.
- * That is not a gap: {@link file://./render.ts renderResult} renders them as a
+ * That is not a gap: {@link file://../computer/render.ts renderResult} renders them as a
  * labelled `--- stderr ---` block for exactly this case. The transcript is the
  * better answer, not the only supported one.
  */

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

@@ -12,8 +12,10 @@ export type WorkspaceWakeHandlers = {
     installRun: () => Promise<void>;
     installWatch: () => Promise<void>;
     idleReclaim: () => Promise<void>;
-    /** Start a cold container before a command needs it — see `./workspace.ts`. */
+    /** 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,14 +1,12 @@
 {
   "name": "@dynamicagents/plugins",
-  "version": "0.12.0",
-  "description": "Optional, composable capabilities for a Dynamic Agent: ARC-AGI-3, browser rendering, a Linux container, git and pull requests, workspace, episodic recall, and pre-turn triage. One subpath per plugin, so a bundle grows only with what it imports.",
+  "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",
     "cloudflare-workers",
     "durable-objects",
     "agents-sdk",
-    "arc-agi",
-    "vectorize",
     "browser-rendering",
     "containers",
     "git",
@@ -32,26 +30,10 @@
     "LICENSE"
   ],
   "exports": {
-    "./arc-agi": {
-      "types": "./dist/arc-agi/index.d.ts",
-      "import": "./dist/arc-agi/index.js"
-    },
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "import": "./dist/browser/index.js"
     },
-    "./workspace": {
-      "types": "./dist/workspace/index.d.ts",
-      "import": "./dist/workspace/index.js"
-    },
-    "./recall": {
-      "types": "./dist/recall/index.d.ts",
-      "import": "./dist/recall/index.js"
-    },
-    "./triage": {
-      "types": "./dist/triage/index.d.ts",
-      "import": "./dist/triage/index.js"
-    },
     "./repo": {
       "types": "./dist/repo/index.d.ts",
       "import": "./dist/repo/index.js"
@@ -64,6 +46,10 @@
       "types": "./dist/claude-code/index.d.ts",
       "import": "./dist/claude-code/index.js"
     },
+    "./workspace": {
+      "types": "./dist/workspace/index.d.ts",
+      "import": "./dist/workspace/index.js"
+    },
     "./computer": {
       "types": "./dist/computer/index.d.ts",
       "import": "./dist/computer/index.js"
@@ -80,29 +66,24 @@
     "check": "npm run verify:peer-ranges && npm run verify:references && npm run types:check && prettier --check . && eslint . && tsc && npm run build && npm run verify:exports",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:record": "RECORD=1 vitest run recorded.spec.ts",
     "verify:exports": "node scripts/verify-exports.mjs",
     "verify:references": "node scripts/verify-references.mjs",
     "verify:peer-ranges": "node scripts/verify-peer-ranges.mjs",
+    "probe:claude-code": "npm run build && node scripts/probe-claude-code.mjs",
     "prepack": "npm run build && npm run verify:exports",
     "prepublishOnly": "npm run check && npm test",
     "prepare": "husky || true && npm run build"
   },
   "peerDependencies": {
-    "@cloudflare/computer": "^0.3.1",
-    "@cloudflare/shell": "^0.4.3",
-    "@dynamicagents/core": ">=0.12.0 <0.13.0",
-    "@platformatic/vfs": "^0.4.0",
-    "agents": ">=0.24.0 <0.25.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",
-    "drizzle-orm": ">=0.45.2",
-    "workers-ai-provider": "^4.0.0",
     "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
-    "@cloudflare/shell": {
-      "optional": true
-    },
     "@cloudflare/computer": {
       "optional": true
     },
@@ -111,15 +92,14 @@
     }
   },
   "devDependencies": {
-    "@cloudflare/computer": "^0.3.1",
-    "@cloudflare/shell": "0.4.3",
-    "@platformatic/vfs": "^0.4.0",
+    "@cloudflare/computer": "^0.5.0",
+    "@cloudflare/think": "^0.20.2",
     "@cloudflare/vitest-plugin": "^1.1.9",
-    "@dynamicagents/core": "^0.12.0",
+    "@dynamicagents/core": "^0.14.0",
+    "@platformatic/vfs": "^0.5.0",
     "@types/node": "^26.5.1",
-    "agents": "^0.24.0",
+    "agents": "^0.28.0",
     "ai": "^7.0.101",
-    "drizzle-orm": ">=0.45.2",
     "eslint": "^10.10.0",
     "husky": "^9.1.7",
     "prettier": "^3.9.6",