@gr8ful/spf 0.9.2 → 0.10.1

package/dist/core/sandbox.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Sandbox lease registry, workspace transport, and teardown chain — SPF #15.
+ *
+ * `SandboxSpec`/`SandboxBackend`/`SandboxScope` live in `data_types.ts`
+ * beside the valibot schemas they are derived from (that leaf module imports
+ * only valibot; this one is runtime machinery). Everything ELSE the design
+ * needs lives here: `SandboxTransport`/`SandboxLease`/`TeardownStep`/
+ * `SandboxLog`, the process-local lease registry keyed on `spec.lease_key`,
+ * `registerRunLog`'s logger channel, the teardown chain, and the workspace
+ * transport (seed / reconcile / extract) written ONCE against the abstract
+ * `SandboxTransport` — both backends (OpenSandbox's `SandboxDriver`,
+ * Cloudflare's `CloudflareSandboxStub`) satisfy it, so there is exactly one
+ * copy of the git sequences below, not one per adapter.
+ *
+ * The ONE invariant everything in the transport section exists to hold:
+ * at every sync point, the sandbox's git HEAD tree is byte-identical to the
+ * host tree the judges (permissions/gates/quality/changes) will inspect —
+ * tree equality, not history equality. See the design doc's §5.2 for the
+ * full proof and the measured transcripts this code reproduces.
+ *
+ * Backend adapters (`sandbox_opensandbox.ts`, `sandbox_cloudflare.ts`) are a
+ * separate slice of this feature — see their own module comments. This file
+ * dispatches to them (`factoryFor`) and calls into their transport objects
+ * (`seedViaTransport`, `preflight`, `reconcileWorkspace`, `extractWorkspace`)
+ * but owns no SDK-specific code itself.
+ */
+import type { SandboxFactory } from "@flue/runtime";
+import type { SandboxSpec } from "./data_types.ts";
+/**
+ * The live handle the transport (seed/reconcile/extract below) issues
+ * commands through. FIVE verbs — narrowed to exactly what BOTH backends can
+ * satisfy: OpenSandbox's `SandboxDriver` and Cloudflare's
+ * `CloudflareSandboxStub` (7 methods, no `stat`). `readFile` is
+ * `Promise<string>` on both, so the transport never hands it a patch —
+ * patches cross as base64 (see `applyPatchInSandbox`/`extractWorkspace`
+ * below); `readFileBuffer` is for the handoff mirror's small binaries.
+ * `size` replaces `stat` for the one thing the patch-size guard needs,
+ * because neither backend has a native `stat` in common.
+ *
+ * `cwd` is REQUIRED on `exec`: the raw driver resolves relative paths
+ * against the SDK's own default cwd, not `workspace_dir`.
+ */
+export interface SandboxTransport {
+    exec(cmd: string, opts: {
+        cwd: string;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    /** Bytes, or null when it cannot be determined (`exec("wc -c < <path>")`, parsed). */
+    size(path: string): Promise<number | null>;
+}
+export type SandboxLog = (event: {
+    level: "info" | "warn" | "error";
+    msg: string;
+    data?: unknown;
+}) => void;
+export type TeardownStep = {
+    name: string;
+    run: () => Promise<void>;
+};
+/**
+ * The registered handle for one live sandbox. `registerLease` creates the
+ * shell (three args — the logger is resolved per-call from `RUN_LOGS`, never
+ * passed in); the adapter that created the underlying provider sandbox sets
+ * `provider_id`/`native` and pushes its own `teardown` steps afterward.
+ */
+export interface SandboxLease {
+    spec: SandboxSpec;
+    /** Provider id — printed by `spf sandbox list`, the human's drop-in handle. Set by the adapter after create. */
+    provider_id: string;
+    transport: SandboxTransport;
+    /** Resolved, per call, as `RUN_LOGS.get(this.spec.adw_id) ?? NOOP_LOG` — never captured at registration time. */
+    log: SandboxLog;
+    created_at: string;
+    /** Seed fingerprint: {head_sha, patch_sha256}. Drives reconcile; updated by extractWorkspace on the way out. */
+    seeded: {
+        head_sha: string;
+        patch_sha256: string;
+    } | null;
+    /** Committed sync points so far. Names the extract's marker commit. */
+    turn: number;
+    /** Flue conversation ids that shared this lease. Trace only, never a key. */
+    flue_conversation_ids: string[];
+    /** Native, provider-specific surface. NEVER attached to the flue Sandbox. */
+    native: {
+        endpointUrl?(port: number): Promise<string>;
+        egress?(): Promise<unknown>;
+        renew?(seconds: number): Promise<void>;
+    };
+    teardown: TeardownStep[];
+}
+/**
+ * The live grant behind one lease's create-time `env`. `env` is what
+ * `createEnv(spec)` (each adapter's `createSandbox` MISS branch) hands the
+ * provider's create call — the ONLY place `issue()` is ever awaited
+ * (`factoryFor` itself stays sync, §6.1/§9). `describe()` is the honest
+ * one-liner `spf sandbox list`/`doctor` print: key NAMES only, NEVER a
+ * value — the same never-log discipline this file already applies to patch
+ * bytes and handoff content. `revoke()` is pushed as the `credentials:revoke`
+ * teardown step, at position 2 of the chain both adapters left free for it
+ * (see each adapter's MISS branch for the exact splice) — the ordering
+ * guarantee itself (a position-2 step is never skipped because position 1
+ * threw) is `teardownLease`'s, tested against a fake step; this is the real
+ * step riding that proven chain.
+ */
+export interface CredentialGrant {
+    env: Record<string, string>;
+    describe(): string;
+    revoke(): Promise<void>;
+}
+/**
+ * `id` is the value `sandbox.credentials.broker` names in config —
+ * `KNOWN_CREDENTIAL_BROKER_IDS` below is the registry `validateSandboxConfig`
+ * (agents.ts) checks an unknown name against, so a typo is a hard config
+ * error rather than a silent fallback to `static` (§6.1). `issue(spec)`
+ * returns a `Promise` on purpose: a real provisioning broker (§6.3 — not
+ * built here, §10 non-goal 2) needs the network, and shaping the interface
+ * around that up front means a future broker is a pure insertion, never a
+ * signature change to this one.
+ */
+export interface CredentialBroker {
+    id: string;
+    issue(spec: SandboxSpec): Promise<CredentialGrant>;
+}
+/**
+ * Factored out of `staticBroker.issue()` so `spf doctor`'s per-agent line
+ * (§7 check #9) can print the IDENTICAL sentence a real grant's `describe()`
+ * would, from key NAMES it already resolved from config alone — doctor has
+ * no live `SandboxSpec` and, deliberately, never reads operator-env VALUES
+ * just to build this string.
+ */
+export declare function describeStaticCredentials(keyNames: string[]): string;
+/**
+ * The ONLY broker registered in this build (§10 non-goal 2; §11's "Deliberately
+ * NOT in A"). `issue()` is the identity on `spec.env` — B is observably a
+ * no-op on the env PLANE (§6.1); what it adds is this seam, the ordered
+ * revoke step, and the describe() line. `revoke()` clears the grant's own
+ * `env` object IN PLACE — it does not, and cannot, un-inject an
+ * already-created container's process environment; §6.2 is explicit that
+ * "revocable" means nothing for a static key, and this is the honest
+ * implementation of that, not a `revoke()` that pretends otherwise.
+ */
+export declare const staticBroker: CredentialBroker;
+/** The registry `validateSandboxConfig` checks `sandbox.credentials.broker` against (agents.ts). */
+export declare const KNOWN_CREDENTIAL_BROKER_IDS: readonly string[];
+/**
+ * THE LOGGER CHANNEL. Module-level, keyed on adw_id, called from where a
+ * tracer is genuinely in hand (`agents.ts`'s `execute()`, immediately after
+ * the spec is built). Leases resolve `lease.log` through this map with a
+ * no-op fallback, so a lease created by a caller that never registered one
+ * still works and simply logs nowhere. `teardownRun(adwId)` DELETES the
+ * entry — otherwise `spf watch` would retain a closure over every Run it
+ * ever processed.
+ */
+export declare function registerRunLog(adwId: string, log: SandboxLog): void;
+/**
+ * Registers a created lease. THREE arguments — the logger is not one of
+ * them (see `SandboxLease.log`'s doc comment). Returns the mutable lease so
+ * the caller (an adapter) can set `provider_id`/`native` and push its own
+ * `teardown` steps once the underlying provider sandbox actually exists.
+ */
+export declare function registerLease(key: string, spec: SandboxSpec, transport: SandboxTransport): SandboxLease;
+/** Find-or-create lookup for adapters — not exported in the design doc's own code block, but required by it: `createSandbox`'s `hit`/`miss` branch reads exactly this. */
+export declare function getLease(key: string): SandboxLease | undefined;
+export declare function leases(): SandboxLease[];
+/**
+ * Bounded renewal for the adapter's `hit` branch: `min(lifetime_seconds,
+ * remaining budget to max_total_lifetime_seconds)`. Throws — never silently
+ * truncates to zero — once the ceiling from creation has passed, so a
+ * long-lived `spf watch` process cannot renew a lease forever.
+ */
+export declare function renewLease(lease: SandboxLease): Promise<void>;
+export declare function teardownLease(lease: SandboxLease): Promise<void>;
+/** Tears down every lease whose `spec.adw_id === adwId` — a SET, not a single lease (see design §4.3). */
+export declare function teardownRun(adwId: string): Promise<void>;
+export declare function teardownAll(): Promise<void>;
+/**
+ * Per-RUN scope, keyed EXPLICITLY on the run's adw_id — never on ambient
+ * async context. Flue's claim loop is detached from the wrap site's own
+ * async context (see the design doc's §4.3 "Why not AsyncLocalStorage"), so
+ * `createSandbox` runs outside any `AsyncLocalStorage` scope a wrapper here
+ * could establish. Attribution instead rides data already in hand:
+ * `lease.spec.adw_id`, written at create time.
+ */
+export declare function withRunScope<T>(adwId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * SYNC. Returns a closure; performs NO I/O. Every provider call — the
+ * preflight, the seed, the `setup` commands — lives inside the returned
+ * `createSandbox`, which is the async boundary flue awaits itself.
+ */
+export declare function factoryFor(spec: SandboxSpec): SandboxFactory;
+/**
+ * Mandatory create-time check, not a "leaning": the transport below shells
+ * out to `git`, `tar` and `base64` inside the sandbox, so all three are hard
+ * requirements of ANY image, not a convenience. Run by both adapters before
+ * their seed.
+ */
+export declare function preflight(spec: SandboxSpec, transport: SandboxTransport): Promise<void>;
+/**
+ * Seeds a freshly created sandbox from the host tree and returns the
+ * fingerprint to store as `lease.seeded`. Steps mirror the design doc's
+ * §5.2 exactly (refuse-no-commits, mkdir scratch+handoff FIRST, the
+ * attributes-proof tar, extract, `git init`+`spf-base` tag, the uncommitted
+ * delta as `spf-local`, the handoff mirror's mandatory first push, then
+ * `setup`). Called by an adapter's `createSandbox` on the `miss` branch,
+ * against the raw driver/stub transport before any lease exists.
+ */
+export declare function seedViaTransport(spec: SandboxSpec, transport: SandboxTransport): Promise<{
+    head_sha: string;
+    patch_sha256: string;
+}>;
+/**
+ * Compares the live host fingerprint against `lease.seeded` and applies
+ * exactly one of two remedies on a mismatch — conflating them is a
+ * data-loss bug (see the design doc's §5.4). A no-op when there is no lease
+ * yet (the first send of a run — the seed that follows is the sync point)
+ * OR when the fingerprint already matches (nothing has moved on the host
+ * since the last sync point, so the sandbox's handoff content — already
+ * synced by the last extract — cannot be stale either; no provider call at
+ * all in that case).
+ */
+export declare function reconcileWorkspace(spec: SandboxSpec): Promise<void>;
+/**
+ * Three ordered acts: stage+diff in-sandbox, apply on the host (atomic —
+ * `--allow-empty` is mandatory here, the opposite fix from the in-sandbox
+ * applies, because no commit follows it), then advance the sandbox's HEAD
+ * with a marker commit so the NEXT extract emits an increment rather than
+ * the cumulative delta again. A no-op when there is no lease yet.
+ */
+export declare function extractWorkspace(spec: SandboxSpec): Promise<void>;