castle-web-cli 0.4.78 → 0.4.80

package/dist/native/openrouter.d.ts

@@ -0,0 +1,55 @@
+import type { NativeUsage } from "./types.js";
+export interface ORToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export type ORContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+export interface ORMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null | ORContentPart[];
+    tool_calls?: ORToolCall[];
+    tool_call_id?: string;
+}
+export interface ORAssistantMessage {
+    role: "assistant";
+    content: string;
+    tool_calls?: ORToolCall[];
+}
+export type ORReasoningEffort = "low" | "medium";
+export interface StreamChatOpts {
+    apiKey: string;
+    model: string;
+    messages: ORMessage[];
+    tools?: unknown[];
+    reasoningEffort?: ORReasoningEffort;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    onDelta?: (delta: string) => void;
+    onThinking?: (delta: string) => void;
+    onRetry?: (info: {
+        attempt: number;
+        status?: number;
+        delayMs: number;
+    }) => void;
+    maxRetries?: number;
+}
+export interface StreamChatResult {
+    message: ORAssistantMessage | null;
+    usage?: NativeUsage;
+    reasoningTokens?: number;
+    crashed: boolean;
+    error?: string;
+}
+export declare function streamChatCompletion(opts: StreamChatOpts): Promise<StreamChatResult>;

package/dist/native/openrouter.js

