@wardby/cli 0.5.3 → 0.6.0

package/dist/native-worker/protocol.js

@@ -0,0 +1,200 @@
+/**
+ * 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 { LLM_EFFORT_LEVELS } from "../providers/llm/types.js";
+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;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GatewayError";
+    }
+}
+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,68 @@
+/**
+ * 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: ends the session (every further gateway call is refused), kills the
+ *   worker, records the run cancelled, 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;
+    now?: () => number;
+}
+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>;
+    /** Watches one worker in this process: its exit, and its deadline. */
+    private watch;
+    private onWorkerExit;
+    private endSession;
+    stop(runId: string, reason?: string): Promise<void>;
+    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>;
+}

package/dist/native-worker/sandbox-executor.js

@@ -0,0 +1,210 @@
+/**
+ * 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: ends the session (every further gateway call is refused), kills the
+ *   worker, records the run cancelled, 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 { logger } from "../core/logger.js";
+import { failNativeRun, nativeRunIntegrations, RunCancelledError, NATIVE_SANDBOX_BACKEND, } from "../core/runner.js";
+import { nativeRunLabel } from "./docker-isolation.js";
+import { startSandboxRun } from "./launch.js";
+import { NATIVE_SANDBOX_CAPACITY } from "./kubernetes-launcher.js";
+import { PrismaGatewayLedger } from "./ledger.js";
+const executorLog = logger.child({ module: "native-sandbox-executor" });
+const isUniqueViolation = (err) => typeof err === "object" && err !== null && err.code === "P2002";
+export const NATIVE_SANDBOX_WORKER_EXITED = "native_sandbox_worker_exited";
+export const NATIVE_SANDBOX_DEADLINE = "native_sandbox_deadline_exceeded";
+export class NativeSandboxExecutor {
+    options;
+    ledger;
+    watching = new Map();
+    deadlineKilled = new Set();
+    constructor(options) {
+        this.options = options;
+        this.ledger = new PrismaGatewayLedger(options.db);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    finishContext(runId) {
+        const { db, providers } = this.options;
+        return { runId, db, providers, ...nativeRunIntegrations(providers, db) };
+    }
+    async start(runId) {
+        const { db, providers, launcher, gatewayUrl } = this.options;
+        // A second start (a retried dispatch) attaches to the run's worker; it never launches another.
+        const existing = await db.nativeGatewaySession.findUnique({ where: { runId }, select: { deadlineAt: true } });
+        if (existing) {
+            this.watch(runId, launcher.handle(runId), existing.deadlineAt);
+            return;
+        }
+        // Fail fast rather than queue (a warm pool's job): every replica counts the same sessions, and a
+        // near-simultaneous start that overshoots by one is still bounded by the cluster's ResourceQuota.
+        const cap = this.options.maxConcurrent;
+        if (cap !== undefined && (await db.nativeGatewaySession.count({ where: { status: "active" } })) >= cap) {
+            throw new Error(`${NATIVE_SANDBOX_CAPACITY}: ${cap} sandbox runs are already active (NATIVE_SANDBOX_MAX_CONCURRENT).`);
+        }
+        let outcome;
+        try {
+            const url = launcher.resolveGatewayUrl ? await launcher.resolveGatewayUrl() : gatewayUrl;
+            outcome = await startSandboxRun({ runId, providers, db, gatewayUrl: url, launcher });
+        }
+        catch (err) {
+            // A concurrent start won the race for the run's one session: attach to its worker.
+            if (!isUniqueViolation(err)) {
+                // The launch failed after the session was created (e.g. isolation could not be proven):
+                // end the session so nothing can use its capability; the caller fails the run.
+                await this.endSession(runId, "cancelled").catch(() => { });
+                throw err;
+            }
+            const raced = await db.nativeGatewaySession.findUniqueOrThrow({ where: { runId }, select: { deadlineAt: true } });
+            this.watch(runId, launcher.handle(runId), raced.deadlineAt);
+            return;
+        }
+        if (outcome.kind === "ended")
+            return;
+        const session = await db.nativeGatewaySession.findUniqueOrThrow({
+            where: { id: outcome.sessionId },
+            select: { deadlineAt: true },
+        });
+        this.watch(runId, outcome.handle, session.deadlineAt);
+    }
+    /** Watches one worker in this process: its exit, and its deadline. */
+    watch(runId, handle, deadlineAt) {
+        if (this.watching.has(runId))
+            return;
+        const msLeft = deadlineAt.getTime() - this.now();
+        const timer = msLeft > 0
+            ? setTimeout(() => {
+                this.deadlineKilled.add(runId);
+                handle.kill();
+            }, msLeft)
+            : undefined;
+        if (msLeft <= 0) {
+            this.deadlineKilled.add(runId);
+            handle.kill();
+        }
+        this.watching.set(runId, timer);
+        void handle.exited
+            .then((code) => this.onWorkerExit(runId, code))
+            .catch((err) => executorLog.error({ err, runId }, "watching a native sandbox worker failed"));
+    }
+    async onWorkerExit(runId, exitCode) {
+        const timer = this.watching.get(runId);
+        if (timer)
+            clearTimeout(timer);
+        this.watching.delete(runId);
+        const { db } = this.options;
+        const run = await db.run.findUnique({ where: { id: runId }, select: { status: true } });
+        if (run && (run.status === "pending" || run.status === "running")) {
+            // The worker ended without its `finish`: nothing will write a result for it, so this does.
+            const reason = this.deadlineKilled.has(runId)
+                ? `${NATIVE_SANDBOX_DEADLINE}: the sandbox run passed its deadline and its worker was stopped.`
+                : `${NATIVE_SANDBOX_WORKER_EXITED}: the sandbox worker exited (code ${exitCode ?? "unknown"}) without a result.`;
+            await failNativeRun(this.finishContext(runId), new Error(reason));
+        }
+        this.deadlineKilled.delete(runId);
+        await this.endSession(runId, "finished");
+        await this.options.launcher.remove(runId).catch((err) => {
+            executorLog.warn({ err, runId }, "removing a native sandbox worker failed; the janitor will retry");
+        });
+    }
+    async endSession(runId, status) {
+        const session = await this.options.db.nativeGatewaySession.findUnique({ where: { runId }, select: { id: true } });
+        if (session)
+            await this.ledger.endSession(session.id, status);
+        return session?.id;
+    }
+    async stop(runId, reason) {
+        // Recorded first, before the session ends or the worker is killed: either of those makes the
+        // worker exit, and its exit watcher must then find the run already ended (and leave it
+        // cancelled) rather than record the exit as a failure.
+        await failNativeRun(this.finishContext(runId), new RunCancelledError(reason ?? "The run was cancelled."));
+        const sessionId = await this.endSession(runId, "cancelled");
+        await this.options.launcher.kill(runId).catch(() => { });
+        if (sessionId) {
+            // Its delegations' children belong to the server's executor; a child left running would
+            // spend on behalf of a parent that no longer waits for it.
+            for (const child of await this.ledger.openDelegationChildren(sessionId)) {
+                await this.options.providers.executor?.stop(child, "parent run cancelled").catch((err) => {
+                    executorLog.warn({ err, runId, child }, "failed to stop a cancelled sandbox run's child");
+                });
+            }
+        }
+        await this.options.launcher.remove(runId).catch(() => { });
+    }
+    async recover(handle) {
+        if (handle.backend !== NATIVE_SANDBOX_BACKEND) {
+            return { state: "lost", reason: `NativeSandboxExecutor cannot recover backend "${handle.backend}".` };
+        }
+        const runId = handle.runId;
+        const { db, launcher } = this.options;
+        const [state, run, session] = await Promise.all([
+            launcher.inspect(runId),
+            db.run.findUnique({ where: { id: runId }, select: { status: true } }),
+            db.nativeGatewaySession.findUnique({ where: { runId }, select: { status: true, deadlineAt: true } }),
+        ]);
+        const runEnded = !run || !(run.status === "pending" || run.status === "running");
+        if (state.state === "running") {
+            if (runEnded) {
+                await launcher.kill(runId).catch(() => { });
+                await launcher.remove(runId).catch(() => { });
+                return { state: "terminal" };
+            }
+            // Re-attach (a restarted server): watch its exit and deadline from here.
+            if (session)
+                this.watch(runId, launcher.handle(runId), session.deadlineAt);
+            return { state: "active" };
+        }
+        if (state.state === "exited") {
+            await this.onWorkerExit(runId, state.exitCode);
+            return { state: "terminal" };
+        }
+        if (runEnded || session?.status === "finished")
+            return { state: "terminal" };
+        return {
+            state: "lost",
+            reason: "native_sandbox_worker_lost: the run's sandbox worker is gone and left no result; it was not relaunched.",
+        };
+    }
+    /** Startup janitor: removes worker containers whose runs have ended or passed their deadline. Starts the warm pool. */
+    async launch() {
+        await this.sweep().catch((err) => executorLog.warn({ err }, "native sandbox janitor failed"));
+        await this.options.launcher
+            .start?.()
+            .catch((err) => executorLog.warn({ err }, "native warm pool failed to start"));
+    }
+    async sweep() {
+        const { db, launcher } = this.options;
+        const workers = await launcher.listWorkers();
+        if (workers.length === 0)
+            return 0;
+        const sessions = await db.nativeGatewaySession.findMany({
+            select: { runId: true, status: true, deadlineAt: true, run: { select: { status: true } } },
+        });
+        // Docker labels carry the full run hash; Kubernetes label values carry its first 40 characters.
+        const labelled = sessions.map((s) => ({ hash: nativeRunLabel(s.runId), session: s }));
+        let removed = 0;
+        for (const worker of workers) {
+            const session = labelled.find((l) => l.hash.startsWith(worker.runHash))?.session;
+            const live = session &&
+                session.status === "active" &&
+                session.deadlineAt.getTime() > this.now() &&
+                (session.run.status === "pending" || session.run.status === "running");
+            if (live)
+                continue;
+            await launcher.removeByWorkerName(worker.name);
+            removed += 1;
+        }
+        return removed;
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * The worker contract over a child process's stdin/stdout, as newline-delimited
+ * JSON. The control plane writes the WorkerInput as the first line, then
+ * answers the worker's requests; the worker writes requests and reads answers.
+ * Both directions are capped at MAX_MESSAGE_BYTES per line. stderr is the
+ * worker's diagnostics only.
+ *
+ * Frames, worker → control:  { id, request }
+ * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message } }
+ *                            | { id, event }  (llm.stream events)  | { id, end: true }
+ */
+import type { Readable, Writable } from "node:stream";
+import type { NativeGateway, WorkerLauncher } from "./gateway.js";
+import type { GatewayTransport } from "./worker.js";
+/** Splits a byte stream into lines, refusing any line over the cap. */
+export declare function readLines(stream: Readable, onLine: (line: string) => void, onError: (err: Error) => void): void;
+/** The worker's side: requests out on `output`, answers in on `input`. */
+export declare function createStdioTransport(input: Readable, output: Writable): GatewayTransport;
+/** Serves one worker's requests from `gateway`, answering on `output`. */
+export declare function serveStdioWorker(input: Readable, output: Writable, gateway: NativeGateway): void;
+export interface WorkerProcessSpec {
+    command: string;
+    args: string[];
+    /** The worker's whole environment. Defaults to empty: it needs nothing from the server's. */
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** Launches the worker as a child process speaking this transport on its stdio. */
+export declare function createProcessLauncher(spec: WorkerProcessSpec): WorkerLauncher;