@zenera/neo 1.1.0

package/dist/models/openai-responses.js

@@ -0,0 +1,258 @@
+var _a;
+import { zeroUsage } from "../types.js";
+/**
+ * Same `Model` contract as `OpenAIModel`, over `/v1/responses` instead of
+ * `/v1/chat/completions`. Reasoning models are the reason to prefer it: effort
+ * and summaries are first-class there.
+ */
+export class OpenAIResponsesModel {
+    id;
+    #client;
+    #reasoningEffort;
+    #reasoningSummary;
+    #store;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#reasoningEffort = options.reasoningEffort;
+        this.#reasoningSummary = options.reasoningSummary;
+        this.#store = options.store ?? false;
+    }
+    async generate(req) {
+        const res = await this.#client.responses.create(this.#params(req), {
+            signal: req.signal,
+        });
+        const toolCalls = readToolCalls(res.output);
+        return {
+            text: readText(res.output),
+            thinking: readThinking(res.output),
+            toolCalls,
+            usage: toUsage(res.usage),
+            stopReason: toStopReason(res, toolCalls.length > 0),
+        };
+    }
+    async stream(req, onDelta) {
+        const stream = await this.#client.responses.create({ ...this.#params(req), stream: true }, { signal: req.signal });
+        let text = '';
+        let thinking = '';
+        let final;
+        // Output items are addressed by their index in `response.output`, which
+        // every delta event carries — that is the only stable key while the
+        // items are still being assembled.
+        const calls = new Map();
+        for await (const event of stream) {
+            // Some models/gateways emit `response.reasoning.delta`, which the
+            // SDK does not carry in its event union, so it is matched before
+            // the typed switch.
+            if (event.type === 'response.reasoning.delta') {
+                const delta = readReasoningDelta(event.delta);
+                if (delta) {
+                    thinking += delta;
+                    onDelta({ type: 'thinking_delta', delta });
+                }
+                continue;
+            }
+            switch (event.type) {
+                case 'response.output_text.delta': {
+                    text += event.delta;
+                    onDelta({ type: 'text_delta', delta: event.delta });
+                    break;
+                }
+                case 'response.reasoning_summary_part.added': {
+                    // A response carries several summary parts, each its own
+                    // paragraph. Nothing separates them in the deltas, so a
+                    // blank line is inserted between them here.
+                    if (thinking) {
+                        thinking += '\n\n';
+                        onDelta({ type: 'thinking_delta', delta: '\n\n' });
+                    }
+                    break;
+                }
+                case 'response.reasoning_summary_text.delta': {
+                    thinking += event.delta;
+                    onDelta({ type: 'thinking_delta', delta: event.delta });
+                    break;
+                }
+                case 'response.output_item.added': {
+                    if (event.item.type === 'function_call') {
+                        const call = {
+                            id: event.item.call_id,
+                            name: event.item.name,
+                            args: '',
+                        };
+                        calls.set(event.output_index, call);
+                        onDelta({
+                            type: 'tool_call_detected',
+                            callId: call.id,
+                            name: call.name,
+                        });
+                    }
+                    break;
+                }
+                case 'response.function_call_arguments.delta': {
+                    const call = calls.get(event.output_index);
+                    if (call) {
+                        call.args += event.delta;
+                        onDelta({
+                            type: 'tool_args_delta',
+                            callId: call.id,
+                            name: call.name,
+                            delta: event.delta,
+                            argsSoFar: call.args,
+                        });
+                    }
+                    break;
+                }
+                case 'response.completed':
+                case 'response.incomplete':
+                case 'response.failed': {
+                    final = event.response;
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        const toolCalls = [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([, c]) => c);
+        return {
+            text,
+            thinking: thinking || undefined,
+            toolCalls,
+            usage: toUsage(final?.usage),
+            stopReason: final
+                ? toStopReason(final, toolCalls.length > 0)
+                : toolCalls.length
+                    ? 'tool_calls'
+                    : 'stop',
+        };
+    }
+    #params(req) {
+        return {
+            model: this.id,
+            // The responses API has a dedicated slot for the system prompt
+            // instead of a leading message.
+            instructions: req.system,
+            input: req.messages.flatMap(_a.#toResponses),
+            store: this.#store,
+            reasoning: this.#reasoningEffort
+                ? { effort: this.#reasoningEffort, summary: this.#reasoningSummary }
+                : undefined,
+            tools: req.tools.length
+                ? req.tools.map((t) => ({
+                    // Tools are flat here — no nested `function` object.
+                    type: 'function',
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                    strict: false,
+                }))
+                : undefined,
+            tool_choice: req.tools.length ? (req.toolChoice ?? 'auto') : undefined,
+        };
+    }
+    /**
+     * Translates one internal message into responses-API input items. Returns a
+     * list because an assistant turn with tool calls becomes several items: the
+     * prose message plus one `function_call` per call.
+     */
+    static #toResponses(m) {
+        switch (m.role) {
+            case 'system':
+                return [{ role: 'system', content: m.content }];
+            case 'user':
+                return [
+                    {
+                        role: 'user',
+                        // Only images have a first-class multimodal representation
+                        // by url; other media degrade to a text reference so the
+                        // thread stays valid instead of throwing.
+                        content: m.content.map((p) => p.type === 'text'
+                            ? { type: 'input_text', text: p.text }
+                            : p.type === 'image'
+                                ? {
+                                    type: 'input_image',
+                                    image_url: p.url,
+                                    detail: 'auto',
+                                }
+                                : { type: 'input_text', text: `[${p.type}] ${p.url}` }),
+                    },
+                ];
+            case 'assistant': {
+                const items = [];
+                if (m.content) {
+                    items.push({ role: 'assistant', content: m.content });
+                }
+                for (const c of m.toolCalls ?? []) {
+                    items.push({
+                        type: 'function_call',
+                        call_id: c.id,
+                        name: c.name,
+                        arguments: c.args,
+                    });
+                }
+                return items;
+            }
+            case 'tool':
+                return [{ type: 'function_call_output', call_id: m.callId, output: m.content }];
+        }
+    }
+}
+_a = OpenAIResponsesModel;
+function readText(output) {
+    return output
+        .flatMap((item) => item.type === 'message'
+        ? item.content.flatMap((p) => (p.type === 'output_text' ? [p.text] : []))
+        : [])
+        .join('');
+}
+function readThinking(output) {
+    const parts = output.flatMap((item) => item.type === 'reasoning' ? item.summary.map((s) => s.text) : []);
+    return parts.join('\n\n') || undefined;
+}
+function readToolCalls(output) {
+    // `call_id` — not `id` — is what a later `function_call_output` must
+    // reference, so it is the identity we carry through the trajectory.
+    return output.flatMap((item) => item.type === 'function_call'
+        ? [{ id: item.call_id, name: item.name, args: item.arguments }]
+        : []);
+}
+function toStopReason(res, hasToolCalls) {
+    if (hasToolCalls) {
+        return 'tool_calls';
+    }
+    switch (res.incomplete_details?.reason) {
+        case 'max_output_tokens':
+            return 'length';
+        case 'content_filter':
+            return 'content_filter';
+        default:
+            return 'stop';
+    }
+}
+function toUsage(u) {
+    if (!u) {
+        return undefined;
+    }
+    return {
+        ...zeroUsage(),
+        inputTokens: u.input_tokens,
+        cachedInputTokens: u.input_tokens_details?.cached_tokens ?? 0,
+        outputTokens: u.output_tokens,
+        reasoningTokens: u.output_tokens_details?.reasoning_tokens ?? 0,
+    };
+}
+/**
+ * `response.reasoning.delta` carries an untyped payload: providers send either a
+ * bare string or `{ text }`.
+ */
+function readReasoningDelta(delta) {
+    if (typeof delta === 'string') {
+        return delta || undefined;
+    }
+    if (delta === null || typeof delta !== 'object') {
+        return undefined;
+    }
+    const text = delta.text;
+    return typeof text === 'string' && text ? text : undefined;
+}
+//# sourceMappingURL=openai-responses.js.map

package/dist/models/openrouter.d.ts

@@ -0,0 +1,44 @@
+import type { OpenRouter } from '@openrouter/sdk';
+import type { ChatRequestPlugin, ProviderPreferences } from '@openrouter/sdk/models';
+import type { StreamDelta } from '../events.ts';
+import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/**
+ * Effort levels, spelled out rather than imported: the SDK's is an *open* enum
+ * (its literals plus any string), which would let a typo through, and naming
+ * its type here would tie this interface to a generated alias. The set is the
+ * same one the OpenAI adapters accept, which is what lets `ModelSpec` extend
+ * both without the two declarations disagreeing.
+ */
+export type OpenRouterEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
+/** Provider-specific knobs. */
+export interface OpenRouterModelOptions {
+    reasoningEffort?: OpenRouterEffort;
+    /** ask for a reasoning summary from models that expose one */
+    reasoningSummary?: 'auto' | 'concise' | 'detailed';
+    /** hard cap on output tokens; the model's own default applies when unset */
+    maxTokens?: number;
+    /**
+     * Which upstream providers may serve this model, and in what order. Named
+     * `routing` rather than the SDK's `provider` because in this runtime a
+     * provider is already the *connection* — OpenRouter itself — and reusing
+     * the word for "who OpenRouter hands the request to" would collide.
+     */
+    routing?: ProviderPreferences;
+    /**
+     * Models to try, in order, when the primary one is unavailable. The SDK
+     * calls this `models`; `fallbacks` says which of the two lists it is.
+     */
+    fallbacks?: string[];
+    /** OpenRouter-side plugins: web search, file parsing, moderation */
+    plugins?: ChatRequestPlugin[];
+    /** provider-dependent latency/price tier, ignored where unsupported */
+    serviceTier?: 'auto' | 'default' | 'fast' | 'flex' | 'priority' | 'scale';
+}
+export declare class OpenRouterModel implements Model {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: OpenRouter, options?: OpenRouterModelOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    stream(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=openrouter.d.ts.map

package/dist/models/openrouter.js

@@ -0,0 +1,230 @@
+var _a;
+import { zeroUsage } from "../types.js";
+function toStopReason(finish) {
+    switch (finish) {
+        case 'tool_calls':
+            return 'tool_calls';
+        case 'length':
+            return 'length';
+        case 'content_filter':
+            return 'content_filter';
+        default:
+            return 'stop';
+    }
+}
+/**
+ * Assistant content is `string | ContentItems[] | null` here, unlike chat
+ * completions where it is a string. The array form appears when a provider
+ * returns text alongside images, so the text parts are what this runtime's
+ * `text` channel means; anything else is carried by other fields.
+ */
+function toText(content) {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!content) {
+        return '';
+    }
+    return content
+        .filter((p) => p.type === 'text')
+        .map((p) => p.text)
+        .join('');
+}
+function toUsage(u) {
+    if (!u) {
+        return undefined;
+    }
+    return {
+        ...zeroUsage(),
+        inputTokens: u.promptTokens,
+        cachedInputTokens: u.promptTokensDetails?.cachedTokens ?? 0,
+        outputTokens: u.completionTokens,
+        reasoningTokens: u.completionTokensDetails?.reasoningTokens ?? 0,
+    };
+}
+export class OpenRouterModel {
+    id;
+    #client;
+    #options;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#options = options;
+    }
+    async generate(req) {
+        const res = await this.#send(req, false);
+        // Both overloads are declared to return the same union, so the narrowing
+        // the `stream` flag implies has to be done here.
+        if (Symbol.asyncIterator in res) {
+            throw new Error(`model "${this.id}": asked for one completion, got a stream`);
+        }
+        const choice = res.choices[0];
+        const message = choice?.message;
+        return {
+            text: toText(message?.content),
+            thinking: message?.reasoning ?? undefined,
+            toolCalls: (message?.toolCalls ?? []).map((c) => ({
+                id: c.id,
+                name: c.function.name,
+                args: c.function.arguments,
+            })),
+            usage: toUsage(res.usage),
+            stopReason: toStopReason(choice?.finishReason),
+        };
+    }
+    async stream(req, onDelta) {
+        const res = await this.#send(req, true);
+        if (!(Symbol.asyncIterator in res)) {
+            throw new Error(`model "${this.id}": asked for a stream, got one completion`);
+        }
+        let text = '';
+        let thinking = '';
+        let usage;
+        let stopReason;
+        // Tool calls arrive as deltas keyed by index, with the id and name in the
+        // first fragment and arguments trickling in afterwards.
+        const calls = new Map();
+        for await (const chunk of res) {
+            // An upstream failure mid-stream arrives as a chunk on a 200, so it
+            // has to be raised here or the turn ends early and looks complete.
+            if (chunk.error) {
+                throw new Error(`model "${this.id}": ${chunk.error.message} (${chunk.error.code})`);
+            }
+            if (chunk.usage) {
+                usage = toUsage(chunk.usage);
+            }
+            const choice = chunk.choices[0];
+            if (!choice) {
+                continue;
+            }
+            if (choice.finishReason) {
+                stopReason = toStopReason(choice.finishReason);
+            }
+            const delta = choice.delta;
+            if (delta.reasoning) {
+                thinking += delta.reasoning;
+                onDelta({ type: 'thinking_delta', delta: delta.reasoning });
+            }
+            if (delta.content) {
+                text += delta.content;
+                onDelta({ type: 'text_delta', delta: delta.content });
+            }
+            for (const part of delta.toolCalls ?? []) {
+                const known = calls.get(part.index);
+                const call = known ?? {
+                    id: part.id ?? `call_${part.index}`,
+                    name: part.function?.name ?? '',
+                    args: '',
+                };
+                if (!known) {
+                    calls.set(part.index, call);
+                }
+                if (part.id) {
+                    call.id = part.id;
+                }
+                if (part.function?.name) {
+                    call.name = part.function.name;
+                }
+                if (!known || (part.function?.name && !known.name)) {
+                    onDelta({ type: 'tool_call_detected', callId: call.id, name: call.name });
+                }
+                const args = part.function?.arguments;
+                if (args) {
+                    call.args += args;
+                    onDelta({
+                        type: 'tool_args_delta',
+                        callId: call.id,
+                        name: call.name,
+                        delta: args,
+                        argsSoFar: call.args,
+                    });
+                }
+            }
+        }
+        return {
+            text,
+            thinking: thinking || undefined,
+            toolCalls: [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([, c]) => c),
+            usage,
+            stopReason: stopReason ?? (calls.size ? 'tool_calls' : 'stop'),
+        };
+    }
+    /**
+     * The abort signal rides in `fetchOptions` rather than on the request: this
+     * SDK keeps transport concerns out of the body it validates.
+     */
+    #send(req, stream) {
+        return this.#client.chat.send({ chatRequest: this.#request(req, stream) }, { fetchOptions: { signal: req.signal } });
+    }
+    #request(req, stream) {
+        const o = this.#options;
+        const messages = [];
+        if (req.system) {
+            messages.push({ role: 'system', content: req.system });
+        }
+        for (const m of req.messages) {
+            messages.push(_a.#toOpenRouter(m));
+        }
+        return {
+            model: this.id,
+            messages,
+            stream,
+            maxCompletionTokens: o.maxTokens,
+            reasoning: o.reasoningEffort || o.reasoningSummary
+                ? { effort: o.reasoningEffort, summary: o.reasoningSummary }
+                : undefined,
+            provider: o.routing,
+            models: o.fallbacks,
+            plugins: o.plugins,
+            serviceTier: o.serviceTier,
+            tools: req.tools.length
+                ? req.tools.map((t) => ({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    },
+                }))
+                : undefined,
+            toolChoice: req.tools.length ? (req.toolChoice ?? 'auto') : undefined,
+        };
+    }
+    /** Translates one internal message into the provider wire format. */
+    static #toOpenRouter(m) {
+        switch (m.role) {
+            case 'system':
+                return { role: 'system', content: m.content };
+            case 'user':
+                return {
+                    role: 'user',
+                    // Only images have a first-class multimodal representation
+                    // here; other media degrade to a text reference so the
+                    // thread stays valid instead of throwing.
+                    content: m.content.map((p) => p.type === 'text'
+                        ? { type: 'text', text: p.text }
+                        : p.type === 'image'
+                            ? { type: 'image_url', imageUrl: { url: p.url } }
+                            : { type: 'text', text: `[${p.type}] ${p.url}` }),
+                };
+            case 'assistant':
+                return {
+                    role: 'assistant',
+                    // A tool-calling turn usually has no prose; the API wants an
+                    // explicit null there rather than an empty string.
+                    content: m.content || null,
+                    toolCalls: m.toolCalls?.length
+                        ? m.toolCalls.map((c) => ({
+                            id: c.id,
+                            type: 'function',
+                            function: { name: c.name, arguments: c.args },
+                        }))
+                        : undefined,
+                };
+            case 'tool':
+                return { role: 'tool', toolCallId: m.callId, content: m.content };
+        }
+    }
+}
+_a = OpenRouterModel;
+//# sourceMappingURL=openrouter.js.map

