npm - castle-web-cli - Versions diffs - 0.4.83 → 0.4.84 - Mend

castle-web-cli 0.4.83 → 0.4.84

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/dist/agent-failures.d.ts +17 -0
package/dist/agent-failures.js +151 -0
package/dist/agent.d.ts +26 -0
package/dist/agent.js +317 -74
package/dist/native/loop.js +35 -0
package/dist/native/openrouter.d.ts +7 -0
package/dist/native/openrouter.js +25 -1
package/dist/native/types.d.ts +2 -0
package/dist/native/types.js +0 -38
package/dist/openrouter-catalog.d.ts +28 -0
package/dist/openrouter-catalog.js +299 -0
package/dist/shell/assets/{index-C9Zhmien.js → index-BOgm5T3W.js} +60 -58
package/dist/shell/assets/{index-BMkQt27u.css → index-DonnH--m.css} +1 -1
package/dist/shell/index.html +2 -2
package/package.json +1 -1

package/dist/native/openrouter.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { type AgentFailure } from "../agent-failures.js";
 import type { NativeUsage } from "./types.js";
 export interface ORToolCall {
     id: string;
@@ -55,5 +56,11 @@ export interface StreamChatResult {
     reasoningTokens?: number;
     crashed: boolean;
     error?: string;
+    failure?: AgentFailure;
+}
+export declare class OpenrouterHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
 }
 export declare function streamChatCompletion(opts: StreamChatOpts): Promise<StreamChatResult>;

package/dist/native/openrouter.js CHANGED Viewed

@@ -13,6 +13,7 @@
 // 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).
+import { failureForStatus } from "../agent-failures.js";
 // 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
@@ -48,6 +49,22 @@ function backoffMs(attempt) {
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;
 }
