flashlite 0.0.0-stage → 0.1.0

package/dist/client.js

@@ -0,0 +1,463 @@
+// RouterClient — HTTP against any OpenAI- or Anthropic-compatible chat endpoint:
+// envelope parsing, per-status hints, and digit-only Retry-After handling.
+import { AnthropicStreamParser, parseAnthropicCompleteBody, toAnthropicBody } from "./adapters/anthropic.js";
+import { OpenAiStreamParser, parseCompleteBody, toWireBody } from "./adapters/openai.js";
+import { sseFrames } from "./sse.js";
+export const ANTHROPIC_VERSION = '2023-06-01';
+const MAX_ERROR_TEXT = 1000;
+export class RouterError extends Error {
+    status;
+    type;
+    code;
+    param;
+    requestId;
+    retryAfterSeconds;
+    constructor(message) {
+        super(message);
+        this.name = 'RouterError';
+    }
+}
+export function statusHint(status) {
+    switch (status) {
+        case 400:
+            return 'Check the request and model ID (run /model for the live catalog).';
+        case 401:
+            return 'The API key is missing or invalid — update it with /settings or edit ~/.config/flashlite/config.json.';
+        case 403:
+            return 'This model is not permitted for this API key.';
+        case 429:
+            return 'Rate limit reached; try again later.';
+        case 502:
+            return 'The provider is disconnected or its credentials need renewal.';
+        default:
+            return 'The endpoint could not complete the request.';
+    }
+}
+function bounded(value) {
+    const trimmed = value.trim();
+    return trimmed.length > MAX_ERROR_TEXT ? trimmed.slice(0, MAX_ERROR_TEXT) + '…' : trimmed;
+}
+/** Display copy for any failure: bare fetch network errors get actionable text. */
+export function errorMessage(err) {
+    if (err instanceof TypeError) {
+        // undici wraps the real socket/DNS failure in `cause`; surface it without leaking anything but the host.
+        const cause = err.cause;
+        const host = typeof cause?.hostname === 'string' ? cause.hostname : 'the endpoint host';
+        switch (cause?.code) {
+            case 'ENOTFOUND':
+            case 'EAI_AGAIN':
+                return `Network error — could not resolve ${host} (DNS lookup failed). Check the base URL, your DNS and any VPN or filter.`;
+            case 'ECONNREFUSED':
+                return 'Network error — the endpoint refused the connection. Check the base URL and port.';
+            case 'ETIMEDOUT':
+            case 'UND_ERR_CONNECT_TIMEOUT':
+                return 'Network error — timed out connecting to the endpoint.';
+        }
+        return 'Network error — could not reach the endpoint.';
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+function scalarString(value) {
+    if (typeof value === 'string')
+        return bounded(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Race an operation against cancellation, without retaining a signal listener. */
+async function abortable(operation, signal) {
+    if (!signal)
+        return await operation;
+    if (signal.aborted)
+        return await Promise.race([operation, Promise.reject(signal.reason)]);
+    let onAbort = () => { };
+    const cancelled = new Promise((_, reject) => {
+        onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([operation, cancelled]);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+/** Read at most cap bytes, not an unbounded response.text() followed by slicing. */
+async function readBody(response, signal, cap = Infinity) {
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    let remaining = cap;
+    let finished = false;
+    try {
+        while (remaining > 0) {
+            signal?.throwIfAborted();
+            const { value, done } = await abortable(reader.read(), signal);
+            if (done) {
+                finished = true;
+                break;
+            }
+            const bytes = value.subarray(0, remaining);
+            text += decoder.decode(bytes, { stream: true });
+            remaining -= bytes.byteLength;
+        }
+        return text + decoder.decode();
+    }
+    finally {
+        // Do not let slow/rejecting upstream cancellation replace the result/error.
+        if (!finished)
+            void reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+async function drainBody(response, cap = 4096, signal) {
+    try {
+        return await readBody(response, signal, cap);
+    }
+    catch {
+        return '';
+    }
+}
+/** A fresh deadline per attempt, retained until the response body is consumed. */
+async function withResponse(url, init, timeoutMs, caller, consume) {
+    caller?.throwIfAborted();
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(caller?.reason);
+    caller?.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException('The request timed out.', 'TimeoutError')), timeoutMs);
+    timer.unref();
+    let response;
+    try {
+        const fetching = fetch(url, { ...init, signal: controller.signal });
+        // Synthetic fetches (and a late resolution during cancellation) may ignore abort.
+        void fetching.then((res) => {
+            if (controller.signal.aborted && res.body && !res.body.locked)
+                void res.body.cancel().catch(() => { });
+        }, () => { });
+        response = await abortable(fetching, controller.signal);
+        const result = await consume(response, controller.signal);
+        caller?.throwIfAborted();
+        return result;
+    }
+    catch (err) {
+        // Diagnostic reads intentionally retain HTTP status on an internal timeout,
+        // but explicit caller cancellation must never be turned into an HTTP error.
+        caller?.throwIfAborted();
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        caller?.removeEventListener('abort', onAbort);
+        if (response?.body && !response.body.locked)
+            void response.body.cancel().catch(() => { });
+    }
+}
+async function readJson(response, signal) {
+    return JSON.parse(await readBody(response, signal));
+}
+/** delta-seconds only: all digits, capped at 60s (Swift parity — no HTTP dates). */
+function retryAfterSecondsFrom(headers) {
+    const raw = headers.get('retry-after')?.trim();
+    if (!raw || !/^\d+$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        return undefined;
+    return Math.min(value, 60);
+}
+async function routerErrorFromResponse(status, response, signal) {
+    const body = safeJson(await drainBody(response, 4096, signal));
+    const nested = body?.error;
+    const nestedObj = typeof nested === 'object' && nested !== null ? nested : undefined;
+    const message = (typeof nestedObj?.message === 'string' && nestedObj.message) ||
+        (typeof body?.message === 'string' && body.message) ||
+        (typeof nested === 'string' ? nested : undefined) ||
+        statusHint(status);
+    const err = new RouterError(bounded(message));
+    err.status = status;
+    if (nestedObj) {
+        err.type = scalarString(nestedObj.type);
+        err.code = scalarString(nestedObj.code);
+        err.param = scalarString(nestedObj.param);
+        err.requestId = scalarString(nestedObj.request_id ?? nestedObj.requestId);
+    }
+    const retryAfter = retryAfterSecondsFrom(response.headers);
+    if (retryAfter !== undefined) {
+        err.retryAfterSeconds = retryAfter;
+        err.message += ` Retry after ${retryAfter} seconds.`;
+    }
+    return err;
+}
+/**
+ * Which wire dialect a model id speaks. A provider prefix always wins, so
+ * `openai/claude-proxy` is not silently rerouted (Swift parity).
+ */
+export function dialectFor(model) {
+    const id = model.trim().toLowerCase();
+    if (!id)
+        throw new RouterError('Model id is empty.');
+    if (id.startsWith('anthropic/'))
+        return 'anthropic';
+    if (id.includes('/'))
+        return 'openai';
+    if (id.startsWith('claude-') || id.startsWith('claude.'))
+        return 'anthropic';
+    if (id.startsWith('gpt-') || id.startsWith('grok-') || id.startsWith('deepseek-'))
+        return 'openai';
+    throw new RouterError(`Cannot route model "${model}" — use the full provider-prefixed id from /model (e.g. opencode/glm-5.3-flash).`);
+}
+/** Strip the /v1 suffix: the Anthropic endpoints hang off the bare root. */
+export function rootFromBase(baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.pathname === '/v1' || url.pathname === '/v1/') {
+        url.pathname = '';
+    }
+    else {
+        url.pathname = url.pathname.replace(/\/+$/, '');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+/** Pure catalog parsing; accepts {"data":[...]} and {"models":[...]} (Swift parity). */
+export function parseModelCatalog(json) {
+    if (typeof json !== 'object' || json === null)
+        return null;
+    const root = json;
+    const entries = Array.isArray(root.data) ? root.data : Array.isArray(root.models) ? root.models : null;
+    if (!entries)
+        return null;
+    const result = [];
+    for (const entry of entries) {
+        if (typeof entry === 'string') {
+            result.push({ id: entry });
+            continue;
+        }
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const id = typeof e.id === 'string' ? e.id : typeof e.name === 'string' ? e.name : undefined;
+        if (!id)
+            continue;
+        result.push({
+            id,
+            displayName: typeof e.display_name === 'string' ? e.display_name : undefined,
+            ownedBy: typeof e.owned_by === 'string' ? e.owned_by : undefined,
+            contextLength: positiveInteger(e.context_length),
+            maxOutputTokens: positiveInteger(e.max_output_tokens),
+        });
+    }
+    return result;
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+export class RouterClient {
+    baseUrl;
+    apiKey;
+    debug;
+    wait;
+    promptCaching;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.debug = options.debug ?? (() => { });
+        this.wait = options.sleep;
+        this.promptCaching = options.promptCaching ?? false;
+    }
+    /** Replace credentials for subsequent requests without exposing them. */
+    setApiKey(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /** Point subsequent requests at another endpoint root (already validated by normalizeBaseUrl). */
+    setBaseUrl(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    /** Wire body for a chat request; Anthropic requests opt into prompt caching when enabled. */
+    requestBody(req) {
+        return JSON.stringify(req.dialect === 'anthropic' ? toAnthropicBody(req, { cache: this.promptCaching }) : toWireBody(req));
+    }
+    /** Bare root without /v1 — Anthropic endpoints hang off this. */
+    rootUrl() {
+        return rootFromBase(this.baseUrl);
+    }
+    /** The completion endpoint for a dialect (used by the harness and adapters). */
+    chatPath(dialect) {
+        return dialect === 'anthropic'
+            ? this.rootUrl() + '/v1/messages'
+            : this.baseUrl + '/chat/completions';
+    }
+    /** Auth headers per dialect; the router accepts Bearer everywhere (Swift parity). */
+    headers(dialect) {
+        const h = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+        if (dialect === 'anthropic') {
+            h['x-api-key'] = this.apiKey;
+            h['anthropic-version'] = ANTHROPIC_VERSION;
+        }
+        return h;
+    }
+    async listModels(signal) {
+        return await withResponse(this.baseUrl + '/models', {
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+            cache: 'no-store',
+        }, 30_000, signal, async (res, deadline) => {
+            if (!res.ok)
+                throw await routerErrorFromResponse(res.status, res, deadline);
+            const entries = parseModelCatalog(await readJson(res, deadline));
+            if (!entries) {
+                throw new RouterError('GET /models: unexpected response shape (no "data" or "models" array).');
+            }
+            return entries;
+        });
+    }
+    /** Non-streaming chat. One retry for retryable failures (429/502/503/network). */
+    async complete(req, signal) {
+        return await this.withRetry(() => withResponse(this.chatPath(req.dialect), {
+            method: 'POST',
+            headers: this.headers(req.dialect),
+            body: this.requestBody(req),
+        }, 300_000, signal, async (res, deadline) => {
+            if (!res.ok)
+                throw await routerErrorFromResponse(res.status, res, deadline);
+            const json = await readJson(res, deadline);
+            return req.dialect === 'anthropic' ? parseAnthropicCompleteBody(json) : parseCompleteBody(json);
+        }), signal);
+    }
+    /**
+     * Streaming chat. Events flow to onEvent as they arrive; resolves with the assembled
+     * turn. Retried once on retryable failures, and only when nothing has been emitted yet
+     * (a mid-stream retry would duplicate text).
+     */
+    async chat(req, onEvent, signal) {
+        let emitted = false;
+        const wrap = (e) => {
+            emitted = true;
+            onEvent(e);
+        };
+        const attempt = () => withResponse(this.chatPath(req.dialect), {
+            method: 'POST',
+            headers: this.headers(req.dialect),
+            body: this.requestBody(req),
+        }, 300_000, signal, async (res, deadline) => {
+            if (!res.ok)
+                throw await routerErrorFromResponse(res.status, res, deadline);
+            if (!res.body)
+                throw new RouterError('The router returned an empty stream.');
+            const parser = req.dialect === 'anthropic' ? new AnthropicStreamParser() : new OpenAiStreamParser();
+            for await (const frame of sseFrames(res.body, deadline)) {
+                // Payloads and server-controlled event names can contain private content.
+                this.debug(`sse: bytes=${Buffer.byteLength(frame.data)}`);
+                if (req.dialect === 'openai' && frame.data.trim() === '[DONE]')
+                    break;
+                if (req.dialect === 'anthropic' && frame.event === 'message_stop') {
+                    const events = parser.push(frame.data);
+                    return { message: parser.assistantMessage(), stopReason: events[0]?.kind === 'stop' ? events[0].stopReason : 'unknown', usage: events[0]?.kind === 'stop' ? events[0].usage : undefined };
+                }
+                const events = parser.push(frame.data);
+                for (const e of events) {
+                    if (e.kind === 'stop') {
+                        return { message: parser.assistantMessage(), stopReason: e.stopReason, usage: e.usage };
+                    }
+                    wrap(e);
+                }
+            }
+            throw new RouterError('The router closed the response before it finished.');
+        });
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (emitted || !this.isRetryable(err))
+                throw err;
+            signal?.throwIfAborted();
+            await this.sleep(this.retryDelayMs(err), signal);
+            signal?.throwIfAborted();
+            return await attempt();
+        }
+    }
+    /**
+     * Exact token count via POST /v1/messages/count_tokens (Messages body only, free).
+     * Advisory: callers must fall back to estimation on any failure.
+     */
+    async countTokens(model, system, messages, tools, signal) {
+        const body = toAnthropicBody({
+            model,
+            dialect: 'anthropic',
+            messages,
+            system,
+            tools,
+            stream: false,
+        });
+        return await withResponse(this.rootUrl() + '/v1/messages/count_tokens', {
+            method: 'POST',
+            headers: this.headers('anthropic'),
+            body: JSON.stringify(body),
+        }, 30_000, signal, async (res, deadline) => {
+            if (!res.ok)
+                throw await routerErrorFromResponse(res.status, res, deadline);
+            const json = (await readJson(res, deadline));
+            if (typeof json.input_tokens !== 'number') {
+                throw new RouterError('count_tokens: unexpected response shape (no input_tokens).');
+            }
+            return json.input_tokens;
+        });
+    }
+    /** One retry for 429/502/503 and network failures; 400/401/403 pass through. */
+    async withRetry(attempt, signal) {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (!this.isRetryable(err))
+                throw err;
+            signal?.throwIfAborted();
+            await this.sleep(this.retryDelayMs(err), signal);
+            signal?.throwIfAborted();
+            return await attempt();
+        }
+    }
+    isRetryable(err) {
+        // A user abort (Ctrl+C) is never retried.
+        if (err instanceof DOMException && err.name === 'AbortError')
+            return false;
+        const e = err;
+        return (!e?.status ||
+            e.status === 429 ||
+            e.status === 502 ||
+            e.status === 503 ||
+            err instanceof TypeError // fetch network failure
+        );
+    }
+    retryDelayMs(err) {
+        if (err.retryAfterSeconds)
+            return err.retryAfterSeconds * 1000;
+        return err.status === 429 ? 2000 : 1000;
+    }
+    async sleep(ms, signal) {
+        signal?.throwIfAborted();
+        this.debug(`retrying after ${ms}ms`);
+        if (this.wait) {
+            await abortable(this.wait(ms), signal);
+            return;
+        }
+        let timer;
+        try {
+            await abortable(new Promise((resolve) => { timer = setTimeout(resolve, ms); }), signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export { routerErrorFromResponse, drainBody, bounded };

package/dist/clipboard.js

@@ -0,0 +1,72 @@
+// User-triggered macOS clipboard access only; never exposed as an agent tool.
+import { execFile } from 'node:child_process';
+import { imageFromBytes, MAX_IMAGE_BYTES } from "./images.js";
+// Fixed JXA reads AppKit's pasteboard directly. No shell, temp files, dependencies,
+// or clipboard-derived code/arguments. Screenshots commonly arrive as TIFF.
+export const CLIPBOARD_SCRIPT = `
+ObjC.import('AppKit');
+function encode(data) {
+  if (data.length > ${MAX_IMAGE_BYTES}) return JSON.stringify({ error: 'large' });
+  return JSON.stringify({ data: ObjC.unwrap(data.base64EncodedStringWithOptions(0)) });
+}
+function run() {
+  const board = $.NSPasteboard.generalPasteboard;
+  const png = board.dataForType($.NSPasteboardTypePNG);
+  if (png && !png.isNil()) return encode(png);
+  const tiff = board.dataForType($.NSPasteboardTypeTIFF);
+  if (!tiff || tiff.isNil()) return JSON.stringify({ error: 'empty' });
+  if (tiff.length > 40 * 1024 * 1024) return JSON.stringify({ error: 'large' });
+  const image = $.NSBitmapImageRep.imageRepWithData(tiff);
+  if (!image || image.isNil()) return JSON.stringify({ error: 'invalid' });
+  if (image.pixelsWide * image.pixelsHigh > 40000000) return JSON.stringify({ error: 'dimensions' });
+  const data = image.representationUsingTypeProperties($.NSBitmapImageFileTypePNG, $({}));
+  if (!data || data.isNil()) return JSON.stringify({ error: 'invalid' });
+  return encode(data);
+}
+`;
+const MAX_BASE64_LENGTH = Math.ceil(MAX_IMAGE_BYTES / 3) * 4;
+const unreadable = 'could not read the clipboard image — copy it again and press Ctrl+V';
+export function decodeClipboardImage(output) {
+    if (output.length > MAX_BASE64_LENGTH + 100)
+        throw new Error('clipboard image exceeds the 10 MiB attachment limit');
+    let result;
+    try {
+        result = JSON.parse(output);
+    }
+    catch {
+        throw new Error(unreadable);
+    }
+    if (!result || typeof result !== 'object')
+        throw new Error(unreadable);
+    const record = result;
+    if (record.error === 'empty')
+        throw new Error('no image in the clipboard — copy an image or use Ctrl+Cmd+Shift+4; Cmd+V pastes text');
+    if (record.error === 'large')
+        throw new Error('clipboard image exceeds the 10 MiB attachment limit');
+    if (record.error === 'dimensions')
+        throw new Error('clipboard image is too large to convert — copy a smaller screenshot');
+    if (typeof record.data !== 'string' || !record.data || /[^A-Za-z0-9+/=]/.test(record.data))
+        throw new Error(unreadable);
+    const bytes = Buffer.from(record.data, 'base64');
+    if (bytes.toString('base64') !== record.data)
+        throw new Error(unreadable);
+    return imageFromBytes(bytes, 'clipboard.png');
+}
+export async function readClipboardImage(signal) {
+    signal?.throwIfAborted();
+    if (process.platform !== 'darwin')
+        throw new Error('clipboard images are supported on macOS only');
+    const output = await new Promise((resolve, reject) => {
+        execFile('/usr/bin/osascript', ['-l', 'JavaScript', '-e', CLIPBOARD_SCRIPT], {
+            encoding: 'utf8', shell: false, timeout: 10_000,
+            maxBuffer: MAX_BASE64_LENGTH + 1024, signal,
+        }, (err, stdout) => {
+            if (err)
+                reject(signal?.aborted ? signal.reason : new Error(unreadable));
+            else
+                resolve(stdout);
+        });
+    });
+    signal?.throwIfAborted();
+    return decodeClipboardImage(output);
+}