@actor0/harness 0.0.0-stage → 0.5.2

package/dist/model-client.js

@@ -0,0 +1,654 @@
+export class ModelTransportError extends Error {
+    retriable;
+    retryAfterMs;
+    /**
+     * @param retryAfterMs how long the server asked us to wait, when it said.
+     *   A retriable error that carries one has a floor under its next attempt:
+     *   see `retryDelay` in harness.ts.
+     */
+    constructor(message, retriable = false, retryAfterMs) {
+        super(message);
+        this.retriable = retriable;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "ModelTransportError";
+    }
+}
+/**
+ * The longest server-requested wait this harness will sit through.
+ *
+ * A windowed rate limit can name a reset twenty minutes out. Honouring that
+ * in a terminal means the turn disappears for twenty minutes with nothing on
+ * screen, which the user reads as a hang; ignoring it means the retries land
+ * inside the window and the turn fails having proved nothing. So the wait is
+ * honoured up to here, and past it the failure is surfaced instead, with the
+ * time the limit lifts in the message the user reads.
+ */
+export const MAX_HONOURED_RETRY_AFTER_MS = 120_000;
+/**
+ * How long the server asked us to wait, in milliseconds.
+ *
+ * `Retry-After` is a count of seconds per RFC 9110, and an HTTP-date in the
+ * dialect several providers actually send. Both are honoured; a value that is
+ * neither is ignored rather than guessed at, because a misread directive is
+ * worse than no directive.
+ */
+export function retryAfterMs(headers, now = Date.now()) {
+    const value = headers.get("retry-after")?.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1_000;
+    // `Date.parse` is a parser for humans and it is lenient: "-5" comes back as
+    // April 2001 and "12.5.6" as December 2006, both of which would be read as a
+    // reset that has already passed and turn a server that said nothing usable
+    // into a claim that it asked us to come back immediately. Every one of the
+    // three date formats HTTP allows begins with a weekday, so that is the gate.
+    if (!/^(?:mon|tue|wed|thu|fri|sat|sun)/i.test(value))
+        return undefined;
+    const at = Date.parse(value);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - now);
+}
+export class OpenAiCompatibleModel {
+    endpoint;
+    apiKey;
+    model;
+    fetchImpl;
+    headers;
+    reasoningEffort;
+    constructor(options) {
+        if (!options.model.trim())
+            throw new Error("model is required");
+        const url = new URL(options.baseUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error("base URL must use http or https");
+        const explicitPath = options.path?.trim();
+        if (explicitPath) {
+            url.pathname = explicitPath.startsWith("/") ? explicitPath : `/${explicitPath}`;
+        }
+        else {
+            url.pathname = url.pathname.replace(/\/+$/, "");
+            if (!url.pathname.endsWith("/chat/completions"))
+                url.pathname = `${url.pathname}/chat/completions`;
+        }
+        url.search = "";
+        url.hash = "";
+        this.endpoint = url.toString();
+        this.apiKey = options.apiKey?.trim() || undefined;
+        this.model = options.model.trim();
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.headers = options.headers ?? {};
+        this.reasoningEffort = options.reasoningEffort;
+    }
+    async *stream(messages, tools, signal) {
+        let response;
+        try {
+            response = await this.fetchImpl(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "text/event-stream",
+                    ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+                    ...this.headers,
+                },
+                body: JSON.stringify({ model: this.model, messages, stream: true, tools, ...(this.reasoningEffort ? { reasoning_effort: this.reasoningEffort } : {}) }),
+                signal,
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            throw new ModelTransportError(`network request failed: ${errorMessage(error)}`, true);
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            const wait = retryAfterMs(response.headers);
+            // A rate limit whose reset is beyond anything worth waiting out is not
+            // retriable: the retries would land inside the window and only prove
+            // the limit is still in force.
+            const transient = response.status === 429 || response.status >= 500;
+            const retriable = transient && (wait === undefined || wait <= MAX_HONOURED_RETRY_AFTER_MS);
+            throw new ModelTransportError(describeHttpFailure(this.endpoint, response, text, retriable, wait), retriable, wait);
+        }
+        // A 200 carrying an HTML page is the same failure as a 500 carrying one,
+        // and it is the worse of the two: read as a stream it has no `data:` frames,
+        // so the turn produced no answer, no tool call and no error — a silent empty
+        // reply. A response that *claims* to be an event stream is taken at its
+        // word; anything else has its head sniffed, because that is cheap and the
+        // cost of guessing wrong is an empty answer with no explanation.
+        const contentType = response.headers.get("content-type");
+        if (!isEventStream(contentType)) {
+            const head = await response.clone().text().catch(() => "");
+            if (looksLikeHtml(contentType, head)) {
+                throw new ModelTransportError(`${this.endpoint} answered 200 with an HTML page, not an event stream. ` +
+                    `That is a platform-level error rather than a model failure. The harness will retry with backoff.`, true);
+            }
+        }
+        if (!response.body)
+            throw new ModelTransportError("response has no body", true);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        const calls = new ToolCallBuffer();
+        let buffer = "";
+        let sawDone = false;
+        // Frames are handed on one at a time, in order, rather than collected and
+        // yielded afterwards. A single network chunk routinely carries several
+        // frames, and one of them can be the last thing a stream ever sends: when
+        // the frames of a chunk were buffered and only yielded once the whole
+        // chunk had been handled, an error frame in that chunk threw first and
+        // took every token before it with it — the model answered, the tokens
+        // were already paid for, and the user was shown nothing.
+        const endpoint = this.endpoint;
+        let truncation;
+        const frames = async function* (parsed) {
+            for (const frame of parsed) {
+                if (frame.done) {
+                    sawDone = true;
+                    continue;
+                }
+                // First truncation wins. Servers repeat the reason on the final
+                // frame, and a later `stop` (or a second stream) must not overwrite
+                // the fact that this answer was cut short.
+                if (truncation === undefined && frame.finishReason !== undefined && TRUNCATION_REASONS.has(frame.finishReason)) {
+                    truncation = frame.finishReason;
+                }
+                if (frame.hasError)
+                    throw streamFrameError(endpoint, frame);
+                if (frame.toolCalls)
+                    calls.push(frame.toolCalls);
+                if (frame.content)
+                    yield { type: "token", delta: frame.content };
+                if (frame.reasoning)
+                    yield { type: "reasoning", delta: frame.reasoning };
+                if (frame.completeToolCalls) {
+                    for (const call of frame.completeToolCalls)
+                        yield { type: "tool_call", tool_calls: [call] };
+                }
+                if (frame.usage)
+                    yield { type: "usage", usage: frame.usage };
+            }
+        };
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const parsed = drainFrames(buffer);
+                buffer = parsed.rest;
+                yield* frames(parsed.frames);
+            }
+            buffer += decoder.decode();
+            const parsedTail = drainFrames(buffer);
+            yield* frames(parsedTail.frames);
+            const completeCalls = calls.finish();
+            if (completeCalls.length > 0)
+                yield { type: "tool_call", tool_calls: completeCalls };
+            // A cut-off answer still ends the stream, so it is still a `done` —
+            // one that says what it is. Emitted even without a `[DONE]` frame,
+            // because the reason arrived and is not going to arrive again.
+            if (sawDone || truncation !== undefined) {
+                yield truncation === undefined
+                    ? { type: "done" }
+                    : { type: "done", truncated: true, reason: truncation };
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+    }
+}
+class ToolCallBuffer {
+    calls = new Map();
+    push(deltas) {
+        for (const [position, delta] of deltas.entries()) {
+            const index = Number.isInteger(delta.index) ? Number(delta.index) : this.calls.size || position;
+            const current = this.calls.get(index) ?? { id: "", type: "function", function: { name: "", arguments: "" } };
+            if (delta.id)
+                current.id = delta.id;
+            if (delta.type)
+                current.type = delta.type;
+            if (delta.function?.name)
+                current.function.name += delta.function.name;
+            if (delta.function?.arguments)
+                current.function.arguments += delta.function.arguments;
+            this.calls.set(index, current);
+        }
+    }
+    finish() {
+        return [...this.calls.entries()].sort(([a], [b]) => a - b).map(([index, call], position) => ({ ...call, id: call.id || `call_${index}_${position}` }));
+    }
+}
+/**
+ * Split an SSE buffer into whole frames. Pure: nothing is thrown, nothing is
+ * emitted, and the caller decides what each frame means and in what order. A
+ * parser that also ran the frames had to buffer them, which is how a frame
+ * that failed to be yielded ended up discarded along with the ones before it.
+ */
+function drainFrames(buffer) {
+    const frames = [];
+    let rest = buffer;
+    const handleFrame = (frame) => {
+        frames.push(frame);
+    };
+    while (true) {
+        const boundary = findBoundary(rest);
+        if (!boundary)
+            break;
+        const block = rest.slice(0, boundary.index);
+        rest = rest.slice(boundary.index + boundary.length);
+        const data = block.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).filter(Boolean).join("\n");
+        if (!data)
+            continue;
+        if (data === "[DONE]") {
+            handleFrame({ done: true });
+            continue;
+        }
+        let value;
+        try {
+            value = JSON.parse(data);
+        }
+        catch {
+            throw new ModelTransportError("endpoint returned invalid SSE JSON", true);
+        }
+        const choices = value.choices;
+        const choice = Array.isArray(choices) && choices.length > 0 && typeof choices[0] === "object" && choices[0] !== null
+            ? choices[0]
+            : undefined;
+        const delta = choice?.delta;
+        handleFrame({ finishReason: finishReasonOf(choice, value), content: typeof delta?.content === "string" ? delta.content : undefined, reasoning: typeof delta?.reasoning_content === "string" ? delta.reasoning_content : typeof delta?.reasoning === "string" ? delta.reasoning : undefined, toolCalls: Array.isArray(delta?.tool_calls) ? delta.tool_calls : undefined, completeToolCalls: Array.isArray(value.tool_calls) ? value.tool_calls : undefined, usage: value.usage, ...errorFields(value) });
+    }
+    return { frames, rest };
+}
+/**
+ * The endpoint's reason for stopping, in whichever of the spellings it uses.
+ *
+ * OpenAI-compatible servers put `finish_reason` on the choice; the
+ * Anthropic-shaped streams actor0 also reads put `stop_reason` on the
+ * message; relays copy either onto the top level. All three are read
+ * because the one that is missing reads as "the model finished", which is
+ * the exact belief this path exists to break — a stream cut off by the
+ * output cap is otherwise indistinguishable from a stream that ended.
+ */
+function finishReasonOf(choice, value) {
+    for (const candidate of [choice?.finish_reason, choice?.stop_reason, value.stop_reason, value.finish_reason]) {
+        if (typeof candidate === "string" && candidate)
+            return candidate.toLowerCase();
+    }
+    return undefined;
+}
+/**
+ * Reasons that mean "this answer was cut off", not "this answer is done".
+ *
+ * `length` is OpenAI's spelling of the output-token cap, `max_tokens` is
+ * Anthropic's, and `model_context_window_exceeded` is what the same API
+ * emits when the model's own window ran out mid-generation. They differ in
+ * which limit was hit and not at all in what a caller must do about it:
+ * the text so far is the start of an answer, and asking again is how the
+ * rest of it arrives. `content_filter` is deliberately absent — a cut made
+ * by a filter is not resumed by being asked again.
+ */
+const TRUNCATION_REASONS = new Set([
+    "length",
+    "max_tokens",
+    "model_length",
+    "model_context_window_exceeded",
+]);
+function findBoundary(buffer) {
+    const lf = buffer.indexOf("\n\n");
+    const crlf = buffer.indexOf("\r\n\r\n");
+    if (lf === -1 && crlf === -1)
+        return null;
+    if (crlf !== -1 && (lf === -1 || crlf < lf))
+        return { index: crlf, length: 4 };
+    return { index: lf, length: 2 };
+}
+/**
+ * True when a response is an HTML document rather than a stream or a JSON
+ * error. Gateways, edge runtimes and bot checks all answer this way, and none
+ * of them say so in the body: the caller has to read the shape.
+ */
+export function looksLikeHtml(contentType, body) {
+    if (contentType && /\btext\/html\b|\bapplication\/xhtml/i.test(contentType))
+        return true;
+    // A declared type that is merely wrong must not veto the body. Gateways
+    // routinely answer an error page as `text/plain`, and trusting the header
+    // there is how a 200 carrying HTML turned into a silent empty answer.
+    return body !== null && /^\s*(?:<!doctype\s+html|<html[\s>])/i.test(body);
+} /** True when the response claims to be the event stream we asked for. */
+function isEventStream(contentType) {
+    return contentType !== null && /\btext\/event-stream\b/i.test(contentType);
+}
+/**
+ * The identifying fields of an in-stream error frame.
+ *
+ * Presence and text are separate. `{"error": "upstream reset"}` and
+ * `{"error": {}}` are both errors and only the first carries a message, so
+ * gating on the message is what let `{"error": {}}` through as silence: the
+ * stream ended, the turn finished with no answer, no tool call and no stated
+ * reason — the same silent empty reply a 200 carrying HTML produces.
+ */
+function errorFields(value) {
+    const field = value.error;
+    if (field === undefined || field === null)
+        return { hasError: false };
+    if (typeof field !== "object") {
+        return { hasError: true, error: typeof field === "string" && field ? field : undefined };
+    }
+    const record = field;
+    const text = (key) => typeof record[key] === "string" ? record[key] : undefined;
+    return { hasError: true, error: text("message"), errorCode: text("code"), errorType: text("type") };
+}
+/**
+ * Whether an error delivered *inside* a 200 response can be fixed by asking
+ * again.
+ *
+ * A 200 means the request was accepted, so the status classification above
+ * never runs — there is no status left to read. Everything then arrives in
+ * one shape, `data: {"error": {...}}`: a dropped upstream connection, a rate
+ * limit, a rejected key, a request that does not fit the context window.
+ * Calling all of them retriable, which is what this did, replays a
+ * deterministic failure three times with 1s/2s/4s of backoff, at four times the
+ * token cost, and ends in exactly the same error.
+ *
+ * Code and type are read first because they are exact, and because they are
+ * the part OpenAI, Anthropic, Gemini and OpenRouter all agree on. The message
+ * is the fallback for the servers that send neither. An unrecognised error
+ * stays retriable: a stream that died mid-flight is far more often a dropped
+ * connection than a request the server will never accept, and guessing wrong
+ * in that direction costs one wasted attempt, while guessing wrong the other
+ * way refuses to start the turn at all.
+ */
+export function isRetriableStreamError(message, code, type) {
+    if (code && RETRIABLE_STREAM_CODES.test(code))
+        return true;
+    if (code && PERMANENT_STREAM_CODES.test(code))
+        return false;
+    if (type && RETRIABLE_STREAM_CODES.test(type))
+        return true;
+    if (type && PERMANENT_STREAM_TYPES.test(type))
+        return false;
+    if (isContextOverflow(message))
+        return false;
+    if (PERMANENT_STREAM_TEXT.test(message))
+        return false;
+    return true;
+}
+/**
+ * Is this failure the conversation not fitting the model?
+ *
+ * Named because it is the one transport failure with a real recovery, and
+ * recovery is not the transport layer's job: the caller has to shorten the
+ * history and ask again, which is a decision about the conversation.
+ */
+export function isContextOverflow(message) {
+    return OVERFLOW_TEXT.test(message);
+}
+/**
+ * Is this thrown value the model saying the request is too big?
+ *
+ * Asked of the error rather than of the message so a host does not have to
+ * know which layer raised it, or re-derive that a retriable failure of the
+ * same shape must not be compacted around. Both spellings land here: a 400
+ * whose body is the diagnosis, and an error frame inside a 200.
+ */
+/**
+ * A request the endpoint will never accept, however often it is
+ * sent — the one transport failure with a host-level recovery
+ * (compact the history and ask again), which is why this is a
+ * classifier and not just a message match.
+ *
+ * It also looks through a `FailedTurnError`: a turn that failed
+ * mid-flight wraps the transport error that ended it (see
+ * `failedTurn`), and without the unwrap every such failure reads
+ * as an unknown error, so the recovery never fires and a turn the
+ * endpoint merely refused rewinds the session instead of being
+ * asked again. That makes the return a plain boolean rather than
+ * a type predicate — in the wrapped case the error is a
+ * `FailedTurnError`, not the `ModelTransportError` the old
+ * signature claimed — and its one caller reads it as a gate.
+ */
+export function isContextOverflowError(error) {
+    const transport = transportError(error);
+    return transport !== undefined && !transport.retriable && isContextOverflow(transport.message);
+}
+/**
+ * The context window the endpoint said it has, in tokens, or undefined.
+ *
+ * The overflow message is not only a diagnosis, it is the one measurement of
+ * the limit the provider will ever volunteer, and reading it as a boolean
+ * throws the number away. A host recovering from an overflow has to decide
+ * how much history to keep, and a guess cannot be smaller than the truth: on
+ * a 4k-window model a recovery that targets 8,000 tokens does not fit by
+ * construction, and the one replay it is allowed fails exactly like the
+ * request it was meant to fix.
+ *
+ * Anchored on the number *and* the word "token" on purpose. The messages that
+ * carry a limit also carry the count that broke it — "your messages resulted
+ * in 91234 tokens" — and a looser pattern reads the wrong number, which is
+ * worse than reading none. A per-message char limit is not a window and is
+ * not returned for one; `OVERFLOW_TEXT` matches that shape too, deliberately,
+ * because it is a different failure with its own advice.
+ *
+ * Returned only for a failure that is a real refusal, so a retriable error
+ * carrying a similar string cannot talk a host into compacting a turn that
+ * was never the problem.
+ */
+export function contextWindowTokens(error) {
+    const transport = transportError(error);
+    if (!transport || transport.retriable)
+        return undefined;
+    const found = CONTEXT_WINDOW_TEXT.exec(transport.message);
+    // Two shapes, so two groups; whichever matched is the window.
+    const digits = found?.[1] ?? found?.[2];
+    if (!digits)
+        return undefined;
+    const tokens = Number.parseInt(digits.replace(/[,_]/g, ""), 10);
+    return Number.isFinite(tokens) && tokens > 0 ? tokens : undefined;
+}
+/** The transport error a thrown value carries, however deeply it was wrapped. */
+function transportError(error) {
+    if (error instanceof ModelTransportError)
+        return error;
+    const wrapped = error?.cause;
+    return wrapped instanceof ModelTransportError ? wrapped : undefined;
+}
+/** The in-stream error as a failure a person can act on. */
+function streamFrameError(endpoint, frame) {
+    const message = frame.error ?? "";
+    const retriable = isRetriableStreamError(message, frame.errorCode, frame.errorType);
+    const advice = !retriable && isContextOverflow(message) ? OVERFLOW_ADVICE : undefined;
+    const detail = frame.error ? `: ${frame.error}` : " and gave no message";
+    return new ModelTransportError(`${endpoint} ended the stream with an error${detail}. ${retryAdvice(retriable, advice)}`, retriable);
+}
+/**
+ * Codes and types that name a transient fault. Matched loosely because
+ * providers disagree on separator and wording: `rate_limit_exceeded`,
+ * `rate limit`, `too_many_requests`, `overloaded_error`, `server_error`.
+ */
+const RETRIABLE_STREAM_CODES = /\b(?:rate[_\s-]?limit(?:ed)?|too[_\s-]?many[_\s-]?requests|429|server[_\s-]?error|internal[_\s-]?error|overloaded(?:[_\s-]?error)?|api[_\s-]?error|service[_\s-]?unavailable|temporarily[_\s-]?unavailable|bad[_\s-]?gateway|upstream[_\s-]?error|capacity[_\s-]?exceeded|timeout|timed[_\s-]?out|transient)\b/i;
+/** Codes that name a request the server will never accept, however often it is sent. */
+const PERMANENT_STREAM_CODES = /\b(?:context[_\s-]?length[_\s-]?exceeded|context[_\s-]?window[_\s-]?exceeded|prompt[_\s-]?too[_\s-]?long|request[_\s-]?too[_\s-]?large|payload[_\s-]?too[_\s-]?large|invalid[_\s-]?api[_\s-]?key|invalid[_\s-]?authentication|permission[_\s-]?denied|insufficient[_\s-]?quota|quota[_\s-]?exceeded|billing[_\s-]?hard[_\s-]?limit[_\s-]?reached|account[_\s-]?deactivated|model[_\s-]?not[_\s-]?found|model[_\s-]?not[_\s-]?available|invalid[_\s-]?model|content[_\s-]?policy[_\s-]?violation)\b/i;
+/**
+ * Types, which are coarser than codes. `invalid_request_error` is OpenAI's
+ * 400, and `insufficient_quota` is a rate-limit-shaped failure that is
+ * actually about the account rather than the request; neither improves on a
+ * third attempt.
+ */
+const PERMANENT_STREAM_TYPES = /\b(?:invalid[_\s-]?request(?:[_\s-]?error)?|authentication[_\s-]?error|permission[_\s-]?error|not[_\s-]?found[_\s-]?error|billing[_\s-]?error|account[_\s-]?error|insufficient[_\s-]?quota|request[_\s-]?too[_\s-]?large)\b/i;
+/**
+ * Text that means "this conversation does not fit", across the providers that
+ * say it.
+ *
+ * Every provider words this differently and no two agree: Anthropic says
+ * `prompt is too long: 137500 tokens > 135000 maximum`, vLLM and DeepSeek say
+ * `This model's maximum context length is 32768 tokens. However, your
+ * messages resulted in 40000 tokens`, Groq says `Requested token count
+ * exceeds the model's maximum context length`, and OpenAI puts the diagnosis
+ * in the code while the message says only `Please reduce the length of the
+ * messages`.
+ *
+ * The first four clauses of this pattern were written against a provider that
+ * does not serve this CLI. They match, and the four tests that cover them
+ * pass, and none of them is a string the endpoint has ever sent — so the
+ * whole overflow recovery path was unreachable in production: a real request
+ * that did not fit came back as a bare failure, with no compaction, no retry,
+ * and the raw body as the only clue.
+ *
+ * The last two clauses are what it actually answers, measured against
+ * `https://aestral-chat.vercel.app/api/chat`: a 400 carrying exactly
+ * `{"error":"Message too large (50k char limit)"}`. The limit is 50,000
+ * characters per message, not per request and not in tokens, which is a
+ * different failure from the one the rest of this pattern describes and needs
+ * its own words rather than a shared one.
+ *
+ * `message too large` and not a bare `too large`, on purpose: "output too
+ * large" is a truncated answer, not a conversation that does not fit, and
+ * reading it as an overflow would compact the history and ask again for a
+ * request that was never the problem.
+ */
+const OVERFLOW_TEXT = /\b(?:maximum context length|context length|context[_\s-]?length|context window|context size|prompt is too long|prompt too long|input is too long|input length|exceeds the (?:model'?s? )?maximum|exceeds the available|requested token count exceeds|messages resulted in|reduce the length of the messages|request entity too large|too many tokens|token limit|char(?:acter)?s? limit|message too large)\b/i;
+/** Message text for the permanent failures that arrive without a code. */
+const PERMANENT_STREAM_TEXT = /\b(?:invalid api key|incorrect api key|api key (?:is )?(?:invalid|missing|expired)|no api key|unauthori[sz]ed|invalid authentication|permission denied|insufficient (?:quota|credit|balance)|quota exceeded|out of credits|payment required|model (?:not found|does not exist|is not available)|account (?:is )?(?:deactivated|suspended)|content policy)\b/i;
+/**
+ * The two shapes an endpoint states its window in, both naming tokens.
+ *
+ * "maximum context length is 8192 tokens" is OpenAI's and the most common
+ * form; the reversed "exceeds the 8192-token context window" is vLLM and
+ * friends. Neither clause reaches across a sentence boundary, so the count
+ * that broke the request — which lives in the next sentence, and is larger —
+ * cannot be mistaken for the window.
+ */
+const CONTEXT_WINDOW_TEXT = /\b(?:maximum context (?:length|window)|context (?:length|window|size))\b[^.\d]{0,32}?([\d][\d,_]*)\s*tokens?\b|\b([\d][\d,_]*)\s*tokens?\b[^.\d]{0,24}?context window\b/i;
+const OVERFLOW_ADVICE = "Retrying will not help — this conversation does not fit the model's context window. Start a new one with /clear, or switch to a model with a larger window.";
+/** The closing line of a failure, derived from what actually happens next. */
+function retryAdvice(retriable, permanentAdvice) {
+    if (retriable)
+        return "The harness will retry with backoff.";
+    return permanentAdvice ?? "Retrying will not help — check the URL, the key, and the model name.";
+}
+/**
+ * A failure message a person can act on.
+ *
+ * The endpoint is included because "request failed" tells the reader nothing
+ * when three of them are configured, and the status because a body alone
+ * cannot distinguish a rate limit from a crash. An HTML body is summarised
+ * rather than quoted: the previous behaviour pasted its first 600 characters
+ * into the transcript, which buried a one-line diagnosis under a wall of markup
+ * and still omitted the two facts that would have identified the fault.
+ *
+ * The closing line is derived from `retriable`, never from a guess about what
+ * "usually" happens. Telling someone a 403 will be retried when it will not is
+ * worse than saying nothing, because they wait for a retry that never comes.
+ *
+ * The URL is safe to print — the constructor clears any query string, so a key
+ * passed as a query parameter is already gone by this point.
+ */
+export function describeHttpFailure(endpoint, response, body, retriable, retryAfterMs) {
+    const status = `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
+    const contentType = response.headers.get("content-type") ?? "no content-type";
+    const head = `${status} from ${endpoint} (${contentType})`;
+    // The closing line goes on this path too. It used to be attached only to
+    // the shapeless-body case below, which meant that a provider that sends a
+    // tidy one-line error -- the common case, and the one a user is most likely
+    // to read -- got no statement of what happens next at all. That is the thing
+    // this function exists to say.
+    const detail = parseErrorMessage(body);
+    const misconfigured = misconfigurationAdvice(response.status);
+    if (detail)
+        return `${head}: ${detail.replace(/[.\s]+$/, "")}. ${closeLine(retriable, retryAfterMs, misconfigured)}`;
+    // Nothing usable in the body. Say what shape arrived instead of quoting it.
+    const html = looksLikeHtml(response.headers.get("content-type"), body);
+    const server = response.status >= 500;
+    const shape = html
+        ? server
+            ? "it answered with an HTML error page, which means the server or its platform failed before the route ran"
+            : "it answered with an HTML page, which usually means a login wall, a bot check, or the wrong URL"
+        : body.trim()
+            ? `it answered with a body that is not a usable error (${contentType}, ${body.length} bytes)`
+            : `it answered with an empty body (${contentType})`;
+    return `${head}: ${shape}. ${closeLine(retriable, retryAfterMs, misconfigured)}`;
+}
+/**
+ * What a status means when the endpoint is one the user chose.
+ *
+ * The two failures a misconfigured endpoint produces every single time are a
+ * rejected credential and a URL that is not there, and both arrive wrapped in
+ * a tidy provider sentence describing the *server's* opinion: "Invalid API
+ * key", "Not Found". That is accurate and useless, because the user needs to
+ * know that the thing to check is the configuration they just wrote rather
+ * than the model they asked for — a distinction the body never makes and the
+ * status always does.
+ *
+ * A complete closing line, not a prefix, because it *replaces* the generic
+ * one rather than preceding it. Appended to the fallback it contradicted
+ * itself: the message said to check the key and, in the next sentence, to
+ * check the URL, the key *and the model* — sending the user past the one thing
+ * that was actually wrong.
+ *
+ * Said without naming a mechanism to fix it, so the transport stays a
+ * transport. Which knob to turn is the host's business.
+ */
+function misconfigurationAdvice(status) {
+    switch (status) {
+        case 401:
+        case 403:
+            return "The endpoint rejected the credential — the API key for this endpoint is missing, wrong, or expired. Retrying will not help.";
+        case 404:
+            return "There is no OpenAI-compatible chat endpoint at that URL and path — check the base URL, and whether the path is /chat/completions. Retrying will not help.";
+        case 400:
+            return "The endpoint rejected the request itself — if this is not an OpenAI-compatible API, it may need a different path. Retrying will not help.";
+        default:
+            return undefined;
+    }
+}
+/**
+ * What happens next, said plainly.
+ *
+ * A rate limit with a reset time is neither of the two defaults: it will be
+ * waited out, and the wait is the server's number rather than the harness's.
+ * Saying "the harness will retry with backoff" about a window that resets in
+ * forty minutes is advice the reader will act on and find false.
+ */
+function closeLine(retriable, wait, permanentAdvice) {
+    if (wait === undefined)
+        return retryAdvice(retriable, permanentAdvice);
+    const seconds = Math.ceil(wait / 1_000);
+    return retriable
+        ? `Rate limited: the harness will wait ${seconds}s and try again.`
+        : `Rate limited until the window resets in about ${seconds}s. The harness will not keep retrying before then.`;
+}
+function parseErrorMessage(body) {
+    if (!body.trim())
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        // Not JSON. An HTML page is never worth quoting, and a truncated JSON
+        // document is a symptom rather than a message. A short, printable,
+        // non-brace-prefixed body is a real message and is worth keeping.
+        if (looksLikeHtml(null, body))
+            return undefined;
+        const text = body.trim();
+        if (/^[{[]/.test(text))
+            return undefined;
+        // eslint-disable-next-line no-control-regex -- this range is a screenful of C0 control characters, and detecting them is the point
+        if (text.length <= 300 && !/[\u0000-\u0008\u000e-\u001f]/.test(text))
+            return text;
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.error === "string")
+        return record.error;
+    if (typeof record.error?.message === "string")
+        return record.error.message;
+    if (typeof record.message === "string")
+        return record.message;
+    if (typeof record.detail === "string")
+        return record.detail;
+    return undefined;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/plan-prefix.d.ts

@@ -0,0 +1,8 @@
+import type { PlanPrefix } from "./types.js";
+export declare function parsePlanPrefix(buffer: string): PlanPrefix | null;
+export declare function needsMorePlanData(buffer: string): boolean;
+export declare function extractPlanPrefix(buffer: string): {
+    plan: PlanPrefix | null;
+    rest: string;
+};
+//# sourceMappingURL=plan-prefix.d.ts.map

package/dist/plan-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-prefix.d.ts","sourceRoot":"","sources":["../src/plan-prefix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAa7C,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA2BjE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMzD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAK3F"}