@wardby/cli 0.5.3 → 0.7.0

package/dist/native-worker/protocol.d.ts

@@ -0,0 +1,296 @@
+/**
+ * The native sandbox worker contract, version 1 (docs/private native sandbox
+ * plan, phase 2). The worker runs the unchanged NativeEngine; everything it
+ * needs from outside — model calls, built-in tools, privileged sandbox
+ * bridges, progress, streamed text, and the terminal result — is a call to the
+ * trusted gateway. The worker is untrusted: the gateway validates every
+ * request against these schemas, and nothing in WorkerInput can carry a
+ * secret value or a credential.
+ *
+ * Transport-neutral: the same messages travel in-process (loopback), over a
+ * child process's stdio, and (phase 3) over HTTP.
+ */
+import { z } from "zod";
+import { causeCodeOf, GATEWAY_CAUSE_CODES } from "../core/error-code.js";
+export { causeCodeOf, GATEWAY_CAUSE_CODES };
+export declare const NATIVE_WORKER_PROTOCOL_VERSION = 1;
+/** Above the sandbox's 12 MiB bridge-result cap, plus envelope. */
+export declare const MAX_MESSAGE_BYTES: number;
+export type ProtocolErrorCode = "unsupported_protocol_version" | "message_too_large" | "message_not_json" | "message_invalid";
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    constructor(code: ProtocolErrorCode, message?: string);
+}
+/** Errors the gateway returns for a call; the worker treats them as final for that call. */
+export type GatewayErrorCode = 
+/** The run is no longer pending/running, or its task was cancelled: stop. */
+"run_not_drivable"
+/** This callId was already used for a call that is still in flight or not replayable. */
+ | "duplicate_call"
+/** A name the run is not allowed to use (unknown tool, bridge, or built-in). */
+ | "not_allowed" | "invalid_request"
+/** A privileged bridge failed; `message` is what the tool sees, as in-process. */
+ | "bridge_error"
+/** The run's budget cannot cover another model call (the gateway's reservation was refused). */
+ | "budget_exhausted"
+/** The worker's network isolation is not proven yet: retry shortly. */
+ | "not_ready" | "internal";
+export declare class GatewayError extends Error {
+    readonly code: GatewayErrorCode;
+    /**
+     * For `internal` only: the code the underlying error's message led with (causeCodeOf), so the
+     * run can name the cause without the rest of that message.
+     */
+    readonly causeCode?: string | undefined;
+    constructor(code: GatewayErrorCode, message: string, 
+    /**
+     * For `internal` only: the code the underlying error's message led with (causeCodeOf), so the
+     * run can name the cause without the rest of that message.
+     */
+    causeCode?: string | undefined);
+}
+/** What the worker is told about an unexpected gateway failure: never the error's own text. */
+export declare const GATEWAY_INTERNAL_MESSAGE = "The gateway could not serve this call.";
+/**
+ * `err` as the worker may see it, on every transport (HTTP, stdio, loopback). An unexpected error
+ * becomes `internal` with the generic message; a GatewayError keeps its code and message. A cause
+ * code is carried only when it is declared (GATEWAY_CAUSE_CODES) and checked: not when it equals, contains, or is contained in a secret
+ * value the run can read (`secretValues`, read only when there is a code to check), and not at
+ * all when there is nothing to check it against or reading the values fails.
+ */
+export declare function workerGatewayError(err: unknown, secretValues?: () => Promise<Iterable<string>>): Promise<GatewayError>;
+/**
+ * `err` as a transport carries it to the worker: a GatewayError (already checked by the gateway
+ * that threw it) as is, with a declared cause code only; anything else `internal` with the generic message and no cause code, since
+ * a transport has no secret values to check one against.
+ */
+export declare function toGatewayError(err: unknown): GatewayError;
+export declare const LlmRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodString;
+        toolCallId: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            argsJson: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
+}, z.core.$strict>;
+export declare const LlmStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    delta: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_call">;
+    id: z.ZodString;
+    name: z.ZodString;
+    argsJson: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    stopReason: z.ZodString;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+        costUsd: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+/** Everything the worker is given, once, at start. No secret values and no credentials. */
+export declare const WorkerInputSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    agent: z.ZodObject<{
+        systemPrompt: z.ZodString;
+        model: z.ZodString;
+        budgetUsd: z.ZodNumber;
+        maxTurns: z.ZodNumber;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+        untrustedContext: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+    builtinTools: z.ZodArray<z.ZodString>;
+    userTools: z.ZodRecord<z.ZodString, z.ZodObject<{
+        code: z.ZodString;
+        paramsZod: z.ZodString;
+    }, z.core.$strict>>;
+    runsConcurrently: z.ZodArray<z.ZodString>;
+    pricing: z.ZodObject<{
+        provider: z.ZodString;
+        modelId: z.ZodString;
+        encoding: z.ZodEnum<{
+            cl100k_base: "cl100k_base";
+            o200k_base: "o200k_base";
+        }>;
+        inputPerMTok: z.ZodNumber;
+        outputPerMTok: z.ZodNumber;
+        cachedInputPerMTok: z.ZodNumber;
+        cacheWritePerMTok: z.ZodNumber;
+        efforts: z.ZodArray<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+        thinkingMode: z.ZodString;
+    }, z.core.$strict>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        capability: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkerInput = z.infer<typeof WorkerInputSchema>;
+/** Each gateway method and its params. */
+export declare const GatewayParamsSchemas: {
+    readonly "llm.stream": z.ZodObject<{
+        request: z.ZodObject<{
+            model: z.ZodString;
+            messages: z.ZodArray<z.ZodObject<{
+                role: z.ZodEnum<{
+                    system: "system";
+                    user: "user";
+                    assistant: "assistant";
+                    tool: "tool";
+                }>;
+                content: z.ZodString;
+                toolCallId: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+                toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    argsJson: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strict>>>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                max: "max";
+            }>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    readonly "llm.countTokens": z.ZodObject<{
+        model: z.ZodString;
+        messages: z.ZodArray<z.ZodObject<{
+            role: z.ZodEnum<{
+                system: "system";
+                user: "user";
+                assistant: "assistant";
+                tool: "tool";
+            }>;
+            content: z.ZodString;
+            toolCallId: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                argsJson: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    readonly "builtin.call": z.ZodObject<{
+        name: z.ZodString;
+        argsJson: z.ZodString;
+    }, z.core.$strict>;
+    /** `invocation` names one tool call, so its bridges share one privileged host (secret redaction is per call). */
+    readonly "host.call": z.ZodObject<{
+        tool: z.ZodString;
+        invocation: z.ZodString;
+        bridge: z.ZodString;
+        argsJson: z.ZodString;
+    }, z.core.$strict>;
+    readonly progress: z.ZodObject<{
+        turns: z.ZodNumber;
+        usage: z.ZodObject<{
+            tokensIn: z.ZodNumber;
+            tokensOut: z.ZodNumber;
+            costUsd: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    readonly text: z.ZodObject<{
+        seq: z.ZodNumber;
+        delta: z.ZodString;
+    }, z.core.$strict>;
+    readonly finish: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            budget_exhausted: "budget_exhausted";
+            refused: "refused";
+            succeeded: "succeeded";
+        }>;
+        finalText: z.ZodString;
+        turns: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};
+export type GatewayMethod = keyof typeof GatewayParamsSchemas;
+export type GatewayParams<M extends GatewayMethod> = z.infer<(typeof GatewayParamsSchemas)[M]>;
+export declare const GatewayRequestSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    callId: z.ZodString;
+    method: z.ZodEnum<{
+        finish: "finish";
+        text: "text";
+        "llm.stream": "llm.stream";
+        "llm.countTokens": "llm.countTokens";
+        "builtin.call": "builtin.call";
+        "host.call": "host.call";
+        progress: "progress";
+    }>;
+    params: z.ZodUnknown;
+}, z.core.$strict>;
+export type GatewayRequest = z.infer<typeof GatewayRequestSchema>;
+/** Rejects before parsing a message too large to accept. */
+export declare function assertMessageSize(text: string): void;
+/** Parses a JSON message text with the size cap, version check, and schema. */
+export declare function parseMessage<T>(text: string, schema: z.ZodType<T>): T;
+/** A gateway request's params, validated for its method. */
+export declare function parseParams<M extends GatewayMethod>(method: M, params: unknown): GatewayParams<M>;

package/dist/native-worker/protocol.js

@@ -0,0 +1,246 @@
+/**
+ * The native sandbox worker contract, version 1 (docs/private native sandbox
+ * plan, phase 2). The worker runs the unchanged NativeEngine; everything it
+ * needs from outside — model calls, built-in tools, privileged sandbox
+ * bridges, progress, streamed text, and the terminal result — is a call to the
+ * trusted gateway. The worker is untrusted: the gateway validates every
+ * request against these schemas, and nothing in WorkerInput can carry a
+ * secret value or a credential.
+ *
+ * Transport-neutral: the same messages travel in-process (loopback), over a
+ * child process's stdio, and (phase 3) over HTTP.
+ */
+import { z } from "zod";
+import { causeCodeOf, GATEWAY_CAUSE_CODES } from "../core/error-code.js";
+import { LLM_EFFORT_LEVELS } from "../providers/llm/types.js";
+import { overlapsSecretValue } from "../sandbox/host-functions.js";
+// The allow-list and its checked helper live in core/error-code.ts (shared with the runner); re-exported here.
+export { causeCodeOf, GATEWAY_CAUSE_CODES };
+export const NATIVE_WORKER_PROTOCOL_VERSION = 1;
+/** Above the sandbox's 12 MiB bridge-result cap, plus envelope. */
+export const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
+export class ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ? `${code}: ${message}` : code);
+        this.code = code;
+        this.name = "ProtocolError";
+    }
+}
+export class GatewayError extends Error {
+    code;
+    causeCode;
+    constructor(code, message, 
+    /**
+     * For `internal` only: the code the underlying error's message led with (causeCodeOf), so the
+     * run can name the cause without the rest of that message.
+     */
+    causeCode) {
+        super(message);
+        this.code = code;
+        this.causeCode = causeCode;
+        this.name = "GatewayError";
+    }
+}
+/** What the worker is told about an unexpected gateway failure: never the error's own text. */
+export const GATEWAY_INTERNAL_MESSAGE = "The gateway could not serve this call.";
+/**
+ * `err` as the worker may see it, on every transport (HTTP, stdio, loopback). An unexpected error
+ * becomes `internal` with the generic message; a GatewayError keeps its code and message. A cause
+ * code is carried only when it is declared (GATEWAY_CAUSE_CODES) and checked: not when it equals, contains, or is contained in a secret
+ * value the run can read (`secretValues`, read only when there is a code to check), and not at
+ * all when there is nothing to check it against or reading the values fails.
+ */
+export async function workerGatewayError(err, secretValues) {
+    const leading = err instanceof GatewayError ? err.causeCode : causeCodeOf(err);
+    // Declared codes only; the exact-value check below is a second guard.
+    const candidate = leading && GATEWAY_CAUSE_CODES.has(leading) ? leading : undefined;
+    let causeCode;
+    if (candidate && secretValues) {
+        const values = await secretValues().catch(() => undefined);
+        if (values && !overlapsSecretValue(candidate, values))
+            causeCode = candidate;
+    }
+    if (err instanceof GatewayError)
+        return new GatewayError(err.code, err.message, causeCode);
+    return new GatewayError("internal", causeCode ? `The gateway could not serve this call (${causeCode}).` : GATEWAY_INTERNAL_MESSAGE, causeCode);
+}
+/**
+ * `err` as a transport carries it to the worker: a GatewayError (already checked by the gateway
+ * that threw it) as is, with a declared cause code only; anything else `internal` with the generic message and no cause code, since
+ * a transport has no secret values to check one against.
+ */
+export function toGatewayError(err) {
+    if (err instanceof GatewayError) {
+        const causeCode = err.causeCode && GATEWAY_CAUSE_CODES.has(err.causeCode) ? err.causeCode : undefined;
+        return new GatewayError(err.code, err.message, causeCode);
+    }
+    return new GatewayError("internal", GATEWAY_INTERNAL_MESSAGE);
+}
+const runId = z.string().min(1).max(64);
+const callId = z.string().min(1).max(128);
+const LlmMessageSchema = z
+    .object({
+    role: z.enum(["system", "user", "assistant", "tool"]),
+    content: z.string(),
+    toolCallId: z.string().optional(),
+    name: z.string().optional(),
+    toolCalls: z.array(z.object({ id: z.string(), name: z.string(), argsJson: z.string() }).strict()).optional(),
+})
+    .strict();
+const LlmToolDefSchema = z
+    .object({ name: z.string(), description: z.string(), parameters: z.record(z.string(), z.unknown()) })
+    .strict();
+export const LlmRequestSchema = z
+    .object({
+    model: z.string(),
+    messages: z.array(LlmMessageSchema),
+    tools: z.array(LlmToolDefSchema).optional(),
+    maxTokens: z.number().int().positive().optional(),
+    temperature: z.number().optional(),
+    stopSequences: z.array(z.string()).optional(),
+    effort: z.enum(LLM_EFFORT_LEVELS).optional(),
+})
+    .strict();
+export const LlmStreamEventSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text"), delta: z.string() }).strict(),
+    z.object({ type: z.literal("tool_call"), id: z.string(), name: z.string(), argsJson: z.string() }).strict(),
+    z
+        .object({
+        type: z.literal("done"),
+        stopReason: z.string(),
+        usage: z
+            .object({
+            inputTokens: z.number(),
+            outputTokens: z.number(),
+            cachedInputTokens: z.number().optional(),
+            cacheWriteTokens: z.number().optional(),
+            costUsd: z.number(),
+        })
+            .strict(),
+    })
+        .strict(),
+]);
+const LoadedToolSchema = z
+    .object({ name: z.string(), description: z.string(), jsonSchema: z.record(z.string(), z.unknown()) })
+    .strict();
+/** A user tool as the worker runs it: code and schema only. Capabilities stay on the gateway. */
+const WorkerUserToolSchema = z.object({ code: z.string(), paramsZod: z.string() }).strict();
+const PricingSchema = z
+    .object({
+    provider: z.string(),
+    modelId: z.string(),
+    encoding: z.enum(["cl100k_base", "o200k_base"]),
+    inputPerMTok: z.number(),
+    outputPerMTok: z.number(),
+    cachedInputPerMTok: z.number(),
+    cacheWritePerMTok: z.number(),
+    efforts: z.array(z.enum(LLM_EFFORT_LEVELS)),
+    thinkingMode: z.string(),
+})
+    .strict();
+/** Everything the worker is given, once, at start. No secret values and no credentials. */
+export const WorkerInputSchema = z
+    .object({
+    v: z.literal(NATIVE_WORKER_PROTOCOL_VERSION),
+    runId,
+    agent: z
+        .object({
+        systemPrompt: z.string(),
+        model: z.string(),
+        budgetUsd: z.number().nonnegative(),
+        maxTurns: z.number().int().positive(),
+        effort: z.enum(LLM_EFFORT_LEVELS).optional(),
+        untrustedContext: z.string().optional(),
+    })
+        .strict(),
+    tools: z.array(LoadedToolSchema),
+    /** Names the gateway serves (memory, repo_*, jira_*, sub-agent memory, delegate_to_*). */
+    builtinTools: z.array(z.string()),
+    /** User tools the worker runs itself, by name. */
+    userTools: z.record(z.string(), WorkerUserToolSchema),
+    /** Tool names whose calls in one turn may run at the same time (delegations, when opted in). */
+    runsConcurrently: z.array(z.string()),
+    /** The run's pinned catalog entry, so the engine's local budget checks price without a network call. */
+    pricing: PricingSchema,
+    /**
+     * Where and how to reach the HTTP gateway. Absent: the gateway is on this process's stdio.
+     * The capability is given once, here, on the worker's stdin; it is never in its environment,
+     * argv, or the server's stored snapshot (only its hash is stored).
+     */
+    gateway: z
+        .object({ url: z.string().url(), capability: z.string().min(32).max(256) })
+        .strict()
+        .optional(),
+})
+    .strict();
+const UsageTotalsSchema = z.object({ tokensIn: z.number(), tokensOut: z.number(), costUsd: z.number() }).strict();
+/** Each gateway method and its params. */
+export const GatewayParamsSchemas = {
+    "llm.stream": z.object({ request: LlmRequestSchema }).strict(),
+    "llm.countTokens": z
+        .object({ model: z.string(), messages: z.array(LlmMessageSchema), tools: z.array(LlmToolDefSchema).optional() })
+        .strict(),
+    "builtin.call": z.object({ name: z.string().max(200), argsJson: z.string() }).strict(),
+    /** `invocation` names one tool call, so its bridges share one privileged host (secret redaction is per call). */
+    "host.call": z
+        .object({
+        tool: z.string().max(200),
+        invocation: z.string().min(1).max(128),
+        bridge: z.string().max(64),
+        argsJson: z.string(),
+    })
+        .strict(),
+    progress: z.object({ turns: z.number().int().nonnegative(), usage: UsageTotalsSchema }).strict(),
+    text: z.object({ seq: z.number().int().nonnegative(), delta: z.string() }).strict(),
+    finish: z
+        .object({
+        status: z.enum(["succeeded", "budget_exhausted", "refused", "failed"]),
+        finalText: z.string(),
+        turns: z.number().int().nonnegative(),
+        error: z.string().optional(),
+    })
+        .strict(),
+};
+export const GatewayRequestSchema = z
+    .object({
+    v: z.literal(NATIVE_WORKER_PROTOCOL_VERSION),
+    runId,
+    callId,
+    method: z.enum(Object.keys(GatewayParamsSchemas)),
+    params: z.unknown(),
+})
+    .strict();
+/** Rejects before parsing a message too large to accept. */
+export function assertMessageSize(text) {
+    if (Buffer.byteLength(text) > MAX_MESSAGE_BYTES)
+        throw new ProtocolError("message_too_large");
+}
+function checkVersion(raw) {
+    if (raw && typeof raw === "object" && "v" in raw && raw.v !== NATIVE_WORKER_PROTOCOL_VERSION) {
+        throw new ProtocolError("unsupported_protocol_version");
+    }
+}
+/** Parses a JSON message text with the size cap, version check, and schema. */
+export function parseMessage(text, schema) {
+    assertMessageSize(text);
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ProtocolError("message_not_json");
+    }
+    checkVersion(raw);
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success)
+        throw new ProtocolError("message_invalid", parsed.error.issues[0]?.message);
+    return parsed.data;
+}
+/** A gateway request's params, validated for its method. */
+export function parseParams(method, params) {
+    const parsed = GatewayParamsSchemas[method].safeParse(params);
+    if (!parsed.success)
+        throw new ProtocolError("message_invalid", parsed.error.issues[0]?.message);
+    return parsed.data;
+}

