@k2b/nessi 0.10.0-rc.0

package/ai/shared/ndjson.js

@@ -0,0 +1,60 @@
+export const parseNDJSON = async function* (reader, timeouts = {}) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let readCount = 0;
+    const readWithTimeout = async () => {
+        const scope = readCount === 0 ? "provider_first_byte" : "provider_idle";
+        const timeoutMs = readCount === 0 ? timeouts.firstByteMs : timeouts.idleMs;
+        if (!timeoutMs || timeoutMs <= 0)
+            return reader.read();
+        let timeout;
+        try {
+            return await Promise.race([
+                reader.read(),
+                new Promise((_, reject) => {
+                    timeout = setTimeout(() => {
+                        const error = {
+                            scope,
+                            message: `NDJSON stream ${scope === "provider_first_byte" ? "first byte" : "idle"} timeout after ${timeoutMs}ms.`,
+                        };
+                        void reader.cancel?.(error).catch(() => { });
+                        reject(error);
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    };
+    while (true) {
+        const { done, value } = await readWithTimeout();
+        readCount++;
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                yield JSON.parse(trimmed);
+            }
+            catch {
+                // silently skip malformed records
+            }
+        }
+    }
+    const trimmed = buffer.trim();
+    if (trimmed) {
+        try {
+            yield JSON.parse(trimmed);
+        }
+        catch {
+            // silently skip trailing malformed records
+        }
+    }
+};

package/ai/shared/sse.d.ts

@@ -0,0 +1,15 @@
+export type SSEEvent = {
+    event?: string;
+    data: string;
+    id?: string;
+};
+export type SSETimeoutScope = "provider_first_byte" | "provider_idle";
+export declare class SSETimeoutError extends Error {
+    readonly scope: SSETimeoutScope;
+    constructor(scope: SSETimeoutScope, timeoutMs: number);
+}
+export type SSETimeouts = {
+    firstByteMs?: number;
+    idleMs?: number;
+};
+export declare const parseSSE: (reader: ReadableStreamDefaultReader<Uint8Array>, timeouts?: SSETimeouts) => AsyncGenerator<SSEEvent>;

package/ai/shared/sse.js

@@ -0,0 +1,79 @@
+export class SSETimeoutError extends Error {
+    scope;
+    constructor(scope, timeoutMs) {
+        super(`SSE stream ${scope === "provider_first_byte" ? "first byte" : "idle"} timeout after ${timeoutMs}ms.`);
+        this.name = "SSETimeoutError";
+        this.scope = scope;
+    }
+}
+const parseFrame = (frame) => {
+    const lines = frame.split(/\r?\n/);
+    const dataLines = [];
+    let event;
+    let id;
+    for (const rawLine of lines) {
+        if (!rawLine || rawLine.startsWith(":"))
+            continue;
+        const idx = rawLine.indexOf(":");
+        const field = idx === -1 ? rawLine : rawLine.slice(0, idx);
+        let value = idx === -1 ? "" : rawLine.slice(idx + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            event = value;
+        else if (field === "data")
+            dataLines.push(value);
+        else if (field === "id")
+            id = value;
+    }
+    if (dataLines.length === 0)
+        return null;
+    return { event, data: dataLines.join("\n"), id };
+};
+const readWithTimeout = async (reader, scope, timeoutMs) => {
+    if (!timeoutMs || timeoutMs <= 0)
+        return reader.read();
+    let timeout;
+    try {
+        return await Promise.race([
+            reader.read(),
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    const error = new SSETimeoutError(scope, timeoutMs);
+                    void reader.cancel?.(error).catch(() => { });
+                    reject(error);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+};
+export const parseSSE = async function* (reader, timeouts = {}) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let readCount = 0;
+    while (true) {
+        const scope = readCount === 0 ? "provider_first_byte" : "provider_idle";
+        const timeoutMs = readCount === 0 ? timeouts.firstByteMs : timeouts.idleMs;
+        const { done, value } = await readWithTimeout(reader, scope, timeoutMs);
+        readCount++;
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const normalized = buffer.replace(/\r\n/g, "\n");
+        const frames = normalized.split("\n\n");
+        buffer = frames.pop() ?? "";
+        for (const frame of frames) {
+            const parsed = parseFrame(frame);
+            if (parsed)
+                yield parsed;
+        }
+    }
+    const finalFrame = buffer.replace(/\r\n/g, "\n");
+    const parsed = parseFrame(finalFrame);
+    if (parsed)
+        yield parsed;
+};

package/ai/shared/stream-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { SSEEvent } from "./sse.js";
+import type { ProviderTimeouts, RawStreamEvent } from "../types.js";
+type SSEStreamResult = {
+    ok: true;
+    events: AsyncGenerator<SSEEvent>;
+} | {
+    ok: false;
+    error: Extract<RawStreamEvent, {
+        type: "error" | "timeout";
+    }>;
+};
+export declare const openSSEStream: (url: string, headers: Record<string, string>, body: unknown, label: string, signal?: AbortSignal, contextWindow?: number, timeouts?: ProviderTimeouts) => Promise<SSEStreamResult>;
+export {};

package/ai/shared/stream-helpers.js

@@ -0,0 +1,105 @@
+import { formatConnectionError, normalizeHttpError } from "./errors.js";
+import { parseSSE, SSETimeoutError } from "./sse.js";
+export const openSSEStream = async (url, headers, body, label, signal, contextWindow, timeouts) => {
+    const serializedBody = JSON.stringify(body);
+    let response;
+    const controller = new AbortController();
+    const abortExternal = () => controller.abort(signal?.reason);
+    const cleanupExternalAbort = () => {
+        if (signal)
+            signal.removeEventListener("abort", abortExternal);
+    };
+    if (signal) {
+        if (signal.aborted)
+            controller.abort(signal.reason);
+        else
+            signal.addEventListener("abort", abortExternal, { once: true });
+    }
+    let firstByteTimeout;
+    const firstByteDeadline = timeouts?.firstByteMs && timeouts.firstByteMs > 0
+        ? Date.now() + timeouts.firstByteMs
+        : undefined;
+    try {
+        response = await Promise.race([
+            fetch(url, {
+                method: "POST",
+                headers,
+                body: serializedBody,
+                signal: controller.signal,
+            }),
+            new Promise((_, reject) => {
+                if (!timeouts?.firstByteMs || timeouts.firstByteMs <= 0)
+                    return;
+                firstByteTimeout = setTimeout(() => {
+                    controller.abort();
+                    reject(new SSETimeoutError("provider_first_byte", timeouts.firstByteMs));
+                }, timeouts.firstByteMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        cleanupExternalAbort();
+        if (error instanceof SSETimeoutError) {
+            return {
+                ok: false,
+                error: { type: "timeout", scope: error.scope, message: error.message, retryable: true },
+            };
+        }
+        // Heuristic: if the request body is large relative to the context window,
+        // a network error likely means the server rejected it for context overflow
+        // (browsers hide the actual HTTP 400 body behind CORS on error responses).
+        const estimatedTokens = serializedBody.length / 4;
+        const isLikelyOverflow = typeof contextWindow === "number"
+            && contextWindow > 0
+            && estimatedTokens > contextWindow * 0.85;
+        if (isLikelyOverflow) {
+            const ratio = estimatedTokens / contextWindow;
+            return {
+                ok: false,
+                error: {
+                    type: "error",
+                    error: `${label}: context window likely exceeded (~${Math.round(estimatedTokens)} tokens estimated, limit ${contextWindow})`,
+                    retryable: false,
+                    contextOverflow: true,
+                    overflowRatio: ratio,
+                },
+            };
+        }
+        return {
+            ok: false,
+            error: { type: "error", error: formatConnectionError(label, error), retryable: true },
+        };
+    }
+    finally {
+        if (firstByteTimeout)
+            clearTimeout(firstByteTimeout);
+    }
+    if (!response.ok) {
+        const normalized = await normalizeHttpError(label, response);
+        cleanupExternalAbort();
+        return { ok: false, error: { type: "error", ...normalized } };
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        cleanupExternalAbort();
+        return {
+            ok: false,
+            error: { type: "error", error: `${label} response body missing`, retryable: false },
+        };
+    }
+    const streamTimeouts = timeouts ? { ...timeouts } : undefined;
+    if (firstByteDeadline && streamTimeouts) {
+        streamTimeouts.firstByteMs = Math.max(1, firstByteDeadline - Date.now());
+    }
+    const events = async function* () {
+        try {
+            yield* parseSSE(reader, streamTimeouts);
+        }
+        finally {
+            cleanupExternalAbort();
+            controller.abort();
+            await reader.cancel().catch(() => { });
+        }
+    };
+    return { ok: true, events: events() };
+};

package/ai/shared/tool-call-ids.d.ts

@@ -0,0 +1,5 @@
+declare const ALNUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+declare const hash32: (input: string) => number;
+declare const encodeBase62: (seed: number, length: number) => string;
+declare const createStrictToolCallIdFactory: () => (seed: string) => string;
+export { ALNUM, hash32, encodeBase62, createStrictToolCallIdFactory };

package/ai/shared/tool-call-ids.js

@@ -0,0 +1,38 @@
+const ALNUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const hash32 = (input) => {
+    let h = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+};
+const encodeBase62 = (seed, length) => {
+    let n = seed >>> 0;
+    let out = "";
+    for (let i = 0; i < length; i++) {
+        if (n === 0)
+            n = hash32(`${seed}:${i}:${out.length}`);
+        out += ALNUM[n % ALNUM.length];
+        n = Math.floor(n / ALNUM.length);
+    }
+    return out;
+};
+const createStrictToolCallIdFactory = () => {
+    const used = new Set();
+    let seq = 0;
+    return (seed) => {
+        let attempt = 0;
+        while (attempt < 50_000) {
+            const candidate = encodeBase62(hash32(`${seed}:${seq}:${attempt}`), 9);
+            if (!used.has(candidate)) {
+                used.add(candidate);
+                seq++;
+                return candidate;
+            }
+            attempt++;
+        }
+        throw new Error("Failed to generate unique strict tool call id");
+    };
+};
+export { ALNUM, hash32, encodeBase62, createStrictToolCallIdFactory };

package/ai/shared/tool-stream-normalizer.d.ts

@@ -0,0 +1,6 @@
+import type { RawStreamEvent, StreamEvent } from "../types.js";
+type NormalizerOptions = {
+    suppressTextAfterMalformedTool?: boolean;
+};
+export declare function normalizeProviderStream(events: AsyncIterable<RawStreamEvent>, options?: NormalizerOptions): AsyncIterable<StreamEvent>;
+export {};

package/ai/shared/tool-stream-normalizer.js

@@ -0,0 +1,271 @@
+import { safeJsonParse, stringifyJson } from "./json.js";
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const parseArgsText = (argsText) => {
+    const trimmed = argsText.trim();
+    if (!trimmed)
+        return { ok: true };
+    return isRecord(safeJsonParse(trimmed))
+        ? { ok: true }
+        : { ok: false };
+};
+const issueMessage = (reason, tool) => {
+    const label = tool?.name ? `"${tool.name}"` : "unknown tool";
+    switch (reason) {
+        case "text_during_tool_call":
+            return `Received text while a tool call for ${label} was still open.`;
+        case "thinking_during_tool_call":
+            return `Received thinking text while a tool call for ${label} was still open.`;
+        case "tool_delta_without_start":
+            return "Received a tool argument delta before a matching tool_start event.";
+        case "missing_tool_name":
+            return "Received a tool call without a usable tool name.";
+        case "invalid_tool_arguments":
+            return `Received malformed JSON arguments for ${label}.`;
+        case "stream_ended_before_tool_call":
+            return `The stream ended before a pending tool call for ${label} became executable.`;
+        case "provider_error_before_tool_call":
+            return `The provider errored before a pending tool call for ${label} became executable.`;
+    }
+};
+function toolIssue(kind, pending, reason, extra) {
+    return {
+        kind,
+        callId: pending?.callId,
+        name: pending?.name,
+        reason,
+        message: issueMessage(reason, pending),
+        argsText: pending?.argsText,
+        textDelta: extra?.textDelta,
+    };
+}
+const blockFromOpen = (block) => block.kind === "thinking"
+    ? { type: "thinking", thinking: block.text }
+    : { type: "text", text: block.text };
+const isProviderTimeoutError = (error) => Boolean(error)
+    && typeof error === "object"
+    && (error.scope === "provider_first_byte" || error.scope === "provider_idle")
+    && typeof error.message === "string";
+export async function* normalizeProviderStream(events, options = {}) {
+    const pending = new Map();
+    const malformedCallIds = new Set();
+    let openBlock;
+    let nextBlockIndex = 0;
+    let emittedToolCallCount = 0;
+    let issueCount = 0;
+    let suppressMalformedTextSpan = false;
+    const emitIssue = function* (value) {
+        issueCount++;
+        yield { type: "issue", issue: value };
+    };
+    const closeOpenBlock = function* () {
+        if (!openBlock)
+            return;
+        const closing = openBlock;
+        openBlock = undefined;
+        yield {
+            type: "block_end",
+            blockId: closing.blockId,
+            index: closing.index,
+            block: blockFromOpen(closing),
+        };
+    };
+    const appendTextBlock = function* (kind, delta) {
+        if (delta.length === 0)
+            return;
+        if (!openBlock && delta.trim().length === 0)
+            return;
+        if (openBlock?.kind !== kind) {
+            yield* closeOpenBlock();
+            if (delta.trim().length === 0)
+                return;
+            const index = nextBlockIndex++;
+            openBlock = { blockId: `block-${index}`, index, kind, text: "" };
+            yield { type: "block_start", blockId: openBlock.blockId, index, kind };
+        }
+        openBlock.text += delta;
+        yield { type: "block_delta", blockId: openBlock.blockId, delta };
+    };
+    const emitToolCallBlock = function* (toolCall) {
+        yield* closeOpenBlock();
+        const index = nextBlockIndex++;
+        const blockId = `block-${index}`;
+        yield {
+            type: "block_start",
+            blockId,
+            index,
+            kind: "tool_call",
+            callId: toolCall.id,
+            name: toolCall.name,
+        };
+        yield { type: "block_delta", blockId, delta: stringifyJson(toolCall.args) };
+        yield { type: "block_end", blockId, index, block: toolCall };
+    };
+    const malformedPending = function* (reason, textDelta) {
+        yield* closeOpenBlock();
+        for (const tool of pending.values()) {
+            malformedCallIds.add(tool.callId);
+            yield* emitIssue(toolIssue("malformed_tool_call", tool, reason, { textDelta }));
+        }
+        pending.clear();
+        if (options.suppressTextAfterMalformedTool)
+            suppressMalformedTextSpan = true;
+    };
+    const cancelPending = function* (reason) {
+        if (pending.size === 0)
+            return;
+        yield* closeOpenBlock();
+        for (const tool of pending.values()) {
+            yield* emitIssue(toolIssue("cancelled_tool_call", tool, reason));
+        }
+        pending.clear();
+    };
+    try {
+        for await (const event of events) {
+            switch (event.type) {
+                case "text":
+                    if (pending.size > 0) {
+                        yield* malformedPending("text_during_tool_call", event.delta);
+                        if (options.suppressTextAfterMalformedTool)
+                            break;
+                    }
+                    if (suppressMalformedTextSpan)
+                        break;
+                    yield* appendTextBlock("text", event.delta);
+                    break;
+                case "thinking":
+                    if (pending.size > 0) {
+                        yield* malformedPending("thinking_during_tool_call", event.delta);
+                        if (options.suppressTextAfterMalformedTool)
+                            break;
+                    }
+                    if (suppressMalformedTextSpan)
+                        break;
+                    yield* appendTextBlock("thinking", event.delta);
+                    break;
+                case "tool_start":
+                    suppressMalformedTextSpan = false;
+                    yield* closeOpenBlock();
+                    pending.set(event.callId, { callId: event.callId, name: event.name, argsText: "", argsDeltas: [] });
+                    break;
+                case "tool_delta": {
+                    suppressMalformedTextSpan = false;
+                    if (malformedCallIds.has(event.callId))
+                        break;
+                    const tool = pending.get(event.callId);
+                    if (!tool) {
+                        yield* emitIssue({
+                            kind: "malformed_tool_call",
+                            reason: "tool_delta_without_start",
+                            message: issueMessage("tool_delta_without_start", undefined),
+                            callId: event.callId,
+                            argsText: event.argsDelta,
+                        });
+                        break;
+                    }
+                    tool.argsText += event.argsDelta;
+                    tool.argsDeltas.push(event.argsDelta);
+                    break;
+                }
+                case "tool_call": {
+                    suppressMalformedTextSpan = false;
+                    const tool = pending.get(event.callId);
+                    if (malformedCallIds.has(event.callId)) {
+                        malformedCallIds.delete(event.callId);
+                        pending.delete(event.callId);
+                        break;
+                    }
+                    if (!event.name.trim()) {
+                        malformedCallIds.add(event.callId);
+                        pending.delete(event.callId);
+                        yield* emitIssue(toolIssue("malformed_tool_call", tool ?? { callId: event.callId, name: event.name, argsText: "", argsDeltas: [] }, "missing_tool_name"));
+                        break;
+                    }
+                    if (tool && !parseArgsText(tool.argsText).ok) {
+                        malformedCallIds.add(event.callId);
+                        pending.delete(event.callId);
+                        yield* emitIssue(toolIssue("malformed_tool_call", tool, "invalid_tool_arguments"));
+                        break;
+                    }
+                    pending.delete(event.callId);
+                    emittedToolCallCount++;
+                    yield* emitToolCallBlock({ type: "tool_call", id: event.callId, name: event.name, args: event.args });
+                    break;
+                }
+                case "tool_error":
+                case "tool_cancel": {
+                    suppressMalformedTextSpan = false;
+                    if (event.callId)
+                        pending.delete(event.callId);
+                    yield* closeOpenBlock();
+                    yield* emitIssue({
+                        kind: event.type === "tool_error" ? "malformed_tool_call" : "cancelled_tool_call",
+                        reason: event.reason,
+                        message: event.message,
+                        callId: event.callId,
+                        name: event.name,
+                        argsText: event.argsText,
+                        textDelta: event.textDelta,
+                    });
+                    break;
+                }
+                case "usage":
+                    suppressMalformedTextSpan = false;
+                    if (event.finishReason && pending.size > 0) {
+                        yield* cancelPending("stream_ended_before_tool_call");
+                    }
+                    yield* closeOpenBlock();
+                    yield {
+                        ...event,
+                        finishReason: event.finishReason === "tool_use" && emittedToolCallCount === 0 && issueCount > 0
+                            ? "stop"
+                            : event.finishReason,
+                    };
+                    break;
+                case "error":
+                    suppressMalformedTextSpan = false;
+                    yield* cancelPending("provider_error_before_tool_call");
+                    yield* closeOpenBlock();
+                    yield* emitIssue({
+                        kind: "provider_error",
+                        message: event.error,
+                        retryable: event.retryable,
+                        contextOverflow: event.contextOverflow,
+                        overflowRatio: event.overflowRatio,
+                    });
+                    break;
+                case "timeout":
+                    suppressMalformedTextSpan = false;
+                    yield* cancelPending("provider_error_before_tool_call");
+                    yield* closeOpenBlock();
+                    yield* emitIssue({
+                        kind: "timeout",
+                        scope: event.scope,
+                        message: event.message,
+                        retryable: event.retryable,
+                    });
+                    break;
+            }
+        }
+    }
+    catch (error) {
+        yield* cancelPending("provider_error_before_tool_call");
+        yield* closeOpenBlock();
+        if (isProviderTimeoutError(error)) {
+            yield* emitIssue({
+                kind: "timeout",
+                scope: error.scope,
+                message: error.message,
+                retryable: true,
+            });
+            return;
+        }
+        yield* emitIssue({
+            kind: "provider_error",
+            message: error instanceof Error ? error.message : String(error),
+            retryable: true,
+        });
+        return;
+    }
+    yield* cancelPending("stream_ended_before_tool_call");
+    yield* closeOpenBlock();
+}

package/ai/shared/tools.d.ts

@@ -0,0 +1,29 @@
+import type { ToolSpec } from "../types.js";
+export declare const toOpenAITools: (tools: ToolSpec[]) => {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+    };
+}[];
+export declare const toAnthropicTools: (tools: ToolSpec[]) => {
+    name: string;
+    description: string;
+    input_schema: unknown;
+}[];
+export declare const toGeminiTools: (tools: ToolSpec[]) => {
+    functionDeclarations: {
+        name: string;
+        description: string;
+        parameters: unknown;
+    }[];
+}[];
+export declare const toOllamaTools: (tools: ToolSpec[]) => {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+    };
+}[];

package/ai/shared/tools.js

@@ -0,0 +1,25 @@
+export const toOpenAITools = (tools) => tools.map((tool) => ({
+    type: "function",
+    function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema,
+    },
+}));
+export const toAnthropicTools = (tools) => tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema,
+}));
+export const toGeminiTools = (tools) => {
+    if (tools.length === 0)
+        return [];
+    return [{
+            functionDeclarations: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema,
+            })),
+        }];
+};
+export const toOllamaTools = toOpenAITools;

package/ai/shared/usage.d.ts

@@ -0,0 +1,3 @@
+import type { Usage } from "../types.js";
+export declare const applyCredits: (usage: Usage, creditsPerInputToken?: number, creditsPerOutputToken?: number) => Usage;
+export declare const makeUsage: (input?: number, output?: number) => Usage;

package/ai/shared/usage.js

@@ -0,0 +1,5 @@
+export const applyCredits = (usage, creditsPerInputToken = 0, creditsPerOutputToken = 0) => ({
+    ...usage,
+    creditsUsed: creditsPerInputToken * usage.input + creditsPerOutputToken * usage.output,
+});
+export const makeUsage = (input = 0, output = 0) => ({ input, output, total: input + output });