@celestea/core 2.7.1

package/dist/skills.d.ts

@@ -0,0 +1,116 @@
+/**
+ * W882 — skill discovery over the two-layer source model (celestea-sources.ts).
+ *
+ * A "skill" is a directory skills/<name>/SKILL.md. The file starts with YAML
+ * frontmatter; the rest is the BODY. Discovery is a pure walk over the layers
+ * [project, global] (project WINS on a name collision). Parsing is a pure
+ * function; the filesystem lives behind the tiny SkillIo seam so the parser and
+ * the precedence rules are unit-testable without touching disk.
+ *
+ * Frontmatter contract (mirrors anthropics/skills):
+ *   - whitelist: name / description / license / allowed-tools / compatibility /
+ *     metadata. ANY unknown key REJECTS the skill with a readable reason.
+ *   - name must equal the directory name, match ^[a-z0-9-]+$ and be <= 64 chars.
+ *   - description is REQUIRED, <= 1024 chars, and must not contain < or >.
+ *     Write it as a TRIGGER sentence ("Use this skill whenever ...").
+ *   - compatibility <= 500 chars.
+ *
+ * Progressive disclosure: loadSkillBody() returns the SKILL.md BODY ONLY. A
+ * skill's child resources (references/, scripts/) are NEVER auto-loaded; the
+ * model must explicitly read them. W882 adds NO tool and does NOT inject any
+ * skill text into a prompt — this module is discovery + lookup only.
+ */
+import { type SourceLayer, type SourceName } from "./celestea-sources.js";
+/** Allowed name shape. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/** name <= 64 chars. */
+export declare const SKILL_NAME_MAX = 64;
+/** description <= 1024 chars. */
+export declare const SKILL_DESCRIPTION_MAX = 1024;
+/** compatibility <= 500 chars. */
+export declare const SKILL_COMPATIBILITY_MAX = 500;
+/** The ONLY frontmatter keys a skill may declare. */
+export declare const SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "license", "allowed-tools", "compatibility", "metadata"];
+export type SkillMetadata = Record<string, string>;
+export interface ParsedSkillFrontmatter {
+    name: string | null;
+    description: string | null;
+    license: string | null;
+    allowedTools: string[];
+    compatibility: string | null;
+    metadata: SkillMetadata;
+}
+export interface SkillDefinition extends ParsedSkillFrontmatter {
+    name: string;
+    description: string;
+    source: SourceName;
+    dir: string;
+    file: string;
+}
+export interface SkillLocation {
+    name: string;
+    dir: string;
+    file: string;
+    source: SourceName;
+}
+export interface SkillRejection extends SkillLocation {
+    reason: string;
+}
+export interface SkillListing {
+    skills: SkillDefinition[];
+    rejected: SkillRejection[];
+}
+export type FrontmatterParse = {
+    ok: true;
+    data: ParsedSkillFrontmatter;
+    body: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type SkillValidation = {
+    ok: true;
+    skill: SkillDefinition;
+} | {
+    ok: false;
+    reason: SkillRejection;
+};
+export type SkillLoad = {
+    ok: true;
+    skill: SkillDefinition;
+    body: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** The thin filesystem seam: the only impure surface of this module. */
+export interface SkillIo {
+    listDirectories(dir: string): string[];
+    readText(file: string): string | null;
+}
+/** Real filesystem; every error (missing root, missing file) reads as "absent". */
+export declare const nodeSkillIo: SkillIo;
+/**
+ * Parse the leading YAML frontmatter of a SKILL.md. PURE. Returns the parsed
+ * whitelist fields plus the body (everything after the closing delimiter). An
+ * unknown key is an ERROR, never silently ignored.
+ */
+export declare function parseSkillFrontmatter(text: string): FrontmatterParse;
+/**
+ * Validate the parsed frontmatter against the anthropics/skills contract.
+ * location.name is the DIRECTORY name; the frontmatter name must equal it.
+ */
+export declare function validateSkill(data: ParsedSkillFrontmatter, location: SkillLocation): SkillValidation;
+/**
+ * Discover every skill in the layers, HIGHEST PRIORITY FIRST. The first layer to
+ * define a name wins; a lower layer is not even parsed for that name. A rejected
+ * project skill therefore shadows (and does not fall back to) a global one, so a
+ * broken override is visible instead of silent. Absent roots are not an error.
+ */
+export declare function listSkills(layers: readonly SourceLayer[], io?: SkillIo): SkillListing;
+/**
+ * The BODY of one named skill, from the first layer that defines it. Returns the
+ * SKILL.md body only — child resources are never auto-loaded (progressive
+ * disclosure). The name must already be a valid skill name (no path traversal).
+ */
+export declare function loadSkillBody(layers: readonly SourceLayer[], name: string, io?: SkillIo): SkillLoad;

package/dist/skills.js

@@ -0,0 +1,273 @@
+/**
+ * W882 — skill discovery over the two-layer source model (celestea-sources.ts).
+ *
+ * A "skill" is a directory skills/<name>/SKILL.md. The file starts with YAML
+ * frontmatter; the rest is the BODY. Discovery is a pure walk over the layers
+ * [project, global] (project WINS on a name collision). Parsing is a pure
+ * function; the filesystem lives behind the tiny SkillIo seam so the parser and
+ * the precedence rules are unit-testable without touching disk.
+ *
+ * Frontmatter contract (mirrors anthropics/skills):
+ *   - whitelist: name / description / license / allowed-tools / compatibility /
+ *     metadata. ANY unknown key REJECTS the skill with a readable reason.
+ *   - name must equal the directory name, match ^[a-z0-9-]+$ and be <= 64 chars.
+ *   - description is REQUIRED, <= 1024 chars, and must not contain < or >.
+ *     Write it as a TRIGGER sentence ("Use this skill whenever ...").
+ *   - compatibility <= 500 chars.
+ *
+ * Progressive disclosure: loadSkillBody() returns the SKILL.md BODY ONLY. A
+ * skill's child resources (references/, scripts/) are NEVER auto-loaded; the
+ * model must explicitly read them. W882 adds NO tool and does NOT inject any
+ * skill text into a prompt — this module is discovery + lookup only.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { SKILL_FILE_NAME, SKILLS_SUBDIR } from "./celestea-sources.js";
+/** Allowed name shape. */
+export const SKILL_NAME_PATTERN = /^[a-z0-9-]+$/;
+/** name <= 64 chars. */
+export const SKILL_NAME_MAX = 64;
+/** description <= 1024 chars. */
+export const SKILL_DESCRIPTION_MAX = 1024;
+/** compatibility <= 500 chars. */
+export const SKILL_COMPATIBILITY_MAX = 500;
+/** The ONLY frontmatter keys a skill may declare. */
+export const SKILL_FRONTMATTER_KEYS = ["name", "description", "license", "allowed-tools", "compatibility", "metadata"];
+/** Real filesystem; every error (missing root, missing file) reads as "absent". */
+export const nodeSkillIo = {
+    listDirectories(dir) {
+        try {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        }
+        catch {
+            return [];
+        }
+    },
+    readText(file) {
+        try {
+            return readFileSync(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+};
+const ALLOWED_KEYS = new Set(SKILL_FRONTMATTER_KEYS);
+const FRONTMATTER_DELIMITER = "---";
+function newFrontmatter() {
+    return { scalars: {}, allowedTools: [], metadata: {}, unknown: [] };
+}
+function unquote(value) {
+    const t = value.trim();
+    const first = t.charAt(0);
+    const last = t.charAt(t.length - 1);
+    if (t.length >= 2 && ((first === '"' && last === '"') || (first === "'" && last === "'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+function splitListValue(value) {
+    const t = value.trim();
+    const inner = t.startsWith("[") && t.endsWith("]") ? t.slice(1, -1) : t;
+    return inner.split(/[,\s]+/).map(unquote).filter((s) => s !== "");
+}
+function applyTopLevel(fm, key, value) {
+    if (key === "metadata")
+        return null;
+    if (key === "allowed-tools") {
+        if (value !== "")
+            fm.allowedTools = splitListValue(value);
+        return null;
+    }
+    if (value !== "")
+        fm.scalars[key] = unquote(value);
+    return null;
+}
+function applyIndented(fm, currentKey, trimmed) {
+    if (currentKey === null)
+        return null;
+    if (trimmed.startsWith("- ")) {
+        if (currentKey === "allowed-tools")
+            fm.allowedTools.push(unquote(trimmed.slice(2)));
+        return null;
+    }
+    if (currentKey === "metadata") {
+        const colon = trimmed.indexOf(":");
+        if (colon <= 0)
+            return "invalid metadata line '" + trimmed + "'";
+        fm.metadata[trimmed.slice(0, colon).trim()] = unquote(trimmed.slice(colon + 1));
+        return null;
+    }
+    return "unsupported frontmatter block under '" + currentKey + "'";
+}
+function parseBlock(block) {
+    const fm = newFrontmatter();
+    let currentKey = null;
+    for (const rawLine of block.split("\n")) {
+        const trimmed = rawLine.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const indent = rawLine.length - rawLine.trimStart().length;
+        if (indent > 0) {
+            const err = applyIndented(fm, currentKey, trimmed);
+            if (err !== null)
+                return { error: err };
+            continue;
+        }
+        const colon = trimmed.indexOf(":");
+        if (colon <= 0)
+            return { error: "invalid frontmatter line '" + trimmed + "'" };
+        const key = trimmed.slice(0, colon).trim();
+        if (!ALLOWED_KEYS.has(key)) {
+            fm.unknown.push(key);
+            currentKey = null;
+            continue;
+        }
+        currentKey = key;
+        const err = applyTopLevel(fm, key, trimmed.slice(colon + 1).trim());
+        if (err !== null)
+            return { error: err };
+    }
+    return { fm };
+}
+function toParsed(fm) {
+    return {
+        name: fm.scalars["name"] ?? null,
+        description: fm.scalars["description"] ?? null,
+        license: fm.scalars["license"] ?? null,
+        allowedTools: fm.allowedTools,
+        compatibility: fm.scalars["compatibility"] ?? null,
+        metadata: fm.metadata,
+    };
+}
+/**
+ * Parse the leading YAML frontmatter of a SKILL.md. PURE. Returns the parsed
+ * whitelist fields plus the body (everything after the closing delimiter). An
+ * unknown key is an ERROR, never silently ignored.
+ */
+export function parseSkillFrontmatter(text) {
+    const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if ((lines[0] ?? "").trim() !== FRONTMATTER_DELIMITER) {
+        return { ok: false, error: "missing YAML frontmatter: file must start with '---'" };
+    }
+    let close = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if ((lines[i] ?? "").trim() === FRONTMATTER_DELIMITER) {
+            close = i;
+            break;
+        }
+    }
+    if (close === -1)
+        return { ok: false, error: "missing closing '---' frontmatter delimiter" };
+    const block = parseBlock(lines.slice(1, close).join("\n"));
+    if ("error" in block)
+        return { ok: false, error: block.error };
+    const { fm } = block;
+    if (fm.unknown.length > 0) {
+        return {
+            ok: false,
+            error: "unknown frontmatter key(s): " + fm.unknown.join(", ") + " (allowed: " + SKILL_FRONTMATTER_KEYS.join(", ") + ")",
+        };
+    }
+    const body = lines.slice(close + 1).join("\n").replace(/^\n/, "");
+    return { ok: true, data: toParsed(fm), body };
+}
+function reject(location, reason) {
+    return { ok: false, reason: { ...location, reason } };
+}
+/**
+ * Validate the parsed frontmatter against the anthropics/skills contract.
+ * location.name is the DIRECTORY name; the frontmatter name must equal it.
+ */
+export function validateSkill(data, location) {
+    const name = data.name;
+    if (name === null || name === "")
+        return reject(location, "missing required frontmatter key 'name'");
+    if (name !== location.name) {
+        return reject(location, "frontmatter name '" + name + "' does not match directory name '" + location.name + "'");
+    }
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        return reject(location, "name '" + name + "' must match " + String(SKILL_NAME_PATTERN) + " (lowercase letters, digits, hyphens)");
+    }
+    if (name.length > SKILL_NAME_MAX)
+        return reject(location, "name is " + name.length + " chars; max " + SKILL_NAME_MAX);
+    const description = data.description;
+    if (description === null || description === "")
+        return reject(location, "missing required frontmatter key 'description'");
+    if (description.length > SKILL_DESCRIPTION_MAX) {
+        return reject(location, "description is " + description.length + " chars; max " + SKILL_DESCRIPTION_MAX);
+    }
+    if (/[<>]/.test(description))
+        return reject(location, "description must not contain angle brackets '<' or '>'");
+    const compatibility = data.compatibility;
+    if (compatibility !== null && compatibility.length > SKILL_COMPATIBILITY_MAX) {
+        return reject(location, "compatibility is " + compatibility.length + " chars; max " + SKILL_COMPATIBILITY_MAX);
+    }
+    return { ok: true, skill: { ...data, name, description, source: location.source, dir: location.dir, file: location.file } };
+}
+function candidateOf(layer, name) {
+    const dir = join(layer.root, SKILLS_SUBDIR, name);
+    return { name, dir, file: join(dir, SKILL_FILE_NAME), source: layer.source };
+}
+function acceptCandidate(location, text) {
+    const parsed = parseSkillFrontmatter(text);
+    if (!parsed.ok)
+        return { reason: parsed.error };
+    const valid = validateSkill(parsed.data, location);
+    if (!valid.ok)
+        return { reason: valid.reason.reason };
+    return { skill: valid.skill, body: parsed.body };
+}
+/**
+ * Discover every skill in the layers, HIGHEST PRIORITY FIRST. The first layer to
+ * define a name wins; a lower layer is not even parsed for that name. A rejected
+ * project skill therefore shadows (and does not fall back to) a global one, so a
+ * broken override is visible instead of silent. Absent roots are not an error.
+ */
+export function listSkills(layers, io = nodeSkillIo) {
+    const winners = new Map();
+    const rejected = [];
+    const claimed = new Set();
+    for (const layer of layers) {
+        const names = io.listDirectories(join(layer.root, SKILLS_SUBDIR)).slice().sort();
+        for (const name of names) {
+            if (claimed.has(name))
+                continue;
+            const location = candidateOf(layer, name);
+            const text = io.readText(location.file);
+            if (text === null)
+                continue;
+            claimed.add(name);
+            const outcome = acceptCandidate(location, text);
+            if ("skill" in outcome)
+                winners.set(name, outcome.skill);
+            else
+                rejected.push({ ...location, reason: outcome.reason });
+        }
+    }
+    const skills = [...winners.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { skills, rejected };
+}
+/**
+ * The BODY of one named skill, from the first layer that defines it. Returns the
+ * SKILL.md body only — child resources are never auto-loaded (progressive
+ * disclosure). The name must already be a valid skill name (no path traversal).
+ */
+export function loadSkillBody(layers, name, io = nodeSkillIo) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return { ok: false, error: "invalid skill name '" + name + "'" };
+    for (const layer of layers) {
+        const location = candidateOf(layer, name);
+        const text = io.readText(location.file);
+        if (text === null)
+            continue;
+        const outcome = acceptCandidate(location, text);
+        if ("skill" in outcome)
+            return { ok: true, skill: outcome.skill, body: outcome.body };
+        return { ok: false, error: "skill '" + name + "' rejected: " + outcome.reason };
+    }
+    return { ok: false, error: "unknown skill '" + name + "'" };
+}

package/dist/sse-bus.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-process SSE bus (P0 skeleton; SDK-side, not an engine seam).
+ *
+ * Mirrors src/main.rs:640-659 (envelope) and 871-896 (512-capacity broadcast
+ * with slow-client degradation). The `lagged` semantics are contract:
+ * a slow subscriber receives ONE status/lagged event and the stream continues;
+ * skipped events are NOT replayed.
+ *
+ * `subscribe(handler)` is PUSH delivery: each queued frame is handed to the
+ * handler on a microtask (W834 F02), so a caller that never awaits still has
+ * a bounded, non-reentrant queue behind it.
+ *
+ * Named SseBus (not EventBus): `EventBus` is the engine's typed plugin seam
+ * (see ./event-bus.ts, mirroring crates/core/src/event_bus.rs).
+ */
+import type { SseEnvelope, SseEventName, Statusline } from "./types.js";
+export interface BusEvent {
+    kind: SseEventName;
+    data: SseEnvelope;
+}
+export declare const BUS_CAPACITY = 512;
+export declare const LAGGED_HINT = "slow client, skipped events";
+export interface Subscriber {
+    readonly id: number;
+    send(ev: BusEvent): void;
+    close(): void;
+}
+export interface SseBus {
+    emit(kind: SseEventName, turn: number, payload: Record<string, unknown>): BusEvent;
+    subscribe(handler: (ev: BusEvent) => void): Subscriber;
+    /** Current global sequence counter (next value to be handed out). */
+    seq(): number;
+    subscriberCount(): number;
+}
+export interface SseBusOptions {
+    capacity?: number;
+    statusline?: () => Statusline | Record<string, unknown>;
+    nextTurn?: () => number;
+}
+export declare function createSseBus(opts?: SseBusOptions): SseBus;

package/dist/sse-bus.js

@@ -0,0 +1,105 @@
+/**
+ * In-process SSE bus (P0 skeleton; SDK-side, not an engine seam).
+ *
+ * Mirrors src/main.rs:640-659 (envelope) and 871-896 (512-capacity broadcast
+ * with slow-client degradation). The `lagged` semantics are contract:
+ * a slow subscriber receives ONE status/lagged event and the stream continues;
+ * skipped events are NOT replayed.
+ *
+ * `subscribe(handler)` is PUSH delivery: each queued frame is handed to the
+ * handler on a microtask (W834 F02), so a caller that never awaits still has
+ * a bounded, non-reentrant queue behind it.
+ *
+ * Named SseBus (not EventBus): `EventBus` is the engine's typed plugin seam
+ * (see ./event-bus.ts, mirroring crates/core/src/event_bus.rs).
+ */
+export const BUS_CAPACITY = 512;
+export const LAGGED_HINT = "slow client, skipped events";
+function laggedMarker(capacity, sub, turn, seq, opts) {
+    // Slow client: drop everything queued, then hand it the lagged marker.
+    sub.buffer = [];
+    sub.dropped += 1;
+    void capacity;
+    sub.buffer.push({
+        kind: "status",
+        data: {
+            v: 2,
+            session: null,
+            turn,
+            seq: seq,
+            payload: {
+                phase: "lagged",
+                hint: LAGGED_HINT,
+                statusline: opts.statusline ? opts.statusline() : {},
+            },
+        },
+    });
+    return seq + 1;
+}
+/**
+ * Queue one frame for delivery and drain on a microtask.
+ *
+ * W834 F02 (R3 batch A): `emit` used to stop at `sub.buffer.push`, so the
+ * handler passed to `subscribe` was never called. Delivery is deferred to a
+ * microtask on purpose: it is what keeps the 512-capacity LAGGED semantics
+ * observable (a synchronous drain would always empty the queue inside the same
+ * `emit`, and a slow client could never fall behind).
+ */
+function scheduleDrain(sub) {
+    if (sub.draining || sub.closed)
+        return;
+    sub.draining = true;
+    queueMicrotask(() => {
+        sub.draining = false;
+        if (sub.closed) {
+            sub.buffer = [];
+            return;
+        }
+        while (sub.buffer.length > 0) {
+            const next = sub.buffer.shift();
+            if (next !== undefined)
+                sub.send(next);
+        }
+    });
+}
+export function createSseBus(opts = {}) {
+    const capacity = opts.capacity ?? BUS_CAPACITY;
+    const subs = new Set();
+    let seq = 0;
+    let nextSubId = 1;
+    function emit(kind, turn, payload) {
+        const ev = { kind, data: { v: 2, session: null, turn, seq: seq++, payload } };
+        for (const sub of subs) {
+            if (sub.buffer.length >= capacity) {
+                // Slow client: drop everything queued, then hand it ONE lagged marker.
+                seq = laggedMarker(capacity, sub, turn, seq, opts);
+            }
+            else {
+                sub.buffer.push(ev);
+            }
+            scheduleDrain(sub);
+        }
+        return ev;
+    }
+    function subscribe(handler) {
+        const sub = {
+            id: nextSubId++,
+            buffer: [],
+            dropped: 0,
+            draining: false,
+            closed: false,
+            send(ev) {
+                if (!sub.closed)
+                    handler(ev);
+            },
+            close() {
+                sub.closed = true;
+                sub.buffer = [];
+                subs.delete(sub);
+            },
+        };
+        subs.add(sub);
+        return sub;
+    }
+    return { emit, subscribe, seq: () => seq, subscriberCount: () => subs.size };
+}

package/dist/stream.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The LLM request/stream seam payloads — ports of
+ * `crates/core/src/message.rs:65-153` (ModelRequest / StreamEvent / LlmError).
+ *
+ * `StreamEvent` is what a provider adapter yields: incremental deltas for the
+ * UI, then exactly one authoritative terminal event. Terminal variants never
+ * follow each other (`Done` after `Failed`/`Interrupted` is a contract
+ * violation), because the engine's five TurnOutcome states are derived from
+ * which terminal event arrived.
+ *
+ * A1 (W746): this module is the SINGLE source of the LLM vocabulary. Provider
+ * packages (`@celestea/llm`) re-export these symbols instead of redeclaring
+ * them, so `instanceof LlmError` and every structural type agree across
+ * packages. `LlmError` here carries the structured classification TS needs
+ * (see the class doc).
+ */
+import type { Message, Usage } from "./message.js";
+import type { ToolSpec } from "./types.js";
+/**
+ * `ModelRequest` — everything the model adapter needs for one call.
+ *
+ * A1 (W746): there is exactly ONE `ModelRequest` in the repo — `@celestea/llm`
+ * re-exports this one instead of declaring a structurally-similar copy. The
+ * shape is unchanged (the engine and the host both fill every field), and the
+ * provider's wire mapper reads it with the same "absent == empty" fallbacks it
+ * always had (`model` empty -> the configured model).
+ */
+export interface ModelRequest {
+    model: string;
+    system: string | null;
+    messages: Message[];
+    tools: ToolSpec[];
+    max_tokens: number | null;
+    temperature: number | null;
+}
+export type StreamEvent = 
+/** A final-answer text delta. */
+{
+    kind: "text";
+    text: string;
+}
+/** A chain-of-thought / reasoning delta (never enters the model history). */
+ | {
+    kind: "thinking";
+    text: string;
+}
+/** Provider-reported usage for this response, just before the terminal event. */
+ | {
+    kind: "usage";
+    usage: Usage;
+}
+/** The single authoritative final message. */
+ | {
+    kind: "done";
+    message: Message;
+}
+/** The stream/generation broke mid-flight; terminal (no Done follows). */
+ | {
+    kind: "failed";
+    kindOf: "generate" | "stream";
+    message: string;
+}
+/** Torn stream without a terminal frame; terminal (no Done follows). */
+ | {
+    kind: "interrupted";
+};
+export declare const STREAM_EVENT_KINDS: readonly ["text", "thinking", "usage", "done", "failed", "interrupted"];
+export type StreamEventKind = (typeof STREAM_EVENT_KINDS)[number];
+/**
+ * The turn-outcome kind a provider failure maps to.
+ *
+ * "generate" = the pre-stream `generate()` call failed; "stream" = the stream
+ * broke mid-flight; "timeout" = a guard tripped (connect / response-header /
+ * SSE idle). The classification rides the `llm timeout:` message prefix;
+ * TS carries it as a field AS WELL (never instead of the text).
+ */
+export type LlmErrorKind = "generate" | "stream" | "timeout";
+/** Which guard tripped when a failure was a timeout. */
+export type TimeoutStage = "connect" | "response" | "idle";
+/** Extra structured fields of `LlmError` (all optional; defaults are safe). */
+export interface LlmErrorOptions {
+    isTimeout?: boolean;
+    timeoutStage?: TimeoutStage | null;
+    /** Status of the failed HTTP response; `null` = no response arrived. */
+    httpStatus?: number | null;
+    /** Whether retrying / switching target could plausibly help. */
+    retryable?: boolean;
+}
+/**
+ * `LlmError` — the provider-facing failure (`LlmError(String)` in the legacy engine).
+ *
+ * The semantics ride the canonical `llm timeout: …` message prefix; TS adds the
+ * machine-readable fields on top of the unchanged text:
+ * `kind` (the turn-outcome kind a caller should report), `isTimeout` +
+ * `timeoutStage`, `httpStatus` and `retryable` (the conservative default pair
+ * is `(null, false)`: a failure with no evidence of being transient is a
+ * local/configuration problem, not something to retry).
+ */
+export declare class LlmError extends Error {
+    /** Turn-outcome kind this failure maps to. */
+    readonly kind: LlmErrorKind;
+    /** True for any timeout; the message then carries the canonical prefix. */
+    readonly isTimeout: boolean;
+    /** Which guard tripped, when the failure was a timeout. */
+    readonly timeoutStage: TimeoutStage | null;
+    /** HTTP status of the failing response; `null` when none was received. */
+    readonly httpStatus: number | null;
+    /** True for transient causes (timeouts, transport, 408/425/429/5xx). */
+    readonly retryable: boolean;
+    constructor(message: string, kind?: LlmErrorKind, options?: LlmErrorOptions);
+}
+/** `LlmStream` — `Pin<Box<dyn Stream<Item = StreamEvent> + Send>>`. */
+export type LlmStream = AsyncIterable<StreamEvent>;
+/** True for the two terminal variants (no further event may follow). */
+export declare function isTerminalStreamEvent(ev: StreamEvent): boolean;