@mlx-node/agent 0.0.7

package/dist/index.js

@@ -0,0 +1,12 @@
+export { MODEL_CATALOG, visibleCatalog } from './catalog.js';
+export { createPermissionGateExtension } from './extensions/permission-gate.js';
+export { createSubagentExtension, discoverSubagents, normalizeSubagentMode, } from './extensions/subagent.js';
+export { createTerminalTitleExtension } from './extensions/terminal-title.js';
+export { buildChatConfig } from './provider/chat-config.js';
+export { contextToChatMessages, toolsToDefinitions } from './provider/convert-messages.js';
+export { TurnEmitter } from './provider/events.js';
+export { createMlxProviderExtension } from './provider/index.js';
+export { MlxModelHost } from './provider/model-host.js';
+export { discoverMlxModels } from './provider/models.js';
+export { runAgent } from './run-agent.js';
+export { makeMlxStreamSimple } from './provider/stream-adapter.js';

package/dist/provider/chat-config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-call `ChatConfig` assembly for the provider bridge.
+ *
+ * Base sampling + output budget come from `@mlx-node/server`'s
+ * `LAUNCH_PRESETS` (the ONLY allowed server import in this package —
+ * presets/preset types, nothing else) extended by the agent-local
+ * {@link AGENT_LAUNCH_PRESETS}, then pi's per-call `SimpleStreamOptions`
+ * overlay on top.
+ */
+import type { SimpleStreamOptions, ThinkingLevel } from '@earendil-works/pi-ai';
+import type { ChatConfig, ModelType, ToolDefinition } from '@mlx-node/lm';
+import { type LaunchPreset } from '@mlx-node/server';
+/**
+ * Preset lookup — agent-local entries win over `LAUNCH_PRESETS` (they
+ * exist precisely because the server table has no correct entry for the
+ * type). This is the ONE preset resolution shared by discovery
+ * (`models.ts`) and per-call config assembly, so a model can never be
+ * discovered without also being streamable (and vice versa).
+ */
+export declare function launchPresetFor(modelType: ModelType): LaunchPreset | undefined;
+export interface ResolvedReasoningMode {
+    reasoningEffort: 'none' | 'low' | 'medium' | 'high';
+    /** The `enable_thinking` value implied by `reasoningEffort` for templates. */
+    thinkingEnabled: boolean;
+}
+/**
+ * Resolve Pi's thinking level once for both native config and persisted replay
+ * provenance. Keeping these values together prevents a low/minimal turn from
+ * being replayed later as an enabled-thinking turn merely because the Pi
+ * option was present.
+ */
+export declare function resolveReasoningMode(reasoning: ThinkingLevel | undefined): ResolvedReasoningMode;
+export declare function buildChatConfig(modelType: ModelType, options: SimpleStreamOptions | undefined, tools: ToolDefinition[] | undefined, rootCacheOwnerId?: string, resolvedReasoning?: ResolvedReasoningMode): ChatConfig;
+//# sourceMappingURL=chat-config.d.ts.map

package/dist/provider/chat-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-config.d.ts","sourceRoot":"","sources":["../../src/provider/chat-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAE9E;AAgBD,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,GAAG,qBAAqB,CAMhG;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,KAAK,EAAE,cAAc,EAAE,GAAG,SAAS,EACnC,gBAAgB,CAAC,EAAE,MAAM,EACzB,iBAAiB,wBAA2C,GAC3D,UAAU,CA6BZ"}

package/dist/provider/chat-config.js

