@dynamicagents/plugins 0.14.0 → 0.15.0

package/dist/sandbox/object.d.ts

@@ -0,0 +1,244 @@
+import { DurableObject } from "cloudflare:workers";
+import { type ContainerEgressBinding, type ContainerInstance, type ContainerMessage, type ContainerOperationResult } from "agents/harness/container";
+import { type DirectoryBackupGatewayBinding } from "@cloudflare/sandbox";
+import { type SandboxAdvisory } from "./advisory.js";
+import { type SandboxEgressRule } from "./egress.js";
+import { type InstallPlan, type InstallState } from "./install-plan.js";
+export interface SandboxObjectConfig {
+    /** Log prefix. */
+    label: string;
+    /** The adapter the daemon in {@link image} serves CLI sessions with. */
+    adapter: string;
+    /** The image to start: a key of `ctx.container.images`. Default `app`. */
+    image?: string;
+    instance: ContainerInstance;
+    /**
+     * Non-secret environment for every command the agent runs — an `exec`, an
+     * install, a CLI turn — under its own. No key a rule's `env` sets.
+     */
+    env?: Readonly<Record<string, string>>;
+    egress: {
+        /** `ctx.exports.<Entrypoint>`: the consumer's entrypoint, calling `sandboxEgress` with {@link rules}. */
+        entrypoint: ContainerEgressBinding;
+        /** The `env` binding this class is reached by, so a rule's handler can reach the sandbox a request came from. */
+        self: string;
+        /** What the container may reach, each declared by the plugin that needs it (`./egress.ts`). */
+        rules: readonly SandboxEgressRule[];
+    };
+    installPlan: InstallPlan;
+    /** Where checkouts are backed up before every stop. Without it an image change loses unpushed work. */
+    backups?: {
+        binding: string;
+        prefix?: string;
+        gateway: DirectoryBackupGatewayBinding;
+    };
+    /** How long after its last use a container is backed up and stopped. */
+    idleStopMs?: number;
+    /** An `env` binding whose value unlocks {@link SandboxObjectBase.debug}. Absent: no debug RPC. */
+    debugSecretBinding?: string;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface CheckoutRecord {
+    dir: string;
+    kind: "repo" | "scratch";
+    repo?: string;
+}
+/** A run's messages as of one poll, each with a digest that changes when the message does. */
+export interface PolledMessage {
+    id: string;
+    digest: string;
+    message: ContainerMessage;
+}
+export interface PollResult {
+    contract: number;
+    /** Set once the operation settled. */
+    result?: ContainerOperationResult;
+    messages: PolledMessage[];
+    /** The `from` that skips every message sent so far. */
+    next: number;
+}
+export interface SnapshotSeed {
+    key: string;
+    snapshot: {
+        id: string;
+    };
+}
+export declare abstract class SandboxObjectBase<Env extends object = Cloudflare.Env> extends DurableObject<Env> {
+    #private;
+    protected abstract sandboxConfig(): SandboxObjectConfig;
+    /** The object's container. A seam so specs can hand in a fake one. */
+    protected containerFor(ctx: DurableObjectState): Container;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * The container, running and ready for a command or a CLI turn.
+     *
+     * A stopped one is started by a `control:wake` prompt on the root session,
+     * which the daemon answers without a CLI: the harness starts containers only
+     * for a prompt. Then, once per container, the egress the harness does not
+     * register, and any checkout an image change left behind.
+     */
+    ensureRunning(): Promise<{
+        runtimeId: string;
+    }>;
+    /** A command as the agent, with no capabilities: the host's `env`, its own over that, and every egress rule's over both. */
+    exec(argv: readonly string[], options?: {
+        cwd?: string;
+        env?: Readonly<Record<string, string>>;
+        timeoutMs?: number;
+    }): Promise<ExecResult>;
+    readFile(path: string): Promise<Uint8Array | null>;
+    writeFile(path: string, content: Uint8Array | string): Promise<void>;
+    stat(path: string): Promise<{
+        type: string;
+        size: number;
+        modifiedAt: number;
+    } | null>;
+    readDir(path: string): Promise<{
+        name: string;
+        type: string;
+    }[]>;
+    mkdir(path: string): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * The harness session a run lives in, made on first ask.
+     *
+     * The harness refuses a session id it did not mint, so a run's own id maps to
+     * one here. A run may instead carry on another run's conversation: `continues`
+     * shares its session, and `forkOf` branches a new one from it. Either only
+     * works inside one object, since the conversation's files are this one's, and
+     * only in the same `cwd`, since the CLI files a conversation by directory.
+     */
+    createRun(runId: string, options: {
+        cwd: string;
+        forkOf?: string;
+        continues?: string;
+    }): Promise<{
+        sessionId: string;
+        created: boolean;
+    }>;
+    /**
+     * Durably submit one turn of a run. `operationId` is the caller's, so a
+     * retried submit is the same operation; a settled one comes back as it ended,
+     * which is why a caller resubmitting after a lost container uses a new one.
+     *
+     * Every turn runs in the run's `cwd`: a turn with no run header gets one, and
+     * a header naming another directory is refused.
+     *
+     * A stopped run takes no turn, checked before and after the turn is queued:
+     * a submission still starting the container when its run is stopped would
+     * otherwise start a CLI after the stop, with nobody left polling it.
+     */
+    submit(runId: string, text: string, operationId: string): Promise<{
+        operationId: string;
+        accepted: boolean;
+    }>;
+    /**
+     * One operation's state, waiting up to `waitMs` for it to settle.
+     *
+     * Only stored messages reach here: the harness keeps a run's messages and
+     * nothing it streamed live. Those of this operation only, so a forked run does
+     * not report its parent's history, each with a digest, because a message is
+     * replaced in place as its tool calls finish.
+     *
+     * `from` skips that many of them, so a long run is not sent whole on every
+     * poll; pass the last poll's `next`. A message replaced behind `from` is not
+     * sent again, so a caller passes it only for an adapter that never replaces
+     * one.
+     */
+    poll(runId: string, operationId: string, waitMs?: number, from?: number): Promise<PollResult>;
+    /**
+     * Stop a run and let its CLI finish leaving.
+     *
+     * The harness settles an abort at once, while the CLI is still exiting — a
+     * SIGINT, a SIGKILL a few seconds later, then one last sync of its session
+     * files. Committing or stopping before that loses what it wrote last, or
+     * races git's index lock. So this waits for no CLI to be left, and one sync.
+     *
+     * A stopped run takes no more turns. Its conversation goes on, if it does, in
+     * a run that `continues` it — whose operations share the session, so only
+     * this run's own are aborted.
+     */
+    stopRun(runId: string): Promise<{
+        stopped: boolean;
+    }>;
+    /**
+     * Snapshot the container now, as the start the harness will make next.
+     *
+     * The harness snapshots only when it stops a container, so one that dies mid-run
+     * starts from whatever it last stopped as. Writing its record is what makes a
+     * checkpoint the next start; the contract spec pins that it reads it.
+     */
+    checkpoint(): Promise<SnapshotSeed | undefined>;
+    /** The last checkpoint, for another sandbox of this class to start from. */
+    snapshotRecord(): Promise<SnapshotSeed | undefined>;
+    /**
+     * Start this sandbox's next container from another's checkpoint.
+     *
+     * Refused while it runs — the record is read at a start — and for a snapshot
+     * of another image, which a container cannot start from.
+     */
+    seedFrom(seed: SnapshotSeed): Promise<{
+        seeded: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Back up and stop the container. Its disk is the next start, as a snapshot.
+     *
+     * Refused while anything is working — an open run, a command, an install:
+     * stopping the harness re-wakes every open session, which starts the
+     * container again. Work that arrives meanwhile waits for the stop, then
+     * starts a new container.
+     */
+    release(): Promise<{
+        released: boolean;
+        reason?: string;
+    }>;
+    noteCheckout(record: CheckoutRecord): Promise<{
+        dir: string;
+        present: boolean;
+    }>;
+    /**
+     * The newest recorded checkout, a repository's or a scratchpad's. Starts no
+     * container and marks no use, so a sweep asking every sandbox does not keep
+     * them alive: a sandbox answers from its record, since a start restores what
+     * its disk lost, until a running container is prepared — then only if its
+     * `.git` is there.
+     */
+    checkoutDir(): Promise<string | undefined>;
+    /**
+     * Install a checkout's dependencies, in the background.
+     *
+     * The command runs detached in the container and writes its exit code to a
+     * file, which the alarm reads: a container process outlives the request that
+     * started it, and the file outlives the object that is waiting for it.
+     */
+    startInstall(target: InstallTarget): Promise<InstallState>;
+    advisories(): Promise<readonly SandboxAdvisory[]>;
+    /** Empty a sandbox nobody has used in `maxIdleMs`: backups, storage and all. */
+    reclaimIfIdle(maxIdleMs: number): Promise<{
+        reclaimed: boolean;
+        idleMs: number;
+    }>;
+    /** For acceptance runs only, behind a secret: reset this object, destroy its container, or run as root. */
+    debug(secret: string, op: {
+        kind: "reset";
+    } | {
+        kind: "destroy";
+    } | {
+        kind: "root-exec";
+        argv: string[];
+    }): Promise<ExecResult | {
+        ok: true;
+    }>;
+}
+interface InstallTarget {
+    dir: string;
+    repo?: string;
+}
+export {};