castle-web-cli 0.4.82 → 0.4.84

package/dist/ide.js

@@ -268,6 +268,136 @@ function handleFilesWrite(deckDir, req, res) {
         }
     })();
 }
+// Add `<rel>/**` to the deck's editor.visiblePaths so files created in a
+// newly-made folder show in the curated Files tree. Only touches a deck that is
+// ALREADY curated (non-empty visiblePaths) -- when visiblePaths is empty
+// everything is visible, and adding a glob would wrongly start hiding things.
+// No-op if an existing glob already covers the folder. Returns whether it wrote.
+function ensureVisiblePath(deckDir, rel) {
+    const file = path.join(deckDir, "castle.json");
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return false; // no castle.json yet (deck never saved) -> treat as not curated
+    }
+    const visible = data.editor && Array.isArray(data.editor.visiblePaths)
+        ? data.editor.visiblePaths.filter((v) => typeof v === "string")
+        : null;
+    if (!visible || visible.length === 0)
+        return false; // not curated -> all visible
+    const glob = `${rel}/**`;
+    if (visible.includes(glob))
+        return false;
+    if (picomatch(visible)(`${rel}/__probe__`))
+        return false; // already covered
+    visible.push(glob);
+    data.editor.visiblePaths = visible;
+    try {
+        fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function handleFilesMkdir(deckDir, req, res) {
+    void (async () => {
+        let body;
+        try {
+            body = JSON.parse(await readRequestBody(req));
+        }
+        catch {
+            return sendJson(res, 400, { error: "Invalid JSON body." });
+        }
+        const resolved = resolveDeckPath(deckDir, body.path);
+        if (!resolved.ok)
+            return sendJson(res, 400, { error: resolved.error });
+        try {
+            fs.mkdirSync(resolved.abs, { recursive: true });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return sendJson(res, 500, { error: `Could not create folder ${resolved.rel}: ${message}` });
+        }
+        const visiblePathAdded = ensureVisiblePath(deckDir, resolved.rel);
+        sendJson(res, 200, { ok: true, path: resolved.rel, visiblePathAdded });
+    })();
+}
+// True when two paths resolve to the same underlying file (same inode+device) --
+// e.g. the source and target of a case-only rename on a case-insensitive FS.
+function isSameFile(a, b) {
+    try {
+        const sa = fs.statSync(a);
+        const sb = fs.statSync(b);
+        return sa.ino === sb.ino && sa.dev === sb.dev;
+    }
+    catch {
+        return false;
+    }
+}
+function handleFilesRename(deckDir, req, res) {
+    void (async () => {
+        let body;
+        try {
+            body = JSON.parse(await readRequestBody(req));
+        }
+        catch {
+            return sendJson(res, 400, { error: "Invalid JSON body." });
+        }
+        const from = resolveDeckPath(deckDir, body.from);
+        if (!from.ok)
+            return sendJson(res, 400, { error: from.error });
+        const to = resolveDeckPath(deckDir, body.to);
+        if (!to.ok)
+            return sendJson(res, 400, { error: to.error });
+        if (!fs.existsSync(from.abs)) {
+            return sendJson(res, 404, { error: `Not found: ${from.rel}` });
+        }
+        // Block a collision with a DIFFERENT existing file. On a case-insensitive
+        // filesystem (default on macOS/Windows) `to` can "exist" only because it is
+        // `from` under a different case -- a case-only rename like bounce.jsx ->
+        // Bounce.jsx. Allow that by treating same-inode as not-a-collision.
+        if (from.abs !== to.abs && fs.existsSync(to.abs) && !isSameFile(from.abs, to.abs)) {
+            return sendJson(res, 409, { error: `Already exists: ${to.rel}` });
+        }
+        try {
+            fs.mkdirSync(path.dirname(to.abs), { recursive: true });
+            fs.renameSync(from.abs, to.abs);
+            sendJson(res, 200, { ok: true, path: to.rel });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, 500, { error: `Could not rename ${from.rel}: ${message}` });
+        }
+    })();
+}
+function handleFilesDelete(deckDir, req, res) {
+    void (async () => {
+        let body;
+        try {
+            body = JSON.parse(await readRequestBody(req));
+        }
+        catch {
+            return sendJson(res, 400, { error: "Invalid JSON body." });
+        }
+        const resolved = resolveDeckPath(deckDir, body.path);
+        if (!resolved.ok)
+            return sendJson(res, 400, { error: resolved.error });
+        if (!fs.existsSync(resolved.abs)) {
+            return sendJson(res, 404, { error: `Not found: ${resolved.rel}` });
+        }
+        try {
+            fs.rmSync(resolved.abs, { recursive: true, force: true });
+            sendJson(res, 200, { ok: true, path: resolved.rel });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, 500, { error: `Could not delete ${resolved.rel}: ${message}` });
+        }
+    })();
+}
 // The builtin Files + code-editor backend: list / read / write deck files and
 // report kit-owned editor extensions. Paths are deck-relative; resolveDeckPath
 // rejects traversal and protected dirs.