@@ -0,0 +1,103 @@
+/**
+ * Per-call `ChatConfig` assembly for the provider bridge.
+ *
+ * Base sampling + output budget come from `@mlx-node/server`'s
+ * `LAUNCH_PRESETS` (the ONLY allowed server import in this package —
+ * presets/preset types, nothing else) extended by the agent-local
+ * {@link AGENT_LAUNCH_PRESETS}, then pi's per-call `SimpleStreamOptions`
+ * overlay on top.
+ */
+import { LAUNCH_PRESETS } from '@mlx-node/server';
+/**
+ * Agent-local launch presets for model types `LAUNCH_PRESETS` does not
+ * cover (kept here — this package must not fork `packages/server`).
+ *
+ * `lfm2_moe` (LFM2.5-8B-A1B): LiquidAI's HF model card for the MoE
+ * checkpoint recommends temperature 0.2 / top_k 80 — deliberately NOT
+ * the dense `lfm2` preset (LFM2.5-1.2B guidance: temperature 0.05 /
+ * top_k 50). repetitionPenalty 1.05 and the 8192-token output budget
+ * match the dense family entry.
+ */
+const AGENT_LAUNCH_PRESETS = {
+    lfm2_moe: {
+        sampling: {
+            temperature: 0.2,
+            topP: 1.0,
+            topK: 80,
+            minP: 0.0,
+            presencePenalty: 0.0,
+            repetitionPenalty: 1.05,
+        },
+        maxOutputTokens: 8192,
+    },
+};
+/**
+ * Preset lookup — agent-local entries win over `LAUNCH_PRESETS` (they
+ * exist precisely because the server table has no correct entry for the
+ * type). This is the ONE preset resolution shared by discovery
+ * (`models.ts`) and per-call config assembly, so a model can never be
+ * discovered without also being streamable (and vice versa).
+ */
+export function launchPresetFor(modelType) {
+    return AGENT_LAUNCH_PRESETS[modelType] ?? LAUNCH_PRESETS[modelType];
+}
+/**
+ * pi thinking level → native `reasoningEffort`. pi never delivers 'off'
+ * here (the agent loop converts it to `undefined` before the provider
+ * sees it), so `undefined` is the "thinking disabled" signal → 'none'.
+ */
+const THINKING_LEVEL_TO_EFFORT = {
+    minimal: 'low',
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+    xhigh: 'high',
+    max: 'high',
+};
+/**
+ * Resolve Pi's thinking level once for both native config and persisted replay
+ * provenance. Keeping these values together prevents a low/minimal turn from
+ * being replayed later as an enabled-thinking turn merely because the Pi
+ * option was present.
+ */
+export function resolveReasoningMode(reasoning) {
+    const reasoningEffort = reasoning === undefined ? 'none' : THINKING_LEVEL_TO_EFFORT[reasoning];
+    return {
+        reasoningEffort,
+        thinkingEnabled: reasoningEffort === 'medium' || reasoningEffort === 'high',
+    };
+}
+export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, resolvedReasoning = resolveReasoningMode(options?.reasoning)) {
+    const preset = launchPresetFor(modelType);
+    if (!preset) {
+        const known = [...new Set([...Object.keys(LAUNCH_PRESETS), ...Object.keys(AGENT_LAUNCH_PRESETS)])].join(', ');
+        throw new Error(`buildChatConfig: no launch preset for model type "${modelType}" (known types: ${known})`);
+    }
+    const config = {
+        ...preset.sampling,
+        maxNewTokens: preset.maxOutputTokens,
+        reasoningEffort: resolvedReasoning.reasoningEffort,
+        // The terminal native chunk carries TTFT/prefill/decode telemetry when
+        // requested. The provider keeps it transient and only renders it in TUI.
+        reportPerformance: true,
+    };
+    // Pi assigns one stable id to the root AgentSession and a distinct id to
+    // every in-memory subagent session. Native Qwen3.5 uses this only to retain
+    // GDN sidecars per logical branch; PagedAttention KV blocks remain shared by
+    // their existing exact content hashes.
+    if (options?.sessionId !== undefined)
+        config.cacheOwnerId = options.sessionId;
+    // The active owner above can be a child AgentSession. Keep the current
+    // top-level session identity separate so a /new or /resume rotation updates
+    // which branch the bounded GDN sidecar store protects from child eviction.
+    if (rootCacheOwnerId !== undefined)
+        config.cacheRootOwnerId = rootCacheOwnerId;
+    if (options?.maxTokens !== undefined)
+        config.maxNewTokens = options.maxTokens;
+    if (options?.temperature !== undefined)
+        config.temperature = options.temperature;
+    if (tools && tools.length > 0)
+        config.tools = tools;
+    // `reuseCache` is deliberately NOT set: ChatSession.mergeConfig forces it on.
+    return config;
+}

package/dist/provider/convert-messages.d.ts