package/dist/payload-stores/factory.d.ts

@@ -0,0 +1,15 @@
+import type { PayloadStore } from '../payload.ts';
+import { type FilePayloadStoreOptions } from './file.ts';
+export interface MemoryPayloadStoreSpec {
+    kind: 'memory';
+    id?: string;
+}
+export interface FilePayloadStoreSpec extends FilePayloadStoreOptions {
+    kind: 'file';
+}
+/** Grows a member per backend (`s3`, …); `kind` is the discriminator. */
+export type PayloadStoreSpec = MemoryPayloadStoreSpec | FilePayloadStoreSpec;
+/** Shorthand: `mem`, `memory`, `file:./.data/blobs`. */
+export type PayloadStoreRef = PayloadStoreSpec | string;
+export declare function createPayloadStore(ref: PayloadStoreRef): PayloadStore;
+//# sourceMappingURL=factory.d.ts.map

package/dist/payload-stores/factory.js

@@ -0,0 +1,30 @@
+import { FilePayloadStore } from "./file.js";
+import { InMemoryPayloadStore } from "./in-memory.js";
+export function createPayloadStore(ref) {
+    const spec = typeof ref === 'string' ? parseRef(ref) : ref;
+    switch (spec.kind) {
+        case 'memory':
+            return new InMemoryPayloadStore(spec.id);
+        case 'file':
+            return new FilePayloadStore(spec);
+        default:
+            throw new TypeError(`unknown payload store kind: ${spec.kind}`);
+    }
+}
+function parseRef(ref) {
+    if (ref === 'mem' || ref === 'memory') {
+        return { kind: 'memory' };
+    }
+    // Only the first colon separates the scheme: a path may contain colons.
+    const colon = ref.indexOf(':');
+    const scheme = colon < 0 ? ref : ref.slice(0, colon);
+    const rest = colon < 0 ? '' : ref.slice(colon + 1);
+    if (scheme === 'file') {
+        if (!rest) {
+            throw new TypeError(`missing directory in "${ref}" (expected file:<dir>)`);
+        }
+        return { kind: 'file', dir: rest };
+    }
+    throw new TypeError(`unknown payload store ref: "${ref}"`);
+}
+//# sourceMappingURL=factory.js.map

package/dist/payload-stores/file.d.ts

@@ -0,0 +1,29 @@
+import { type Payload, type PayloadStore } from '../payload.ts';
+export interface FilePayloadStoreOptions {
+    /** root directory; created on demand */
+    dir: string;
+    /**
+     * Store id embedded in every `Payload` this store hands out. Keep it a
+     * logical name (not the path) so a run stays portable between machines.
+     */
+    id?: string;
+    /** parallel reads in `getMany` — guards against EMFILE on big projections */
+    concurrency?: number;
+    /** re-hash on read; turns silent corruption into a loud error */
+    verify?: boolean;
+}
+/**
+ * Same contract as the in-memory store, on disk. Content addressing does the
+ * hard part: writes are write-once and therefore idempotent under retry and
+ * replay, and two processes racing on the same blob produce identical bytes.
+ */
+export declare class FilePayloadStore implements PayloadStore {
+    #private;
+    readonly id: string;
+    constructor(opts: FilePayloadStoreOptions | string);
+    get dir(): string;
+    put(value: string): Promise<Payload>;
+    get(p: Payload): Promise<string>;
+    getMany(ps: Payload[]): Promise<string[]>;
+}
+//# sourceMappingURL=file.d.ts.map