@wardby/cli 0.5.3 → 0.7.0

package/dist/native-worker/gateway-server.js

@@ -0,0 +1,412 @@
+/**
+ * The native sandbox gateway over HTTP (native sandbox phase 3): stateless per
+ * request. Each request is authenticated by the hash of its bearer capability,
+ * rebuilt from its run's gateway session (the snapshot pinned at launch), the
+ * run row, and the call ledger, and served by the same trusted code the
+ * in-process path uses — so any control-plane replica can serve any call, and a
+ * replica restart is only a retry for the worker.
+ *
+ * Authority stays here: a model call reserves its worst case against the
+ * session budget before the provider is called and settles at the provider's
+ * reported usage; the worker's own usage numbers are never read.
+ */
+import { createNativeRunTools, durableDelegate, failNativeRun, finishNativeRun, nativeRunIntegrations, recordNativeRunProgress, runDrivability, sandboxCapabilityHash, userToolSecretValues, } from "../core/runner.js";
+import { ReviewReadLedger } from "../core/review-reads.js";
+import { DELEGATE_TOOL_PREFIX } from "../core/tool-names.js";
+import { relayedOutputTokens } from "../providers/coding-proxy/interrupted.js";
+import { RoutingLlmProvider } from "../providers/llm/routing.js";
+import { isPrivilegedBridgeName } from "../sandbox/host-functions.js";
+import { forWorker, gatewayLog } from "./gateway.js";
+import { PrismaGatewayLedger } from "./ledger.js";
+import { GatewayError, GatewayRequestSchema, parseParams, } from "./protocol.js";
+/** Output tokens reserved for a model call that names no maxTokens (as the coding proxy does). */
+export const GATEWAY_DEFAULT_RESERVE_OUTPUT_TOKENS = 4_096;
+/** The most output tokens one call may reserve for. */
+export const GATEWAY_MAX_RESERVE_OUTPUT_TOKENS = 128_000;
+/** A replayable result is kept only up to this size; a larger one cannot be replayed on retry. */
+export const GATEWAY_MAX_REPLAY_BYTES = 256 * 1024;
+const ok = (result) => ({
+    kind: "json",
+    status: 200,
+    body: { ok: true, result: result ?? null },
+});
+const fail = (status, code, message, causeCode) => ({
+    kind: "json",
+    status,
+    body: { ok: false, error: { code, message, ...(causeCode ? { causeCode } : {}) } },
+});
+const STATUS_FOR = {
+    invalid_request: 400,
+    not_allowed: 403,
+    run_not_drivable: 409,
+    duplicate_call: 409,
+    budget_exhausted: 402,
+    not_ready: 503,
+    bridge_error: 200,
+    internal: 500,
+};
+/** Serves one gateway request. Never throws: every failure is a response. */
+export async function serveGatewayRequest(deps, authorization, body) {
+    // The capability once parsed, then every secret value of the rebuilt run: what a cause code and
+    // the log line are checked against. Unset (no bearer), no cause code is sent.
+    const scope = {};
+    try {
+        return await handle(deps, authorization, body, scope);
+    }
+    catch (err) {
+        return failureResponse(err, scope.secretValues);
+    }
+}
+/**
+ * Every secret value the rebuilt run can read (each user tool's readable or brokered values), and
+ * the request's own capability: what a cause code is checked against before it leaves the gateway.
+ */
+export function runSecretValues(ctx, capability) {
+    return async () => [
+        capability,
+        ...(await userToolSecretValues(ctx.tools, Object.keys(ctx.snapshot.input.userTools))),
+    ];
+}
+/**
+ * A failure as its response. Only a checked cause code leaves the gateway (workerGatewayError),
+ * never the rest of an unexpected error's message; the server's own log line is redacted by the
+ * same values.
+ */
+export async function failureResponse(err, secretValues) {
+    const sent = await forWorker(err, secretValues, "native gateway request failed");
+    return fail(STATUS_FOR[sent.code] ?? 500, sent.code, sent.message, sent.causeCode);
+}
+/** A model stream whose failure reaches the worker as the same checked error a JSON response carries. */
+export async function* checkedEvents(events, secretValues) {
+    try {
+        yield* events;
+    }
+    catch (err) {
+        throw await forWorker(err, secretValues, "native gateway model stream failed");
+    }
+}
+async function handle(deps, authorization, body, scope) {
+    const { db } = deps;
+    const ledger = new PrismaGatewayLedger(db);
+    const token = /^Bearer (\S+)$/.exec(authorization ?? "")?.[1];
+    if (!token)
+        return fail(401, "unauthorized", "A gateway capability is required.");
+    // Until the run's tools are rebuilt, the capability is the secret value an error is checked against.
+    scope.secretValues = async () => [token];
+    const session = await ledger.findSessionByCapabilityHash(sandboxCapabilityHash(token));
+    if (!session)
+        return fail(401, "unauthorized", "Unknown gateway capability.");
+    const parsed = GatewayRequestSchema.safeParse(body);
+    if (!parsed.success)
+        throw new GatewayError("invalid_request", parsed.error.issues[0]?.message ?? "invalid request");
+    const request = parsed.data;
+    if (request.runId !== session.runId)
+        throw new GatewayError("not_allowed", "request for another run");
+    let params;
+    try {
+        params = parseParams(request.method, request.params);
+    }
+    catch (err) {
+        throw new GatewayError("invalid_request", err instanceof Error ? err.message : String(err));
+    }
+    if (session.status !== "active" || Date.now() >= session.deadlineAt.getTime()) {
+        throw new GatewayError("run_not_drivable", "This run's gateway session has ended.");
+    }
+    // Nothing is served before the worker's network isolation is proven: until then its egress may
+    // not yet be limited to this gateway, so it must not receive tool code results, secrets, or data.
+    if (!session.networkReadyAt) {
+        throw new GatewayError("not_ready", "This run's network isolation is not proven yet; retry shortly.");
+    }
+    if ((await runDrivability(db, session.runId)) !== "drivable") {
+        throw new GatewayError("run_not_drivable", "This run is no longer running.");
+    }
+    const ctx = await rebuild(deps, session);
+    scope.secretValues = runSecretValues(ctx, token);
+    switch (request.method) {
+        case "llm.stream":
+            return {
+                kind: "stream",
+                status: 200,
+                events: checkedEvents(streamModel(ctx, ledger, request.callId, params), scope.secretValues),
+            };
+        case "llm.countTokens": {
+            const p = params;
+            return ok(await ctx.llm.countTokens(p.model, p.messages, p.tools));
+        }
+        case "builtin.call":
+            return ok(await builtin(ctx, ledger, request.callId, params, deps.pollWindowMs, scope.secretValues));
+        case "host.call":
+            return ok(await hostCall(ctx, ledger, request.callId, params));
+        case "progress": {
+            const p = params;
+            const totals = await ledger.totals(session.id);
+            await recordNativeRunProgress(db, session.runId, {
+                turns: p.turns,
+                usage: { tokensIn: totals.tokensIn, tokensOut: totals.tokensOut, costUsd: totals.costUsd },
+            });
+            return ok(null);
+        }
+        case "text":
+            // Live text is for an attached observer; a background sandbox run has none.
+            return ok(null);
+        case "finish":
+            return ok(await finish(ctx, ledger, request.callId, params));
+    }
+}
+async function rebuild(deps, session) {
+    const { db, providers } = deps;
+    const snapshot = session.snapshot;
+    const existingRun = await db.run.findUniqueOrThrow({ where: { id: session.runId } });
+    const { reviewHosts, repoAccess, issueTrackers } = nativeRunIntegrations(providers, db);
+    const loaded = snapshot.loaded;
+    const llm = loaded.pricing && providers.llm instanceof RoutingLlmProvider
+        ? providers.llm.forRun(loaded.pricing.entry)
+        : providers.llm;
+    const reviewReads = ReviewReadLedger.fromJSON(session.reviewReads);
+    return {
+        session,
+        snapshot,
+        llm,
+        reviewReads,
+        tools: createNativeRunTools({
+            runId: session.runId,
+            existingRun,
+            loaded,
+            providers,
+            db,
+            reviewHosts,
+            repoAccess,
+            issueTrackers,
+            reviewReads,
+        }),
+        finishContext: { runId: session.runId, db, providers, reviewHosts, repoAccess, issueTrackers },
+        delegation: {
+            runId: session.runId,
+            existingRun,
+            loaded,
+            providers,
+            db,
+            issueTrackers,
+            pollWindowMs: deps.pollWindowMs,
+        },
+    };
+}
+/** Exported for its unit test; the HTTP handler is its only production caller. */
+export async function* streamModel(ctx, ledger, callId, params) {
+    const req = params.request;
+    if (req.model !== ctx.snapshot.input.agent.model)
+        throw new GatewayError("not_allowed", "A run may only call its own model.");
+    const inputTokens = await ctx.llm.countTokens(req.model, req.messages, req.tools);
+    const outputTokens = Math.min(req.maxTokens ?? GATEWAY_DEFAULT_RESERVE_OUTPUT_TOKENS, GATEWAY_MAX_RESERVE_OUTPUT_TOKENS);
+    const reservationUsd = ctx.llm.priceUsd(req.model, { inputTokens, outputTokens });
+    const reserved = await ledger.reserve({ sessionId: ctx.session.id, callId, reservationUsd, now: new Date() });
+    if (reserved.outcome === "duplicate")
+        throw new GatewayError("duplicate_call", `callId "${callId}" was already used.`);
+    if (reserved.outcome === "inactive")
+        throw new GatewayError("run_not_drivable", "This run's gateway session has ended.");
+    if (reserved.outcome === "budget_exhausted") {
+        throw new GatewayError("budget_exhausted", "This run's budget cannot cover another model call.");
+    }
+    let settled = false;
+    let sawEvent = false;
+    // Set once the provider's response starts: it may bill hidden thinking or reasoning before any event.
+    let responseStarted = false;
+    // Generated output seen so far (text and tool calls), for an estimate if the stream is cut.
+    let streamedText = "";
+    try {
+        const hooks = {
+            onResponseStarted: () => {
+                responseStarted = true;
+            },
+        };
+        for await (const event of ctx.llm.stream(req, undefined, hooks)) {
+            sawEvent = true;
+            if (event.type === "text")
+                streamedText += event.delta;
+            if (event.type === "tool_call")
+                streamedText += event.name + event.argsJson;
+            if (event.type === "done") {
+                settled = true;
+                await ledger.complete(ctx.session.id, callId, {
+                    inputTokens: event.usage.inputTokens,
+                    outputTokens: event.usage.outputTokens,
+                    cachedInputTokens: event.usage.cachedInputTokens ?? 0,
+                    cacheWriteTokens: event.usage.cacheWriteTokens ?? 0,
+                    costUsd: event.usage.costUsd,
+                });
+            }
+            yield event;
+        }
+    }
+    catch (err) {
+        if (!settled) {
+            // Failed before the response started: the provider billed nothing. Once started: settle at an estimate.
+            if (sawEvent || responseStarted) {
+                // Bill the input and the output seen so far, never more than the hold. With no output seen
+                // (cut while thinking or reasoning), the run's median completed call, or none before the
+                // first one: as the coding proxy does. Estimating must never mask the stream error: on any
+                // failure, keep the full hold and rethrow the original.
+                try {
+                    const output = streamedText
+                        ? await streamedOutputTokens(ctx.llm, req.model, streamedText)
+                        : ((await ledger.medianOutputTokens(ctx.session.id)) ?? 0);
+                    const costUsd = Math.min(reservationUsd, ctx.llm.priceUsd(req.model, { inputTokens, outputTokens: output }));
+                    await ledger.markUncertain(ctx.session.id, callId, {
+                        inputTokens,
+                        outputTokens: output,
+                        cachedInputTokens: 0,
+                        cacheWriteTokens: 0,
+                        costUsd,
+                    });
+                }
+                catch {
+                    await ledger.markUncertain(ctx.session.id, callId).catch(() => undefined);
+                }
+            }
+            else
+                await ledger.release(ctx.session.id, callId);
+            settled = true;
+        }
+        throw err;
+    }
+    finally {
+        if (!settled) {
+            // The worker stopped reading (its own budget cutoff) before usage arrived: bill an estimate.
+            const output = await streamedOutputTokens(ctx.llm, req.model, streamedText);
+            await ledger.complete(ctx.session.id, callId, {
+                inputTokens,
+                outputTokens: output,
+                cachedInputTokens: 0,
+                cacheWriteTokens: 0,
+                costUsd: ctx.llm.priceUsd(req.model, { inputTokens, outputTokens: output }),
+            });
+        }
+    }
+}
+/** Output tokens of a cut stream's output: counted, else the deliberately high bytes / 3 estimate. */
+async function streamedOutputTokens(llm, model, streamed) {
+    if (!streamed)
+        return 0;
+    return llm
+        .countTokens(model, [{ role: "assistant", content: streamed }])
+        .catch(() => relayedOutputTokens(Buffer.byteLength(streamed)));
+}
+/** The review tools that record reads (repo_publish_review checks them). */
+const REVIEW_READ_TOOLS = new Set(["repo_pr_read", "repo_read_file"]);
+async function builtin(ctx, ledger, callId, params, pollWindowMs, secretValues) {
+    if (!ctx.snapshot.input.builtinTools.includes(params.name)) {
+        throw new GatewayError("not_allowed", `"${params.name}" is not a built-in tool of this run.`);
+    }
+    if (params.name.startsWith(DELEGATE_TOOL_PREFIX)) {
+        const outcome = await durableDelegate({ ...ctx.delegation, pollWindowMs, ledger, sessionId: ctx.session.id, secretValues }, callId, params.name, params.argsJson);
+        return "pending" in outcome ? { pending: true } : outcome.result;
+    }
+    const handler = ctx.tools.builtinHandler(params.name);
+    if (!handler)
+        throw new GatewayError("not_allowed", `"${params.name}" is not a built-in tool of this run.`);
+    return replayable(ledger, ctx.session.id, callId, "builtin.call", async () => {
+        const result = await handler(params.argsJson);
+        // Each request rebuilds the tools, so what a read recorded is saved for the publish request's check.
+        if (REVIEW_READ_TOOLS.has(params.name))
+            await ledger.mergeReviewReads(ctx.session.id, ctx.reviewReads);
+        return result;
+    });
+}
+/**
+ * Logged (at warn) in place of a user tool's console line when that tool's redaction list cannot
+ * be read: without the complete list the line cannot be shown to be free of its secret values, so
+ * none of it is logged. The tool's call still succeeds, as a console write does in-process.
+ */
+export const CONSOLE_WITHHELD_MESSAGE = "sandbox tool console line withheld: the tool's secret values could not be read";
+/** Serves one privileged bridge call for a worker (exported for tests). */
+export async function hostCall(ctx, ledger, callId, params) {
+    if (!isPrivilegedBridgeName(params.bridge))
+        throw new GatewayError("not_allowed", "unknown bridge");
+    if (!ctx.snapshot.input.userTools[params.tool]) {
+        throw new GatewayError("not_allowed", `"${params.tool}" is not a user tool of this run.`);
+    }
+    let redact;
+    if (params.bridge === "__bridge_console") {
+        // Fail closed: a console line is redacted by the tool's complete list or not logged at all.
+        const values = await ctx.tools.readableSecretValues(params.tool).then((v) => v, () => undefined);
+        if (!values) {
+            gatewayLog.warn({ tool: params.tool }, CONSOLE_WITHHELD_MESSAGE);
+            return null;
+        }
+        redact = values;
+    }
+    const host = ctx.tools.privilegedHostFor(params.tool, AbortSignal.timeout(30_000), redact);
+    if (!host)
+        throw new GatewayError("not_allowed", `"${params.tool}" is not a user tool of this run.`);
+    const bridge = host[params.bridge];
+    const run = async () => {
+        try {
+            return await bridge(params.argsJson);
+        }
+        catch (err) {
+            // What the tool sees, exactly as in-process (bridge.ts truncates the same way).
+            throw new GatewayError("bridge_error", err instanceof Error ? err.message.slice(0, 1024) : "Host function failed.");
+        }
+    };
+    // Console lines are not worth a ledger row, and a secret value must never be stored in one
+    // (a secrets.get is a side-effect-free read, so a retried callId simply reads it again).
+    if (params.bridge === "__bridge_console" || params.bridge === "__bridge_secretsGet")
+        return run();
+    return replayable(ledger, ctx.session.id, callId, "host.call", run);
+}
+/** Runs a one-shot call once per callId; a retry replays its recorded result. */
+async function replayable(ledger, sessionId, callId, method, run) {
+    const claimed = await ledger.claim(sessionId, callId, method);
+    if (claimed.outcome === "done") {
+        const stored = claimed.result;
+        if (stored.tooLarge)
+            throw new GatewayError("internal", "This call's result was too large to replay.");
+        if (stored.error)
+            throw new GatewayError(stored.error.code, stored.error.message);
+        return stored.value;
+    }
+    if (claimed.outcome === "in_flight")
+        throw new GatewayError("duplicate_call", `callId "${callId}" is still in flight.`);
+    try {
+        const value = await run();
+        const record = { value: value ?? null };
+        await ledger.recordResult(sessionId, callId, JSON.stringify(record).length <= GATEWAY_MAX_REPLAY_BYTES ? record : { tooLarge: true });
+        return value;
+    }
+    catch (err) {
+        if (err instanceof GatewayError && err.code === "bridge_error") {
+            await ledger.recordResult(sessionId, callId, { error: { code: err.code, message: err.message } });
+        }
+        throw err;
+    }
+}
+/** The worker's terminal call: the run's one terminal write (masked by finishNativeRun), then the session ends. */
+export async function finish(ctx, ledger, callId, params) {
+    const claimed = await ledger.claim(ctx.session.id, callId, "finish");
+    if (claimed.outcome !== "claimed")
+        return null;
+    const totals = await ledger.totals(ctx.session.id);
+    try {
+        await finishNativeRun(ctx.finishContext, ctx.snapshot.input.agent.model, {
+            status: params.status,
+            finalText: params.finalText,
+            turns: params.turns,
+            ...(params.error !== undefined ? { error: params.error } : {}),
+            usage: {
+                tokensIn: totals.tokensIn,
+                tokensOut: totals.tokensOut,
+                costUsd: totals.costUsd,
+                cachedInputTokens: totals.cachedInputTokens,
+                cacheWriteTokens: totals.cacheWriteTokens,
+            },
+        });
+    }
+    catch (err) {
+        await failNativeRun(ctx.finishContext, err);
+    }
+    finally {
+        await ledger.recordResult(ctx.session.id, callId, { value: null });
+        await ledger.endSession(ctx.session.id, "finished");
+    }
+    return null;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The trusted side of the native sandbox worker contract. `runSandboxedEngine`
+ * is an Engine in all but name: the runner hands it the same context it would
+ * hand NativeEngine, and it returns an EngineResult — but the turn loop runs
+ * in a worker, and this module serves the worker's calls from that context.
+ *
+ * Authority stays here (invariant 8 of the plan): model usage and cost are
+ * metered from what the provider streamed through this gateway, never taken
+ * from the worker; every call is validated against the protocol schemas and
+ * refused once the run is no longer drivable; built-in tools and privileged
+ * sandbox bridges are served only by name from the run's own surface.
+ */
+import type { EngineResult, EngineRunContext } from "../providers/engine/types.js";
+import type { LlmStreamEvent } from "../providers/llm/types.js";
+import pino from "pino";
+import { type PrivilegedHost } from "../sandbox/host-functions.js";
+import { logger } from "../core/logger.js";
+import { GatewayError, type WorkerInput } from "./protocol.js";
+/**
+ * The gateways' log. Both (in-process and HTTP) log an unexpected error here, as `native gateway
+ * request failed` (or `native gateway model stream failed`). Exported so tests can watch it.
+ */
+export declare const gatewayLog: pino.Logger<never, boolean>;
+/**
+ * Logs an unexpected error for the operator, redacted by exact value. A successfully read list is
+ * complete (its reader rejects when any secret's read fails), so an empty one means the run has no
+ * secret values and the message is logged as is. Fail closed: a thrown value that is not an Error
+ * (a string, an object: its text cannot be redacted reliably), or no list (unavailable or
+ * unreadable), logs only the error's name and declared code, never its message, stack or content.
+ */
+export declare function logUnexpectedError(log: Pick<typeof logger, "error">, err: unknown, values: readonly string[] | undefined, logMessage: string, fields?: Record<string, unknown>): void;
+/**
+ * The one way either gateway turns a failure into what the worker sees: an unexpected error is
+ * logged for the operator (redacted by the run's secret values) and becomes the checked
+ * GatewayError (workerGatewayError); the values are read once and serve both.
+ */
+export declare function forWorker(err: unknown, secretValues: (() => Promise<Iterable<string>>) | undefined, logMessage: string): Promise<GatewayError>;
+/** The trusted gateway as a transport sees it: untrusted requests in, results or GatewayErrors out. */
+export interface NativeGateway {
+    call(request: unknown): Promise<unknown>;
+    stream(request: unknown): AsyncIterable<LlmStreamEvent>;
+}
+/** Starts a worker for `input`, lets it call `gateway`, and resolves when it exits. */
+export interface WorkerLauncher {
+    run(input: WorkerInput, gateway: NativeGateway, signal: AbortSignal): Promise<{
+        exitCode: number | null;
+    }>;
+}
+/** Where a run stands, read live on every call. */
+export type RunDrivability = "drivable" | "cancelled" | "ended";
+/** Thrown when the worker stopped because the run was cancelled; the runner records `cancelled`. */
+export declare class SandboxRunCancelledError extends Error {
+}
+export interface SandboxedEngineOptions {
+    runId: string;
+    input: WorkerInput;
+    /** The context the runner would hand NativeEngine: the run-bound LLM, onText, and onProgress. */
+    ctx: Pick<EngineRunContext, "providers" | "onText" | "onProgress">;
+    builtinHandler: (name: string) => ((argsJson: string) => Promise<string>) | undefined;
+    privilegedHostFor: (tool: string, signal: AbortSignal) => PrivilegedHost | undefined;
+    /**
+     * Every secret value the user tool `tool` may read. A failure's cause code that overlaps any of
+     * the run's values is not sent to the worker; without this, no cause code is sent.
+     */
+    readableSecretValues?: (tool: string) => Promise<string[]>;
+    drivability: () => Promise<RunDrivability>;
+    launcher: WorkerLauncher;
+}
+/** Runs one native run's engine in a worker and returns its result with gateway-metered usage. */
+export declare function runSandboxedEngine(options: SandboxedEngineOptions): Promise<EngineResult>;