@@ -0,0 +1,59 @@
+/**
+ * pi `Context` → native `ChatMessage[]` / `ToolDefinition[]` conversion.
+ *
+ * The provider bridge replays pi's full message history through
+ * `ChatSession.primeHistory()` on every LLM call, so this conversion must
+ * be deterministic and byte-stable: an unstable rendering (key-order
+ * churn, nondeterministic joins) would change the token prefix between
+ * replays and silently kill native KV-cache reuse.
+ */
+import type { Context, Tool } from '@earendil-works/pi-ai';
+import type { ChatMessage, ToolDefinition } from '@mlx-node/lm';
+/**
+ * Convert a pi `Context` into the `ChatMessage[]` accepted by
+ * `ChatSession.primeHistory()`.
+ *
+ * - `systemPrompt` becomes the leading `system` message.
+ * - For text-only models (the default), image parts become literal
+ *   `[image omitted]` lines.
+ * - For an image-capable loaded model, user images stay on their native user
+ *   message. Images from a consecutive tool-result run are decoded, collected
+ *   in source order, and emitted on one synthetic user message after every
+ *   textual tool message in that run. This mirrors pi's OpenAI conversion and
+ *   avoids templates that ignore images attached to the `tool` role.
+ *
+ * Two-pass mirror of pi's canonical `transformMessages` (pi-ai
+ * `dist/api/transform-messages.js`). That transform normally sanitizes the
+ * history INSIDE pi's built-in providers, but our custom `streamSimple` bypasses
+ * it (and `defaultConvertToLlm` filters by role only), so the same two passes
+ * must run here or a failed/interrupted turn reaches `primeHistory` unchanged:
+ *
+ *  1. DROP every assistant turn whose `stopReason` is `error` or `aborted` —
+ *     partial or not. These incomplete turns (partial text, a half-emitted tool
+ *     call) must not be replayed: after a native error (R2-3 resets the native
+ *     cache) or an Esc/abort, priming the invalid partial turn garbles the
+ *     continuation or leaves a dangling `<tool_call>` and corrupts the native
+ *     `unresolvedOkToolCallCount`. A dropped turn's tool calls are NOT tracked.
+ *  2. ORPHAN-REPAIR: track the tool-call ids of each RETAINED assistant and,
+ *     before every following user/assistant message and at the end, synthesize a
+ *     native tool result (`{ role: 'tool', content: 'No result provided',
+ *     isError: true }`) for any tracked call with no matching `toolResult`
+ *     (pi's `insertSyntheticToolResults`), so no assistant tool call is left
+ *     unanswered in the primed history.
+ *
+ * The happy path (every assistant completes, every tool call answered) is
+ * untouched, so the byte-stable joins that keep the replayed KV prefix stable
+ * are preserved.
+ */
+export declare function contextToChatMessages(context: Context, supportsImages?: boolean): ChatMessage[];
+/**
+ * Convert pi `Tool[]` (TypeBox-built plain JSON Schema objects) into the
+ * native OpenAI-style `ToolDefinition[]`.
+ *
+ * The NAPI layer requires `parameters.properties` as a JSON string;
+ * `JSON.stringify` preserves the schema's own key order, keeping the
+ * rendered tool block byte-stable across replays. Returns `undefined`
+ * for an absent or empty tool list so `ChatConfig.tools` stays unset.
+ */
+export declare function toolsToDefinitions(tools: Tool[] | undefined): ToolDefinition[] | undefined;
+//# sourceMappingURL=convert-messages.d.ts.map

package/dist/provider/convert-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-messages.d.ts","sourceRoot":"","sources":["../../src/provider/convert-messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAsC,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAwHhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,UAAQ,GAAG,WAAW,EAAE,CA2E7F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,GAAG,cAAc,EAAE,GAAG,SAAS,CAmB1F"}

package/dist/provider/convert-messages.js

