@zenera/neo 1.1.0

package/dist/models/gemini.js

@@ -0,0 +1,368 @@
+import { zeroUsage, } from "../types.js";
+/**
+ * Google's `ThinkingLevel` is a *string* enum, so its members are just their
+ * own names on the wire. Spelling them out keeps `@google/genai` out of this
+ * module's runtime imports — an enum is a value, and importing one would load
+ * the whole SDK for anyone who merely imports the library. The cast is what an
+ * enum costs: a literal is not assignable to a nominal enum type, even when it
+ * is the same string.
+ */
+const THINKING_LEVELS = {
+    minimal: 'MINIMAL',
+    low: 'LOW',
+    medium: 'MEDIUM',
+    high: 'HIGH',
+};
+/** `FunctionCallingConfigMode`, spelled out for the same reason. */
+const CALLING_MODES = {
+    any: 'ANY',
+    none: 'NONE',
+    auto: 'AUTO',
+};
+/**
+ * Ids this adapter invented. The Gemini API returns function calls without one
+ * — Vertex does populate `id` — but the runner pairs results to calls by id, so
+ * one has to exist. The prefix is how a synthesized id is recognised on the way
+ * back out and dropped, leaving the API to pair by function name as it expects.
+ */
+const SYNTHETIC_ID = 'gemini-call-';
+/**
+ * The `Model` contract over `generateContent`.
+ *
+ * Google publishes an OpenAI-compatible endpoint, and reaching Gemini through
+ * it costs nothing but a base url. What it costs *afterwards* is everything
+ * this file exists for: thinking budgets and thought summaries, thought
+ * signatures (without which Gemini 3 function calling is rejected outright),
+ * cached-content accounting, and the block reasons that come back when a safety
+ * filter fires. None of those have an OpenAI field to be carried in.
+ */
+export class GeminiModel {
+    id;
+    #client;
+    #options;
+    #nextId = 0;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#options = options;
+    }
+    async generate(req) {
+        const res = await this.#client.models.generateContent(this.#params(req));
+        const read = emptyRead();
+        for (const part of candidateParts(res)) {
+            this.#readPart(part, read);
+        }
+        return this.#finish(read, res);
+    }
+    async stream(req, onDelta) {
+        const stream = await this.#client.models.generateContentStream(this.#params(req));
+        const read = emptyRead();
+        let last;
+        for await (const chunk of stream) {
+            last = chunk;
+            for (const part of candidateParts(chunk)) {
+                this.#readPart(part, read, onDelta);
+            }
+        }
+        return this.#finish(read, last);
+    }
+    /**
+     * Folds one part into the accumulator, emitting deltas when streaming.
+     * Shared by both paths so a streamed run and a plain one cannot disagree
+     * about what a part meant.
+     */
+    #readPart(part, into, onDelta) {
+        if (part.text !== undefined) {
+            // Thought summaries arrive as ordinary text parts flagged
+            // `thought`; the flag is the only thing separating reasoning from
+            // the answer.
+            if (part.thought) {
+                into.thinking += part.text;
+                onDelta?.({ type: 'thinking_delta', delta: part.text });
+            }
+            else {
+                into.text += part.text;
+                onDelta?.({ type: 'text_delta', delta: part.text });
+            }
+            return;
+        }
+        const call = part.functionCall;
+        if (!call) {
+            return;
+        }
+        const id = this.#callId(call.id);
+        const name = call.name ?? '';
+        const args = JSON.stringify(call.args ?? {});
+        // Gemini 3 requires the signature back on the replayed call and fails
+        // the request without it, so it rides along on the call rather than in
+        // an adapter-side cache that a handoff or a restart would lose.
+        into.toolCalls.push({ id, name, args, signature: part.thoughtSignature });
+        // Arguments are not streamed incrementally by this API: a call arrives
+        // whole, so detection and the arguments are one event apart and
+        // `argsSoFar` is complete the moment it is first seen.
+        onDelta?.({ type: 'tool_call_detected', callId: id, name });
+        onDelta?.({ type: 'tool_args_delta', callId: id, name, delta: args, argsSoFar: args });
+    }
+    #finish(read, res) {
+        return {
+            text: read.text,
+            thinking: read.thinking || undefined,
+            toolCalls: read.toolCalls,
+            usage: toUsage(res?.usageMetadata),
+            stopReason: toStopReason(res?.candidates?.[0]?.finishReason, read.toolCalls.length > 0),
+        };
+    }
+    #params(req) {
+        return {
+            model: this.id,
+            contents: toContents(req.messages),
+            config: this.#config(req),
+        };
+    }
+    #config(req) {
+        const o = this.#options;
+        const thinking = o.thinkingBudget !== undefined || o.thinkingLevel !== undefined
+            ? {
+                thinkingBudget: o.thinkingBudget,
+                thinkingLevel: o.thinkingLevel && THINKING_LEVELS[o.thinkingLevel],
+                includeThoughts: o.includeThoughts ?? true,
+            }
+            : { includeThoughts: o.includeThoughts ?? true };
+        return {
+            // Unlike the other two vendors this is a *config* field rather than
+            // a turn, so a system prompt never occupies a position in the
+            // conversation and cannot be reordered by history trimming.
+            systemInstruction: req.system,
+            maxOutputTokens: o.maxTokens,
+            thinkingConfig: thinking,
+            abortSignal: req.signal,
+            tools: req.tools.length
+                ? [
+                    {
+                        functionDeclarations: req.tools.map((t) => ({
+                            name: t.name,
+                            description: t.description,
+                            // The `parameters` field takes Google's own
+                            // trimmed-down Schema; this one takes the JSON
+                            // Schema the rest of the runtime already speaks.
+                            parametersJsonSchema: t.parameters,
+                        })),
+                    },
+                ]
+                : undefined,
+            toolConfig: req.tools.length
+                ? { functionCallingConfig: { mode: toCallingMode(req.toolChoice) } }
+                : undefined,
+        };
+    }
+    /** Mints an id for a call the API left unidentified. */
+    #callId(id) {
+        return id ?? `${SYNTHETIC_ID}${this.#nextId++}`;
+    }
+}
+function emptyRead() {
+    return { text: '', thinking: '', toolCalls: [] };
+}
+function candidateParts(res) {
+    return res.candidates?.[0]?.content?.parts ?? [];
+}
+/**
+ * Internal messages → Gemini contents.
+ *
+ * The role vocabulary is `user` and `model`, with tool results carried as
+ * `functionResponse` parts inside a *user* turn — so, as with Anthropic,
+ * adjacent turns of the same role are merged rather than emitted one per
+ * message. The user side is buffered rather than merged in place, because
+ * Gemini constrains the shape of the turn answering a set of tool calls in two
+ * ways that the message order does not respect on its own: see `flushUser`.
+ */
+function toContents(messages) {
+    const out = [];
+    let results = [];
+    let plain = [];
+    /**
+     * Emits the pending user turn, tool results first and on their own.
+     *
+     * Every `functionResponse` answering one model turn has to arrive in a
+     * single `Content` holding nothing else. Both halves of that are enforced
+     * by the API and neither is hypothetical here: a `load_skills` node lands
+     * between the `skill_load` result and the results of the calls issued
+     * alongside it, which naively yields `[response][text][response]` and
+     * breaks the rule twice over. The API's two complaints are worth writing
+     * down, since neither describes what is actually wrong:
+     *
+     * - splitting the responses gets `Please ensure that the number of function
+     *   response parts is equal to the number of function call parts`
+     * - mixing text in with them gets `Requests ending with a model turn are
+     *   not supported`
+     *
+     * Deferring the text to a turn of its own satisfies both. Nothing is lost:
+     * the parts still sit between the same two model turns, in the same order
+     * relative to everything the model reads as prose.
+     */
+    const flushUser = () => {
+        if (results.length) {
+            out.push({ role: 'user', parts: results });
+            results = [];
+        }
+        if (plain.length) {
+            out.push({ role: 'user', parts: plain });
+            plain = [];
+        }
+    };
+    const pushModel = (parts) => {
+        if (!parts.length) {
+            return;
+        }
+        flushUser();
+        const last = out.at(-1);
+        if (last?.role === 'model') {
+            last.parts?.push(...parts);
+            return;
+        }
+        out.push({ role: 'model', parts });
+    };
+    for (const m of messages) {
+        switch (m.role) {
+            case 'system':
+                // A mid-conversation system message is a memory recall, and
+                // hoisting it into `systemInstruction` would move it away from
+                // the point it was injected at. A user turn keeps the position.
+                plain.push({ text: m.content });
+                break;
+            case 'user':
+                plain.push(...m.content.map(toPart));
+                break;
+            case 'assistant': {
+                const parts = [];
+                if (m.content) {
+                    parts.push({ text: m.content });
+                }
+                for (const c of m.toolCalls ?? []) {
+                    parts.push({
+                        functionCall: {
+                            id: wireId(c.id),
+                            name: c.name,
+                            args: parseArgs(c.args),
+                        },
+                        // Gemini 3 rejects a replayed call whose signature is
+                        // missing. One produced by a different Gemini model is
+                        // still accepted — the backend handles compatibility —
+                        // so a handoff between two of them replays cleanly.
+                        thoughtSignature: c.signature,
+                    });
+                }
+                pushModel(parts);
+                break;
+            }
+            case 'tool':
+                results.push({
+                    functionResponse: {
+                        id: wireId(m.callId),
+                        name: m.name,
+                        // The API wants an object, not a string. `output`
+                        // and `error` are the conventional keys, and the
+                        // distinction is otherwise lost.
+                        response: m.isError ? { error: m.content } : { output: m.content },
+                    },
+                });
+                break;
+        }
+    }
+    flushUser();
+    return out;
+}
+/** Drops ids this adapter invented, so the API pairs by function name instead. */
+function wireId(id) {
+    return id.startsWith(SYNTHETIC_ID) ? undefined : id;
+}
+/** Only text and inline media have first-class parts; the rest degrade to text. */
+function toPart(part) {
+    if (part.type === 'text') {
+        return { text: part.text };
+    }
+    const inline = readDataUri(part.url);
+    if (inline) {
+        return { inlineData: inline };
+    }
+    // A remote uri has to be one the service can fetch — a Files API or GCS
+    // reference — and needs its mime type declared, which a bare url does not
+    // carry. Without one there is nothing to send but the url itself.
+    return part.mimeType
+        ? { fileData: { fileUri: part.url, mimeType: part.mimeType } }
+        : { text: `[${part.type}] ${part.url}` };
+}
+const DATA_URI = /^data:([^;,]+);base64,(.*)$/s;
+function readDataUri(url) {
+    const match = DATA_URI.exec(url);
+    return match ? { mimeType: match[1], data: match[2] } : undefined;
+}
+/**
+ * Tool arguments travel as the raw JSON string the model produced, because that
+ * is what the trajectory stores and what other providers want back verbatim.
+ * Gemini wants the parsed object, and a malformed one is the model's error to
+ * see rather than a crash here.
+ */
+function parseArgs(args) {
+    if (!args.trim()) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(args);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return { _raw: args };
+    }
+}
+function toCallingMode(choice) {
+    switch (choice) {
+        case 'required':
+            return CALLING_MODES.any;
+        case 'none':
+            return CALLING_MODES.none;
+        default:
+            return CALLING_MODES.auto;
+    }
+}
+/**
+ * `promptTokenCount` already includes whatever the cache served, matching this
+ * runtime's definition of `cachedInputTokens` as a subset. Thinking is the
+ * opposite: `thoughtsTokenCount` is reported *beside* `candidatesTokenCount`
+ * rather than inside it, so it is added in to keep `reasoningTokens` a subset
+ * of `outputTokens`.
+ */
+function toUsage(u) {
+    if (!u) {
+        return undefined;
+    }
+    const thoughts = u.thoughtsTokenCount ?? 0;
+    return {
+        ...zeroUsage(),
+        inputTokens: u.promptTokenCount ?? 0,
+        cachedInputTokens: u.cachedContentTokenCount ?? 0,
+        outputTokens: (u.candidatesTokenCount ?? 0) + thoughts,
+        reasoningTokens: thoughts,
+    };
+}
+/**
+ * Gemini has no finish reason for "stopped to call a tool" — a turn ending in
+ * function calls still reports `STOP`. The presence of calls is therefore the
+ * only signal, and it has to be applied here rather than left to the kernel's
+ * fallback, which only fires when a stop reason is missing entirely.
+ */
+function toStopReason(reason, toolCalls) {
+    switch (reason) {
+        case 'MAX_TOKENS':
+            return 'length';
+        case 'SAFETY':
+        case 'RECITATION':
+        case 'BLOCKLIST':
+        case 'PROHIBITED_CONTENT':
+        case 'SPII':
+            return 'content_filter';
+        default:
+            return toolCalls ? 'tool_calls' : 'stop';
+    }
+}
+//# sourceMappingURL=gemini.js.map

