@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/computer/index.d.ts

@@ -15,18 +15,13 @@ import type { WorkspaceAdvisory } from "./advisory.js";
  * filesystem plugin — an agent holding two gives the model no way to know which
  * one a path refers to.
  *
- * ## `node_modules` is **not** in the workspace
+ * ## The dependency tree is not in the workspace
  *
- * The one thing to internalise before reading further. `computerd` excludes it
- * from the sync, and the exclusion is right: pushing a real one (429 MB, 22,470
- * files) into the object exceeds the Durable Object's 128 MB isolate memory
- * limit, leaving the tree silently short — and the reconciliation that follows
- * propagates the shortfall back into the container.
- *
- * So dependencies live in the container and die with it, while source and `.git`
- * are durable. Two consequences run through everything below: an install has to
- * be re-run on a cold container, and `sb_read` cannot see a path under
- * `node_modules` even though a shell in the same container can.
+ * The one thing to internalise before reading further. A package root's
+ * `node_modules` is a bind mount of the container's disk, so installs never
+ * sync, and a new container reinstalls — see `./host/container-deps.ts`. The file tools read
+ * the workspace, so they refuse it; `sb_exec` reaches it. `paths.ts` owns what a
+ * path may be and what walks drop.
  *
  * Requires the Workers **Paid** plan (containers) and a Durable Object binding
  * whose class owns the workspace — see the README for the wrangler block.
@@ -49,8 +44,8 @@ export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand, type I
  * `verify:exports` treats `./computer` as one realm, and everything below stays
  * inside `dist/computer/`.
  */
-export { isContainerOnly, isGitInternal } from "./paths.js";
-export { cancelledNote, packBlocks, renderGrepMatches, renderResult, truncateOutput } from "./render.js";
+export { isGitInternal, WALK_SKIPS } from "./paths.js";
+export { cancelledNote, packBlocks, renderGrepMatches, renderResult, syncPendingNote, truncateOutput } from "./render.js";
 export { execGate, needsDependencies, writeGate, type ExecGate } from "./gate.js";
 /**
  * The workspace-advisory vocabulary, which a host needs all of: the type to
@@ -97,6 +92,7 @@ export declare const WORKSPACE_RUNTIME_KEY = "workspaceName";
  * is right there.
  */
 export declare function workspaceNameFromRuntime(runtime: unknown): string | undefined;
+export { withShell, withShellTranscript } from "./shell.js";
 /**
  * The Durable Object the workspace lives in, as this plugin needs to see it.
  *
@@ -109,6 +105,19 @@ export declare function workspaceNameFromRuntime(runtime: unknown): string | und
  */
 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 `./host/workspace.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.
@@ -120,52 +129,33 @@ export interface WorkspaceHost extends Rpc.DurableObjectBranded {
      * `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 three values rather than writing policy.
+     * implementing this is gathering what the host has rather than writing policy.
      */
     advisories(): Promise<readonly WorkspaceAdvisory[]>;
 }
 /**
- * Run a command under {@link ComputerConfig.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 computerExec} 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.
+ * Open the workspace behind a Durable Object stub.
  *
- * Two functions rather than one with a flag, because the difference is a change
- * to the *output contract* and a boolean hides it at the call site. Merging the
- * streams here would give every `/repo` git command an empty `stderr` and a
- * `stdout` that is a transcript rather than an answer — which fails silently,
- * since the commands `/repo` parses are quiet ones and a single `warning:` is
- * enough to skip the empty-branch guard.
+ * 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 withShell(command: string, shell: string | undefined): string;
+export declare function openWorkspace(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;
 /**
- * Run a command under {@link ComputerConfig.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 &&
- * 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
- * `npm run check > /tmp/out 2>&1; cat /tmp/out`. This is that workaround, done
- * once, for free.
+ * The same workspace, opened for filesystem work alone.
  *
- * The redirect binds to the wrapper process, so it applies to everything the
- * command writes however deeply nested — and there is no inner brace group or
- * subshell to mis-parse a command that already contains `&&`, quotes or redirects
- * of its own.
+ * `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.
  *
- * 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 renderResult} renders them as a labelled
- * `--- stderr ---` block for exactly this case. The transcript is the better
- * answer, not the only supported one.
+ * **Only the file tools take this.** `sb_exec` and {@link computerExec} need the
+ * container started and its CA installed, so they open it the other way.
  */
-export declare function withShellTranscript(command: string, shell: string | undefined): string;
+export declare function openWorkspaceFs(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;
 export interface ComputerConfig {
     /**
      * The Durable Object namespace holding workspaces, closed over at
@@ -261,7 +251,16 @@ export interface ComputerConfig {
      */
     env?: () => Record<string, string | undefined>;
 }
-export declare function buildComputerTools(workspace: () => Promise<WorkspaceClient>, config: ComputerConfig, advisories?: () => Promise<readonly WorkspaceAdvisory[]>): ToolSet;
+/**
+ * @param workspace Opens the workspace for a command: container started, CA
+ *   installed.
+ * @param fsWorkspace Opens it for the file tools, which touch nothing but the
+ *   host's SQLite. Defaults to {@link workspace}, so a host with one way in
+ *   behaves as before. See {@link openWorkspaceFs}.
+ * @param lockScope Names the workspace a write locks within — see
+ *   {@link file://./file-lock.ts}. Defaults to this tool set alone.
+ */
+export declare function buildComputerTools(workspace: () => Promise<WorkspaceClient>, config: ComputerConfig, advisories?: () => Promise<readonly WorkspaceAdvisory[]>, fsWorkspace?: () => Promise<WorkspaceClient>, lockScope?: () => string): ToolSet;
 /**
  * An `exec` bound to this workspace, for plugins that need a shell but should
  * not own a container.
@@ -309,3 +308,24 @@ export declare function computerExec(config: ComputerConfig): (command: string,
     exitCode: number;
 }>;
 export declare function computer(config: ComputerConfig): AgentPlugin;
+/**
+ * The Durable Object everything above talks to.
+ *
+ * `./host/` is a directory rather than a subpath of its own, and that is the
+ * point: one capability is one import path, so a consumer cannot install the
+ * tools and miss the object they address. The two halves have opposite bundle
+ * costs — an agent that only calls `sb_exec` carries no container backend and no
+ * isomorphic-git — and `"sideEffects": false` is what keeps that true, since
+ * nothing here references the host unless the consumer does.
+ *
+ * The dependency runs one way for a mechanical reason: `./host/` imports the
+ * leaf modules beside this file, never this barrel, because this barrel
+ * re-exports `./host/` and a cycle through a module that builds a class at
+ * import time is a base that evaluates `undefined`.
+ */
+export { WorkspaceObjectBase, WORKSPACE_DIR, workspaceName, type WorkspaceObjectConfig, type WorkspaceGitConfig } from "./host/workspace.js";
+export { InstallJob, type InstallJobDeps } from "./host/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 "./host/sync.js";
+export { ContainerTrust, TRUST_CA_COMMAND, type ContainerTrustDeps } from "./host/ca-trust.js";
+export { WorkspaceGitHost, type GitHostDeps } from "./host/git-host.js";
+export type { WorkspaceWakeHandlers } from "./host/wake.js";