@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/computer/index.d.ts

@@ -1,206 +1,41 @@
 import type { ToolSet } from "ai";
 import type { AgentPlugin } from "@dynamicagents/core";
-import type { WorkspaceClient, WorkspaceStub } from "@cloudflare/computer";
-import type { WorkspaceAdvisory } from "./advisory.js";
+import type { WorkspaceClient } from "@cloudflare/computer";
+import type { WorkspaceAdvisory } from "../workspace/advisory.js";
+import type { WorkspaceClientConfig } from "../workspace/exec.js";
 /**
- * `@dynamicagents/plugins/computer` — a Linux container whose filesystem outlives it.
- *
- * 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.
- *
- * Not to be confused with `@dynamicagents/plugins/workspace`, which is a virtual
- * filesystem with no processes and nothing to run. Install exactly one
- * 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 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.
- *
- * Requires the Workers **Paid** plan (containers) and a Durable Object binding
- * whose class owns the workspace — see the README for the wrangler block.
- */
-/**
- * How a repository installs its dependencies — the mechanical half.
- *
- * Re-exported from the plugin's one entry point rather than given a subpath of
- * its own: `verify:exports` treats each subpath as an isolated realm, and a host
- * needs the resolver and the tools together anyway.
+ * `@dynamicagents/plugins/computer` — an agent's tools over a container
+ * workspace: `bash`, `grep` and `edit`, and `computerWorkspace`, the agent's own
+ * `this.workspace`, which Think's `read`, `write`, `delete`, `find` and `list`
+ * go through.
+ *
+ * The workspace itself — the Durable Object, its container, its git, its
+ * install — is `@dynamicagents/plugins/workspace`. This plugin reaches it only
+ * through that subpath's client modules, never its object, so an agent that
+ * holds the tools carries no container backend and no isomorphic-git.
+ *
+ * The agent's own workspace has to be this one — `computerWorkspace` — or
+ * Think's `read` and `write` would work on a different tree from `bash`. The
+ * plugin refuses to start otherwise; see `./proxy.ts`.
+ *
+ * ## The dependency tree is not in the workspace
+ *
+ * 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 `/workspace`'s
+ * `container-deps.ts`. The file tools read the workspace, so they refuse it;
+ * `bash` reaches it. `paths.ts` owns what a path may be and what walks drop.
  */
-export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand, type InstallPlan, type InstallProbe, type InstallResolution, type InstallRule, type InstallState } from "./install.js";
 /**
- * The helpers this plugin's own tests and hosts reach for, re-exported from the
- * one entry point.
- *
- * They live in sibling modules — `paths.ts`, `render.ts`, `gate.ts` — because
- * this file was 1,900 lines and the seams were obvious. The subpath is the unit a
- * consumer imports, so what it exports must not move when the files behind it do:
- * `verify:exports` treats `./computer` as one realm, and everything below stays
- * inside `dist/computer/`.
+ * The helpers this plugin's own tests reach for, re-exported from the one
+ * entry point. `verify:exports` treats `./computer` as one realm, so what it
+ * exports must not move when the files behind it do.
  */