package/dist/models/index.d.ts

@@ -0,0 +1,7 @@
+export * from './anthropic.ts';
+export * from './factory.ts';
+export * from './gemini.ts';
+export * from './openai-chat.ts';
+export * from './openai-responses.ts';
+export * from './openrouter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/models/index.js

@@ -0,0 +1,7 @@
+export * from "./anthropic.js";
+export * from "./factory.js";
+export * from "./gemini.js";
+export * from "./openai-chat.js";
+export * from "./openai-responses.js";
+export * from "./openrouter.js";
+//# sourceMappingURL=index.js.map

package/dist/models/openai-chat.d.ts

@@ -0,0 +1,19 @@
+import type OpenAI from 'openai';
+import type { StreamDelta } from '../events.ts';
+import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/**
+ * Provider-specific knobs. Reasoning effort is deliberately *not* part of
+ * `ModelRequest`: every provider spells it differently (and most models ignore
+ * it), so it belongs to the concrete adapter rather than the `Model` contract.
+ */
+export interface OpenAIModelOptions {
+    reasoningEffort?: OpenAI.ReasoningEffort;
+}
+export declare class OpenAIModel implements Model {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: OpenAI, options?: OpenAIModelOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    stream(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=openai-chat.d.ts.map

package/dist/models/openai-chat.js

@@ -0,0 +1,203 @@
+var _a;
+import { zeroUsage } from "../types.js";
+// ---------------------------------------------------------------------------
+// OpenAI chat-completions adapter
+// ---------------------------------------------------------------------------
+function toStopReason(finish) {
+    switch (finish) {
+        case 'tool_calls':
+        case 'function_call':
+            return 'tool_calls';
+        case 'length':
+            return 'length';
+        case 'content_filter':
+            return 'content_filter';
+        default:
+            return 'stop';
+    }
+}
+export class OpenAIModel {
+    id;
+    #client;
+    #reasoningEffort;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#reasoningEffort = options.reasoningEffort;
+    }
+    async generate(req) {
+        const res = await this.#client.chat.completions.create(this.#params(req), {
+            signal: req.signal,
+        });
+        const choice = res.choices[0];
+        const message = choice?.message;
+        return {
+            text: message?.content ?? '',
+            thinking: readReasoning(message),
+            toolCalls: (message?.tool_calls ?? []).flatMap((c) => c.type === 'function'
+                ? [{ id: c.id, name: c.function.name, args: c.function.arguments }]
+                : []),
+            usage: toUsage(res.usage),
+            stopReason: toStopReason(choice?.finish_reason),
+        };
+    }
+    async stream(req, onDelta) {
+        const stream = await this.#client.chat.completions.create({ ...this.#params(req), stream: true, stream_options: { include_usage: true } }, { signal: req.signal });
+        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 stream) {
+            if (chunk.usage) {
+                usage = toUsage(chunk.usage);
+            }
+            const choice = chunk.choices[0];
+            if (!choice) {
+                continue;
+            }
+            if (choice.finish_reason) {
+                stopReason = toStopReason(choice.finish_reason);
+            }
+            const delta = choice.delta;
+            const reasoning = readReasoning(delta);
+            if (reasoning) {
+                thinking += reasoning;
+                onDelta({ type: 'thinking_delta', delta: reasoning });
+            }
+            if (delta?.content) {
+                text += delta.content;
+                onDelta({ type: 'text_delta', delta: delta.content });
+            }
+            for (const part of delta?.tool_calls ?? []) {
+                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'),
+        };
+    }
+    #params(req) {
+        const messages = [];
+        if (req.system) {
+            messages.push({ role: 'system', content: req.system });
+        }
+        for (const m of req.messages) {
+            messages.push(_a.#toOpenAI(m));
+        }
+        return {
+            model: this.id,
+            messages,
+            reasoning_effort: this.#reasoningEffort,
+            tools: req.tools.length
+                ? req.tools.map((t) => ({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    },
+                }))
+                : undefined,
+            tool_choice: req.tools.length ? (req.toolChoice ?? 'auto') : undefined,
+        };
+    }
+    /**
+     * Translates one internal message into the provider wire format. Static +
+     * private because it is pure and must not be part of the public surface.
+     */
+    static #toOpenAI(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 in
+                    // chat completions; 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', image_url: { 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,
+                    tool_calls: 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', tool_call_id: m.callId, content: m.content };
+        }
+    }
+}
+_a = OpenAIModel;
+function toUsage(u) {
+    if (!u) {
+        return undefined;
+    }
+    return {
+        ...zeroUsage(),
+        inputTokens: u.prompt_tokens,
+        cachedInputTokens: u.prompt_tokens_details?.cached_tokens ?? 0,
+        outputTokens: u.completion_tokens,
+        reasoningTokens: u.completion_tokens_details?.reasoning_tokens ?? 0,
+    };
+}
+/**
+ * Reasoning text is not part of the chat-completions type surface, but several
+ * providers (and OpenAI-compatible gateways) put it on the message or delta.
+ */
+function readReasoning(v) {
+    if (v === null || typeof v !== 'object') {
+        return undefined;
+    }
+    const r = v;
+    const value = typeof r.reasoning === 'string' ? r.reasoning : r.reasoning_content;
+    return typeof value === 'string' && value ? value : undefined;
+}
+//# sourceMappingURL=openai-chat.js.map

package/dist/models/openai-responses.d.ts

@@ -0,0 +1,31 @@
+import type OpenAI from 'openai';
+import type { StreamDelta } from '../events.ts';
+import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/**
+ * Provider-specific knobs, mirroring `OpenAIModelOptions` but expressed the way
+ * the responses API spells them.
+ */
+export interface OpenAIResponsesModelOptions {
+    reasoningEffort?: OpenAI.ReasoningEffort;
+    /** ask the model for a reasoning summary — the only reasoning text this API exposes */
+    reasoningSummary?: 'auto' | 'concise' | 'detailed';
+    /**
+     * Server-side conversation state. Off by default: the runner already owns
+     * the trajectory and replays the full thread on every call, so storing it
+     * again would duplicate state rather than help.
+     */
+    store?: boolean;
+}
+/**
+ * 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 declare class OpenAIResponsesModel implements Model {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: OpenAI, options?: OpenAIResponsesModelOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    stream(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=openai-responses.d.ts.map