+// A non-retryable HTTP error from OpenRouter, carrying the status as a NUMBER
+// rather than only baked into a message. This path knows the status
+// first-hand, so classification upstream is a lookup instead of a regex over
+// our own error prose (the claude-CLI path has no such luxury -- see
+// classifyProviderError). `message` keeps the old "HTTP <status>: <body>"
+// wording so logs and any string-matching callers read the same as before.
+export class OpenrouterHttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}${body ? `: ${body.slice(0, 300)}` : ""}`);
+        this.status = status;
+        this.body = body;
+        this.name = "OpenrouterHttpError";
+    }
+}
 async function safeReadText(res) {
     try {
         return (await res.text()).trim();
@@ -93,7 +110,7 @@ async function connectWithRetry(init, opts) {
             continue;
         }
         const bodyText = await safeReadText(res);
-        throw new Error(`HTTP ${res.status}${bodyText ? `: ${bodyText.slice(0, 300)}` : ""}`);
+        throw new OpenrouterHttpError(res.status, bodyText);
     }
     // Unreachable (the loop above always returns or throws), but keeps the
     // return type honest for TS.
@@ -242,6 +259,13 @@ export async function streamChatCompletion(opts) {
             message: null,
             crashed: false,
             error: `could not run openrouter: ${err instanceof Error ? err.message : String(err)}`,
+            // Only an HTTP error carries a status worth classifying. A network-level
+            // failure (DNS, refused, reset) stays unlabelled so it keeps landing in
+            // the pre-existing "spawn" bucket via the "could not run" prefix --
+            // that's already the right read: the request never got going.
+            failure: err instanceof OpenrouterHttpError
+                ? failureForStatus(err.status, err.body)
+                : undefined,
         };
     }
     if (!res.body) {

package/dist/native/types.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import type { AgentFailure } from "../agent-failures.js";
 import type { PlaytestExecutor } from "./playtest.js";
 import type { ORReasoningEffort, ORRoutingMode } from "./openrouter.js";
 export type NativeRole = "router" | "task";
@@ -37,6 +38,7 @@ export interface NativeRunOpts {
 export interface NativeRunResult {
     text: string;
     error?: string;
+    failure?: AgentFailure;
     usage?: NativeUsage;
     playtestFrames?: string[];
     crashed?: boolean;

package/dist/native/types.js CHANGED Viewed

@@ -1,41 +1,3 @@
 // Shapes for the native (in-process, OpenRouter-backed) agent backend --
 // see the plan at native_openrouter_agent_loop_fd7d9b3e.plan.md, "Path B".
-//
-// These MIRROR the non-exported CliRunOpts / CliRunResult / CliUsage
-// interfaces in cli/src/agent.ts (see runAgentCli there), which normalize
-// the headless `claude` / `cursor-agent` CLI backends into onDelta/onActivity/
-// onThinking hooks plus a { finalText, error, usage, crashed } result. This
-// file is a SEPARATE set of types for now (new-files-only
-// constraint -- agent.ts is being edited concurrently by a sibling change),
-// not a re-export, so field names differ in a few places. When the native
-// backend is wired into agent.ts, expect one of these two outcomes:
-//
-//   1. CliRunOpts/CliRunResult are widened to a shape both backends share
-//      (command/args/parser and children become backend-specific extras), or
-//   2. the call site maps between the two shapes directly:
-//        - NativeRunResult.text            -> CliRunResult.finalText
-//        - NativeRunResult.error/usage/crashed -> same names
-//        - CliRunResult.ok                 <- derived as
-//              `!result.error && !result.crashed` (no native equivalent of
-//              a process exit code -- "ok" always follows from the other
-//              two fields)
-//        - CliRunOpts.children (Set<ChildProcess>) has no native
-//          equivalent -- runAgentNative takes `signal` (AbortSignal)
-//          instead, so a caller cancels a run the same way it would abort
-//          any other fetch-based operation. The wiring step would create one
-//          AbortController per run and adapt it to whatever cancellation
-//          registry agent.ts uses for CLI children.
-//        - CliRunOpts.command/args/parser have no native equivalent --
-//          replaced by `model` (the free-form OpenRouter model id) and
-//          `apiKey`.
-//        - CliRunOpts.logPath maps to NativeRunOpts.logPath: same file
-//          locations (tasks/<id>/log.jsonl, .castle/agent/router-log.jsonl),
-//          same append-JSONL discipline, but the native lines are STRUCTURED
-//          run events (init/assistant/tool_result/eviction/retry/result --
-//          see createRunLogger in loop.ts) rather than raw CLI stream-json.
-//
-// Turns stay stateless exactly as they are today: the caller rebuilds one big
-// prompt string per turn (buildRouterPrompt/buildTaskPrompt) and passes it as
-// `prompt`; runAgentNative holds the resulting message array only for the
-// lifetime of that one call.
 export {};

package/dist/openrouter-catalog.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+export interface CatalogEntry {
+    id: string;
+    supportedParameters: string[];
+    reasoning: unknown;
+}
+export type ModelCheck = {
+    status: "ok";
+} | {
+    status: "unknown-model";
+    suggestions: string[];
+} | {
+    status: "no-tools";
+} | {
+    status: "unavailable";
+};
+export declare function primeOpenrouterCatalog(): void;
+export type KeyCheck = {
+    status: "ok";
+} | {
+    status: "bad-key";
+} | {
+    status: "no-credits";
+} | {
+    status: "unavailable";
+};
+export declare function checkOpenrouterKey(apiKey: string): Promise<KeyCheck>;
+export declare function checkOpenrouterModel(slug: string): Promise<ModelCheck>;
+export declare function openrouterCatalogEntry(slug: string): Promise<CatalogEntry | null>;

package/dist/openrouter-catalog.js ADDED Viewed

@@ -0,0 +1,299 @@
+// Asks OpenRouter about our own configuration BEFORE a run starts: is this
+// model slug real, can it tool-call, and is this API key usable. Both answers
+// come from cheap metadata endpoints, and both turn an expensive runtime
+// failure into an instant one.
+//
+// - https://openrouter.ai/api/v1/models is public (no auth) and every entry
+//   carries `supported_parameters`, which contains "tools" exactly when the
+//   model can tool-call. That decides two failures a run would otherwise
+//   discover the hard way: a slug that doesn't exist, and a slug that exists
+//   but can never do agent work (image/audio/embedding models share the
+//   catalog).
+// - https://openrouter.ai/api/v1/key validates the key in ~0.2s. Worth the
+//   call: measured against the real binary, a bad key makes the claude CLI
+//   retry internally for OVER TWO MINUTES before it surfaces anything.
+//
+// This module NEVER blocks a run on the network, and never turns "we don't
+// know" into "it's bad". Every failure path resolves to "unavailable", which
+// callers treat as "allow" -- OpenRouter ships models faster than any cache
+// refreshes, and a free-form field that rejects a brand-new model would be
+// worse than one that validates nothing.
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// Overridable for the QA battery, which runs fake endpoints. Without the cache
+// override the battery would read/write the developer's real ~/.castle and its
+// fall-open assertions would pass spuriously off a warm real catalog.
+function modelsUrl() {
+    return (process.env.CASTLE_OPENROUTER_MODELS_URL ??
+        "https://openrouter.ai/api/v1/models");
+}
+function keyUrl() {
+    return process.env.CASTLE_OPENROUTER_KEY_URL ?? "https://openrouter.ai/api/v1/key";
+}
+function cachePath() {
+    return (process.env.CASTLE_OPENROUTER_CATALOG_CACHE ??
+        path.join(os.homedir(), ".castle", "openrouter-models.json"));
+}
+const FETCH_TIMEOUT_MS = 3_000;
+// Past this the cache is refreshed, but the STALE copy is still served while
+// that happens (see loadCatalog) -- staleness costs a wrong verdict on a model
+// that changed in the last day, which is cheap; a blocking fetch is not.
+const FRESH_MS = 24 * 60 * 60 * 1000;
+const MAX_SUGGESTIONS = 3;
+// Levenshtein ceiling for a "did you mean". Past ~4 edits the suggestion stops
+// being a plausible typo and starts being noise.
+const MAX_SUGGESTION_DISTANCE = 4;
+function hasTools(entry) {
+    return entry.supportedParameters.includes("tools");
+}
+let memo = null;
+// Single-flight: tasks spawn at max concurrency, and N cold pre-flights must
+// not become N fetches of a ~500KB payload.
+let inflight = null;
+function isFresh(file) {
+    const age = Date.now() - file.fetchedAt;
+    // A negative age means the clock moved backwards (or the file was hand-
+    // edited); treat it as stale rather than trusting it forever.
+    return age >= 0 && age < FRESH_MS;
+}
+function parseCatalog(body) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        return null;
+    const models = [];
+    for (const raw of data) {
+        if (typeof raw?.id !== "string")
+            continue;
+        const params = Array.isArray(raw.supported_parameters)
+            ? raw.supported_parameters.filter((p) => typeof p === "string")
+            : [];
+        models.push({
+            id: raw.id,
+            supportedParameters: params,
+            reasoning: raw.reasoning ?? null,
+        });
+    }
+    // An empty list means the endpoint answered with something we don't
+    // understand -- treat it as a failure rather than caching "no models exist",
+    // which would reject every slug.
+    return models.length > 0 ? models : null;
+}
+async function fetchCatalog() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(modelsUrl(), { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const models = parseCatalog(await res.json());
+        if (!models)
+            return null;
+        return { fetchedAt: Date.now(), models };
+    }
+    catch {
+        // Offline, DNS failure, timeout, malformed JSON -- all the same to us.
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(), "utf8"));
+        if (!Array.isArray(parsed?.models) || typeof parsed?.fetchedAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(file) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+        fs.writeFileSync(cachePath(), JSON.stringify(file));
+    }
+    catch {
+        // A cache we can't persist just means we refetch next boot. Not fatal.
+    }
+}
+async function refresh() {
+    inflight ??= fetchCatalog().finally(() => {
+        inflight = null;
+    });
+    const fetched = await inflight;
+    if (fetched) {
+        memo = fetched;
+        writeCache(fetched);
+    }
+    return fetched;
+}
+// Stale-while-revalidate: a usable copy (however old) is returned immediately
+// and a refresh runs in the background. Only a cold start with no cache at all
+// awaits the network, and priming at serve boot (primeOpenrouterCatalog) means
+// even that lands off the critical path in practice.
+async function loadCatalog() {
+    memo ??= readCache();
+    if (memo) {
+        if (!isFresh(memo))
+            void refresh();
+        return memo;
+    }
+    return refresh();
+}
+// Called at serve boot so the first pre-flight never pays for the fetch. Safe
+// to ignore the result -- it only warms memo/disk.
+export function primeOpenrouterCatalog() {
+    void loadCatalog();
+}
+function levenshtein(a, b) {
+    // Single-row DP -- the id list is ~350 entries and this runs only on a miss.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const curr = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[b.length];
+}
+function suggestionsFor(slug, models) {
+    const scored = [];
+    for (const m of models) {
+        // A substring match ranks above any edit distance: someone who typed
+        // "gpt-5.6-terra" without the vendor prefix wants openai/gpt-5.6-terra,
+        // which is 7 edits away and would otherwise never surface.
+        const score = m.id.includes(slug) ? 0 : levenshtein(slug, m.id);
+        if (score <= MAX_SUGGESTION_DISTANCE)
+            scored.push({ id: m.id, score });
+    }
+    scored.sort((x, y) => x.score - y.score || x.id.localeCompare(y.id));
+    if (scored.length === 0)
+        return [];
+    // Keep only what's close to the BEST match, not everything under the ceiling.
+    // Model names in one family sit within a few edits of each other, so a
+    // 1-edit typo on gpt-5.6-terra also "matches" gpt-5.6-luna at 4 -- padding a
+    // confident answer with two wrong ones reads as a guess.
+    const cutoff = scored[0].score + 1;
+    return scored
+        .filter((s) => s.score <= cutoff)
+        .slice(0, MAX_SUGGESTIONS)
+        .map((s) => s.id);
+}
+// OpenRouter accepts routing suffixes that are NOT catalog ids of their own --
+// ":nitro" (throughput) and ":floor" (price) route to a base model. Confirmed
+// against the live catalog: ":free" and ":thinking" ARE listed as distinct ids,
+// ":nitro"/":floor" are not. So an exact miss retries the base slug, or we'd
+// reject "anthropic/claude-opus-4.8:nitro" as unknown when it's perfectly valid.
+function findEntry(slug, models) {
+    const exact = models.find((m) => m.id === slug);
+    if (exact)
+        return exact;
+    const colon = slug.lastIndexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const base = slug.slice(0, colon);
+    return models.find((m) => m.id === base);
+}
+// Verdicts are cached in memory only, never on disk: the cache key is derived
+// from a live credential, and a process-lifetime cache is enough to keep this
+// off the hot path (one check per serve boot per key). Short TTL so revoking a
+// key or topping up credits takes effect without a restart.
+const KEY_CHECK_TTL_MS = 5 * 60 * 1000;
+const keyChecks = new Map();
+const keyInflight = new Map();
+// Cache/log handle for a key that is never itself stored or printed. Not a
+// security boundary (an in-process Map already holds the real key upstream) --
+// it just keeps credentials out of anything that might get dumped.
+function keyHandle(apiKey) {
+    let h = 0;
+    for (let i = 0; i < apiKey.length; i++)
+        h = (Math.imul(h, 31) + apiKey.charCodeAt(i)) | 0;
+    return `k${(h >>> 0).toString(36)}`;
+}
+async function fetchKeyCheck(apiKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(keyUrl(), {
+            headers: { authorization: `Bearer ${apiKey}` },
+            signal: controller.signal,
+        });
+        // Only explicit status codes are trusted. The endpoint also reports
+        // `limit`/`usage`, and inferring exhaustion from that arithmetic is
+        // tempting -- but a wrong inference BLOCKS a working setup, which is the
+        // one outcome this whole module is built to avoid. An out-of-credit key is
+        // still caught at run time by the classifier; a false "no credits" here
+        // would be unrecoverable from the UI.
+        if (res.status === 401 || res.status === 403)
+            return { status: "bad-key" };
+        if (res.status === 402)
+            return { status: "no-credits" };
+        if (!res.ok)
+            return { status: "unavailable" };
+        return { status: "ok" };
+    }
+    catch {
+        return { status: "unavailable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function checkOpenrouterKey(apiKey) {
+    if (!apiKey)
+        return { status: "bad-key" };
+    const handle = keyHandle(apiKey);
+    const cached = keyChecks.get(handle);
+    if (cached && Date.now() - cached.at < KEY_CHECK_TTL_MS)
+        return cached.result;
+    // Single-flight per key: tasks spawn concurrently and must not each probe.
+    const existing = keyInflight.get(handle);
+    if (existing)
+        return existing;
+    const p = fetchKeyCheck(apiKey)
+        .then((result) => {
+        // An "unavailable" verdict is deliberately NOT cached -- it means the
+        // network hiccuped, and caching it would suppress validation for the
+        // next 5 minutes over one dropped request.
+        if (result.status !== "unavailable") {
+            keyChecks.set(handle, { at: Date.now(), result });
+        }
+        return result;
+    })
+        .finally(() => keyInflight.delete(handle));
+    keyInflight.set(handle, p);
+    return p;
+}
+export async function checkOpenrouterModel(slug) {
+    const catalog = await loadCatalog();
+    if (!catalog)
+        return { status: "unavailable" };
+    // Catalog ids are all lowercase (verified against the live endpoint), so a
+    // case-only difference is a typo we can match through rather than reject.
+    const normalized = slug.trim().toLowerCase();
+    const entry = findEntry(normalized, catalog.models);
+    if (!entry) {
+        return {
+            status: "unknown-model",
+            suggestions: suggestionsFor(normalized, catalog.models),
+        };
+    }
+    return hasTools(entry) ? { status: "ok" } : { status: "no-tools" };
+}
+// The single catalog lookup for the rest of the CLI -- the settings popover's
+// capabilities endpoint (fetchModelCaps in agent.ts) reads reasoning support
+// from here rather than fetching /models a second time. Resolves null when the
+// slug is unknown OR the catalog is unreachable; callers that need to tell
+// those apart use checkOpenrouterModel.
+export async function openrouterCatalogEntry(slug) {
+    const catalog = await loadCatalog();
+    if (!catalog)
+        return null;
+    return findEntry(slug.trim().toLowerCase(), catalog.models) ?? null;
+}