-export { isContainerOnly, isGitInternal } from "./paths.js";
-export { cancelledNote, packBlocks, renderGrepMatches, renderResult, truncateOutput } from "./render.js";
+export { isGitInternal, SESSION_STATE_DIR, WALK_SKIPS } from "./paths.js";
+export { packBlocks, renderGrepMatches, renderResult, syncPendingNote } 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
- * 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 { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf, type AdvisoryAudience, type AdvisoryInput, type AdvisoryShape, type WorkspaceAdvisory } from "./advisory.js";
-export { pathExists } from "./read.js";
-/**
- * This plugin's tool-family name, as a recipe's `toolFamilies` lists it.
- *
- * `"sandbox"` names the capability — a shell and a filesystem — rather than the
- * package providing it, and it appears in recipes, souls and allowlists that
- * have nothing to do with either. Renaming it would have `validateRecipe`
- * silently drop the family from every recipe that still says `sandbox`: a
- * subagent with no tools and no error explaining why.
- */
-export declare const SANDBOX_FAMILY = "sandbox";
-/**
- * Where a parent puts the workspace name so its subagents reach the same one.
- *
- * A subagent cannot compute this itself. The name is derived from the verified
- * caller and the repository, and core deliberately gives a subagent execution a
- * `callerKey` thunk that **throws** — "a subagent execution has no caller
- * identity". So a facet running a `code` subtask would fail at its first tool
- * call, with the parent's checkout sitting in a workspace it cannot name.
- *
- * `resolveRuntime` runs on the parent, where the name resolves, and its return
- * value reaches every tool family as `ToolFamilyContext.runtime`. That is the
- * channel core built for exactly this, and it is emphatically *not* `params`,
- * which are declared in the subtask type's schema and rendered to the delegating
- * model — 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 subtask's runtime state.
- *
- * Returns `undefined` rather than throwing on anything unexpected: the main
- * agent's tools have 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>;
-    /**
-     * 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 an `sb_exec` 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 three values 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.
- *
- * 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.
- */
-export declare function withShell(command: string, shell: string | undefined): string;
-/**
- * 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 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.
- *
- * 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.
- */
-export declare function withShellTranscript(command: string, shell: string | undefined): string;
-export interface ComputerConfig {
-    /**
-     * The Durable Object namespace holding workspaces, closed over at
-     * instantiation so it is never model input.
-     */
-    binding: DurableObjectNamespace<WorkspaceHost>;
-    /**
-     * Which workspace this agent gets, by name. A thunk because the useful name —
-     * caller plus repository — does not exist when the plugin list is built.
-     *
-     * One workspace is one container is one repository: `@cloudflare/computer`
-     * pairs a Durable Object with exactly one container, so "never mix two
-     * repositories" is structural here rather than a convention to maintain.
-     */
-    workspaceName: () => string;
-    /** Working directory for every command. Defaults to `/workspace`. */
-    cwd?: string;
-    /**
-     * Run every command through this shell, e.g. `"bash"`. Unset, the command
-     * string goes to the runtime as-is and lands on whatever `/bin/sh` is.
-     *
-     * Worth setting, because "whatever `/bin/sh` is" is **dash** on Debian and
-     * Ubuntu, and a model writing shell writes *bash*. `${PIPESTATUS[0]}` is the
-     * one that costs most — a bash builtin a model reaches for to read a piped exit
-     * code, which dash fails with exit 2, after the command it wrapped has already
-     * run. It is one member of a family (`[[ ]]`, arrays, `set -o pipefail`,
-     * process substitution), so the fix is the shell rather than a note in a prompt
-     * telling the model to write POSIX.
-     *
-     * Set it only if the image actually has that shell: a missing one fails *every*
-     * command rather than the bash-flavoured ones.
-     */
-    shell?: string;
-    /** Per-command timeout. Defaults to ten minutes. */
-    timeoutMs?: number;
+export { computerWorkspace, isComputerWorkspace } from "./proxy.js";
+export interface ComputerConfig extends WorkspaceClientConfig {
     /**
      * Output ceiling per command, in **characters**. Defaults to 16,000.
      *
@@ -215,33 +50,31 @@ export interface ComputerConfig {
      * characters far better than they track UTF-8 bytes. So the name moved to meet
      * the implementation rather than the other way round.
      *
-     * `sb_read` is the one place a byte bound survives, and it is derived from
-     * this rather than separate — see `readBounded`.
      */
     maxOutputChars?: number;
     /**
-     * How long `sb_exec` waits for a running dependency install before giving the
+     * How long `bash` waits for a running dependency install before giving the
      * turn back. Defaults to 90 seconds.
      *
-     * Bounded rather than open-ended because the wait happens inside a subagent's
-     * chunk, and a tool call that blocks for the length of an `npm ci` is exactly
-     * the thing moving the install out of the round loop was meant to prevent. On
-     * expiry the tool runs nothing and says so, which costs one cheap turn.
+     * Bounded rather than open-ended because the wait happens inside a turn, and
+     * a tool call that blocks for the length of an `npm ci` is exactly what
+     * running the install as the host's own job was meant to prevent. On expiry
+     * the tool runs nothing and says so, which costs one cheap step.
      */
     installGateMs?: number;
     /**
      * Environment merged into every command **these tools** run — a registry host,
      * a `CI` flag, proxy settings. Host-supplied and never model input.
      *
-     * "These tools" is exact: {@link computerExec} deliberately does not merge it,
-     * so a proxy set here does not reach the git that `@dynamicagents/plugins/repo`
-     * runs through that export. The reasoning, and how a host opts in explicitly,
-     * is written up there.
+     * "These tools" is exact: `/workspace`'s `workspaceExec` deliberately does not
+     * merge it, so a proxy set here does not reach the git that
+     * `@dynamicagents/plugins/repo` runs through that export. The reasoning, and
+     * how a host opts in explicitly, is written up there.
      *
      * ## Put no secret here
      *
-     * *Every* command gets this environment, and `sb_exec`'s command is written by
-     * the model: `sb_exec("printenv")` prints all of it, and so does a
+     * *Every* command gets this environment, and `bash`'s command is written by
+     * the model: `bash("printenv")` prints all of it, and so does a
      * `postinstall` script in a repository the agent was asked to clone, which
      * nobody vetted.
      *
@@ -255,57 +88,26 @@ export interface ComputerConfig {
      *
      * Do not hand the agent the credential; hand it the *action*. Keep the secret
      * on the Worker and expose one tool that makes the call it is for.
-     * `@dynamicagents/plugins/repo` is the worked example: it holds a forge token, calls
+     * `@dynamicagents/plugins/repo` is the worked example: it holds a GitHub token, calls
      * the API from the Worker, and runs clone, fetch and push on the host's side of
      * the boundary. **No command in its container is ever given that token.**
      */
     env?: () => Record<string, string | undefined>;
 }
-export declare function buildComputerTools(workspace: () => Promise<WorkspaceClient>, config: ComputerConfig, advisories?: () => Promise<readonly WorkspaceAdvisory[]>): ToolSet;
 /**
- * An `exec` bound to this workspace, for plugins that need a shell but should
- * not own a container.
- *
- * `@dynamicagents/plugins/repo` is the reason this exists: it needs `git` on a real
- * shell, but depending on this module would weld the two together and stop a
- * host from pointing it at its own container. Structurally typed for the same
- * reason — the two plugins compose without either importing the other.
- *
- * ## {@link ComputerConfig.env} is deliberately **not** merged here
- *
- * {@link buildComputerTools} merges it into every command; this does not.
- *
- * What this hands out is a raw shell to *another plugin*, whose commands this
- * module neither writes nor sees. `/repo` runs its unauthenticated git through
- * it and pins the environment those need — `GIT_TERMINAL_PROMPT=0` plus the
- * model-authored values it passes as variables. A host environment merged
- * underneath lets through every key it does *not* pin: `http_proxy`,
- * `GIT_PROXY_COMMAND`, `GIT_SSL_CAINFO`, `GIT_CONFIG_GLOBAL`, `GIT_EXEC_PATH` —
- * the last two redirect the config git reads and relocate its helper binaries.
- *
- * No token is at stake, since the credentialed operations do not run here at
- * all. The point is that changing what git does inside another plugin's commands
- * should not be something a container plugin's config field does by accident,
- * from a host that only meant to set a registry. A host that wants it composes
- * it where the merge is visible:
- *
- * ```ts
- * exec: (command, options) =>
- *   computerExec(config)(command, {
- *     ...options,
- *     env: { ...mine, ...options?.env }
- *   });
- * ```
+ * @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;
+/**
+ * The container plugin. Its tools reach the workspace through the agent's own
+ * `computerWorkspace` — the one Think's `read` and `write` use — so the two can
+ * never resolve different ones. `config` answers everything else: the shell,
+ * the limits, the environment.
  */
-export declare function computerExec(config: ComputerConfig): (command: string, options?: {
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-    timeout?: number;
-    runtime?: unknown;
-}) => Promise<{
-    success: boolean;
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}>;
 export declare function computer(config: ComputerConfig): AgentPlugin;