@@ -286,7 +416,14 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         return true;
     }
     if (action === "list") {
-        const files = filterDeckFiles(listDeckFiles(deckDir), readEditorConfig(deckDir));
+        // `?all=1` returns the unfiltered listing (the "show hidden files & folders"
+        // toggle) -- still minus the always-ignored dirs (node_modules/.castle/...),
+        // just without the deck's visible/hidden path curation.
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const listed = listDeckFiles(deckDir);
+        const files = url.searchParams.get("all") === "1"
+            ? listed
+            : filterDeckFiles(listed, readEditorConfig(deckDir));
         sendJson(res, 200, { files });
         return true;
     }
@@ -308,6 +445,18 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         handleFilesWrite(deckDir, req, res);
         return true;
     }
+    if (action === "rename") {
+        handleFilesRename(deckDir, req, res);
+        return true;
+    }
+    if (action === "delete") {
+        handleFilesDelete(deckDir, req, res);
+        return true;
+    }
+    if (action === "mkdir") {
+        handleFilesMkdir(deckDir, req, res);
+        return true;
+    }
     return sendJson(res, 404, { error: `Unknown files action: ${action}` }), true;
 }
 function defaultShell() {

package/dist/native/loop.js

@@ -565,6 +565,10 @@ async function runLoop(opts, toolSchemas, log) {
     const imageLabels = new Map();
     let finalText = "";
     let totalUsage;
+    // Whether this run has called ANY tool, across every iteration -- not just
+    // the current one. Scoped to the run because the question is "did this task
+    // do anything at all", which one iteration can't answer.
+    let usedAnyTool = false;
     // Once our own timeout/external-abort fires, whatever streamChatCompletion
     // reports is moot -- the abort IS the reason for stopping, so we always
     // attribute the final error to it (rather than a network error that might
@@ -598,7 +602,11 @@ async function runLoop(opts, toolSchemas, log) {
                 model: opts.model,
                 messages,
                 tools: toolSchemas,
-                reasoningEffort: REASONING_EFFORT[opts.role],
+                // Settings-driven per-role effort; falls back to the built-in table
+                // when a caller doesn't supply one (e.g. the QA harness).
+                reasoningEffort: opts.reasoningEffort ?? REASONING_EFFORT[opts.role],
+                routing: opts.routing,
+                providerTier: opts.providerTier,
                 maxTokens: MAX_COMPLETION_TOKENS,
                 signal: controller.signal,
                 onDelta: opts.onDelta,
@@ -631,6 +639,9 @@ async function runLoop(opts, toolSchemas, log) {
                 return {
                     text: finalText,
                     error: streamResult.error ?? "openrouter stream ended without a final response",
+                    // Present only for an HTTP status streamChat could label; absent for
+                    // a dropped connection, which stays unclassified on purpose.
+                    failure: streamResult.failure,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                     crashed: streamResult.crashed,
@@ -653,12 +664,40 @@ async function runLoop(opts, toolSchemas, log) {
                     : {}),
             });
             if (toolCalls.length === 0) {
+                // No tool calls is the normal way a run ends -- the model is done and
+                // signing off. But a TASK that reaches this on iteration 1, having
+                // never called a single tool, did no work: it chatted. That used to
+                // return a bare success, so the card finalized "done" at 100% with
+                // nothing changed -- the loudest silent failure this backend had.
+                //
+                // Only tasks: the router legitimately answers in plain text, and a
+                // task that used tools and THEN signs off with prose is fine.
+                //
+                // This narrows the failure class rather than closing it: a task whose
+                // only tool calls were reads still counts as "used a tool" here and
+                // can still finish having changed nothing. Detecting that needs a
+                // notion of which tools mutate, which is a bigger change than this.
+                if (opts.role === "task" && !usedAnyTool) {
+                    return {
+                        text: finalText,
+                        error: "the model replied without calling any tools, so nothing was done",
+                        failure: {
+                            kind: "no-work",
+                            detail: "model returned prose with no tool calls",
+                            model: opts.model,
+                            verbose: finalText,
+                        },
+                        usage: totalUsage,
+                        playtestFrames: playtestFrameList(playtestFrames),
+                    };
+                }
                 return {
                     text: finalText,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                 };
             }
+            usedAnyTool = true;
             messages.push({
                 role: "assistant",
                 content: streamResult.message.content || null,

package/dist/native/openrouter.d.ts

@@ -1,3 +1,4 @@
+import { type AgentFailure } from "../agent-failures.js";
 import type { NativeUsage } from "./types.js";
 export interface ORToolCall {
     id: string;
@@ -27,13 +28,17 @@ export interface ORAssistantMessage {
     content: string;
     tool_calls?: ORToolCall[];
 }
-export type ORReasoningEffort = "low" | "medium";
+export type ORReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type ORRoutingMode = "balanced" | "nitro" | "exacto" | "floor";
+export declare function applyRoutingMode(model: string, routing?: ORRoutingMode): string;
 export interface StreamChatOpts {
     apiKey: string;
     model: string;
     messages: ORMessage[];
     tools?: unknown[];
     reasoningEffort?: ORReasoningEffort;
+    routing?: ORRoutingMode;
+    providerTier?: string;
     maxTokens?: number;
     signal?: AbortSignal;
     onDelta?: (delta: string) => void;
@@ -51,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

@@ -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
@@ -24,6 +25,20 @@ function openrouterUrl() {
 const DEFAULT_MAX_RETRIES = 2; // -> 3 total connect attempts
 const RETRY_BASE_MS = 500;
 const RETRY_MAX_MS = 4_000;
+const ROUTING_SUFFIX = {
+    nitro: ":nitro",
+    exacto: ":exacto",
+    floor: ":floor",
+};
+// Append the routing-mode suffix to a model slug, first stripping any suffix
+// we might have added on a previous turn (or that the user typed into the
+// free-form slug field) so switching modes doesn't stack `:nitro:floor`.
+export function applyRoutingMode(model, routing) {
+    const base = model.replace(/:(nitro|exacto|floor)$/, "");
+    if (!routing || routing === "balanced")
+        return base;
+    return base + ROUTING_SUFFIX[routing];
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -34,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();
@@ -79,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.
@@ -188,7 +219,8 @@ function finalizeToolCalls(pending) {
 }
 export async function streamChatCompletion(opts) {
     const body = {
-        model: opts.model,
+        // Routing mode rides the slug as a suffix (see applyRoutingMode).
+        model: applyRoutingMode(opts.model, opts.routing),
         messages: opts.messages,
         stream: true,
         // Deprecated on OpenRouter's side (usage is always included now) but
@@ -199,6 +231,10 @@ export async function streamChatCompletion(opts) {
         // See ORReasoningEffort / StreamChatOpts.reasoningEffort above for the
         // doc reference and the graceful-degradation guarantee this relies on.
         ...(opts.reasoningEffort ? { reasoning: { effort: opts.reasoningEffort } } : {}),
+        // Pin a provider tier when requested (see StreamChatOpts.providerTier).
+        ...(opts.providerTier
+            ? { provider: { order: [opts.providerTier], allow_fallbacks: true } }
+            : {}),
         // See StreamChatOpts.maxTokens above -- bounds one completion call's
         // total output (content + tool-call arguments + reasoning).
         ...(opts.maxTokens !== undefined ? { max_tokens: opts.maxTokens } : {}),
@@ -223,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

@@ -1,4 +1,6 @@
+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";
 export interface NativePlaytestOpts {
     executor: PlaytestExecutor;
@@ -16,6 +18,9 @@ export interface NativeRunOpts {
     role: NativeRole;
     model: string;
     apiKey: string;
+    reasoningEffort?: ORReasoningEffort;
+    routing?: ORRoutingMode;
+    providerTier?: string;
     prompt: string;
     systemReminder?: string;
     attachments?: string[];
@@ -33,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

@@ -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

@@ -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>;