@@ -0,0 +1,248 @@
+/**
+ * pi `Context` → native `ChatMessage[]` / `ToolDefinition[]` conversion.
+ *
+ * The provider bridge replays pi's full message history through
+ * `ChatSession.primeHistory()` on every LLM call, so this conversion must
+ * be deterministic and byte-stable: an unstable rendering (key-order
+ * churn, nondeterministic joins) would change the token prefix between
+ * replays and silently kill native KV-cache reuse.
+ */
+const IMAGE_PLACEHOLDER = '[image omitted]';
+const PI_NON_VISION_IMAGE_NOTE = '[Current model does not support images. The image will be omitted from this request.]';
+const TOOL_RESULT_IMAGE_PLACEHOLDER = '(see attached image)';
+const TOOL_RESULT_IMAGE_PROMPT = 'Attached image(s) from tool result:';
+/**
+ * Convert Pi's mixed text/image blocks into the native message shape.
+ *
+ * Text-only models retain the historical byte-stable placeholder rendering.
+ * Image-capable models keep text order and image order independently — the
+ * most ordering the native `ChatMessage { content, images }` shape can express
+ * — while decoding Pi's base64 payloads into the bytes consumed by NAPI.
+ */
+function convertParts(parts, supportsImages, stripStaleToolImageNote = false) {
+    if (!supportsImages) {
+        return {
+            content: parts.map((part) => (part.type === 'image' ? IMAGE_PLACEHOLDER : part.text)).join('\n'),
+        };
+    }
+    const text = [];
+    const images = [];
+    for (const part of parts) {
+        if (part.type === 'image') {
+            images.push(Buffer.from(part.data, 'base64'));
+        }
+        else {
+            // Pi added this exact standalone line to image tool results before the
+            // loaded native capability could be published. A resumed pre-fix history
+            // still contains it; replaying the warning contradicts the now-loaded
+            // capability even when image processing failed before producing bytes.
+            // Scope cleanup to tool results: identical direct-user text is literal.
+            text.push(stripStaleToolImageNote
+                ? part.text
+                    .split('\n')
+                    .filter((line) => line !== PI_NON_VISION_IMAGE_NOTE)
+                    .join('\n')
+                : part.text);
+        }
+    }
+    return {
+        content: text.join('\n'),
+        ...(images.length > 0 ? { images } : {}),
+    };
+}
+/** Per-message conversion (byte-stable joins). Never drops — the drop / orphan
+ * repair and grouped tool-result image turn live in
+ * {@link contextToChatMessages}, mirroring pi's transformMessages and OpenAI
+ * provider conversion. */
+function convertMessage(message, supportsImages) {
+    switch (message.role) {
+        case 'user': {
+            if (typeof message.content === 'string') {
+                return { message: { role: 'user', content: message.content } };
+            }
+            return { message: { role: 'user', ...convertParts(message.content, supportsImages) } };
+        }
+        case 'assistant': {
+            // Preserve the parser's reasoning body so thinking-capable templates can
+            // reconstruct the exact channel/tag sequence generated on the prior
+            // turn. The native Gemma4 parser already removes its fixed `thought\n`
+            // channel label; the template adds that label back during replay.
+            const reasoningContent = message.content
+                .filter((part) => part.type === 'thinking')
+                .map((part) => part.thinking)
+                .join('');
+            const text = message.content
+                .filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join('\n');
+            const toolCalls = message.content
+                .filter((part) => part.type === 'toolCall')
+                .map((part) => ({ id: part.id, name: part.name, arguments: JSON.stringify(part.arguments) }));
+            const converted = { role: 'assistant', content: text };
+            if (reasoningContent.length > 0)
+                converted.reasoningContent = reasoningContent;
+            const thinkingEnabled = message.mlxThinkingEnabled;
+            if (thinkingEnabled !== undefined)
+                converted.thinkingEnabled = thinkingEnabled;
+            if (toolCalls.length > 0)
+                converted.toolCalls = toolCalls;
+            return { message: converted };
+        }
+        case 'toolResult': {
+            const converted = convertParts(message.content, supportsImages, true);
+            const images = converted.images ?? [];
+            return {
+                message: {
+                    role: 'tool',
+                    content: converted.content.length > 0
+                        ? converted.content
+                        : images.length > 0
+                            ? TOOL_RESULT_IMAGE_PLACEHOLDER
+                            : converted.content,
+                    toolCallId: message.toolCallId,
+                    isError: message.isError,
+                },
+                ...(images.length > 0 ? { toolResultImages: images } : {}),
+            };
+        }
+    }
+}
+/**
+ * Convert a pi `Context` into the `ChatMessage[]` accepted by
+ * `ChatSession.primeHistory()`.
+ *
+ * - `systemPrompt` becomes the leading `system` message.
+ * - For text-only models (the default), image parts become literal
+ *   `[image omitted]` lines.
+ * - For an image-capable loaded model, user images stay on their native user
+ *   message. Images from a consecutive tool-result run are decoded, collected
+ *   in source order, and emitted on one synthetic user message after every
+ *   textual tool message in that run. This mirrors pi's OpenAI conversion and
+ *   avoids templates that ignore images attached to the `tool` role.
+ *
+ * Two-pass mirror of pi's canonical `transformMessages` (pi-ai
+ * `dist/api/transform-messages.js`). That transform normally sanitizes the
+ * history INSIDE pi's built-in providers, but our custom `streamSimple` bypasses
+ * it (and `defaultConvertToLlm` filters by role only), so the same two passes
+ * must run here or a failed/interrupted turn reaches `primeHistory` unchanged:
+ *
+ *  1. DROP every assistant turn whose `stopReason` is `error` or `aborted` —
+ *     partial or not. These incomplete turns (partial text, a half-emitted tool
+ *     call) must not be replayed: after a native error (R2-3 resets the native
+ *     cache) or an Esc/abort, priming the invalid partial turn garbles the
+ *     continuation or leaves a dangling `<tool_call>` and corrupts the native
+ *     `unresolvedOkToolCallCount`. A dropped turn's tool calls are NOT tracked.
+ *  2. ORPHAN-REPAIR: track the tool-call ids of each RETAINED assistant and,
+ *     before every following user/assistant message and at the end, synthesize a
+ *     native tool result (`{ role: 'tool', content: 'No result provided',
+ *     isError: true }`) for any tracked call with no matching `toolResult`
+ *     (pi's `insertSyntheticToolResults`), so no assistant tool call is left
+ *     unanswered in the primed history.
+ *
+ * The happy path (every assistant completes, every tool call answered) is
+ * untouched, so the byte-stable joins that keep the replayed KV prefix stable
+ * are preserved.
+ */
+export function contextToChatMessages(context, supportsImages = false) {
+    const messages = [];
+    if (context.systemPrompt) {
+        messages.push({ role: 'system', content: context.systemPrompt });
+    }
+    // Orphan-repair state: the tool-call ids awaiting a result from the most
+    // recent RETAINED assistant, and the result ids seen since.
+    let pendingToolCallIds = [];
+    let seenToolResultIds = new Set();
+    let pendingToolResultImages = [];
+    const flushOrphans = () => {
+        if (pendingToolCallIds.length === 0)
+            return;
+        for (const id of pendingToolCallIds) {
+            if (!seenToolResultIds.has(id)) {
+                messages.push({ role: 'tool', content: 'No result provided', toolCallId: id, isError: true });
+            }
+        }
+        pendingToolCallIds = [];
+        seenToolResultIds = new Set();
+    };
+    const flushToolResultImages = () => {
+        if (pendingToolResultImages.length === 0)
+            return;
+        messages.push({
+            role: 'user',
+            content: TOOL_RESULT_IMAGE_PROMPT,
+            images: pendingToolResultImages,
+        });
+        pendingToolResultImages = [];
+    };
+    const flushToolResultBoundary = () => {
+        // A grouped image attachment is logically a user turn. Repair any missing
+        // sibling tool result before that boundary, then append the single image
+        // turn after every real/synthetic tool result.
+        flushOrphans();
+        flushToolResultImages();
+    };
+    for (const message of context.messages) {
+        switch (message.role) {
+            case 'user':
+                flushToolResultBoundary();
+                messages.push(convertMessage(message, supportsImages).message);
+                break;
+            case 'assistant': {
+                flushToolResultBoundary();
+                if (message.stopReason === 'error' || message.stopReason === 'aborted') {
+                    break; // dropped: not primed, and its tool calls are NOT tracked
+                }
+                const converted = convertMessage(message, supportsImages).message;
+                messages.push(converted);
+                if (converted.toolCalls && converted.toolCalls.length > 0) {
+                    // Native ToolCall.id is optional; only ids can be matched against a
+                    // tool result, so an id-less call is never tracked for orphan repair.
+                    pendingToolCallIds = converted.toolCalls.map((tc) => tc.id).filter((id) => id !== undefined);
+                    seenToolResultIds = new Set();
+                }
+                break;
+            }
+            case 'toolResult': {
+                seenToolResultIds.add(message.toolCallId);
+                const converted = convertMessage(message, supportsImages);
+                messages.push(converted.message);
+                if (converted.toolResultImages) {
+                    pendingToolResultImages.push(...converted.toolResultImages);
+                }
+                break;
+            }
+        }
+    }
+    flushToolResultBoundary();
+    return messages;
+}
+/**
+ * Convert pi `Tool[]` (TypeBox-built plain JSON Schema objects) into the
+ * native OpenAI-style `ToolDefinition[]`.
+ *
+ * The NAPI layer requires `parameters.properties` as a JSON string;
+ * `JSON.stringify` preserves the schema's own key order, keeping the
+ * rendered tool block byte-stable across replays. Returns `undefined`
+ * for an absent or empty tool list so `ChatConfig.tools` stays unset.
+ */
+export function toolsToDefinitions(tools) {
+    if (!tools || tools.length === 0)
+        return undefined;
+    return tools.map((tool) => {
+        // pi's Tool.parameters is a TSchema — at runtime a plain JSON Schema
+        // object (TypeBox kind markers live on symbols, which JSON ignores).
+        const schema = tool.parameters;
+        return {
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: {
+                    type: 'object',
+                    properties: JSON.stringify(schema.properties ?? {}),
+                    required: schema.required,
+                },
+            },
+        };
+    });
+}

