castle-web-cli 0.4.83 → 0.4.84

package/dist/agent-failures.d.ts

@@ -0,0 +1,17 @@
+export type FailureKind = "config" | "transient" | "no-work" | "spawn" | "timeout" | "exit";
+export type ConfigReason = "no-key" | "bad-key" | "no-credits" | "unknown-model" | "no-tools" | "no-endpoints" | "flagged" | "context-length";
+export interface AgentFailure {
+    kind: FailureKind;
+    reason?: ConfigReason;
+    detail: string;
+    verbose?: string;
+    model?: string;
+    suggestion?: string;
+}
+export declare function failureForStatus(status: number, body: string, model?: string): AgentFailure | undefined;
+export declare function classifyProviderError(text: string | undefined, model?: string): AgentFailure | undefined;
+export declare function failureCopy(opts: {
+    failure: AgentFailure;
+    spawnedTasks: boolean;
+    willRetry: boolean;
+}): string;

package/dist/agent-failures.js

@@ -0,0 +1,151 @@
+// How an agent run failed, and what to tell the user about it.
+//
+// Split out of agent.ts (already ~3.8k lines) because the classification and
+// the copy are one concern: the ONLY reason to distinguish failures is to give
+// the user a different next action. The taxonomy is therefore organised by
+// recovery, not by where the error came from:
+//
+//   config    - deterministic and won't fix itself (bad slug, bad key, no
+//               credits). Never retried: retrying is pure latency. Copy names
+//               what's wrong and points at settings / Castle.
+//   transient - the provider was busy or broke. NOT auto-retried either (see
+//               below), but the copy invites the user to send again.
+//   no-work   - the model answered instead of working. Config is fine; the
+//               model is the problem.
+//   spawn     - the CLI binary itself wouldn't start.
+//   timeout   - we gave up waiting.
+//   exit      - anything else, including unclassified. The safe default.
+//
+// On `transient` not auto-retrying: both paths ALREADY retried at the
+// transport layer (native/openrouter.ts connectWithRetry does 3 backed-off
+// connects on 429/5xx; the claude CLI retries internally). A turn-level retry
+// on top stacks to ~6 connects and doubles the wait with the composer frozen,
+// for no new information. A 429 that survived three backed-off attempts is not
+// "one more go" territory.
+// The single mapping from "OpenRouter said N" to a failure. Both paths funnel
+// through it -- the native loop, which knows the status first-hand, and the
+// claude-CLI path, which recovers it from text -- so the two can't drift into
+// disagreeing about what a 402 means.
+//
+// `body` disambiguates the codes that mean more than one thing: OpenRouter
+// returns 400/404 for a bad slug, an unreachable slug, and an oversized
+// request alike.
+export function failureForStatus(status, body, model) {
+    const detail = `HTTP ${status}${body ? `: ${body.slice(0, 200)}` : ""}`;
+    const config = (reason) => ({
+        kind: "config",
+        reason,
+        detail,
+        model,
+        verbose: `HTTP ${status}: ${body}`,
+    });
+    if (status === 401)
+        return config("bad-key");
+    if (status === 402)
+        return config("no-credits");
+    if (status === 403)
+        return config("flagged");
+    if (status === 429 || status >= 500) {
+        return { kind: "transient", detail, model, verbose: `HTTP ${status}: ${body}` };
+    }
+    if (status === 400 || status === 404) {
+        if (/no endpoints found|no allowed providers/i.test(body))
+            return config("no-endpoints");
+        if (/context length|context window|too many tokens/i.test(body)) {
+            return config("context-length");
+        }
+        if (/model[ _-]?not[ _-]?found|not a valid model|unknown model/i.test(body)) {
+            return config("unknown-model");
+        }
+    }
+    // Unrecognised: leave it unlabelled so the caller keeps its existing
+    // behavior rather than inventing a diagnosis.
+    return undefined;
+}
+// Provider errors reach the claude-CLI path as TEXT -- specifically in the
+// stream-json `result` event with is_error:true and exit code 0, NOT stderr,
+// which is typically empty (this is why firstErrorLine special-cases "agent
+// exited 0"). Verified against the real binary pointed at both a local probe
+// and real openrouter.ai; the shape is:
+//
+//   API Error: 402 This request requires more credits, or fewer max_tokens...
+//   Failed to authenticate. API Error: 401 User not found.
+//
+// So the status code is right there in the text and does the classifying --
+// the prose is only a tiebreaker for the codes that mean several things. The
+// regex is unanchored because the CLI sometimes prefixes its own sentence.
+const API_ERROR_RE = /API Error:\s*(\d{3})\b/i;
+// Unrecognised text returns undefined, and the caller keeps today's "exit"
+// behavior. That fallback is the whole safety story here: claude CLI's error
+// prose is not a contract, so a miss must cost one wasted retry, never a wrong
+// diagnosis. The deterministic failures don't depend on this at all --
+// pre-flight catches them before a run starts.
+//
+// Recovering the status and handing off to failureForStatus (rather than
+// re-deciding here) is what keeps the two paths honest: there is exactly one
+// place that decides what a status means.
+export function classifyProviderError(text, model) {
+    if (!text)
+        return undefined;
+    const status = Number(API_ERROR_RE.exec(text)?.[1] ?? NaN);
+    if (Number.isNaN(status))
+        return undefined;
+    return failureForStatus(status, text, model);
+}
+function quoted(model) {
+    return model ? `"${model}"` : "the model this session is set to";
+}
+// Plain-language copy for a failed run. Deliberately ONE table rather than a
+// router copy and a task copy: the sentences would be near-identical, and the
+// duplicate-detection gate (jscpd, threshold 0) is right to reject that.
+//
+// Voice matches the pre-existing copy: second person, no jargon, no status
+// codes, and "the person running this session" for anything the user in the
+// chat can't fix themselves. Every config case ends in an action.
+function configCopy(failure) {
+    const model = quoted(failure.model);
+    switch (failure.reason) {
+        case "no-key":
+            return "This session isn't set up to use OpenRouter -- there's no API key. The person running this session needs to add one; reach out to Castle if you need help.";
+        case "bad-key":
+            return "OpenRouter rejected this session's API key. The person running this session needs to check it -- reach out to Castle if you need help.";
+        case "no-credits":
+            return "OpenRouter is out of credits for this session's key. Reach out to Castle to top it up, or switch to a different model in settings.";
+        case "unknown-model": {
+            const hint = failure.suggestion ? ` Did you mean "${failure.suggestion}"?` : "";
+            return `I can't use the model this session is set to -- OpenRouter doesn't recognize ${model}.${hint} Pick a different model in settings. If you think that model should work, reach out to Castle.`;
+        }
+        case "no-tools":
+            return `The model this session is set to (${model}) can't use tools, so it can't do work here. Pick a different model in settings.`;
+        case "no-endpoints":
+            return `OpenRouter knows ${model} but this session's key can't reach it. Pick a different model in settings, or reach out to Castle.`;
+        case "flagged":
+            return `${model} refused that request. Try rewording it, or switch to a different model in settings.`;
+        case "context-length":
+            return `That turn got too big for ${model} to hold. Try breaking it into smaller steps, or switch to a model with more room in settings.`;
+        default:
+            return "Something about this session's model setup isn't right. Check the model in settings, or reach out to Castle.";
+    }
+}
+export function failureCopy(opts) {
+    if (opts.willRetry) {
+        return "Something went wrong on my end -- give me a moment to try that again.";
+    }
+    const tasksNote = opts.spawnedTasks
+        ? " The steps I already kicked off are still running."
+        : "";
+    switch (opts.failure.kind) {
+        case "config":
+            return `${configCopy(opts.failure)}${tasksNote}`;
+        case "transient":
+            return `OpenRouter is busy right now and I couldn't get through. Send that again in a moment.${tasksNote}`;
+        case "no-work":
+            return `The model this session is set to (${quoted(opts.failure.model)}) answered instead of doing the work. Try a different model in settings -- if it keeps happening, reach out to Castle.${tasksNote}`;
+        case "spawn":
+            return `I couldn't start working on that -- something in this setup isn't right. If this keeps happening, the person running this session needs to take a look.${tasksNote}`;
+        case "timeout":
+            return `That took me too long and I had to stop partway. Send another message and I'll pick it back up.${tasksNote}`;
+        case "exit":
+            return `Something went wrong on my end partway through. Send another message and I'll pick it back up.${tasksNote}`;
+    }
+}

