@zenera/neo 1.1.0

package/dist/memory.js

@@ -0,0 +1,213 @@
+import { hash } from "./payload.js";
+import { MEMORY_DELETE_TOOL, MEMORY_SEARCH_TOOL, MEMORY_UPDATE_TOOL, MEMORY_WRITE_TOOL, tool, withEffects, } from "./types.js";
+export function memoryOpId(runId, callId) {
+    return hash(`${runId}\u0000${callId}`);
+}
+export function renderMemories(hits) {
+    if (!hits.length) {
+        return '';
+    }
+    const lines = hits.map((h) => `- [${h.record.id}] (${h.record.kind}, score ${h.score.toFixed(2)}) ${h.record.text}`);
+    return `Relevant memories:\n${lines.join('\n')}`;
+}
+// ---------------------------------------------------------------------------
+// Shared ranking
+// ---------------------------------------------------------------------------
+/**
+ * Filtering plus token-overlap scoring, shared by the backends that have no
+ * embeddings of their own. A vector store ignores this and ranks in the
+ * database instead — the kernel only ever sees `MemoryHit[]`.
+ */
+export function rankMemories(records, q) {
+    const limit = q.limit ?? 8;
+    const terms = tokenize(q.text ?? '');
+    const hits = [];
+    for (const rec of records) {
+        if (q.kind && rec.kind !== q.kind) {
+            continue;
+        }
+        if (q.filter && !matches(rec.metadata, q.filter)) {
+            continue;
+        }
+        const score = terms.length ? overlap(terms, tokenize(rec.text)) : 1;
+        if (score <= 0 || (q.minScore !== undefined && score < q.minScore)) {
+            continue;
+        }
+        hits.push({ record: rec, score });
+    }
+    return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+function tokenize(v) {
+    return v
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 2);
+}
+function overlap(a, b) {
+    const set = new Set(b);
+    const shared = a.filter((t) => set.has(t)).length;
+    return a.length ? shared / a.length : 0;
+}
+function matches(meta, filter) {
+    return Object.entries(filter).every(([k, v]) => meta?.[k] === v);
+}
+// ---------------------------------------------------------------------------
+// Built-in memory tools
+// ---------------------------------------------------------------------------
+function spaceParam(bindings) {
+    return bindings.length > 1
+        ? { type: 'string', enum: bindings.map((b) => b.scope), description: 'memory space' }
+        : undefined;
+}
+function pick(bindings, space) {
+    const b = space ? bindings.find((x) => x.scope === space) : bindings[0];
+    if (!b) {
+        throw new Error(`unknown memory space: ${space ?? '(default)'}`);
+    }
+    return b;
+}
+/**
+ * Memory is reachable both explicitly (these tools) and implicitly (auto-recall
+ * in the runner). Both land in the trajectory; only the explicit path is
+ * visible to the model as a tool.
+ */
+export function memoryTools(bindings) {
+    if (!bindings.length) {
+        return [];
+    }
+    const writable = bindings.filter((b) => b.access === 'read-write');
+    const space = spaceParam(bindings);
+    const withSpace = (props) => (space ? { ...props, space } : props);
+    const tools = [
+        tool({
+            name: MEMORY_SEARCH_TOOL,
+            description: 'Search long-lived memories.',
+            parameters: {
+                type: 'object',
+                properties: withSpace({
+                    query: { type: 'string' },
+                    kind: { type: 'string' },
+                    limit: { type: 'integer' },
+                }),
+                required: ['query'],
+                additionalProperties: false,
+            },
+            execute: async (args, tc) => {
+                const b = pick(bindings, args.space);
+                const store = tc.services.memoryStore(b.store);
+                const hits = await store.search(b.scope, {
+                    text: args.query,
+                    kind: args.kind,
+                    limit: args.limit,
+                });
+                return hits.map((h) => ({
+                    id: h.record.id,
+                    kind: h.record.kind,
+                    text: h.record.text,
+                    revision: h.record.revision,
+                    score: Number(h.score.toFixed(3)),
+                }));
+            },
+        }),
+    ];
+    if (!writable.length) {
+        return tools;
+    }
+    const wSpace = spaceParam(writable);
+    const withWSpace = (props) => wSpace ? { ...props, space: wSpace } : props;
+    tools.push(tool({
+        name: MEMORY_WRITE_TOOL,
+        description: 'Store a new long-lived memory.',
+        parameters: {
+            type: 'object',
+            properties: withWSpace({ text: { type: 'string' }, kind: { type: 'string' } }),
+            required: ['text'],
+            additionalProperties: false,
+        },
+        execute: async (args, tc) => {
+            const b = pick(writable, args.space);
+            const opId = memoryOpId(tc.state.runId, tc.callId);
+            const rec = await tc.services
+                .memoryStore(b.store)
+                .write(b.scope, { text: args.text, kind: args.kind }, opId);
+            return withEffects(`stored memory ${rec.id}`, {
+                kind: 'memory_op',
+                spec: {
+                    kind: 'op',
+                    op: 'write',
+                    store: b.store,
+                    scope: b.scope,
+                    opId,
+                    recordId: rec.id,
+                    revision: rec.revision,
+                    after: rec.text,
+                },
+            });
+        },
+    }), tool({
+        name: MEMORY_UPDATE_TOOL,
+        description: 'Update an existing memory by id.',
+        parameters: {
+            type: 'object',
+            properties: withWSpace({
+                id: { type: 'string' },
+                text: { type: 'string' },
+                kind: { type: 'string' },
+            }),
+            required: ['id'],
+            additionalProperties: false,
+        },
+        execute: async (args, tc) => {
+            const b = pick(writable, args.space);
+            const store = tc.services.memoryStore(b.store);
+            const before = await store.get(b.scope, args.id);
+            const opId = memoryOpId(tc.state.runId, tc.callId);
+            const rec = await store.update(b.scope, args.id, { text: args.text, kind: args.kind }, opId);
+            return withEffects(`updated memory ${rec.id}`, {
+                kind: 'memory_op',
+                spec: {
+                    kind: 'op',
+                    op: 'update',
+                    store: b.store,
+                    scope: b.scope,
+                    opId,
+                    recordId: rec.id,
+                    revision: rec.revision,
+                    before: before?.text,
+                    after: rec.text,
+                },
+            });
+        },
+    }), tool({
+        name: MEMORY_DELETE_TOOL,
+        description: 'Delete a memory by id.',
+        parameters: {
+            type: 'object',
+            properties: withWSpace({ id: { type: 'string' } }),
+            required: ['id'],
+            additionalProperties: false,
+        },
+        execute: async (args, tc) => {
+            const b = pick(writable, args.space);
+            const store = tc.services.memoryStore(b.store);
+            const before = await store.get(b.scope, args.id);
+            const opId = memoryOpId(tc.state.runId, tc.callId);
+            await store.delete(b.scope, args.id, opId);
+            return withEffects(`deleted memory ${args.id}`, {
+                kind: 'memory_op',
+                spec: {
+                    kind: 'op',
+                    op: 'delete',
+                    store: b.store,
+                    scope: b.scope,
+                    opId,
+                    recordId: args.id,
+                    revision: before?.revision ?? 0,
+                    before: before?.text,
+                },
+            });
+        },
+    }));
+    return tools;
+}
+//# sourceMappingURL=memory.js.map