package/dist/provider/error-coercion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hardened coercion of arbitrary thrown values to message strings.
+ *
+ * Shared by the stream adapter's TurnEmitter-independent failsafe path
+ * and `TurnEmitter.onError`: both receive caller-supplied error values
+ * and both promise never to throw, so every read here is guarded.
+ */
+/**
+ * Coerce an arbitrary thrown value to a message string without trusting
+ * it: an `Error` whose `message` getter throws, an object with a poisoned
+ * `toString` / `Symbol.toPrimitive`, a null-prototype object (where
+ * `String(err)` itself throws), and a revoked Proxy — where even
+ * `err instanceof Error` throws, because `instanceof` walks the prototype
+ * chain through the (revoked or throwing) `getPrototypeOf` trap — all
+ * land on the constant fallback instead of escaping. Circular objects are
+ * fine — `String` never serializes deeply.
+ */
+export declare function coerceErrorMessage(err: unknown): string;
+//# sourceMappingURL=error-coercion.d.ts.map

package/dist/provider/error-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-coercion.d.ts","sourceRoot":"","sources":["../../src/provider/error-coercion.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAiBvD"}

package/dist/provider/error-coercion.js

@@ -0,0 +1,38 @@
+/**
+ * Hardened coercion of arbitrary thrown values to message strings.
+ *
+ * Shared by the stream adapter's TurnEmitter-independent failsafe path
+ * and `TurnEmitter.onError`: both receive caller-supplied error values
+ * and both promise never to throw, so every read here is guarded.
+ */
+/**
+ * Coerce an arbitrary thrown value to a message string without trusting
+ * it: an `Error` whose `message` getter throws, an object with a poisoned
+ * `toString` / `Symbol.toPrimitive`, a null-prototype object (where
+ * `String(err)` itself throws), and a revoked Proxy — where even
+ * `err instanceof Error` throws, because `instanceof` walks the prototype
+ * chain through the (revoked or throwing) `getPrototypeOf` trap — all
+ * land on the constant fallback instead of escaping. Circular objects are
+ * fine — `String` never serializes deeply.
+ */
+export function coerceErrorMessage(err) {
+    try {
+        // The `instanceof` check MUST live inside the guard: on a revoked
+        // Proxy (or any Proxy with a throwing `getPrototypeOf` trap) the
+        // check itself throws a TypeError before any property is read.
+        if (err instanceof Error) {
+            const { message } = err;
+            if (typeof message === 'string' && message.length > 0)
+                return message;
+        }
+    }
+    catch {
+        // hostile prototype walk or poisoned `message` getter — fall through
+    }
+    try {
+        return String(err);
+    }
+    catch {
+        return 'unserializable error';
+    }
+}