package/dist/agent.d.ts

@@ -1,11 +1,33 @@
 import * as http from "http";
 import { Duplex } from "stream";
+import type { ORReasoningEffort, ORRoutingMode } from "./native/openrouter.js";
 export declare const AGENT_WS_PATH = "/__castle/agent";
 export declare const AGENT_ATTACHMENT_PREFIX = "/__castle/agent/attachments/";
 export declare const AGENT_PLAYTEST_PREFIX = "/__castle/agent/playtest/";
 export declare const AGENT_MODEL_CAPS_PREFIX = "/__castle/agent/model-caps";
 export type AgentBackend = "cursor" | "claude" | "smith";
 export type ClaudeModel = "sonnet" | "opus" | "fable" | "openrouter";
+interface AgentSettings {
+    router: AgentBackend;
+    tasks: AgentBackend;
+    routerClaudeModel: ClaudeModel;
+    tasksClaudeModel: ClaudeModel;
+    routerOpenrouterModel: string;
+    tasksOpenrouterModel: string;
+    routerReasoningEffort: ORReasoningEffort;
+    tasksReasoningEffort: ORReasoningEffort;
+    routerRouting: ORRoutingMode;
+    tasksRouting: ORRoutingMode;
+    routerProviderTier: string;
+    tasksProviderTier: string;
+}
+type OpenrouterSlugKey = "routerOpenrouterModel" | "tasksOpenrouterModel";
+type SettingsWarnings = Partial<Record<OpenrouterSlugKey, {
+    model: string;
+    status: "unknown-model" | "no-tools";
+    message: string;
+    suggestion?: string;
+}>>;
 type TaskStatus = "waiting" | "running" | "blocked" | "done" | "failed" | "interrupted";
 interface TaskRecord {
     id: string;
@@ -23,17 +45,21 @@ interface TaskRecord {
     originMessageId?: string;
     playtestFrames?: string[];
     resultSummary?: string;
+    errorCopy?: string;
+    errorDetail?: string;
     avatar?: string;
     phase?: string;
     acknowledged?: boolean;
     rejected?: boolean;
     blockedBy?: string[];
 }
+export declare function roleUsesOpenrouter(backend: AgentBackend, claudeModel: ClaudeModel): boolean;
 export interface DepsState {
     kind: "ready" | "waiting" | "blocked";
     blockedBy?: string[];
 }
 export declare function classifyDeps(tasks: Map<string, TaskRecord>, task: TaskRecord): DepsState;
+export declare function computeSettingsWarnings(settings: AgentSettings): Promise<SettingsWarnings>;
 export interface AgentServer {
     /** Attach the agent WebSocket if the upgrade targets the agent path. */
     handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;