@zenera/neo 1.1.0

package/dist/embeddings/gemini.js

@@ -0,0 +1,71 @@
+import { embeddingResponse, } from "../embedding.js";
+// ---------------------------------------------------------------------------
+// Google Gemini embeddings adapter
+//
+// Serves `google` and `vertex` alike: the two differ in how the client
+// authenticates, which is the provider's business, not this file's.
+// ---------------------------------------------------------------------------
+/**
+ * Google's task types are plain strings in `EmbedContentConfig` — unlike
+ * `ThinkingLevel` next door, there is no enum to inline. Only the retrieval
+ * pair is mapped: the others (clustering, similarity, classification) are jobs
+ * this runtime does not have a word for.
+ */
+const TASK_TYPES = {
+    query: 'RETRIEVAL_QUERY',
+    document: 'RETRIEVAL_DOCUMENT',
+};
+/** Requests in flight at once when a batch has to be split across several. */
+const CONCURRENCY = 8;
+export class GeminiEmbedder {
+    id;
+    #client;
+    #options;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#options = options;
+    }
+    async embed(req) {
+        const config = {
+            taskType: req.taskType ? TASK_TYPES[req.taskType] : undefined,
+            // Only meaningful alongside RETRIEVAL_DOCUMENT; the API ignores it
+            // otherwise rather than rejecting the request.
+            title: this.#options.title,
+            outputDimensionality: req.dimensions ?? this.#options.dimensions,
+            abortSignal: req.signal,
+        };
+        // The contract is batch-first and this endpoint usually is not, so the
+        // splitting happens here rather than in every caller. Chunks are issued
+        // in waves and their results concatenated in order, so a caller cannot
+        // tell how many requests it took.
+        const size = Math.max(1, this.#options.maxBatch ?? 1);
+        const chunks = [];
+        for (let i = 0; i < req.input.length; i += size) {
+            chunks.push(req.input.slice(i, i + size));
+        }
+        const vectors = [];
+        for (let i = 0; i < chunks.length; i += CONCURRENCY) {
+            const wave = await Promise.all(chunks.slice(i, i + CONCURRENCY).map((chunk) => this.#send(chunk, config)));
+            for (const part of wave) {
+                vectors.push(...part);
+            }
+        }
+        // Usage stays undefined on purpose: this API reports billable
+        // *characters*, on Vertex only, which is not a token count and would be
+        // a lie in `TokenUsage`.
+        return embeddingResponse(vectors, req);
+    }
+    async #send(input, config) {
+        const res = await this.#client.models.embedContent({
+            model: this.id,
+            // Spelled out as one `Content` per text. `ContentListUnion` also
+            // accepts a `string[]`, and reads it as the *parts of a single
+            // document* — six sentences in, one vector back, and no error.
+            contents: input.map((text) => ({ parts: [{ text }] })),
+            config,
+        });
+        return (res.embeddings ?? []).map((e) => e.values ?? []);
+    }
+}
+//# sourceMappingURL=gemini.js.map

package/dist/embeddings/index.d.ts

@@ -0,0 +1,4 @@
+export * from './gemini.ts';
+export * from './openai.ts';
+export * from './openrouter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/embeddings/index.js

@@ -0,0 +1,4 @@
+export * from "./gemini.js";
+export * from "./openai.js";
+export * from "./openrouter.js";
+//# sourceMappingURL=index.js.map

package/dist/embeddings/openai.d.ts

@@ -0,0 +1,18 @@
+import type OpenAI from 'openai';
+import { type Embedder, type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+/**
+ * Provider-specific knobs. `taskType` has no counterpart here: OpenAI's models
+ * are symmetric, so a query and a document are encoded identically and the
+ * request's hint is simply not sent.
+ */
+export interface OpenAIEmbedderOptions {
+    /** default width; a request may override it */
+    dimensions?: number;
+}
+export declare class OpenAIEmbedder implements Embedder {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: OpenAI, options?: OpenAIEmbedderOptions);
+    embed(req: EmbeddingRequest): Promise<EmbeddingResponse>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/embeddings/openai.js

@@ -0,0 +1,27 @@
+import { embeddingResponse, } from "../embedding.js";
+import { zeroUsage } from "../types.js";
+export class OpenAIEmbedder {
+    id;
+    #client;
+    #dimensions;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#dimensions = options.dimensions;
+    }
+    async embed(req) {
+        const res = await this.#client.embeddings.create({
+            model: this.id,
+            input: req.input,
+            dimensions: req.dimensions ?? this.#dimensions,
+        }, { signal: req.signal });
+        // The API documents the order but does not promise it, and `index` is
+        // the only thing that ties a vector back to its text.
+        const vectors = [...res.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
+        return embeddingResponse(vectors, req, {
+            ...zeroUsage(),
+            inputTokens: res.usage.prompt_tokens,
+        });
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/embeddings/openrouter.d.ts

@@ -0,0 +1,21 @@
+import type { OpenRouter } from '@openrouter/sdk';
+import type { ProviderPreferences } from '@openrouter/sdk/models';
+import type { Embedder, EmbeddingRequest, EmbeddingResponse } from '../embedding.ts';
+/** Provider-specific knobs. */
+export interface OpenRouterEmbedderOptions {
+    /** default width; a request may override it */
+    dimensions?: number;
+    /**
+     * Which upstream providers may serve this model, and in what order. Named
+     * as in `OpenRouterModelOptions`, and for the same reason: a *provider*
+     * here is already the connection.
+     */
+    routing?: ProviderPreferences;
+}
+export declare class OpenRouterEmbedder implements Embedder {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: OpenRouter, options?: OpenRouterEmbedderOptions);
+    embed(req: EmbeddingRequest): Promise<EmbeddingResponse>;
+}
+//# sourceMappingURL=openrouter.d.ts.map

