@dynamicagents/plugins 0.11.1 → 0.12.0

package/dist/computer/host/workspace.d.ts

@@ -0,0 +1,424 @@
+import { DurableObject } from "cloudflare:workers";
+import { type WorkspaceEgressPolicy, type WorkspaceStub } from "@cloudflare/computer";
+import { CloudflareContainerBackend } from "@cloudflare/computer/backends/container";
+import { type WorkspaceAdvisory } from "../advisory.js";
+import type { InstallPlan, InstallState } from "../install.js";
+import type { RepoGitResult } from "../../repo/index.js";
+/**
+ * A workspace: one Durable Object, one container, one repository.
+ *
+ * **Shared by every agent in a Worker that has a container.** Each subclasses
+ * {@link WorkspaceObjectBase}, supplies a {@link WorkspaceObjectConfig}, and
+ * inherits everything else. Keep that seam narrow: it is the complete answer to
+ * "what is different about this agent's container", and anything that does not
+ * fit through it becomes a second copy of this file.
+ *
+ * A directory inside the plugin rather than a subpath beside it, so that one
+ * capability stays one import path and a consumer cannot take the tools without
+ * the object they address. The bundle cost of that is nothing: `sideEffects` is
+ * false, so an agent that only calls `sb_exec` carries no container backend and
+ * no isomorphic-git.
+ *
+ * What this file must not do is import the plugin barrel. The barrel re-exports
+ * this module, and the class below is built at import time — a cycle would
+ * evaluate its base as `undefined`. The imports above reach the leaf modules
+ * beside it instead.
+ *
+ * `@cloudflare/computer` pairs a SQLite-backed virtual filesystem in *this*
+ * object's storage with a container running `computerd`, which mounts it over
+ * FUSE at `/workspace`. Commands run against the same tree the Worker reads over
+ * RPC, and the tree outlives the container.
+ *
+ * **One repository per object**, because `computer` is strictly 1 DO ↔ 1
+ * container: the id derives from caller *and* repository (see `workspaceName`),
+ * so two repositories for one caller are two objects and two containers.
+ *
+ * **It constructs `Workspace` rather than using `withWorkspace`.** The mixin
+ * stores the `Workspace` under a module-private symbol the package does not
+ * export, so a method on the object cannot reach it — and what the host is
+ * required to do needs exactly that: driving an outstanding pull (the library
+ * owns no alarm and schedules nothing of its own), and the direct `runtime`
+ * access the detached install needs. So this object owns the `Workspace` and
+ * implements the one method the mixin otherwise provides,
+ * `__getWorkspaceStub`. Callers outside see no difference.
+ *
+ * ## What is here, and what is a module next door
+ *
+ * This file is the Durable Object: the wake map, the deadlines, the RPC surface
+ * and the wiring between them. The work each of those drives has its own home,
+ * and each carries the reasoning for its own decisions:
+ *
+ * - `./install-job.ts` — when a dependency install runs, and every guard on it.
+ * - `./sync.ts` — the host's half of syncing, which nothing else will do.
+ * - `./ca-trust.ts` — making a container able to speak TLS.
+ * - `./git-identity.ts` — who a container's commits belong to.
+ * - `./git-host.ts` — the operations that hold the forge credential.
+ *
+ * Each takes a small explicit seam, and that is the test: a module that needed
+ * the whole object back would be a module that did not want extracting.
+ */
+/** Where every checkout lives, inside the container and in the VFS. */
+export declare const WORKSPACE_DIR = "/workspace";
+/**
+ * The Durable Object name for one caller's checkout of one repository.
+ *
+ * Exported because several places must agree on it and none can see the others:
+ * the plugin that resolves the stub, the agent that hands it down to subagents,
+ * and the cancellation path. A pipe rather than a slash, so the caller half
+ * cannot forge a repository boundary by containing one.
+ *
+ * `repo` is undefined only before the first `repo_clone` or `scratch_open` of a
+ * session — what a task works in is model-chosen, so there is genuinely nothing
+ * to key on until it has chosen. That window resolves to a caller-level
+ * workspace, which is never worked in: `beforeCheckout` sets the repository
+ * before any git runs, and `scratch_open` sets its sentinel before anything
+ * resolves a name.
+ *
+ * `repo` is not always a repository. A host may pass a sentinel through here as
+ * one — a scratchpad is modelled that way, which is what keys it to its own
+ * object and its own container. Anything that is not a forge name works, as long
+ * as no caller could clone something that collides with it.
+ */
+export declare function workspaceName(callerKey: string, repo?: string): string;
+/**
+ * `work`, refused once `ms` pass without it settling. The work itself goes on;
+ * only the wait for it ends — see {@link READY_DEADLINE_MS}.
+ */
+export declare function readyWithin(work: Promise<void>, ms: number): Promise<void>;
+/**
+ * Named rather than the anonymous class expression an app would write here.
+ *
+ * This package emits declarations, and `DurableObject` brings `ctx` and `env` in
+ * protected — which makes the mixin's return type unnameable in a `.d.ts` and
+ * fails the build with TS4094. A named base gives the emitted type something to
+ * refer to. It costs one identifier and is invisible to a consumer.
+ */
+declare class WorkspaceContainerHost extends DurableObject<Cloudflare.Env> {
+}
+/**
+ * `withWorkspaceContainer` adds one method, `getWorkspaceContainer()`, over
+ * `this.ctx.container` — the runtime's own container handle. There is no
+ * `@cloudflare/containers` `Container` subclass here and so no `sleepAfter`:
+ * idle shutdown is this object's job, and it lands on the wake map with
+ * everything else.
+ */
+declare const WorkspaceContainerBase: typeof WorkspaceContainerHost & (new (...args: any[]) => WorkspaceContainerHost & {
+    getWorkspaceContainer(): import("@cloudflare/computer/backends/container").WorkspaceContainerAPI;
+});
+/**
+ * The forge credential, and who a commit made on this side is attributed to.
+ *
+ * Config rather than an env read, because this class cannot name a consumer's
+ * ambient `Env` — it is an interface `wrangler types` generates into *their*
+ * app, and a plugin that named it would compile only against the one Worker that
+ * happened to spell its bindings that way.
+ *
+ * It is also the honest direction. These are the repo plugin's secrets, declared
+ * by that plugin's `requires.secrets`, and a workspace holds them only because
+ * git runs on this side of the container boundary — see
+ * {@link file://./git-host.ts} for why it has to.
+ */
+export interface WorkspaceGitConfig {
+    /**
+     * The **name** of the binding holding the forge credential — never the
+     * credential itself.
+     *
+     * `workspaceConfig()` is an ordinary method on the prototype, and on a Durable
+     * Object `protected` is a typechecker's opinion rather than a runtime
+     * boundary: anything holding the namespace can call it. A config carrying the
+     * token would therefore hand it to any caller that asked — exactly what
+     * {@link file://./git-host.ts} exists to prevent, since the credential is
+     * supposed to be unreachable from anywhere but the moment git authenticates.
+     *
+     * So the config names the binding and the object reads it. Naming a secret by
+     * string is what the plugin contract's `requires.secrets` already does, and it
+     * is the only form available here: this package cannot name a consumer's
+     * ambient `Env`.
+     *
+     * An unset binding reads `undefined`, which means an unauthenticated request
+     * rather than a throw — that is what lets a workspace with no token still
+     * clone a public repository.
+     */
+    tokenBinding: string;
+    /**
+     * Who a commit is attributed to — on this side, and in the container.
+     *
+     * Two things read it: this object's git client, and `./git-identity.ts`,
+     * which writes it into the container's system config so a repository the
+     * container made for itself is attributed rather than nameless.
+     *
+     * **The repo plugin is not one of them.** It resolves `RepoConfig.author`
+     * independently, with a generic fallback of its own, and nothing in either
+     * package checks the two agree — so a commit *can* be attributed differently
+     * depending on which side made it, and the only thing preventing that is a
+     * consumer answering both from one place. A deployment's fallback for an
+     * unset binding belongs where that binding is read; this takes the resolved
+     * answer.
+     */
+    author: {
+        name: string;
+        email: string;
+    };
+}
+/**
+ * What one workspace object does not share with the next.
+ *
+ * Everything else about a workspace is identical between agents, which is why
+ * this interface is short and why it is worth having at all: a seam this narrow
+ * makes "what is different about this agent's container" a question with a
+ * complete answer in one place.
+ */
+export interface WorkspaceObjectConfig {
+    /**
+     * The wrangler Durable Object binding this class is bound as.
+     *
+     * Not cosmetic and not derivable: `computerd` dials **back** through it. The
+     * backend builds the container's loopback from this name plus the object id,
+     * so a wrong one produces a container that starts, mounts nothing and fails
+     * at the first command with no mention of a binding.
+     */
+    binding: string;
+    /**
+     * Where this workspace's container may send traffic, and through what.
+     *
+     * `direct` is the plain behaviour: the container's own network position.
+     * `http-gateway` routes **everything** through a `Fetcher` this Worker
+     * supplies, which is what puts the Worker on the model path — see
+     * `@dynamicagents/plugins/claude-code`.
+     *
+     * **Required in practice, and its absence is silent.** It is a policy that
+     * defaults to `{ mode: "none" }`, and the backend derives the container's
+     * network flag from it. Omit it and the container
+     * comes up with no network at all: the workspace mounts, commands run, and
+     * the install dies on a registry it cannot reach with nothing naming egress
+     * as the cause.
+     */
+    egress: WorkspaceEgressPolicy;
+    /** How this deployment installs dependencies for this agent's checkouts. */
+    installPlan: InstallPlan;
+    /** Log prefix — `coder-workspace`, `claude-coder-workspace`. */
+    label: string;
+    /**
+     * How long this agent's container stays up after the last command **started**.
+     *
+     * A per-agent value because the invariant on {@link CONTAINER_IDLE_MS} — it
+     * must exceed the longest command the shell allows — is an invariant about the
+     * *agent*, and the two differ by a factor of four. The coder's longest command
+     * is a tool call; `claude-coder`'s is a whole `claude -p` session that runs
+     * detached for its entire timeout.
+     *
+     * Omit it for the default. Raise it, never lower it, and raise it whenever the
+     * agent's longest command grows.
+     */
+    containerIdleMs?: number;
+    /** The forge credential and commit identity — see {@link WorkspaceGitConfig}. */
+    git: WorkspaceGitConfig;
+}
+/**
+ * One caller's checkout of one repository, and the container that mounts it.
+ *
+ * Abstract because a Durable Object class takes no constructor arguments, so
+ * per-agent configuration cannot arrive that way. {@link workspaceConfig} is the
+ * seam, and it is the shape core's own `RecipeSubagentBase.subagentRuntime`
+ * uses for exactly the same reason.
+ *
+ * ## Why `backend` and `#workspace` are lazy
+ *
+ * **Base class fields run before subclass fields**, so as plain fields they
+ * would read `undefined` from any `workspaceConfig()` that touches a subclass
+ * field — which `ClaudeCoderWorkspaceDO`'s does, for its credential store.
+ * Memoised getters remove the hazard rather than documenting it, which is what
+ * lets a subclass implement the seam however it likes.
+ */
+export declare abstract class WorkspaceObjectBase<TEnv extends Cloudflare.Env = Cloudflare.Env> extends WorkspaceContainerBase {
+    #private;
+    /**
+     * This Worker's bindings, as the host's own generated `Env` spells them.
+     *
+     * Re-declared rather than inherited so a subclass reading a binding of its own
+     * — `claude-coder`'s reaches for its credential pool — gets its real type
+     * instead of the base's. `declare` because the field is the runtime's; this
+     * only narrows what TypeScript believes about it.
+     */
+    readonly env: TEnv;
+    /**
+     * Everything this agent's workspace does differently. Called once, lazily.
+     *
+     * Read through {@link #cfg}, never directly: an implementation may build
+     * something real — `claude-coder`'s constructs its egress gateway — and this
+     * is consulted on the busiest path in the object.
+     */
+    protected abstract workspaceConfig(): WorkspaceObjectConfig;
+    get backend(): CloudflareContainerBackend;
+    /**
+     * What `getWorkspace(stub)` calls from outside this object.
+     *
+     * The one piece of `withWorkspace` reimplemented here — see the file comment
+     * for why the mixin is not used. `ready()` first, because the stub is only
+     * meaningful once the workspace has opened its store.
+     */
+    __getWorkspaceStub(): Promise<WorkspaceStub>;
+    /**
+     * The same workspace, for a caller that will only touch the filesystem.
+     *
+     * **The container is not started, and that is the whole difference.** The
+     * filesystem is this object's own SQLite, so a read or write of it needs no
+     * container and an absent one cannot block it. {@link __getWorkspaceStub} adds
+     * `#ready()`, and the first command in a fresh container re-pushes the whole
+     * tree before it runs, with `timeoutMs` reaching the spawned process and
+     * nothing earlier.
+     *
+     * A stub cannot enforce what the caller does with it: `runtime.exec` on this
+     * one would run against a container with no CA. The exec paths take the other
+     * method — see `openWorkspaceFs` in `@dynamicagents/plugins/computer`.
+     */
+    __getWorkspaceFsStub(): Promise<WorkspaceStub>;
+    /**
+     * Clone, fetch and push — the operations that need the forge token.
+     *
+     * The work is `./git-host.ts`, which owns why the credential stays on this
+     * side of the boundary. What stays here is what only this object can do: the
+     * entry-point bookkeeping, and making the workspace current before git reads
+     * it.
+     */
+    gitClone(req: {
+        url: string;
+        dir: string;
+        allowedHosts: string[];
+        branch?: string;
+        depth?: number;
+    }): Promise<RepoGitResult>;
+    gitFetch(req: {
+        url: string;
+        dir: string;
+        allowedHosts: string[];
+        depth?: number;
+    }): Promise<RepoGitResult>;
+    gitPush(req: {
+        url: string;
+        dir: string;
+        branch: string;
+        allowedHosts: string[];
+    }): Promise<RepoGitResult>;
+    /**
+     * Start this checkout's dependency install, and return without waiting.
+     *
+     * Called from `repo_clone` through the repo plugin's `afterCheckout` hook, so
+     * it runs inside a model turn — see `./install-job.ts` for why the drain's owner
+     * is the thing that matters here.
+     */
+    startInstall(req: {
+        dir: string;
+        repo?: string;
+    }): Promise<InstallState>;
+    /**
+     * Throw this workspace away if nothing has touched it for `maxIdleMs`.
+     *
+     * Re-checks the clock rather than trusting the caller: the alarm may have been
+     * armed a week ago, and a use since then must win. Safe to call from anywhere
+     * for the same reason, which is what lets the agent's cron poke it as a
+     * backstop without needing to know anything.
+     */
+    reclaimIfIdle(maxIdleMs?: number): Promise<{
+        reclaimed: boolean;
+        idleMs: number;
+        bytes: number;
+    }>;
+    /**
+     * Record what was checked out here, and say whether it is actually visible.
+     *
+     * **The single writer of {@link CHECKOUT_KEY}**, called by the two paths that
+     * know a checkout landed: the repo plugin's `afterCheckout` hook, which fires
+     * only once a tree is established, and `scratch_open`, which fires once
+     * `git init` has exited 0.
+     *
+     * **Why the checkout is recorded apart from the install**, which call sites
+     * point here for rather than restating: an install is conditional and a
+     * checkout is not. `resolveInstallCommand` skips a checkout it finds nothing
+     * to install in — any without a `package.json` — so a path written only as
+     * part of an install is missing exactly there. What that costs is not an
+     * optimisation: {@link checkoutDir} is how a delegated session is told where
+     * to work, so a repository can clone perfectly, report itself correctly
+     * through the repo tools, and never be worked in. The install keeps its own
+     * context for the mirror-image reason — what to re-run on a cold container has
+     * a different lifetime from what is on disk.
+     *
+     * Returns the probe as well as the path, so a caller learns in one round trip
+     * whether the tree is visible rather than discovering it a delegation later.
+     */
+    noteCheckout(req: {
+        dir: string;
+        repo?: string;
+        kind: "repo" | "scratch";
+    }): Promise<{
+        dir: string;
+        present: boolean;
+    }>;
+    /**
+     * Where the work is — a directory holding a git repository, or nothing.
+     *
+     * Two callers depend on that being the meaning rather than "a path somebody
+     * wrote down once": a Claude Code session takes it as its cwd, and
+     * `discardWorkingTree` runs `git reset --hard` in it. Both want the same
+     * question answered, and neither can recover from a confident wrong answer.
+     *
+     * So it is **probed, not remembered**. A record is where to look; `.git` being
+     * there is what makes the answer true. That costs one local read of this
+     * object's own SQLite — everything under the checkout is durable, `.git`
+     * included — and it is what turns a stale record into `undefined` instead of
+     * into a session started in a directory that is no longer a checkout.
+     *
+     * The record is the only source. A workspace that has never recorded one
+     * answers `undefined` until its next checkout does, which `repo_clone` does on
+     * any tree it can fetch and reset.
+     */
+    checkoutDir(): Promise<string | undefined>;
+    /**
+     * Everything currently true about this workspace that a caller must not assume
+     * away — the array `sb_exec`, `sb_write` and `sb_edit` all consult.
+     *
+     * The policy is not here. `deriveAdvisories` decides which facts matter and
+     * how they are worded; this method gathers what only the object can see and
+     * hands it over. That split is why a host cannot get the severity of its own
+     * workspace wrong.
+     *
+     * **Nothing that starts a long job belongs on this path**, and the rule is
+     * sharper here than anywhere else in the object because every tool call reads
+     * it. `startInstall` in particular must never be reached from here: it hands
+     * its drain to `ctx.waitUntil`, whose lifetime is the invocation's, and an
+     * invocation on this path is a tool call that returns in milliseconds. The
+     * drain outlives its owner, dies mid-`npm ci` with "WritableStream RPC stub
+     * was disposed without calling close()", and leaves a half-written tree.
+     *
+     * A missing dependency tree arms an install here, which runs in the alarm,
+     * which owns no request and outlives every RPC. Here because a command reads
+     * this before its `#ready()` starts a container, so the gate holds it for the
+     * install rather than letting it outrun one.
+     */
+    advisories(): Promise<readonly WorkspaceAdvisory[]>;
+    /**
+     * `computerd`'s outbound WebSocket upgrade, on its way back in.
+     *
+     * The container dials the loopback rather than the other way round, so this
+     * object is the server for its own container's capnweb session. Everything
+     * else on this object is RPC; this is the only HTTP it speaks.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Every durable wake-up this object has, dispatched from the one alarm.
+     *
+     * **This must not throw.** The runtime retries a failing alarm handler a
+     * bounded number of times and then stops for good — so a throw here would
+     * eventually take every *future* wake-up down with it, permanently, and the
+     * only symptom is that nothing ever happens again.
+     *
+     * Nothing else belongs here. Each reason to wake is a registered callback the
+     * scheduler dispatches by name, so this method neither matches on keys nor
+     * catches per-callback failures — the scheduler retries a failing callback and
+     * reports one that fails for good through `onError`. Nor does it sweep for a
+     * schedule that neither rescheduled nor cleared itself: a one-shot row is
+     * dropped when it runs, so it cannot stay due forever.
+     */
+    alarm(): Promise<void>;
+}
+export {};