package/dist/provider/events.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `TurnEmitter` — maps one native `ChatStreamEvent` turn onto pi's
+ * `AssistantMessageEvent` protocol.
+ *
+ * Correctness contract (spike-proven):
+ *   - pi's agent loop takes the final message from `stream.result()` and
+ *     reads `stopReason` off THAT message — the `done` event's `reason`
+ *     field is discarded. Both are still emitted protocol-correct.
+ *   - Aborted native streams end with NO final event, so the caller must
+ *     invoke {@link TurnEmitter.onAborted} to synthesize the terminal
+ *     AssistantMessage (stopReason 'aborted', accumulated deltas intact).
+ *   - Every method is throw-safe: the pi StreamFn contract does not allow
+ *     the emitter to throw, so internal failures route to {@link onError}.
+ */
+import type { Api, AssistantMessage, AssistantMessageEventStream, Model, Usage } from '@earendil-works/pi-ai';
+import type { ChatStreamDelta, ChatStreamFinal, PerformanceMetrics } from '@mlx-node/lm';
+/**
+ * All-zero usage. Shared with the stream adapter's TurnEmitter-independent
+ * failsafe terminal, so it must stay trivially non-throwing.
+ */
+export declare function emptyUsage(): Usage;
+export declare class TurnEmitter {
+    private readonly onPerformance?;
+    private readonly stream;
+    private readonly partial;
+    private readonly textBuffer;
+    private readonly thinkingBuffer;
+    /**
+     * Leading whitespace-only text parked before any text block exists, so
+     * a `"\n\n"` emitted right before `<tool_call>` markup never ratifies a
+     * whitespace-only text content block (mirrors the server endpoints).
+     * Joined onto the first non-whitespace text; dropped at terminal time.
+     */
+    private pendingLeadingWhitespace;
+    private openBlock;
+    private finished;
+    constructor(stream: AssistantMessageEventStream, model: Model<Api>, onPerformance?: ((message: AssistantMessage, performance: PerformanceMetrics) => void) | undefined, thinkingEnabled?: boolean);
+    onDelta(delta: ChatStreamDelta): void;
+    onFinal(final: ChatStreamFinal): void;
+    /**
+     * Synthesize the terminal message for an aborted native stream (which
+     * ends with no final event). Mirrors pi's provider abort pattern:
+     * `{type:'error', reason:'aborted', error: <partial message>}` with all
+     * accumulated text/thinking preserved on the message.
+     */
+    onAborted(): void;
+    /**
+     * Terminal for internal/adapter failures. `err` is untrusted: coercion
+     * is fully guarded (shared `coerceErrorMessage`), so even a revoked
+     * Proxy or a poisoned `message` getter cannot throw out of here.
+     */
+    onError(err: unknown): void;
+    /**
+     * Shared terminal path for every non-`done` ending (abort, native
+     * finishReason=error, internal failure). Recovers any held-back buffer
+     * residue and closes the open text/thinking block BEFORE emitting the
+     * terminal event — a stream must never end `text_start/text_delta/error`
+     * with no `text_end` (pi's reference providers balance all blocks
+     * before terminals).
+     */
+    private finishWithError;
+    private appendThinking;
+    private appendVisibleText;
+    private closeOpenBlock;
+    private blockIndex;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/provider/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/provider/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,KAAK,EAIL,KAAK,EACN,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAkB,MAAM,cAAc,CAAC;AAMzG;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,CASlC;AA2CD,qBAAa,WAAW;IAkBpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAjBjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAAM;IACtC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAS;IAEzB,YACE,MAAM,EAAE,2BAA2B,EACnC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACA,aAAa,CAAC,GAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,KAAK,IAAI,aAAA,EACrG,eAAe,CAAC,EAAE,OAAO,EAuB1B;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAqBpC;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CA8CpC;IAED;;;;;OAKG;IACH,SAAS,IAAI,IAAI,CAGhB;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG1B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,UAAU;CAGnB"}