package/dist/model.d.ts

@@ -0,0 +1,25 @@
+import type { StreamDelta } from './events.ts';
+import type { Message, TokenUsage, ToolCall, ToolSchema } from './types.ts';
+export type StopReason = 'stop' | 'tool_calls' | 'length' | 'content_filter';
+export interface ModelRequest {
+    system?: string;
+    messages: Message[];
+    tools: ToolSchema[];
+    toolChoice?: 'auto' | 'required' | 'none';
+    signal?: AbortSignal;
+}
+export interface ModelResponse {
+    text: string;
+    /** reasoning chain, when the provider returns one */
+    thinking?: string;
+    toolCalls: ToolCall[];
+    usage?: TokenUsage;
+    stopReason?: StopReason;
+}
+export interface Model {
+    readonly id: string;
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    /** optional: non-streaming models simply never produce deltas */
+    stream?(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/models/anthropic.d.ts

@@ -0,0 +1,36 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { StreamDelta } from '../events.ts';
+import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/**
+ * Provider-specific knobs.
+ *
+ * `maxTokens` has no counterpart in the OpenAI adapters because there it is
+ * optional; Anthropic *requires* an output cap on every request, so one has to
+ * exist. 8192 is the largest value every current Claude model accepts, which
+ * makes it the only safe default — raise it per model when you know better.
+ */
+export interface AnthropicModelOptions {
+    /** hard cap on output tokens; required by the API, so it always has a value */
+    maxTokens?: number;
+    /**
+     * Extended thinking budget, in tokens (≥1024 enables it). Off by default,
+     * and deliberately so — see the note on `#params` about tool use.
+     */
+    thinkingBudgetTokens?: number;
+}
+/**
+ * The `Model` contract over `/v1/messages`.
+ *
+ * Unlike Google, Anthropic is not worth reaching through an OpenAI-compatible
+ * shim: the compatibility layer they publish is explicitly a porting aid, and
+ * it drops the two things this runtime cares most about — accurate cache
+ * accounting and extended thinking. A real adapter is ~200 lines and gets both.
+ */
+export declare class AnthropicModel implements Model {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: Anthropic, options?: AnthropicModelOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    stream(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/models/anthropic.js

@@ -0,0 +1,293 @@
+import { zeroUsage, } from "../types.js";
+/** Every current Claude model accepts at least this many output tokens. */
+const DEFAULT_MAX_TOKENS = 8192;
+/** The API's floor for a thinking budget; below it the request is rejected. */
+const MIN_THINKING_BUDGET = 1024;
+/**
+ * The `Model` contract over `/v1/messages`.
+ *
+ * Unlike Google, Anthropic is not worth reaching through an OpenAI-compatible
+ * shim: the compatibility layer they publish is explicitly a porting aid, and
+ * it drops the two things this runtime cares most about — accurate cache
+ * accounting and extended thinking. A real adapter is ~200 lines and gets both.
+ */
+export class AnthropicModel {
+    id;
+    #client;
+    #maxTokens;
+    #thinkingBudget;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#thinkingBudget =
+            options.thinkingBudgetTokens && options.thinkingBudgetTokens >= MIN_THINKING_BUDGET
+                ? options.thinkingBudgetTokens
+                : undefined;
+        // The budget is spent *out of* the output cap, so a cap at or below it
+        // leaves no room to answer in.
+        this.#maxTokens = Math.max(options.maxTokens ?? DEFAULT_MAX_TOKENS, (this.#thinkingBudget ?? 0) + MIN_THINKING_BUDGET);
+    }
+    async generate(req) {
+        const res = await this.#client.messages.create(this.#params(req), { signal: req.signal });
+        return {
+            ...readBlocks(res.content),
+            usage: toUsage(res.usage),
+            stopReason: toStopReason(res.stop_reason),
+        };
+    }
+    async stream(req, onDelta) {
+        const stream = this.#client.messages.stream(this.#params(req), { signal: req.signal });
+        // Blocks are addressed by index, and a tool call's id and name arrive in
+        // its `content_block_start` while the arguments trickle in afterwards.
+        const calls = new Map();
+        for await (const event of stream) {
+            if (event.type === 'content_block_start') {
+                const block = event.content_block;
+                if (block.type === 'tool_use') {
+                    calls.set(event.index, { id: block.id, name: block.name, args: '' });
+                    onDelta({ type: 'tool_call_detected', callId: block.id, name: block.name });
+                }
+                continue;
+            }
+            if (event.type !== 'content_block_delta') {
+                continue;
+            }
+            const delta = event.delta;
+            switch (delta.type) {
+                case 'text_delta':
+                    onDelta({ type: 'text_delta', delta: delta.text });
+                    break;
+                case 'thinking_delta':
+                    onDelta({ type: 'thinking_delta', delta: delta.thinking });
+                    break;
+                case 'input_json_delta': {
+                    const call = calls.get(event.index);
+                    if (call && delta.partial_json) {
+                        call.args += delta.partial_json;
+                        onDelta({
+                            type: 'tool_args_delta',
+                            callId: call.id,
+                            name: call.name,
+                            delta: delta.partial_json,
+                            argsSoFar: call.args,
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+        // The accumulated message is authoritative: it has the parsed tool
+        // inputs and the final usage, so the deltas above are for the UI only
+        // and nothing here depends on having reassembled them correctly.
+        const final = await stream.finalMessage();
+        return {
+            ...readBlocks(final.content),
+            usage: toUsage(final.usage),
+            stopReason: toStopReason(final.stop_reason),
+        };
+    }
+    /**
+     * Note what is *not* here: prior thinking blocks are never replayed. The
+     * API requires the original block, signature included, when extended
+     * thinking is on and the turn being replayed made tool calls — and a
+     * signature is not something the trajectory carries, since it is meaningless
+     * to every other provider. So `thinkingBudgetTokens` is safe for plain
+     * conversation and will be rejected by the API on a tool-using multi-turn
+     * run. Preserving signatures would mean a provider-specific field on
+     * `AssistantMessage`, which is a trajectory change, not an adapter change.
+     */
+    #params(req) {
+        return {
+            model: this.id,
+            max_tokens: this.#maxTokens,
+            system: req.system,
+            messages: toMessages(req.messages),
+            thinking: this.#thinkingBudget
+                ? { type: 'enabled', budget_tokens: this.#thinkingBudget }
+                : undefined,
+            tools: req.tools.length
+                ? req.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    input_schema: t.parameters,
+                }))
+                : undefined,
+            tool_choice: req.tools.length ? toToolChoice(req.toolChoice) : undefined,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Wire translation
+// ---------------------------------------------------------------------------
+/**
+ * Internal messages → Anthropic turns.
+ *
+ * Two things differ from the OpenAI shape and both are handled by merging
+ * adjacent same-role turns: a tool result is a *user* turn rather than a role
+ * of its own, and parallel tool results have to arrive together in one turn
+ * rather than as one message each.
+ */
+function toMessages(messages) {
+    const out = [];
+    const push = (role, blocks) => {
+        if (!blocks.length) {
+            return;
+        }
+        const last = out.at(-1);
+        if (last?.role === role) {
+            last.content.push(...blocks);
+            return;
+        }
+        out.push({ role, content: blocks });
+    };
+    for (const m of messages) {
+        switch (m.role) {
+            case 'system':
+                // There is no mid-conversation system turn in this API, and
+                // hoisting it to the top-level `system` would move it away from
+                // the point it was injected at — which is the whole value of a
+                // memory recall. A user turn keeps the position.
+                push('user', [{ type: 'text', text: m.content }]);
+                break;
+            case 'user':
+                push('user', m.content.map(toBlock));
+                break;
+            case 'assistant': {
+                const blocks = [];
+                if (m.content) {
+                    blocks.push({ type: 'text', text: m.content });
+                }
+                for (const c of m.toolCalls ?? []) {
+                    blocks.push({
+                        type: 'tool_use',
+                        id: c.id,
+                        name: c.name,
+                        input: parseArgs(c.args),
+                    });
+                }
+                push('assistant', blocks);
+                break;
+            }
+            case 'tool':
+                push('user', [
+                    {
+                        type: 'tool_result',
+                        tool_use_id: m.callId,
+                        content: m.content,
+                        is_error: m.isError,
+                    },
+                ]);
+                break;
+        }
+    }
+    return out;
+}
+/** Only images have a first-class representation; other media degrade to text. */
+function toBlock(part) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    if (part.type !== 'image') {
+        return { type: 'text', text: `[${part.type}] ${part.url}` };
+    }
+    const inline = readDataUri(part.url);
+    return inline
+        ? { type: 'image', source: { type: 'base64', ...inline } }
+        : { type: 'image', source: { type: 'url', url: part.url } };
+}
+const DATA_URI = /^data:([^;,]+);base64,(.*)$/s;
+function readDataUri(url) {
+    const match = DATA_URI.exec(url);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        media_type: match[1],
+        data: match[2],
+    };
+}
+/**
+ * Tool arguments travel as the raw JSON string the model produced, because that
+ * is what every other provider wants back verbatim. Anthropic wants the parsed
+ * object, and a malformed one is the model's error to see, not a crash here.
+ */
+function parseArgs(args) {
+    if (!args.trim()) {
+        return {};
+    }
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return { _raw: args };
+    }
+}
+function toToolChoice(choice) {
+    switch (choice) {
+        case 'required':
+            return { type: 'any' };
+        case 'none':
+            return { type: 'none' };
+        default:
+            return { type: 'auto' };
+    }
+}
+function readBlocks(content) {
+    let text = '';
+    let thinking = '';
+    const toolCalls = [];
+    for (const block of content) {
+        switch (block.type) {
+            case 'text':
+                text += block.text;
+                break;
+            case 'thinking':
+                thinking += block.thinking;
+                break;
+            case 'tool_use':
+                toolCalls.push({
+                    id: block.id,
+                    name: block.name,
+                    args: JSON.stringify(block.input ?? {}),
+                });
+                break;
+        }
+    }
+    return { text, thinking: thinking || undefined, toolCalls };
+}
+/**
+ * Anthropic reports `input_tokens` *excluding* what the cache served, while
+ * `TokenUsage.cachedInputTokens` is defined as a subset of `inputTokens`. So
+ * the cache figures are added back in rather than passed through, and a run
+ * that mixes providers still sums to a comparable number.
+ */
+function toUsage(u) {
+    if (!u) {
+        return undefined;
+    }
+    const read = u.cache_read_input_tokens ?? 0;
+    const written = u.cache_creation_input_tokens ?? 0;
+    return {
+        ...zeroUsage(),
+        inputTokens: u.input_tokens + read + written,
+        cachedInputTokens: read,
+        outputTokens: u.output_tokens,
+        // Thinking is billed as ordinary output and is not broken out, so
+        // claiming a number here would be inventing one.
+        reasoningTokens: 0,
+    };
+}
+function toStopReason(reason) {
+    switch (reason) {
+        case 'tool_use':
+            return 'tool_calls';
+        case 'max_tokens':
+        case 'model_context_window_exceeded':
+            return 'length';
+        case 'refusal':
+            return 'content_filter';
+        default:
+            return 'stop';
+    }
+}
+//# sourceMappingURL=anthropic.js.map