package/dist/embeddings/openrouter.js

@@ -0,0 +1,54 @@
+import { embeddingResponse } from "../embedding.js";
+import { zeroUsage } from "../types.js";
+// ---------------------------------------------------------------------------
+// OpenRouter embeddings adapter
+//
+// The same trade as the chat adapter next door: its own SDK rather than the
+// OpenAI client aimed at another base url, because provider routing is the
+// reason to be here at all and chat completions has nowhere to put it.
+// ---------------------------------------------------------------------------
+/** OpenRouter's word for the retrieval side, which it takes as a free string. */
+const INPUT_TYPES = { query: 'search_query', document: 'search_document' };
+export class OpenRouterEmbedder {
+    id;
+    #client;
+    #options;
+    constructor(id, client, options = {}) {
+        this.id = id;
+        this.#client = client;
+        this.#options = options;
+    }
+    async embed(req) {
+        const requestBody = {
+            model: this.id,
+            input: req.input,
+            dimensions: req.dimensions ?? this.#options.dimensions,
+            inputType: req.taskType ? INPUT_TYPES[req.taskType] : undefined,
+            provider: this.#options.routing,
+            // `encodingFormat` is deliberately not sent. Its type is an open
+            // enum, whose values are branded and so unreachable without a value
+            // import of the SDK — and float is the default anyway. The string
+            // branch of `embedding` below is what catches a gateway that
+            // decides otherwise.
+        };
+        const res = await this.#client.embeddings.generate({ requestBody }, { fetchOptions: { signal: req.signal } });
+        // The response is declared as the body *or* a bare string, so the
+        // parsed shape has to be established before anything is read off it.
+        if (typeof res === 'string') {
+            throw new Error(`embedder "${this.id}": expected an embeddings response, got text`);
+        }
+        const vectors = [...res.data].sort(byIndex).map((d) => vectorOf(d, this.id));
+        return embeddingResponse(vectors, req, res.usage ? { ...zeroUsage(), inputTokens: res.usage.promptTokens } : undefined);
+    }
+}
+/** `index` is optional here, so its absence has to mean "keep the order given". */
+function byIndex(a, b) {
+    return (a.index ?? 0) - (b.index ?? 0);
+}
+function vectorOf(data, id) {
+    if (typeof data.embedding === 'string') {
+        throw new Error(`embedder "${id}": got a base64 embedding, which this adapter does not decode`);
+    }
+    return data.embedding;
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/events.d.ts

@@ -0,0 +1,144 @@
+import type { AgentState, RunResult } from './state.ts';
+import type { ForkNode, JoinNode, LlmCallNode, ToolResultNode } from './trajectory.ts';
+import type { Payload } from './payload.ts';
+export interface BranchRef {
+    /** the fork that created this branch */
+    forkId: string;
+    /** declared branch name */
+    name: string;
+    /** the child run's id */
+    runId: string;
+    /** spec.forkDepth of the emitting run */
+    depth: number;
+}
+export interface EventBase {
+    /** emitting run (the root run id on the trunk) */
+    runId: string;
+    /** active agent in that run */
+    agent: string;
+    /** absent on the trunk; set on every event emitted by a branch */
+    branch?: BranchRef;
+}
+/**
+ * What a `Model` produces while streaming. It carries no `EventBase`: a model
+ * knows nothing about runs or branches, so the runner tags these before they
+ * reach consumers.
+ */
+export type StreamDelta = {
+    type: 'thinking_delta';
+    delta: string;
+} | {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'tool_args_delta';
+    callId: string;
+    name: string;
+    delta: string;
+    argsSoFar: string;
+} | {
+    type: 'tool_call_detected';
+    callId: string;
+    name: string;
+};
+/** Fine-grained progress. Never required for correctness; safe to drop. */
+export type StreamEvent = EventBase & StreamDelta;
+/**
+ * Coarse-grained state transitions. The `state` in every checkpoint is a
+ * complete snapshot: persist it, and `runner.resume(state)` continues the run
+ * with no loss.
+ */
+export type CheckpointEvent = EventBase & ({
+    type: 'run_created';
+    state: AgentState;
+} | {
+    type: 'before_llm_call';
+    state: AgentState;
+} | {
+    type: 'after_llm_call';
+    state: AgentState;
+    node: LlmCallNode;
+} | {
+    type: 'before_tool_call';
+    state: AgentState;
+    call: PendingToolCall;
+} | {
+    type: 'after_tool_call';
+    state: AgentState;
+    node: ToolResultNode;
+} | {
+    type: 'handoff';
+    state: AgentState;
+    from: string;
+    to: string;
+} | {
+    type: 'before_fork';
+    state: AgentState;
+    node: ForkNode;
+} | {
+    type: 'branch_started';
+    state: AgentState;
+    child: BranchRef;
+    childState: AgentState;
+} | {
+    type: 'branch_finished';
+    state: AgentState;
+    child: BranchRef;
+    childState: AgentState;
+    status: 'ok' | 'error' | 'aborted';
+} | {
+    type: 'after_join';
+    state: AgentState;
+    node: JoinNode;
+} | {
+    type: 'run_finished';
+    state: AgentState;
+    result: RunResult<unknown>;
+});
+export type AgentEvent = StreamEvent | CheckpointEvent;
+export interface PendingToolCall {
+    callId: string;
+    name: string;
+    args: Payload;
+}
+export declare function isCheckpoint(e: AgentEvent): e is CheckpointEvent;
+/**
+ * A run has two audiences: observers that want every step, and callers that
+ * only want the answer. `RunStream` serves both over a single generator.
+ *
+ *   await runner.run(a, 'hi')                     // RunResult (thenable)
+ *   await runner.run(a, 'hi').text()              // string
+ *   for await (const e of runner.run(a, 'hi')) {} // events
+ */
+export declare class RunStream<T = string> implements AsyncIterable<AgentEvent>, PromiseLike<RunResult<T>> {
+    #private;
+    constructor(gen: AsyncGenerator<AgentEvent, RunResult<T>>);
+    /**
+     * Iteration is single-pass and shared with `final()`: a partially consumed
+     * stream resumes where the loop stopped instead of re-running the agent.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<AgentEvent, RunResult<T> | undefined>;
+    /**
+     * Drains whatever events are left and yields the run's result. The `??=`
+     * memoizes, so calling it twice gives the same result.
+     */
+    final(): Promise<RunResult<T>>;
+    text(): Promise<string>;
+    /**
+     * Implementing `then` makes the object a thenable, so `await` unwraps it
+     * exactly like a promise. Note this also starts draining the stream.
+     */
+    then<A = RunResult<T>, B = never>(onOk?: ((r: RunResult<T>) => A | PromiseLike<A>) | null, onErr?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+}
+/**
+ * Branches run concurrently, so their events cannot be `yield*`-ed one stream
+ * at a time. They are pushed here instead and drained by the parent generator
+ * while it awaits the branch promises.
+ */
+export declare class EventQueue<T> {
+    #private;
+    push(v: T): void;
+    close(): void;
+    drain(): AsyncGenerator<T>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.js

@@ -0,0 +1,110 @@
+export function isCheckpoint(e) {
+    return 'state' in e;
+}
+// ---------------------------------------------------------------------------
+// RunStream
+// ---------------------------------------------------------------------------
+/**
+ * A run has two audiences: observers that want every step, and callers that
+ * only want the answer. `RunStream` serves both over a single generator.
+ *
+ *   await runner.run(a, 'hi')                     // RunResult (thenable)
+ *   await runner.run(a, 'hi').text()              // string
+ *   for await (const e of runner.run(a, 'hi')) {} // events
+ */
+export class RunStream {
+    #gen;
+    #result;
+    #done;
+    constructor(gen) {
+        this.#gen = gen;
+    }
+    /**
+     * `for await` discards the generator's *return* value, so it is latched here
+     * on the way past: a loop that runs to completion and a later `final()` then
+     * see the same result instead of `undefined`.
+     */
+    async #next() {
+        if (this.#done) {
+            return { done: true, value: this.#done };
+        }
+        const step = await this.#gen.next();
+        if (step.done) {
+            this.#done = step.value;
+        }
+        return step;
+    }
+    /**
+     * Iteration is single-pass and shared with `final()`: a partially consumed
+     * stream resumes where the loop stopped instead of re-running the agent.
+     */
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.#next(),
+            // `break` calls this. Closing the underlying generator would abandon
+            // the run half-way, so the run is left alive on purpose — `final()`
+            // still drives it to the end. Cancellation belongs to the signal.
+            return: async () => ({ done: true, value: this.#done }),
+        };
+    }
+    /**
+     * Drains whatever events are left and yields the run's result. The `??=`
+     * memoizes, so calling it twice gives the same result.
+     */
+    final() {
+        this.#result ??= (async () => {
+            for (;;) {
+                const step = await this.#next();
+                if (step.done) {
+                    return step.value;
+                }
+            }
+        })();
+        return this.#result;
+    }
+    async text() {
+        const r = await this.final();
+        return typeof r.output === 'string' ? r.output : JSON.stringify(r.output);
+    }
+    /**
+     * Implementing `then` makes the object a thenable, so `await` unwraps it
+     * exactly like a promise. Note this also starts draining the stream.
+     */
+    then(onOk, onErr) {
+        return this.final().then(onOk, onErr);
+    }
+}
+/**
+ * Branches run concurrently, so their events cannot be `yield*`-ed one stream
+ * at a time. They are pushed here instead and drained by the parent generator
+ * while it awaits the branch promises.
+ */
+export class EventQueue {
+    #items = [];
+    #wake;
+    #closed = false;
+    push(v) {
+        this.#items.push(v);
+        this.#wake?.();
+        this.#wake = undefined;
+    }
+    close() {
+        this.#closed = true;
+        this.#wake?.();
+        this.#wake = undefined;
+    }
+    async *drain() {
+        for (;;) {
+            while (this.#items.length) {
+                yield this.#items.shift();
+            }
+            if (this.#closed) {
+                return;
+            }
+            await new Promise((resolve) => {
+                this.#wake = resolve;
+            });
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * All nondeterminism that the kernel needs (ids and wall clock) enters through
+ * this one interface, passed explicitly as an argument. Reading a clock from
+ * module scope would make replay-based hosts (Temporal) nondeterministic and
+ * would leak state between concurrent runs.
+ */
+export interface IdClock {
+    newId(): string;
+    now(): string;
+}
+/** Lexicographically sortable, collision-resistant id (ULID layout). */
+export declare function ulid(now?: number): string;
+export declare const systemClock: IdClock;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -0,0 +1,33 @@
+import { randomBytes } from 'node:crypto';
+// Crockford base32 — the ULID alphabet (no I, L, O, U).
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+function encodeTime(ms) {
+    let out = '';
+    let rest = ms;
+    for (let i = 0; i < TIME_LEN; i++) {
+        out = ALPHABET[rest % 32] + out;
+        rest = Math.floor(rest / 32);
+    }
+    return out;
+}
+function encodeRandom() {
+    // One byte per character wastes 3 bits each, which is irrelevant here and
+    // keeps the mapping obvious (no bit-packing arithmetic to get wrong).
+    const bytes = randomBytes(RANDOM_LEN);
+    let out = '';
+    for (const b of bytes) {
+        out += ALPHABET[b % 32];
+    }
+    return out;
+}
+/** Lexicographically sortable, collision-resistant id (ULID layout). */
+export function ulid(now = Date.now()) {
+    return encodeTime(now) + encodeRandom();
+}
+export const systemClock = {
+    newId: () => ulid(),
+    now: () => new Date().toISOString(),
+};
+//# sourceMappingURL=ids.js.map

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export * from './agent.ts';
+export * from './architecture.ts';
+export * from './embedding.ts';
+export * from './embeddings/index.ts';
+export * from './events.ts';
+export * from './ids.ts';
+export * from './inspect/index.ts';
+export * as Kernel from './kernel.ts';
+export * from './memory-stores/index.ts';
+export * from './memory.ts';
+export * from './model.ts';
+export * from './models/index.ts';
+export * from './payload-stores/index.ts';
+export * from './payload.ts';
+export * from './project/index.ts';
+export * from './prompt.ts';
+export * from './runner.ts';
+export * from './services.ts';
+export * from './skill-providers/index.ts';
+export * from './skills.ts';
+export * from './state.ts';
+export * from './tools/index.ts';
+export * from './trajectory.ts';
+export * from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+export * from "./agent.js";
+export * from "./architecture.js";
+export * from "./embedding.js";
+export * from "./embeddings/index.js";
+export * from "./events.js";
+export * from "./ids.js";
+export * from "./inspect/index.js";
+export * as Kernel from "./kernel.js";
+export * from "./memory-stores/index.js";
+export * from "./memory.js";
+export * from "./model.js";
+export * from "./models/index.js";
+export * from "./payload-stores/index.js";
+export * from "./payload.js";
+export * from "./project/index.js";
+export * from "./prompt.js";
+export * from "./runner.js";
+export * from "./services.js";
+export * from "./skill-providers/index.js";
+export * from "./skills.js";
+export * from "./state.js";
+export * from "./tools/index.js";
+export * from "./trajectory.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map