@gr8ful/spf 0.9.2 → 0.10.0

package/dist/core/sandbox_sdk_types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Hand-written surface of `@alibaba-group/opensandbox` v0.1.11 (SPF #15
+ * design doc §4.1's "SDK dependency — no new entry in package.json").
+ *
+ * NOTHING in this file imports the real package — every shape below is
+ * copied from the spike's MEASURED API surface (see the scratchpad's
+ * `sandbox-spike.json`, `api_surface` field), not from the package's own
+ * `.d.ts` (which is never on disk in this tree: the SDK is a documented user
+ * install, §4.1, never a `package.json` dependency). `sandbox_opensandbox.ts`
+ * types `loadOpenSandboxSdk`'s return value against these interfaces so the
+ * whole tree typechecks with the SDK absent from `node_modules` — exactly
+ * the trade `CloudflareSandboxStub` makes deliberately
+ * (`dist/cloudflare/index.d.mts:6-12`: "A wrong object fails loudly on the
+ * first method call").
+ *
+ * A shape mismatch against a REAL installed SDK surfaces as a runtime error
+ * from the first call that touches the mismatched field, never as a compile
+ * error — there is nothing here for `tsc` to check it against.
+ */
+export interface OpenSandboxConnectionConfig {
+    domain: string;
+    protocol?: "http" | "https";
+    apiKey?: string;
+    /** The SDK's CLIENT-SIDE HTTP timeout for control-plane calls. NOT a bound on a streamed `commands.run`. */
+    requestTimeoutSeconds?: number;
+    headers?: Record<string, string>;
+    useServerProxy?: boolean;
+}
+export interface OpenSandboxNetworkPolicy {
+    defaultAction: "allow" | "deny";
+    egress?: Array<{
+        action: "allow" | "deny";
+        target: string;
+    }>;
+}
+export interface OpenSandboxCreateOptions {
+    connectionConfig: OpenSandboxConnectionConfig;
+    image: string;
+    entrypoint?: string;
+    /** Provider-side lease expiry, in seconds — `sandbox.renew()` extends it while a lease is live. */
+    timeoutSeconds?: number;
+    env?: Record<string, string>;
+    resource?: unknown;
+    metadata?: Record<string, string>;
+    networkPolicy?: OpenSandboxNetworkPolicy;
+    credentialProxy?: unknown;
+    extensions?: unknown;
+    skipHealthCheck?: boolean;
+    healthCheck?: unknown;
+    /** Readiness bound — distinct from `requestTimeoutSeconds`. The spike measured a 30-90s cold egress-sidecar start against exactly this knob. */
+    readyTimeoutSeconds?: number;
+}
+export interface OpenSandboxCommandOptions {
+    /** Maps to the API's `cwd` — the SDK's own field name is `workingDirectory`, not `cwd` (confirmed against the installed SDK's `.d.ts`). */
+    workingDirectory?: string;
+    /** The SDK's own field name is `envs`, not `env`. */
+    envs?: Record<string, string>;
+    /**
+     * O-1 (open question, design §12): the spike documented `commands.run`'s
+     * signature but never measured whether it accepts a per-command deadline.
+     * Forwarded best-effort, seconds, rounded UP per `sandbox-api.md:225` —
+     * the adapter's OWN host-side timer (§4.1 point 3) is what actually
+     * enforces the deadline regardless of whether the SDK honors this field.
+     */
+    timeoutSeconds?: number;
+}
+export interface OpenSandboxLogChunk {
+    text: string;
+}
+export interface OpenSandboxCommandResult {
+    logs: {
+        stdout: OpenSandboxLogChunk[];
+        stderr: OpenSandboxLogChunk[];
+    };
+    exitCode: number;
+    executionTimeMs: number;
+}
+export interface OpenSandboxExecutionHandlers {
+    onStdout?: (chunk: OpenSandboxLogChunk) => void;
+    onStderr?: (chunk: OpenSandboxLogChunk) => void;
+    onExecutionComplete?: (result: OpenSandboxCommandResult) => void;
+}
+export interface OpenSandboxCommandsApi {
+    run(command: string, options?: OpenSandboxCommandOptions, handlers?: OpenSandboxExecutionHandlers): Promise<OpenSandboxCommandResult>;
+}
+export interface OpenSandboxDirEntry {
+    path: string;
+    mode?: number;
+}
+export interface OpenSandboxFileEntry {
+    path: string;
+    data: string | Uint8Array;
+    mode?: number;
+}
+export interface OpenSandboxFilesApi {
+    createDirectories(dirs: OpenSandboxDirEntry[]): Promise<void>;
+    writeFiles(files: OpenSandboxFileEntry[]): Promise<void>;
+    readFile(path: string): Promise<string>;
+    search(options: {
+        path: string;
+        pattern: string;
+    }): Promise<unknown>;
+    deleteDirectories(paths: string[]): Promise<void>;
+}
+export interface OpenSandboxInfo {
+    status: {
+        state: string;
+    };
+    createdAt: string;
+    expiresAt: string;
+}
+export interface OpenSandboxEgressRule {
+    action: "allow" | "deny";
+    target: string;
+}
+export interface OpenSandboxEgressPolicy {
+    defaultAction: "allow" | "deny";
+    egress: OpenSandboxEgressRule[];
+}
+export interface OpenSandboxInstance {
+    readonly id: string;
+    commands: OpenSandboxCommandsApi;
+    files: OpenSandboxFilesApi;
+    getInfo(): Promise<OpenSandboxInfo>;
+    pause(): Promise<void>;
+    /** Resumes returns a FRESH connected instance — not `this`, per the spike. */
+    resume(): Promise<OpenSandboxInstance>;
+    renew(seconds: number): Promise<void>;
+    /** Terminates the remote sandbox + sidecar. Does NOT release the local HTTP agent — see `close()`. */
+    kill(): Promise<void>;
+    /** Releases the Node undici keep-alive agent. Separate from `kill()` — BOTH are required teardown calls (spike caveat). */
+    close(): Promise<void>;
+    getEndpoint(port: number): Promise<{
+        endpoint: string;
+    }>;
+    getEndpointUrl(port: number): Promise<string>;
+    /** Talks directly to the egress sidecar's own REST surface on sandbox port 18080 — NOT proxied through the control plane. */
+    getEgressPolicy(): Promise<OpenSandboxEgressPolicy>;
+    patchEgressRules(rules: OpenSandboxEgressRule[]): Promise<void>;
+}
+export interface OpenSandboxCtor {
+    create(options: OpenSandboxCreateOptions): Promise<OpenSandboxInstance>;
+}
+export interface OpenSandboxManagerListItem {
+    id: string;
+    metadata?: Record<string, string>;
+    status?: {
+        state: string;
+    };
+}
+export interface OpenSandboxManagerListResult {
+    items: OpenSandboxManagerListItem[];
+    pagination?: unknown;
+}
+export interface OpenSandboxManagerInstance {
+    listSandboxInfos(options?: {
+        states?: string[];
+        pageSize?: number;
+    }): Promise<OpenSandboxManagerListResult>;
+    close(): Promise<void>;
+}
+export interface OpenSandboxManagerCtor {
+    create(options: {
+        connectionConfig: OpenSandboxConnectionConfig;
+    }): Promise<OpenSandboxManagerInstance>;
+}
+/** The module namespace shape `import(OPENSANDBOX_SPECIFIER)` resolves to. */
+export interface OpenSandboxModuleShape {
+    Sandbox: OpenSandboxCtor;
+    SandboxManager: OpenSandboxManagerCtor;
+}

package/dist/core/sandbox_sdk_types.js

@@ -0,0 +1,20 @@
+/**
+ * Hand-written surface of `@alibaba-group/opensandbox` v0.1.11 (SPF #15
+ * design doc §4.1's "SDK dependency — no new entry in package.json").
+ *
+ * NOTHING in this file imports the real package — every shape below is
+ * copied from the spike's MEASURED API surface (see the scratchpad's
+ * `sandbox-spike.json`, `api_surface` field), not from the package's own
+ * `.d.ts` (which is never on disk in this tree: the SDK is a documented user
+ * install, §4.1, never a `package.json` dependency). `sandbox_opensandbox.ts`
+ * types `loadOpenSandboxSdk`'s return value against these interfaces so the
+ * whole tree typechecks with the SDK absent from `node_modules` — exactly
+ * the trade `CloudflareSandboxStub` makes deliberately
+ * (`dist/cloudflare/index.d.mts:6-12`: "A wrong object fails loudly on the
+ * first method call").
+ *
+ * A shape mismatch against a REAL installed SDK surfaces as a runtime error
+ * from the first call that touches the mismatched field, never as a compile
+ * error — there is nothing here for `tsc` to check it against.
+ */
+export {};

package/dist/core/watch.d.ts

@@ -1,4 +1,5 @@
 import type { GitHandle } from "./git_helper.ts";
+import { type AttemptDispatch, type AttemptMetrics } from "./fanout.ts";
 import type { CodeHostProvider, Issue, IssueComment, IssueProvider, WatchMarker, WatchState } from "./issues/provider.ts";
 import type { NotifyEvent } from "./notify/channel.ts";
 import { type RefinedPriority } from "./data_types.ts";
@@ -52,6 +53,50 @@ export interface RefineRunResult {
     /** What the refiner is asking, read back from its own side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted` or when the run published a tree instead of escalating; `gates.refinementWellFormed` guarantees `created` and `questions` are never both non-empty. */
     questions: RefinedQuestionRef[];
 }
+/**
+ * The fan-out lane's injected trio + the two values `WatchDeps` cannot derive.
+ * Exported as a NAMED type (not an inline object literal) because
+ * `cli/commands/watch.ts`'s `makeWatchFanoutDispatch` factory returns it and
+ * `src/test/watch_fanout_sandbox_wiring.test.ts` names it — an inline literal
+ * would have to be duplicated in three places.
+ */
+export interface WatchFanoutDeps {
+    /** > 1. `cli/commands/watch.ts` passes `undefined` for this whole object when `watch.fanout.n` is 1. */
+    n: number;
+    /** Attempts IN FLIGHT within one issue — NOT `WatchDeps.concurrency`, which counts issues. Does NOT bound worktrees on disk (see the module's fan-out doc). */
+    concurrency: number;
+    /** The MAIN repo root. `GitHandle` has no accessor for it — `cli/commands/watch.ts` passes its anchor's `repo_root`, the same value `deps.git` is bound to. */
+    repoRoot: string;
+    /** One attempt's chain, in that attempt's own worktree — the same ctx `runChain` builds, per attempt. */
+    runAttempt: (dispatch: AttemptDispatch) => Promise<number>;
+    /** Gate/usage rows for one attempt's adw_id, from the SHARED db. Must not throw. */
+    readMetrics: (adwId: string) => AttemptMetrics;
+    /**
+     * True when NOT ONE of these adw_ids has a session row yet — the same db,
+     * the same predicate and the same reasoning as `spf fanout`'s reuse
+     * preflight (`cli/commands/fanout.ts`, `preflight.session(id) !== null`).
+     * This is what advances the fan-out lane's base-adw_id salt on EVERY claim
+     * (see `runIssueFanout`'s salt probe) — the sessions the previous claim's
+     * attempts left behind are the only thing that reliably changes on every
+     * re-claim, unlike `WatchMarker.attempt`, which only advances on the
+     * orphan-retry path.
+     *
+     * Must not throw, and its safe direction is FALSE: a db it cannot read
+     * reports "taken", which burns an id and keeps the selection basis clean,
+     * rather than reporting "free" and letting a previous run's rows decide
+     * this run's winner.
+     */
+    adwIdsFree: (adwIds: string[]) => boolean;
+    /** The winner's review posture, read back post-hoc — the same two fields `runChain` returns, keyed on a WINNER instead of the sole attempt. */
+    reviewFor: (opts: {
+        cwd: string;
+        adwId: string;
+        chainOptions: Record<string, string>;
+    }) => {
+        reviewRequired: boolean;
+        reviewSummary?: string;
+    };
+}
 export interface WatchDeps {
     provider: IssueProvider;
     codeHost: CodeHostProvider;
@@ -133,6 +178,17 @@ export interface WatchDeps {
      * just be noise in a channel.
      */
     notify: (event: NotifyEvent) => void;
+    /**
+     * Best-of-N per claimed issue (`watch.fanout`). `undefined` — the default,
+     * and what every existing test constructs — means single dispatch:
+     * `runIssue` takes the path it always has.
+     *
+     * ONE OPTIONAL OBJECT, not several optional fields: everything the fan-out
+     * lane needs is required WHEN THE LANE IS ON and meaningless when it is
+     * off, so the optionality belongs at the lane, not at each field. There is
+     * no "optional but secretly required" member to get wrong.
+     */
+    fanout?: WatchFanoutDeps;
 }
 export interface WatchRunState {
     inflight: Set<string>;