@@ -0,0 +1,354 @@
+// Streaming client for OpenRouter's OpenAI-shaped chat completions endpoint.
+// One call = one assistant turn: POST with stream:true, manually parse the
+// SSE body (no SDK), and resolve once the stream reports a finish_reason (or
+// dies trying). See native/loop.ts for the multi-turn tool loop built on top
+// of this, and native/types.ts for how the result maps back to agent.ts's
+// CliRunResult shape.
+//
+// Retry policy: only the CONNECT step (the initial fetch -- before any bytes
+// of the response body have been read) retries on 429/5xx, jittered, up to a
+// small cap. Once streaming has started, a dropped connection is a crash
+// (surfaced via `crashed: true`), not something this client silently retries
+// mid-turn -- replaying a partial generation would require re-deriving what
+// the model already said, which the caller (native/loop.ts) is better placed
+// to decide (or simply not do, matching today's crash-then-relaunch policy at
+// the task-attempt level).
+// Overridable via CASTLE_OPENROUTER_URL so the QA harness (see
+// scripts/tests/agent-qa/native/fake-openrouter.mjs) can point this client at
+// a local fake server instead of the real API -- read per-call (not hoisted
+// to a module-level const) so a test process that imports this module once
+// can still point successive runAgentNative calls at different fake servers.
+function openrouterUrl() {
+    return process.env.CASTLE_OPENROUTER_URL || "https://openrouter.ai/api/v1/chat/completions";
+}
+const DEFAULT_MAX_RETRIES = 2; // -> 3 total connect attempts
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_MS = 4_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function backoffMs(attempt) {
+    const exp = Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_MAX_MS);
+    return exp + Math.random() * 250;
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+async function safeReadText(res) {
+    try {
+        return (await res.text()).trim();
+    }
+    catch {
+        return "";
+    }
+}
+// Connect with retry-on-429/5xx. Resolves to an ok Response or throws. A
+// non-retryable HTTP error (4xx other than 429) throws immediately with the
+// response body folded into the message, same as a network-level failure --
+// both are "the request never got a stream going" and get the same
+// "could not run openrouter: ..." wrapper one level up (see loop.ts), which
+// mirrors the wording classifyRouterFailure's "spawn" bucket in agent.ts
+// looks for (agent.ts: `error?.startsWith("could not run")`).
+async function connectWithRetry(init, opts) {
+    const maxAttempts = 1 + (opts.maxRetries ?? DEFAULT_MAX_RETRIES);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        if (opts.signal?.aborted) {
+            throw new DOMException("aborted", "AbortError");
+        }
+        let res;
+        try {
+            res = await fetch(openrouterUrl(), init);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError")
+                throw err;
+            if (attempt < maxAttempts - 1) {
+                const delayMs = backoffMs(attempt);
+                opts.onRetry?.({ attempt: attempt + 1, delayMs });
+                await sleep(delayMs);
+                continue;
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+        if (res.ok)
+            return res;
+        if (isRetryableStatus(res.status) && attempt < maxAttempts - 1) {
+            const delayMs = backoffMs(attempt);
+            opts.onRetry?.({ attempt: attempt + 1, status: res.status, delayMs });
+            await sleep(delayMs);
+            continue;
+        }
+        const bodyText = await safeReadText(res);
+        throw new Error(`HTTP ${res.status}${bodyText ? `: ${bodyText.slice(0, 300)}` : ""}`);
+    }
+    // Unreachable (the loop above always returns or throws), but keeps the
+    // return type honest for TS.
+    throw new Error("connectWithRetry: exhausted attempts without resolving");
+}
+// Yields one JSON payload per complete SSE event ("data: ..." line(s) up to a
+// blank line), skipping ":"-prefixed comment/keep-alive lines (OpenRouter
+// sends these periodically while a slow upstream provider is thinking) and
+// terminating on the literal "[DONE]" sentinel.
+async function* iterateSseData(body) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let dataLines = [];
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let nl = buffer.indexOf("\n");
+            while (nl >= 0) {
+                const rawLine = buffer.slice(0, nl);
+                buffer = buffer.slice(nl + 1);
+                nl = buffer.indexOf("\n");
+                const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+                if (line === "") {
+                    if (dataLines.length > 0) {
+                        const payload = dataLines.join("\n");
+                        dataLines = [];
+                        if (payload === "[DONE]")
+                            return;
+                        yield payload;
+                    }
+                }
+                else if (line.startsWith(":")) {
+                    // comment / keep-alive -- ignore
+                }
+                else if (line.startsWith("data:")) {
+                    dataLines.push(line.slice(5).replace(/^ /, ""));
+                }
+            }
+        }
+        if (dataLines.length > 0) {
+            const payload = dataLines.join("\n");
+            if (payload !== "[DONE]")
+                yield payload;
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* already released */
+        }
+    }
+}
+function mapUsage(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const src = raw;
+    const usage = {};
+    if (typeof src.prompt_tokens === "number")
+        usage.input_tokens = src.prompt_tokens;
+    if (typeof src.completion_tokens === "number")
+        usage.output_tokens = src.completion_tokens;
+    const promptDetails = src.prompt_tokens_details;
+    if (promptDetails && typeof promptDetails === "object") {
+        const d = promptDetails;
+        if (typeof d.cached_tokens === "number")
+            usage.cache_read_input_tokens = d.cached_tokens;
+        if (typeof d.cache_write_tokens === "number")
+            usage.cache_creation_input_tokens = d.cache_write_tokens;
+    }
+    // OpenAI-shaped completion_tokens_details.reasoning_tokens -- the count of
+    // hidden "thinking" tokens billed as output for this call. This is the
+    // number that would have caught the incident motivating this file's
+    // per-iteration usage logging (loop.ts): ~60K reasoning tokens on one
+    // multimodal iteration, invisible until forensically summed after the
+    // fact because usage was only ever logged once per whole run.
+    let reasoningTokens;
+    const completionDetails = src.completion_tokens_details;
+    if (completionDetails && typeof completionDetails === "object") {
+        const d = completionDetails;
+        if (typeof d.reasoning_tokens === "number")
+            reasoningTokens = d.reasoning_tokens;
+    }
+    return {
+        usage: Object.keys(usage).length > 0 ? usage : undefined,
+        reasoningTokens,
+    };
+}
+function finalizeToolCalls(pending) {
+    if (pending.size === 0)
+        return undefined;
+    const indices = [...pending.keys()].sort((a, b) => a - b);
+    return indices.map((i) => {
+        const p = pending.get(i);
+        return {
+            id: p.id ?? `call_${i}`,
+            type: "function",
+            function: { name: p.name ?? "", arguments: p.arguments },
+        };
+    });
+}
+export async function streamChatCompletion(opts) {
+    const body = {
+        model: opts.model,
+        messages: opts.messages,
+        stream: true,
+        // Deprecated on OpenRouter's side (usage is always included now) but
+        // harmless to send -- keeps this client correct against providers that
+        // still gate usage on it.
+        stream_options: { include_usage: true },
+        ...(opts.tools && opts.tools.length > 0 ? { tools: opts.tools } : {}),
+        // See ORReasoningEffort / StreamChatOpts.reasoningEffort above for the
+        // doc reference and the graceful-degradation guarantee this relies on.
+        ...(opts.reasoningEffort ? { reasoning: { effort: opts.reasoningEffort } } : {}),
+        // See StreamChatOpts.maxTokens above -- bounds one completion call's
+        // total output (content + tool-call arguments + reasoning).
+        ...(opts.maxTokens !== undefined ? { max_tokens: opts.maxTokens } : {}),
+    };
+    let res;
+    try {
+        res = await connectWithRetry({
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${opts.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: opts.signal,
+        }, { signal: opts.signal, maxRetries: opts.maxRetries, onRetry: opts.onRetry });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            return { message: null, crashed: false };
+        }
+        return {
+            message: null,
+            crashed: false,
+            error: `could not run openrouter: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!res.body) {
+        return { message: null, crashed: false, error: "could not run openrouter: empty response body" };
+    }
+    let content = "";
+    // Observed live (2026-07): some providers' MID-stream usage passthrough is
+    // junk (constant cache_read=128 / cache_created=0 on every event) while the
+    // FINAL usage chunk -- the one OpenRouter emits at/after finish_reason --
+    // carries the real cumulative numbers. So usage from a chunk that arrives
+    // once finish_reason is known is authoritative (finalUsage); earlier
+    // mid-stream usage is kept only as a fallback for streams that die before
+    // reaching that point.
+    let usage;
+    let finalUsage;
+    // Tracked in parallel with usage/finalUsage above, same final-over-mid-
+    // stream preference (see mapUsage's comment for why this is a real,
+    // observed-live distinction and not theoretical).
+    let reasoningTokens;
+    let finalReasoningTokens;
+    let finishReason = null;
+    let midStreamError;
+    const pendingToolCalls = new Map();
+    try {
+        for await (const raw of iterateSseData(res.body)) {
+            let obj;
+            try {
+                obj = JSON.parse(raw);
+            }
+            catch {
+                continue; // non-JSON keep-alive noise -- ignore
+            }
+            const choices = obj.choices;
+            const choice = choices?.[0];
+            if (obj.usage) {
+                const mapped = mapUsage(obj.usage);
+                if (mapped.usage)
+                    usage = mapped.usage;
+                if (mapped.reasoningTokens !== undefined)
+                    reasoningTokens = mapped.reasoningTokens;
+                // Final if finish_reason already streamed OR rides on this very
+                // chunk (providers differ on whether usage shares the finish chunk
+                // or follows it as a choices-less trailer).
+                if (finishReason !== null || (typeof choice?.finish_reason === "string" && choice.finish_reason)) {
+                    if (mapped.usage)
+                        finalUsage = mapped.usage;
+                    if (mapped.reasoningTokens !== undefined)
+                        finalReasoningTokens = mapped.reasoningTokens;
+                }
+            }
+            if (!choice)
+                continue;
+            const delta = choice.delta ?? {};
+            if (typeof delta.content === "string" && delta.content) {
+                content += delta.content;
+                opts.onDelta?.(delta.content);
+            }
+            if (typeof delta.reasoning === "string" && delta.reasoning) {
+                opts.onThinking?.(delta.reasoning);
+            }
+            const toolCallDeltas = delta.tool_calls;
+            if (Array.isArray(toolCallDeltas)) {
+                for (const tc of toolCallDeltas) {
+                    const index = typeof tc.index === "number" ? tc.index : 0;
+                    const entry = pendingToolCalls.get(index) ?? { arguments: "" };
+                    if (typeof tc.id === "string" && tc.id)
+                        entry.id = tc.id;
+                    const fn = tc.function;
+                    if (fn) {
+                        if (typeof fn.name === "string" && fn.name)
+                            entry.name = fn.name;
+                        if (typeof fn.arguments === "string")
+                            entry.arguments += fn.arguments;
+                    }
+                    pendingToolCalls.set(index, entry);
+                }
+            }
+            if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+                finishReason = choice.finish_reason;
+                if (finishReason === "error") {
+                    const errObj = obj.error;
+                    midStreamError =
+                        (typeof errObj?.message === "string" && errObj.message) ||
+                            "openrouter reported a mid-stream error";
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            return { message: null, usage, reasoningTokens, crashed: false };
+        }
+        // The connection died while we were mid-read -- a genuine crash, not a
+        // clean finish_reason termination.
+        return {
+            message: null,
+            usage,
+            reasoningTokens,
+            crashed: true,
+            error: `openrouter stream failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (finishReason === null) {
+        // Stream closed (or hit [DONE]) without ever reporting a finish_reason --
+        // treat the same as a mid-read failure.
+        return {
+            message: null,
+            usage,
+            reasoningTokens,
+            crashed: true,
+            error: "openrouter stream ended without a finish reason",
+        };
+    }
+    if (finishReason === "error") {
+        return {
+            message: null,
+            usage: finalUsage ?? usage,
+            reasoningTokens: finalReasoningTokens ?? reasoningTokens,
+            crashed: false,
+            error: midStreamError,
+        };
+    }
+    return {
+        message: { role: "assistant", content, tool_calls: finalizeToolCalls(pendingToolCalls) },
+        usage: finalUsage ?? usage,
+        reasoningTokens: finalReasoningTokens ?? reasoningTokens,
+        crashed: false,
+    };
+}

package/dist/native/playtest-browser.d.ts

@@ -0,0 +1,34 @@
+import type { Browser } from "playwright-core";
+import type { PlaytestInstallEvent } from "./playtest.js";
+export declare const INSTALL_START_LABEL = "Downloading playtest browser (one-time, ~250MB)\u2026";
+export declare const INSTALL_WAIT_LABEL = "Waiting for browser download (shared)\u2026";
+export interface PlaywrightChromiumLike {
+    executablePath(): string;
+    launch(options?: {
+        args?: string[];
+    }): Promise<Browser>;
+}
+export interface PlaywrightModuleLike {
+    chromium: PlaywrightChromiumLike;
+}
+export interface PlaytestBrowserSeams {
+    loadPlaywright?: () => Promise<PlaywrightModuleLike>;
+    runInstall?: (onLine: (line: string) => void) => Promise<void>;
+}
+export interface BrowserInstallHooks {
+    onProgress?: (label: string) => void;
+    onInstallEvent?: (evt: PlaytestInstallEvent) => void;
+}
+export interface PlaytestBrowserManager {
+    withBrowser<T>(fn: (browser: Browser) => Promise<T>, hooks?: BrowserInstallHooks): Promise<{
+        ok: true;
+        value: T;
+        installedMs?: number;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    prewarm(): void;
+    shutdown(): Promise<void>;
+}
+export declare function createPlaytestBrowserManager(seams?: PlaytestBrowserSeams): PlaytestBrowserManager;