package/dist/native-worker/sandbox-executor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The Executor for sandbox-mode native runs (docs/native-sandbox.md). Phase 1's
+ * RoutingExecutor sends every run whose snapshot says `sandbox` here.
+ *
+ * - start: creates the run's gateway session (pinning the run and recording
+ *   `native-sandbox` as its backend before any worker exists), launches the
+ *   worker, and returns. Whichever gateway replica serves the worker's
+ *   `finish` makes the terminal write; this executor only watches for a
+ *   worker that exits without one, and for its deadline.
+ * - stop: records the run cancelled, ends the session (every further gateway
+ *   call is refused, so the worker exits at its next one), gives the worker a
+ *   short grace to exit, then kills and removes it (a warm pool worker is
+ *   discarded, never reused), and stops its open delegations.
+ * - recover: answers the reconciler from the worker's container state, and
+ *   never launches one.
+ * - launch: the janitor removes workers whose runs have ended.
+ */
+import { type NativeRunProviders, type RunnerDb } from "../core/runner.js";
+import type { ExecutionRecoveryResult, Executor, PersistedExecutionHandle } from "../providers/executor/types.js";
+import type { NativeWorkerState } from "./docker-launcher.js";
+import { type DetachedWorkerLauncher, type WorkerHandle } from "./launch.js";
+import { type GatewayLedgerDb } from "./ledger.js";
+/** What the executor needs from a worker launcher (DockerNativeWorkerLauncher, or a test double). */
+export interface ManagedWorkerLauncher extends DetachedWorkerLauncher {
+    handle(runId: string): WorkerHandle;
+    inspect(runId: string): Promise<NativeWorkerState>;
+    kill(runId: string): Promise<void>;
+    remove(runId: string): Promise<void>;
+    listWorkers(): Promise<{
+        name: string;
+        runHash: string;
+    }[]>;
+    removeByWorkerName(name: string): Promise<void>;
+    /** The URL workers dial, when only the launcher can know it (a Kubernetes Service's ClusterIP). */
+    resolveGatewayUrl?(): Promise<string>;
+    /** Background upkeep the long-lived process runs from the executor's `launch()` (the warm pool's). */
+    start?(): Promise<void>;
+}
+export interface NativeSandboxExecutorOptions {
+    db: RunnerDb & GatewayLedgerDb;
+    /** The server's providers: the run's load, and its terminal writes when the worker cannot make them. */
+    providers: NativeRunProviders;
+    launcher: ManagedWorkerLauncher;
+    /** What workers dial: the gateway's alias on their run network. */
+    gatewayUrl: string;
+    /** NATIVE_SANDBOX_MAX_CONCURRENT: a start past this many active sessions fails with native_sandbox_capacity. */
+    maxConcurrent?: number;
+    /** How long a stopped run's worker gets to exit on its own before it is killed (default NATIVE_SANDBOX_STOP_GRACE_MS). */
+    stopGraceMs?: number;
+    /** How often a launching run's heartbeat is refreshed (default a third of HEARTBEAT_TIMEOUT_MS). */
+    heartbeatIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A stopped sandbox run's worker exits at its next (refused) gateway call; past this it is killed. */
+export declare const NATIVE_SANDBOX_STOP_GRACE_MS = 5000;
+export declare const NATIVE_SANDBOX_WORKER_EXITED = "native_sandbox_worker_exited";
+export declare const NATIVE_SANDBOX_DEADLINE = "native_sandbox_deadline_exceeded";
+export declare class NativeSandboxExecutor implements Executor {
+    private readonly options;
+    private readonly ledger;
+    private readonly watching;
+    private readonly deadlineKilled;
+    constructor(options: NativeSandboxExecutorOptions);
+    private now;
+    private finishContext;
+    start(runId: string): Promise<void>;
+    /** Refreshes a still-live run's heartbeat while `work` runs. */
+    private whileHeartbeating;
+    /** The run is still live and its session open: a worker launched now would have work to do. */
+    private stillWanted;
+    /** Watches one worker in this process: its exit, and its deadline. */
+    private watch;
+    private onWorkerExit;
+    private endSession;
+    stop(runId: string, reason?: string): Promise<void>;
+    /** Waits up to stopGraceMs for the run's worker to exit or be gone; false when it still runs. Never throws. */
+    private awaitWorkerExit;
+    recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
+    /** Startup janitor: removes worker containers whose runs have ended or passed their deadline. Starts the warm pool. */
+    launch(): Promise<void>;
+    sweep(): Promise<number>;
+}