@dynamicagents/plugins 0.14.0 → 0.16.0

package/dist/workspace/object.d.ts

@@ -1,522 +0,0 @@
-import { DurableObject } from "cloudflare:workers";
-import { type WorkspaceEgressPolicy, type WorkspaceStub } from "@cloudflare/computer";
-import { ContainerBackend, type ContainerInstanceSize } from "@cloudflare/computer/backends/container";
-import { type DepsSnapshotRecord } from "./deps-snapshot.js";
-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 `bash` 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 `@cloudflare/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.
- * - `./deps-snapshot.ts` — starting a container from one that already installed.
- * - `./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 GitHub 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 sub-agents,
- * 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 GitHub name works, as long
- * as no caller could clone something that collides with it.
- */
-export declare function workspaceName(callerKey: string, repo?: string): string;
-/**
- * How long a workspace survives without being used.
- *
- * A Durable Object is **never** reclaimed by the platform, and a namespace
- * cannot be enumerated from a Worker, so nothing else is coming to clean up.
- * Source-only workspaces are small (6.3 MB for slack-gatekeeper), which makes
- * this hygiene rather than cost control — but unbounded hygiene is still
- * unbounded.
- *
- * Exported because a host keeping work in a workspace has to say how long that
- * work survives untouched.
- */
-export declare const IDLE_RECLAIM_MS: number;
-/**
- * `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, started with the
- * image and instance size this object asks for. Stopping it is this object's
- * job — see {@link CONTAINER_IDLE_MS}.
- */
-declare const WorkspaceContainerBase: typeof WorkspaceContainerHost & (new (...args: any[]) => WorkspaceContainerHost & {
-    getWorkspaceContainer(): import("@cloudflare/computer/backends/container").WorkspaceContainerAPI;
-});
-/**
- * The GitHub 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 GitHub 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 — `coding-workspace`, `claude-coordinator-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-coordinator`'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 size this agent's container starts at — a tier such as `standard-2`, or
-     * `{ vcpu, memoryMib, diskMb }`.
-     *
-     * Requested on every start, and part of what a running container is matched
-     * against: change it and the next connect replaces a container started at the
-     * old size. Which size, and why there is no default: {@link file://./README.md}.
-     */
-    instance: ContainerInstanceSize;
-    /** The GitHub 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, for the same reason Think's own hooks are methods rather than options.
- *
- * ## 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 `ClaudeCoordinatorWorkspace`'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-coordinator`'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-coordinator`'s constructs its egress gateway — and this
-     * is consulted on the busiest path in the object.
-     */
-    protected abstract workspaceConfig(): WorkspaceObjectConfig;
-    get backend(): ContainerBackend;
-    /**
-     * 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 `./open.ts`.
-     */
-    __getWorkspaceFsStub(): Promise<WorkspaceStub>;
-    /**
-     * Clone, fetch and push — the operations that need the GitHub 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>;
-    /**
-     * A checkout's `origin`, from this object's storage. Starts no container and
-     * moves no deadline, like {@link checkoutDir}: a pull request polled for its
-     * review is not the workspace in use.
-     */
-    gitOrigin(dir: string): Promise<string | undefined>;
-    /**
-     * 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>;
-    /**
-     * This workspace's dependency snapshot, for another of the same class to start
-     * from — see {@link seedDepsSnapshot}. Starts no container and moves no
-     * deadline.
-     */
-    depsSnapshot(): Promise<DepsSnapshotRecord | undefined>;
-    /**
-     * Start this workspace's next container from `record`, another workspace's
-     * dependency snapshot, when it fits the checkout here — a worktree at the same
-     * path as the checkout it was cut from. Call it after the checkout and before
-     * the first command.
-     *
-     * A snapshot is that workspace's whole disk, so offer one only between
-     * workspaces of the same caller.
-     */
-    seedDepsSnapshot(record: DepsSnapshotRecord): Promise<{
-        seeded: boolean;
-        reason?: string;
-    }>;
-    /**
-     * Stop the container, and **keep everything on disk**.
-     *
-     * The counterpart to {@link reclaimIfIdle}, and the difference is the whole
-     * reason both exist. A reclaim is for a workspace nobody wants again: it empties
-     * storage, so the checkout and the dependency snapshot go with the container.
-     * This is for a workspace that will be worked in again — the next task on the
-     * same repository skips the clone, and the install by restoring the snapshot.
-     *
-     * **Why a caller needs this at all.** The idle deadline would eventually do it,
-     * but it cannot be tuned down to meet a cost target: `containerIdleMs` must
-     * exceed the longest command the agent allows, and a container that outlives its
-     * work by that much bills for the difference. So a host that knows the work is
-     * finished says so, and the deadline goes back to being a backstop for the case
-     * where nothing got to say anything.
-     *
-     * Deliberately does **not** touch: `#touch()` would push the very deadline this
-     * is standing in for.
-     *
-     * `released: false` means the container is still up and the standing deadline
-     * still owns it — an install is running, or a pull is still moving blocks. Both
-     * resolve themselves: the drain re-arms the deadline to come back and finish,
-     * which is the same path `#onContainerIdle` takes. Under a {@link hold} the
-     * release is deferred instead, to the last `unhold`.
-     */
-    releaseContainer(): Promise<{
-        released: boolean;
-    }>;
-    /**
-     * Keep the container up for work this object cannot see, until `untilMs` or
-     * {@link unhold}.
-     *
-     * A Claude Code session a host starts here runs detached: nothing calls in
-     * while it works, and the runtime cannot list
-     * what is running. So a host done with the workspace cannot tell that the
-     * container is not, and {@link releaseContainer} would stop the session with
-     * it. A hold is the host saying so. It defers a release; it is not use, so it
-     * does not touch, and the idle deadline already outlasts a session.
-     *
-     * `untilMs` bounds a hold whose `unhold` never comes — a run cut between its
-     * start and its end. Past it the hold is ignored.
-     */
-    hold(key: string, untilMs: number): Promise<void>;
-    /**
-     * The work a {@link hold} stood for is over. When it was the last hold, a
-     * release asked for while it stood happens now — unless the workspace was
-     * used since, in which case the next release is asked for by whoever used it.
-     */
-    unhold(key: string): Promise<{
-        released: boolean;
-    }>;
-    /**
-     * 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 `bash`, `edit` and the workspace's writes 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 {};