faberwright 0.3.1 → 0.4.1

package/dist/llm.js

@@ -1,18 +1,143 @@
+import { signRequest, discoverAwsCredentials } from "./sigv4.js";
+import { priceFor } from "./pricing.js";
 import { FatalError, TransientAPIError, withRetries, CancelledError } from "./errors.js";
 const RETRYABLE = new Set([408, 409, 429, 500, 502, 503, 504, 529]);
+/**
+ * Why the last model listing came back empty. "Couldn't reach the provider"
+ * is not a useful thing to tell someone whose key demonstrably works — the
+ * status code or error usually says exactly what went wrong.
+ */
+let lastListError;
+export function lastModelListError() { return lastListError; }
+/** AWS credentials discovered once per process for SigV4 routes. */
+let awsCredsPromise;
 export class LLMClient {
     config;
     constructor(config) {
         this.config = config;
+        // Local servers (Ollama, LM Studio, vLLM on localhost) accept any bearer
+        // token, so requiring a key there would block the one route that is free.
+        const isLocal = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(config.baseUrl);
+        // Routes that sign with AWS credentials need no API key at all — in
+        // SageMaker Studio, ECS or Lambda the execution role supplies them.
+        if (!config.apiKey && config.route === "bedrock")
+            return;
+        if (!config.apiKey && isLocal) {
+            this.config = { ...config, apiKey: "local" };
+            return;
+        }
         if (!config.apiKey) {
             const v = config.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
-            throw new FatalError(`No API key found. Set ${v} or add it to .faber/config.json.`);
+            throw new FatalError(`No API key found. Set ${v}, or run /route to pick a local model that doesn't need one.`);
+        }
+    }
+    /**
+     * Ask the provider which models this credential can actually use.
+     * Anthropic: GET /v1/models  -> { data: [{ id, display_name }] }, newest first.
+     * OpenAI-compatible (incl. Bedrock mantle, Ollama): GET /models, same shape
+     * minus display_name. Returns [] on any failure — this is a convenience,
+     * never a blocker, so an offline or restricted key just falls back.
+     */
+    /**
+     * Check whether the provider accepts this credential.
+     * "rejected" means the key is definitively wrong (401/403) — that is a
+     * failed setup. "unreachable" covers being offline or an endpoint without a
+     * models route, which says nothing about the key and must not block setup.
+     */
+    async verifyKey() {
+        const anthropic = this.config.provider === "anthropic";
+        const url = anthropic ? `${this.config.baseUrl}/v1/models?limit=1`
+            : `${this.config.baseUrl}/models`;
+        const headers = anthropic
+            ? { "x-api-key": this.config.apiKey, "anthropic-version": "2023-06-01" }
+            : { authorization: `Bearer ${this.config.apiKey}` };
+        try {
+            const ctl = new AbortController();
+            const timer = setTimeout(() => ctl.abort(), 8000);
+            const res = await fetch(url, { headers, signal: ctl.signal });
+            clearTimeout(timer);
+            if (res.status === 401 || res.status === 403)
+                return "rejected";
+            return res.ok ? "ok" : "unreachable";
+        }
+        catch {
+            return "unreachable";
+        }
+    }
+    async listModels(signal) {
+        lastListError = undefined;
+        const anthropic = this.config.provider === "anthropic";
+        const url = anthropic
+            ? `${this.config.baseUrl}/v1/models?limit=100`
+            : `${this.config.baseUrl}/models`;
+        const headers = anthropic
+            ? { "x-api-key": this.config.apiKey, "anthropic-version": "2023-06-01" }
+            : { authorization: `Bearer ${this.config.apiKey}` };
+        try {
+            const ctl = new AbortController();
+            const timer = setTimeout(() => ctl.abort(), 6000);
+            signal?.addEventListener("abort", () => ctl.abort(), { once: true });
+            const res = await fetch(url, { headers, signal: ctl.signal });
+            clearTimeout(timer);
+            if (!res.ok) {
+                lastListError = `HTTP ${res.status} from ${url}`;
+                return [];
+            }
+            const body = await res.json();
+            return (body.data ?? [])
+                .filter((m) => typeof m.id === "string")
+                .map((m) => ({
+                id: m.id,
+                name: m.display_name,
+                // OpenAI sends a unix timestamp; Anthropic an ISO date. Either way
+                // this is the release date the picker sorts on.
+                created: typeof m.created === "number" ? m.created
+                    : m.created_at ? Math.floor(Date.parse(m.created_at) / 1000) || undefined
+                        : undefined,
+            }));
+        }
+        catch (e) {
+            lastListError = e instanceof Error ? e.message : String(e);
+            return []; // offline, no permission, or an endpoint without the route
         }
     }
+    /**
+     * Auth for one request. An API key is a header; AWS credentials mean signing
+     * the whole request, which is how an IAM role authenticates with no key.
+     */
+    async authHeaders(url, body) {
+        if (this.config.apiKey)
+            return { "x-api-key": this.config.apiKey };
+        if (this.config.route !== "bedrock")
+            return {};
+        awsCredsPromise ??= discoverAwsCredentials();
+        const creds = await awsCredsPromise;
+        if (!creds) {
+            throw new FatalError("No AWS credentials found for the Bedrock route. Set BEDROCK_API_KEY, " +
+                "or run in an environment with an IAM role (SageMaker, ECS, EC2) " +
+                "or `aws configure`.");
+        }
+        return signRequest({
+            method: "POST",
+            url,
+            body,
+            region: this.config.region ?? "us-east-1",
+            service: "bedrock",
+            credentials: creds,
+            headers: { "content-type": "application/json" },
+        });
+    }
+    /** Switch model at runtime (/model). Cache prefixes are per-model. */
+    setModel(id) { this.config = { ...this.config, model: id }; }
     complete(system, messages, tools, onText, signal, modelOverride) {
+        // Which OpenAI API a model speaks isn't a user setting — the dataset
+        // records it per model, so route on that rather than asking anyone.
+        const model = modelOverride ?? this.config.model;
         return withRetries(() => this.config.provider === "anthropic"
             ? this.anthropicStream(system, messages, tools, onText, signal, modelOverride)
-            : this.openaiStream(system, messages, tools, onText, signal, modelOverride), { maxAttempts: this.config.retryMaxAttempts, signal });
+            : usesResponsesApi(model)
+                ? this.responsesStream(system, messages, tools, onText, signal, modelOverride)
+                : this.openaiWithResponsesFallback(system, messages, tools, onText, signal, modelOverride), { maxAttempts: this.config.retryMaxAttempts, signal });
     }
     /** Internal summarization: routed to the cheap weak model when configured. */
     async summarize(text, instruction) {
@@ -41,8 +166,10 @@ export class LLMClient {
         };
         if (tools.length)
             body.tools = cachedTools;
-        const res = await this.post(`${this.config.baseUrl}/v1/messages`, {
-            "x-api-key": this.config.apiKey,
+        const url = `${this.config.baseUrl}/v1/messages`;
+        const authHeaders = await this.authHeaders(url, JSON.stringify(body));
+        const res = await this.post(url, {
+            ...authHeaders,
             "anthropic-version": "2023-06-01",
             "content-type": "application/json",
         }, body, signal);
@@ -176,6 +303,145 @@ export class LLMClient {
             rawContent.push({ type: "tool_use", id: c.id, name: c.name, input: c.input });
         return { text, toolCalls, rawContent, stopReason: toolCalls.length ? "tool_use" : "end_turn", usage };
     }
+    /**
+     * Chat completions, retrying on the Responses API if the provider says the
+     * model belongs there.
+     *
+     * Routing normally comes from the dataset, but a model can be missing from
+     * it, or the local copy can predate the fields we read. Rather than failing
+     * with a 404 the user can do nothing about, take the provider at its word
+     * and retry on the endpoint it named.
+     */
+    async openaiWithResponsesFallback(system, messages, tools, onText, signal, modelOverride) {
+        try {
+            return await this.openaiStream(system, messages, tools, onText, signal, modelOverride);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!/responses/i.test(msg) || !/endpoint|not supported/i.test(msg))
+                throw e;
+            return this.responsesStream(system, messages, tools, onText, signal, modelOverride);
+        }
+    }
+    // ------------------------------------------------------------- responses
+    /**
+     * OpenAI's Responses API — the only way to reach the codex models, which are
+     * the coding-tuned ones a coding agent actually wants.
+     *
+     * Three things differ from chat completions, and each is a place to get it
+     * wrong: the request carries `instructions` and `input` rather than a
+     * `messages` array; the stream is a sequence of named events keyed by a
+     * `type` field rather than `choices[].delta`; and usage arrives as
+     * input_tokens/output_tokens, which the cost ledger reads directly, so a
+     * mismatch here silently under-reports spend rather than failing loudly.
+     */
+    async responsesStream(system, messages, tools, onText, signal, modelOverride) {
+        const input = [];
+        for (const m of messages)
+            input.push(...toResponsesInput(m));
+        const body = {
+            model: modelOverride ?? this.config.model,
+            instructions: system,
+            input,
+            stream: true,
+            max_output_tokens: this.config.maxTokens,
+        };
+        if (tools.length) {
+            // Flatter than chat completions: no nested `function` object.
+            body.tools = tools.map((t) => ({
+                type: "function",
+                name: t.name,
+                description: t.description,
+                parameters: t.input_schema,
+            }));
+        }
+        const res = await this.post(`${this.config.baseUrl}/responses`, {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "content-type": "application/json",
+        }, body, signal);
+        let text = "";
+        const usage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+        // Tool calls arrive as items announced first, then filled in by argument
+        // deltas addressed to the item's id.
+        const calls = new Map();
+        for await (const evt of sseEvents(res, signal)) {
+            const e = evt;
+            switch (e.type) {
+                case "response.output_text.delta": {
+                    const d = typeof e.delta === "string" ? e.delta : "";
+                    if (d) {
+                        text += d;
+                        onText?.(d);
+                    }
+                    break;
+                }
+                case "response.output_item.added": {
+                    const item = e.item;
+                    if (item?.type === "function_call") {
+                        calls.set(String(item.id ?? item.call_id), {
+                            id: String(item.call_id ?? item.id ?? ""),
+                            name: String(item.name ?? ""),
+                            args: typeof item.arguments === "string" ? item.arguments : "",
+                        });
+                    }
+                    break;
+                }
+                case "response.function_call_arguments.delta": {
+                    const key = String(e.item_id ?? "");
+                    const cur = calls.get(key) ?? { id: key, name: "", args: "" };
+                    cur.args += typeof e.delta === "string" ? e.delta : "";
+                    calls.set(key, cur);
+                    break;
+                }
+                case "response.function_call_arguments.done": {
+                    // Some responses send the complete arguments here instead of deltas.
+                    const key = String(e.item_id ?? "");
+                    const cur = calls.get(key);
+                    if (cur && !cur.args && typeof e.arguments === "string")
+                        cur.args = e.arguments;
+                    break;
+                }
+                case "response.completed":
+                case "response.incomplete": {
+                    const u = e.response?.usage;
+                    if (u) {
+                        const cached = u.input_tokens_details?.cached_tokens ?? 0;
+                        usage.input = (u.input_tokens ?? 0) - cached;
+                        usage.cacheRead = cached;
+                        usage.output = u.output_tokens ?? 0;
+                    }
+                    break;
+                }
+                case "error":
+                case "response.failed": {
+                    const msg = e.message ?? e.response?.error?.message ?? "stream failed";
+                    throw new FatalError(`Responses API error: ${String(msg)}`);
+                }
+                default: break; // ignore lifecycle events we don't need
+            }
+        }
+        const toolCalls = [...calls.values()]
+            .filter((c) => c.name)
+            .map((c) => {
+            let parsed = {};
+            try {
+                parsed = c.args ? JSON.parse(c.args) : {};
+            }
+            catch { /* leave empty */ }
+            return { id: c.id, name: c.name, input: parsed };
+        });
+        const rawContent = [];
+        if (text)
+            rawContent.push({ type: "text", text });
+        for (const c of toolCalls) {
+            rawContent.push({ type: "tool_use", id: c.id, name: c.name, input: c.input });
+        }
+        return {
+            text, toolCalls, rawContent,
+            stopReason: toolCalls.length ? "tool_use" : "end_turn",
+            usage,
+        };
+    }
     // ------------------------------------------------------------------ http
     async post(url, headers, body, signal) {
         let res;
@@ -194,8 +460,28 @@ export class LLMClient {
         if (res.status === 401 || res.status === 403) {
             throw new FatalError(`Authentication failed (HTTP ${res.status}). Check your API key.`);
         }
-        if (!res.ok)
-            throw new FatalError(`API error HTTP ${res.status}: ${(await res.text()).slice(0, 500)}`);
+        if (!res.ok) {
+            const body = (await res.text()).slice(0, 500);
+            // Record what the provider just told us. Neither OpenAI's catalogue nor
+            // its /v1/models response flags retired models or says which endpoint a
+            // model needs, so the failing request is the only reliable signal — and
+            // remembering it keeps the model out of every future menu.
+            const { classifyModelError, markUnusable } = await import("./models.js");
+            const why = classifyModelError(body);
+            if (why)
+                markUnusable(this.config.model, why);
+            // Some newer OpenAI models are only served by the Responses API, which
+            // Faber doesn't speak yet. The raw 404 doesn't say what to do about it.
+            if (/v1\/responses endpoint/i.test(body)) {
+                // Not fatal: the caller retries this request on the Responses API.
+                throw new FatalError(`${this.config.model} is served by the responses endpoint, not chat completions.`);
+            }
+            if (/has been deprecated/i.test(body)) {
+                throw new FatalError(`${this.config.model} has been deprecated by the provider.\n` +
+                    `  It won't be offered again. Pick another with /model.`);
+            }
+            throw new FatalError(`API error HTTP ${res.status}: ${body}`);
+        }
         return res;
     }
 }
@@ -234,6 +520,58 @@ async function* sseEvents(res, signal) {
         reader.releaseLock();
     }
 }
+/**
+ * Convert a message to Responses API input items.
+ *
+ * The Responses API doesn't take a `messages` array of chat turns. It takes a
+ * flat list of items where a tool call and its result are siblings rather than
+ * nested inside an assistant turn — so one Faber message can expand into
+ * several items. Tool calls are joined to their results by `call_id`.
+ */
+/**
+ * Does this model require the Responses API? Answered by the pricing dataset's
+ * `mode` and `supported_endpoints`, refreshed on every launch, so a model
+ * released tomorrow routes correctly without a Faber update.
+ */
+export function usesResponsesApi(modelId) {
+    const p = priceFor(modelId);
+    if (p?.mode === "responses")
+        return true;
+    if (p?.endpoints?.length) {
+        return p.endpoints.includes("/v1/responses")
+            && !p.endpoints.some((e) => e.includes("chat/completions"));
+    }
+    return false;
+}
+function toResponsesInput(m) {
+    const out = [];
+    const texts = [];
+    for (const b of m.content) {
+        if (b.type === "text")
+            texts.push(b.text);
+        else if (b.type === "tool_use") {
+            out.push({
+                type: "function_call",
+                call_id: b.id,
+                name: b.name,
+                arguments: JSON.stringify(b.input),
+            });
+        }
+        else if (b.type === "tool_result") {
+            out.push({
+                type: "function_call_output",
+                call_id: b.tool_use_id,
+                output: typeof b.content === "string" ? b.content : JSON.stringify(b.content),
+            });
+        }
+    }
+    if (texts.length) {
+        // input_text for what we send, output_text for what the model said
+        const kind = m.role === "assistant" ? "output_text" : "input_text";
+        out.unshift({ role: m.role, content: [{ type: kind, text: texts.join("\n") }] });
+    }
+    return out;
+}
 function toOpenAI(m) {
     const out = [];
     const texts = [];

package/dist/models.js

@@ -0,0 +1,180 @@
+/**
+ * Model discovery: ask the provider what this credential can actually use,
+ * cache it, and fall back to the built-in list when that isn't possible.
+ *
+ * Why bother: hardcoded model lists go stale the moment a provider ships
+ * something new, and they can't know which models YOUR account is entitled to.
+ * A live list is always current and always accurate for the caller.
+ *
+ * Discovery is strictly a convenience. Every failure path — offline, a key
+ * without models:list permission, an endpoint that doesn't implement it —
+ * falls back to the static aliases rather than blocking the picker.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { modelsForRoute } from "./routes.js";
+import { priceFor } from "./pricing.js";
+/**
+ * Order the model list the way someone choosing one would want it.
+ *
+ * On OpenAI the coding-tuned models matter most to a coding agent, so those
+ * come first as a group; everything else follows. Within each group, newest
+ * first, since a release date is the only ranking the provider actually gives
+ * us. Anthropic has no such split, so it's purely newest first.
+ */
+export function isCodexModel(id) {
+    return /codex/i.test(id);
+}
+export function sortModels(models, wire) {
+    const byDate = (a, b) => {
+        if (a.created && b.created)
+            return b.created - a.created;
+        if (a.created)
+            return -1; // dated entries above undated ones
+        if (b.created)
+            return 1;
+        return a.id.localeCompare(b.id);
+    };
+    if (wire !== "openai")
+        return [...models].sort(byDate);
+    const codex = models.filter((m) => isCodexModel(m.id)).sort(byDate);
+    const rest = models.filter((m) => !isCodexModel(m.id)).sort(byDate);
+    return [...codex, ...rest];
+}
+const TTL_MS = 24 * 60 * 60 * 1000; // a day: new models are rare, staleness is cheap
+function cacheFile(routeId) {
+    return path.join(os.homedir(), ".faber", "cache", `models-${routeId}.json`);
+}
+export function readCache(routeId, now = Date.now()) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(cacheFile(routeId), "utf8"));
+        if (!Array.isArray(raw.models) || now - raw.fetchedAt > TTL_MS)
+            return undefined;
+        return raw.models;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeCache(routeId, models, now = Date.now()) {
+    try {
+        const f = cacheFile(routeId);
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        fs.writeFileSync(f, JSON.stringify({ fetchedAt: now, models }, null, 2));
+    }
+    catch { /* cache is best-effort */ }
+}
+export function clearCache(routeId) {
+    try {
+        fs.unlinkSync(cacheFile(routeId));
+    }
+    catch { /* already gone */ }
+}
+/**
+ * Can this model actually run an agent loop?
+ *
+ * Provider catalogues list everything the key can call: embeddings, speech,
+ * transcription, moderation, image generation. None of them accept a chat
+ * request, so offering them as a choice is offering a guaranteed failure.
+ * Excluding by capability keyword is deliberately conservative — anything
+ * unrecognised is kept, since a new chat model must never be filtered out.
+ */
+const NOT_CHAT = /(^|[-_/])(embedding|embed|tts|whisper|moderation|dall-e|dalle|image|audio|transcribe|realtime|speech|rerank|search-preview|codex-mini-latest)([-_/]|$)/i;
+/** Retired completion-only families that predate the chat API. */
+const LEGACY = /^(davinci|babbage|curie|ada|text-davinci|code-davinci)/i;
+export function isChatModel(id) {
+    // The dataset states each model's mode and endpoints, so use that rather
+    // than reading the name. Guessing from an id misclassifies every new naming
+    // scheme; this is the provider's own answer, refreshed on every launch.
+    const p = priceFor(id);
+    // "responses" counts as a chat model now that Faber speaks that API too.
+    if (p?.mode)
+        return p.mode === "chat" || p.mode === "completion" || p.mode === "responses";
+    if (p?.endpoints?.length) {
+        return p.endpoints.some((e) => e.includes("chat/completions") || e === "/v1/responses");
+    }
+    // Only fall back to name-based rules when the dataset has never seen it,
+    // which is the case for a brand new model or a local one.
+    return !NOT_CHAT.test(id) && !LEGACY.test(id);
+}
+/**
+ * Does this model need an API Faber doesn't speak? The dataset records it —
+ * gpt-5.3-codex reports mode "responses" and endpoint /v1/responses — so
+ * these can be labelled honestly instead of failing at request time.
+ */
+export function requiresUnsupportedApi(_id) {
+    // Responses-only models are supported now, so nothing is excluded on this
+    // basis. Kept as the hook for the next API Faber doesn't yet speak.
+    return undefined;
+}
+/**
+ * Build the /model menu: built-in aliases first (stable names people type),
+ * then anything discovered that an alias doesn't already cover.
+ * Provider lists arrive newest-first, and that order is preserved.
+ */
+export function buildPicker(route, discovered, currentId) {
+    const aliases = modelsForRoute(route);
+    const entries = aliases.map((a) => ({
+        value: a.alias,
+        label: a.alias,
+        blurb: a.blurb,
+        live: false,
+    }));
+    const covered = new Set(aliases.map((a) => a.id));
+    const unusable = readUnusable();
+    for (const m of sortModels(discovered, route.wire)) {
+        if (covered.has(m.id))
+            continue;
+        if (!isChatModel(m.id))
+            continue; // embeddings, speech, moderation…
+        // Only genuinely dead models are hidden. An endpoint mismatch is handled
+        // by retrying on the right endpoint, so it must not remove the model.
+        if (unusable[m.id] === "deprecated")
+            continue;
+        entries.push({ value: m.id, label: m.id, blurb: m.name ?? "", live: true });
+    }
+    // if the model in use is neither an alias nor discovered, keep it visible
+    if (!entries.some((e) => e.value === currentId) && !covered.has(currentId)) {
+        entries.push({ value: currentId, label: currentId, blurb: "current", live: false });
+    }
+    return entries;
+}
+function unusableFile() {
+    return path.join(os.homedir(), ".faber", "cache", "unusable-models.json");
+}
+export function readUnusable() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(unusableFile(), "utf8"));
+        return raw && typeof raw === "object" ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function markUnusable(modelId, why) {
+    try {
+        const f = unusableFile();
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        fs.writeFileSync(f, JSON.stringify({ ...readUnusable(), [modelId]: why }, null, 2));
+    }
+    catch { /* best effort */ }
+}
+export function clearUnusable() {
+    try {
+        fs.unlinkSync(unusableFile());
+    }
+    catch { /* already gone */ }
+}
+/** Classify a provider error, so a failure teaches us something. */
+export function classifyModelError(message) {
+    const m = message.toLowerCase();
+    if (m.includes("deprecat") || m.includes("model_not_found") || m.includes("has been retired")) {
+        return "deprecated";
+    }
+    if (m.includes("/v1/responses") || m.includes("responses endpoint")
+        || m.includes("not supported in the v1/chat/completions")) {
+        return "wrong-endpoint";
+    }
+    return undefined;
+}