@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/computer/gate.d.ts

@@ -1,8 +1,8 @@
-import { type WorkspaceAdvisory } from "./advisory.js";
+import { type WorkspaceAdvisory } from "../workspace/advisory.js";
 /**
  * What one shell command has to wait for, and what to say when it never ran.
  *
- * {@link file://./advisory.ts} decides what is true about the workspace and how
+ * {@link file://../workspace/advisory.ts} decides what is true about the workspace and how
  * to word it; this file decides what that means for a command about to run.
  * {@link needsDependencies} is the part that cannot move there — it is a
  * question about the *command*, and it is what stops `cat README.md` queueing
@@ -12,7 +12,7 @@ import { type WorkspaceAdvisory } from "./advisory.js";
  * replaced underneath a command that was running.
  */
 /**
- * The one `sb_exec` failure that is not the command's fault.
+ * The one `bash` failure that is not the command's fault.
  *
  * An execution running when the container is replaced throws `EEXEC_LOST`.
  * Unexplained, the model receives `Execution "…" was lost when its container
@@ -75,7 +75,7 @@ export declare function execGate(advisories: readonly WorkspaceAdvisory[], comma
 /**
  * Whether a write should happen at all, and what to say when it should not.
  *
- * `sb_write` and `sb_edit` do not go through {@link execGate}: they run no
+ * `write`, `edit` and `delete` do not go through {@link execGate}: they run no
  * command, and a dependency install has nothing to do with writing source. One
  * thing does reach them, and it is the worst of the set — a workspace that
  * accepts no further writes takes an edit, reports the character count, and

package/dist/computer/gate.js

@@ -1,8 +1,8 @@
-import { renderAdvisory, shapeOf } from "./advisory.js";
+import { renderAdvisory, shapeOf } from "../workspace/advisory.js";
 /**
  * What one shell command has to wait for, and what to say when it never ran.
  *
- * {@link file://./advisory.ts} decides what is true about the workspace and how
+ * {@link file://../workspace/advisory.ts} decides what is true about the workspace and how
  * to word it; this file decides what that means for a command about to run.
  * {@link needsDependencies} is the part that cannot move there — it is a
  * question about the *command*, and it is what stops `cat README.md` queueing
@@ -12,7 +12,7 @@ import { renderAdvisory, shapeOf } from "./advisory.js";
  * replaced underneath a command that was running.
  */
 /**
- * The one `sb_exec` failure that is not the command's fault.
+ * The one `bash` failure that is not the command's fault.
  *
  * An execution running when the container is replaced throws `EEXEC_LOST`.
  * Unexplained, the model receives `Execution "…" was lost when its container
@@ -76,7 +76,7 @@ export function execGate(advisories, command) {
 /**
  * Whether a write should happen at all, and what to say when it should not.
  *
- * `sb_write` and `sb_edit` do not go through {@link execGate}: they run no
+ * `write`, `edit` and `delete` do not go through {@link execGate}: they run no
  * command, and a dependency install has nothing to do with writing source. One
  * thing does reach them, and it is the worst of the set — a workspace that
  * accepts no further writes takes an edit, reports the character count, and
@@ -108,7 +108,7 @@ export function writeGate(advisories) {
  * Position is what makes this usable rather than merely cautious. Matching these
  * anywhere in the string looks equivalent and is not: `\bvitest\b` also fires on
  * `cat vitest.config.ts`, and `next.config.js`, `eslint.config.js` and
- * `vite.config.ts` are exactly the files a subagent reads while orienting itself.
+ * `vite.config.ts` are exactly the files an agent reads while orienting itself.
  * Every one of those reads would then queue behind an `npm ci` it has no use for,
  * which is the cost this whole check exists to remove.
  */

package/dist/computer/index.d.ts

@@ -1,196 +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.
+ * `@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 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.
+ * 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.
  *
- * 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.
+ * 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 `./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.
+ * 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.
  */
 /**
- * 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.
+ * 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 { 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/`.
- */
-export { isGitInternal, WALK_SKIPS } from "./paths.js";
-export { cancelledNote, packBlocks, renderGrepMatches, renderResult, syncPendingNote, 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;
-export { withShell, withShellTranscript } from "./shell.js";
-/**
- * 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 `./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.
-     *
-     * 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 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.** `sb_exec` and {@link computerExec} need the
- * container started and its CA installed, so they open it the other way.
- */
-export declare function openWorkspaceFs(host: DurableObjectStub<WorkspaceHost>): Promise<WorkspaceClient>;
-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.
      *
@@ -205,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.
      *
@@ -245,7 +88,7 @@ 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.**
      */
@@ -262,70 +105,9 @@ export interface ComputerConfig {
  */
 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.
- *
- * `@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 }
- *   });
- * ```
+ * 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;
-/**
- * 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";