@zenera/neo 1.1.0

package/dist/trajectory.d.ts

@@ -0,0 +1,213 @@
+import type { MemoryQuery } from './memory.ts';
+import type { Payload, PayloadResolver } from './payload.ts';
+import type { PromptSource } from './prompt.ts';
+import { type MediaKind, type Message, type TokenUsage } from './types.ts';
+export interface NodeBase {
+    /** ulid — unique within a trajectory */
+    id: string;
+    /** ISO timestamp (informational, not used for logic) */
+    ts: string;
+    /** active agent when the node was created */
+    agent: string;
+}
+/** A content part whose text lives behind a payload reference. */
+export type PayloadPart = {
+    type: 'text';
+    text: Payload;
+} | {
+    type: MediaKind;
+    url: string;
+    mimeType?: string;
+};
+export interface UserInputNode extends NodeBase {
+    type: 'user_input';
+    content: PayloadPart[];
+    /** produced by the runtime (e.g. a "call final_output" nudge), not the user */
+    synthetic?: boolean;
+}
+export interface SystemPromptNode extends NodeBase {
+    type: 'system_prompt';
+    /** exactly what the provider received */
+    prompt: Payload;
+    /**
+     * The file-backed contributors, in the order they were rendered — the
+     * answer to "which file do I edit to change this?". Inline text, the skill
+     * index and runtime notes are inside `prompt` but not listed here: none of
+     * them is a document anyone opens.
+     */
+    sources?: PromptSource[];
+}
+export interface LoadSkillsNode extends NodeBase {
+    type: 'load_skills';
+    provider: string;
+    skills: {
+        name: string;
+        version?: string;
+        contentHash: string;
+        file?: string;
+    }[];
+    /** concatenated instructions the model saw */
+    content: Payload;
+    /** tools this activation unlocked */
+    toolNames: string[];
+}
+export interface MemoryRecallNode extends NodeBase {
+    type: 'memory_recall';
+    store: string;
+    scope: string;
+    query: MemoryQuery;
+    /** ids, not bodies — the rendered block is the payload */
+    hits: {
+        id: string;
+        score: number;
+        revision: number;
+    }[];
+    content: Payload;
+}
+export interface MemoryOpNode extends NodeBase {
+    type: 'memory_op';
+    op: 'write' | 'update' | 'delete';
+    store: string;
+    scope: string;
+    /** sha256(runId, callId) — deterministic, so a replay is deduplicated */
+    opId: string;
+    recordId: string;
+    revision: number;
+    before?: Payload;
+    after?: Payload;
+}
+export interface LlmCallNode extends NodeBase {
+    type: 'llm_call';
+    /** exact model id used */
+    model: string;
+    /** sha256 of the projected request, for replay checks */
+    requestDigest: string;
+    request?: Payload;
+    text: Payload;
+    thinking?: Payload;
+    /** `signature` is opaque provider state — see `ToolCall.signature` */
+    toolCalls: {
+        callId: string;
+        name: string;
+        args: Payload;
+        signature?: string;
+    }[];
+    usage: TokenUsage;
+    stopReason: 'stop' | 'tool_calls' | 'length' | 'content_filter';
+}
+export interface ToolCallNode extends NodeBase {
+    type: 'tool_call';
+    callId: string;
+    name: string;
+    args: Payload;
+}
+export interface ToolResultNode extends NodeBase {
+    type: 'tool_result';
+    callId: string;
+    name: string;
+    result: Payload;
+    isError: boolean;
+    durationMs?: number;
+}
+export interface HandoffNode extends NodeBase {
+    type: 'handoff';
+    from: string;
+    to: string;
+    reason?: string;
+}
+export interface ForkNode extends NodeBase {
+    type: 'fork';
+    /** the fork tool call that caused it — also the fork's identity */
+    callId: string;
+    contextMode: 'inherit' | 'compact' | 'none';
+    branches: {
+        name: string;
+        agent: string;
+        instructions: Payload;
+        childRunId: string;
+    }[];
+}
+/**
+ * The outcome of a fork. Each branch's own history hangs off its row: fork is a
+ * scope, and nesting makes that structural rather than conventional — a walk of
+ * the parent array simply never encounters a branch node.
+ */
+export interface JoinNode extends NodeBase {
+    type: 'join';
+    /** the fork tool call this answers */
+    callId: string;
+    /** always in declared branch order, never completion order */
+    branches: {
+        name: string;
+        agent: string;
+        status: 'ok' | 'error' | 'aborted';
+        output: Payload;
+        error?: string;
+        /** display only — the branch's own `llm_call` nodes carry the tokens */
+        usage: TokenUsage;
+        /**
+         * What the branch did. Never projected into the parent's prompt; kept
+         * for audit, accounting and export. A nested fork's history hangs off
+         * a `join` in here, so depth costs nothing but recursion.
+         */
+        nodes: TrajectoryNode[];
+    }[];
+    /** display only; `totalUsage` recurses into the branches instead */
+    usage: TokenUsage;
+}
+/**
+ * Collapses a set of nodes into one summary. The covered nodes stay in the
+ * trajectory — the log is append-only — and only the projection skips them.
+ */
+export interface CompactionNode extends NodeBase {
+    type: 'compaction';
+    /** real when the model called `compact`, synthesized when policy-driven */
+    callId: string;
+    /** ids of the nodes this summary replaces */
+    covers: string[];
+    summary: Payload;
+    reason: 'handoff_noise' | 'token_budget' | 'branch_context' | 'manual' | string;
+    /** what the summarizer itself burned */
+    usage: TokenUsage;
+}
+export interface FinalOutputNode extends NodeBase {
+    type: 'final_output';
+    output: Payload;
+    /** present when an output schema was set */
+    parsed?: unknown;
+}
+export type TrajectoryNode = UserInputNode | SystemPromptNode | LoadSkillsNode | MemoryRecallNode | MemoryOpNode | LlmCallNode | ToolCallNode | ToolResultNode | HandoffNode | ForkNode | JoinNode | CompactionNode | FinalOutputNode;
+export type NodeBody<T extends TrajectoryNode> = Omit<T, keyof NodeBase>;
+/**
+ * Ids replaced by a compaction. A branch's compactions live inside its own
+ * `nodes` array, so they are structurally out of reach here — a branch can
+ * never collapse the parent's history, even though it may compact the prefix
+ * it inherited and name ids the parent also has.
+ *
+ * The union is unconditional, so compaction is monotone: once a node has been
+ * summarized it stays hidden, even if a later compaction covers the summary.
+ */
+export declare function coveredIds(nodes: TrajectoryNode[]): Set<string>;
+/**
+ * What the model sees. Compaction hides nodes, it never deletes them: the
+ * trajectory is append-only, and audit and replay always see the full history.
+ */
+export declare function projected(nodes: TrajectoryNode[]): TrajectoryNode[];
+/**
+ * Total consumption, including every token spent inside a fork at any depth.
+ * This is the one place that deliberately crosses the branch boundary, so the
+ * recursion is the explicit opt-in; `JoinNode.usage` is display only and is not
+ * added, since counting it too would double every branch.
+ */
+export declare function totalUsage(trajectory: TrajectoryNode[]): TokenUsage;
+export declare function lastOfType<T extends TrajectoryNode['type']>(trajectory: TrajectoryNode[], type: T): Extract<TrajectoryNode, {
+    type: T;
+}> | undefined;
+/** What a node contributes to the *projection* — not everything it references. */
+export declare function nodePayloads(n: TrajectoryNode): Payload[];
+export interface Projection {
+    system?: string;
+    messages: Message[];
+}
+export declare function projectMessages(trajectory: TrajectoryNode[], payloads: PayloadResolver): Promise<Projection>;
+//# sourceMappingURL=trajectory.d.ts.map

package/dist/trajectory.js

@@ -0,0 +1,232 @@
+import { addUsage, zeroUsage, } from "./types.js";
+// ---------------------------------------------------------------------------
+// Derived views
+// ---------------------------------------------------------------------------
+/**
+ * Ids replaced by a compaction. A branch's compactions live inside its own
+ * `nodes` array, so they are structurally out of reach here — a branch can
+ * never collapse the parent's history, even though it may compact the prefix
+ * it inherited and name ids the parent also has.
+ *
+ * The union is unconditional, so compaction is monotone: once a node has been
+ * summarized it stays hidden, even if a later compaction covers the summary.
+ */
+export function coveredIds(nodes) {
+    const out = new Set();
+    for (const n of nodes) {
+        if (n.type === 'compaction') {
+            for (const id of n.covers) {
+                out.add(id);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * What the model sees. Compaction hides nodes, it never deletes them: the
+ * trajectory is append-only, and audit and replay always see the full history.
+ */
+export function projected(nodes) {
+    const covered = coveredIds(nodes);
+    return covered.size ? nodes.filter((n) => !covered.has(n.id)) : nodes;
+}
+/**
+ * Total consumption, including every token spent inside a fork at any depth.
+ * This is the one place that deliberately crosses the branch boundary, so the
+ * recursion is the explicit opt-in; `JoinNode.usage` is display only and is not
+ * added, since counting it too would double every branch.
+ */
+export function totalUsage(trajectory) {
+    return trajectory.reduce((acc, n) => {
+        if (n.type === 'llm_call' || n.type === 'compaction') {
+            return addUsage(acc, n.usage);
+        }
+        if (n.type === 'join') {
+            return n.branches.reduce((sum, b) => addUsage(sum, totalUsage(b.nodes)), acc);
+        }
+        return acc;
+    }, zeroUsage());
+}
+export function lastOfType(trajectory, type) {
+    for (let i = trajectory.length - 1; i >= 0; i--) {
+        if (trajectory[i].type === type) {
+            return trajectory[i];
+        }
+    }
+    return undefined;
+}
+/** What a node contributes to the *projection* — not everything it references. */
+export function nodePayloads(n) {
+    switch (n.type) {
+        case 'user_input':
+            return n.content.flatMap((p) => (p.type === 'text' ? [p.text] : []));
+        case 'system_prompt':
+            return [n.prompt];
+        case 'load_skills':
+            return [n.content];
+        case 'memory_recall':
+            return [n.content];
+        case 'llm_call':
+            return [n.text, ...n.toolCalls.map((c) => c.args)];
+        case 'tool_call':
+            return [n.args];
+        case 'tool_result':
+            return [n.result];
+        case 'join':
+            // Branch histories are not projected; only their outputs are.
+            return n.branches.map((b) => b.output);
+        case 'compaction':
+            return [n.summary];
+        case 'final_output':
+            return [n.output];
+        default:
+            // memory_op / handoff / fork carry only provenance in the projection
+            return [];
+    }
+}
+export async function projectMessages(trajectory, payloads) {
+    const visible = projected(trajectory);
+    const blobs = await payloads.getMany(visible.flatMap(nodePayloads));
+    const get = (p) => blobs.get(p.sha256) ?? '';
+    let system;
+    const messages = [];
+    for (const n of visible) {
+        switch (n.type) {
+            case 'system_prompt':
+                // Last one wins; earlier prompts are superseded, not emitted.
+                system = get(n.prompt);
+                break;
+            case 'user_input':
+                messages.push({
+                    role: 'user',
+                    content: n.content.map((p) => p.type === 'text'
+                        ? { type: 'text', text: get(p.text) }
+                        : { type: p.type, url: p.url, mimeType: p.mimeType }),
+                });
+                break;
+            case 'load_skills':
+            case 'memory_recall': {
+                const content = get(n.content);
+                if (content) {
+                    messages.push({ role: 'user', content: [{ type: 'text', text: content }] });
+                }
+                break;
+            }
+            case 'llm_call': {
+                const toolCalls = n.toolCalls.map((c) => ({
+                    id: c.callId,
+                    name: c.name,
+                    args: get(c.args),
+                    signature: c.signature,
+                }));
+                messages.push({
+                    role: 'assistant',
+                    content: get(n.text),
+                    toolCalls: toolCalls.length ? toolCalls : undefined,
+                    agent: n.agent,
+                });
+                break;
+            }
+            case 'tool_call':
+                // Already folded into the owning llm_call; the standalone node
+                // exists only so a checkpoint can be cut before execution.
+                break;
+            case 'tool_result':
+                messages.push({
+                    role: 'tool',
+                    callId: n.callId,
+                    name: n.name,
+                    content: get(n.result),
+                    isError: n.isError || undefined,
+                });
+                break;
+            case 'join': {
+                const rendered = n.branches
+                    .map((b) => `### ${b.name} (${b.status})\n` +
+                    (b.status === 'ok' ? get(b.output) : (b.error ?? get(b.output))))
+                    .join('\n\n');
+                messages.push({
+                    role: 'tool',
+                    callId: n.callId,
+                    name: 'fork',
+                    content: rendered,
+                    isError: n.branches.some((b) => b.status !== 'ok') || undefined,
+                });
+                break;
+            }
+            case 'compaction': {
+                // A tool-call pair, not a user message: the summary is the
+                // runtime's, and putting it in the user's mouth misattributes
+                // it. Both halves come from this one node, so a later
+                // compaction removes them together and cannot orphan either.
+                messages.push({
+                    role: 'assistant',
+                    content: '',
+                    agent: n.agent,
+                    toolCalls: [
+                        {
+                            id: n.callId,
+                            name: 'compact',
+                            args: JSON.stringify({ reason: n.reason, nodes: n.covers.length }),
+                        },
+                    ],
+                });
+                messages.push({
+                    role: 'tool',
+                    callId: n.callId,
+                    name: 'compact',
+                    content: get(n.summary),
+                });
+                break;
+            }
+            case 'final_output':
+                {
+                    const text = get(n.output);
+                    const prev = messages.at(-1);
+                    // An untyped run ends by simply answering, and the kernel
+                    // records that answer as a node of its own — so the text is
+                    // already in the projection as the assistant's last turn.
+                    // Emitting it again would duplicate a whole turn in every
+                    // later request of a multi-turn conversation, and in every
+                    // branch that inherits one. A typed run has no such twin:
+                    // its answer travelled as tool-call arguments, and the
+                    // assistant message that carried them is gone.
+                    if (prev?.role !== 'assistant' || prev.content !== text) {
+                        messages.push({ role: 'assistant', content: text, agent: n.agent });
+                    }
+                }
+                break;
+            default:
+                // handoff / memory_op / fork project through other nodes
+                break;
+        }
+    }
+    return { system, messages: repairToolCalls(messages) };
+}
+/**
+ * Providers reject a thread whose assistant tool call has no matching tool
+ * message — and vice versa. Compaction can cover either side of a pair, so the
+ * projection drops the orphaned half instead of producing an invalid request.
+ * This is also what makes non-contiguous compaction safe, and what keeps an
+ * unanswered `fork` call out of an inheriting branch's prompt.
+ */
+function repairToolCalls(messages) {
+    const called = new Set(messages.flatMap((m) => m.role === 'assistant' ? (m.toolCalls ?? []).map((c) => c.id) : []));
+    const kept = messages.filter((m) => m.role !== 'tool' || called.has(m.callId));
+    const answered = new Set(kept.flatMap((m) => (m.role === 'tool' ? [m.callId] : [])));
+    const out = [];
+    for (const m of kept) {
+        if (m.role !== 'assistant' || !m.toolCalls?.length) {
+            out.push(m);
+            continue;
+        }
+        const calls = m.toolCalls.filter((c) => answered.has(c.id));
+        if (!calls.length && !m.content) {
+            continue;
+        }
+        const fixed = { ...m, toolCalls: calls.length ? calls : undefined };
+        out.push(fixed);
+    }
+    return out;
+}
+//# sourceMappingURL=trajectory.js.map

package/dist/types.d.ts

@@ -0,0 +1,195 @@
+import type { Agent } from './agent.ts';
+import type { MemoryOpSpec } from './memory.ts';
+import type { Services } from './services.ts';
+import type { SkillLoadSpec } from './skills.ts';
+import type { AgentState } from './state.ts';
+export type MediaKind = 'image' | 'audio' | 'video' | 'file';
+export interface TextPart {
+    type: 'text';
+    text: string;
+}
+export interface MediaPart {
+    type: MediaKind;
+    /** http(s) url or data: uri */
+    url: string;
+    mimeType?: string;
+}
+export type ContentPart = TextPart | MediaPart;
+/**
+ * Sugar accepted on input boundaries. A bare string inside an array is text,
+ * `{ image: url }` & co. are media shorthands.
+ */
+export type InputPart = string | ContentPart | {
+    image: string;
+    mimeType?: string;
+} | {
+    audio: string;
+    mimeType?: string;
+} | {
+    video: string;
+    mimeType?: string;
+} | {
+    file: string;
+    mimeType?: string;
+};
+/** Either plain text, or an array of content parts. */
+export type Input = string | InputPart[];
+export declare function text(value: string): TextPart;
+export declare function media(kind: MediaKind, url: string, mimeType?: string): MediaPart;
+/** Normalizes any accepted input shape into a flat `ContentPart[]`. */
+export declare function toContent(input: Input): ContentPart[];
+export declare function contentToText(content: ContentPart[]): string;
+export interface ToolCall {
+    id: string;
+    name: string;
+    /** raw JSON string as produced by the model */
+    args: string;
+    /**
+     * Opaque provider state that has to be handed back verbatim when the call
+     * is replayed. Gemini 3 puts an encrypted thought signature here and
+     * rejects a function call that comes back without one; every other vendor
+     * ignores the field.
+     *
+     * It is vendor-specific and so arguably does not belong in a neutral type
+     * — but the alternative is an adapter-side cache, and the identity that
+     * would key it does not survive a handoff to an agent on a different model
+     * or a run resumed in another process. The call is the only thing that
+     * lives exactly as long as the signature is needed.
+     */
+    signature?: string;
+}
+export interface SystemMessage {
+    role: 'system';
+    content: string;
+}
+export interface UserMessage {
+    role: 'user';
+    content: ContentPart[];
+}
+export interface AssistantMessage {
+    role: 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+    /** which agent produced it — useful after hand-offs */
+    agent?: string;
+}
+export interface ToolMessage {
+    role: 'tool';
+    callId: string;
+    name: string;
+    content: string;
+    isError?: boolean;
+}
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+export interface TokenUsage {
+    inputTokens: number;
+    /** subset of inputTokens served from cache */
+    cachedInputTokens: number;
+    outputTokens: number;
+    /** subset of outputTokens spent on thinking */
+    reasoningTokens: number;
+}
+export declare function zeroUsage(): TokenUsage;
+export declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+export interface JsonSchema {
+    type: 'object';
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolContext<TCtx = unknown> {
+    ctx: TCtx;
+    state: AgentState;
+    agent: Agent<TCtx>;
+    /** id of the call being executed — memory ops derive their opId from it */
+    callId: string;
+    services: Services;
+    signal?: AbortSignal;
+}
+/** What the model needs to know about a tool — no execution details. */
+export interface ToolSchema {
+    name: string;
+    description?: string;
+    parameters: JsonSchema;
+}
+/**
+ * What a tool produced. `effects` are structured side-effect records the kernel
+ * must fold into the trajectory (memory writes, skill activations); the tool
+ * itself performed the I/O, because the kernel stays free of it.
+ */
+export interface ToolOutcome {
+    output: string;
+    isError: boolean;
+    durationMs?: number;
+    effects?: ToolEffect[];
+}
+export type ToolEffect = {
+    kind: 'memory_op';
+    spec: MemoryOpSpec;
+} | {
+    kind: 'skill_load';
+    spec: SkillLoadSpec;
+};
+declare const TOOL_RETURN: unique symbol;
+/**
+ * What a tool returns when it needs the kernel to record something beyond the
+ * tool message itself. Tagged with a symbol so an ordinary object result can
+ * never be mistaken for one.
+ */
+export interface ToolReturn {
+    [TOOL_RETURN]: true;
+    output: unknown;
+    effects: ToolEffect[];
+}
+export declare function withEffects(output: unknown, ...effects: ToolEffect[]): ToolReturn;
+export declare function isToolReturn(v: unknown): v is ToolReturn;
+export interface Tool<TArgs = unknown, TCtx = unknown> extends ToolSchema {
+    /**
+     * The family this tool belongs to, so config can name the whole set at
+     * once as `<group>:*`. Purely an authoring convenience — it is never sent
+     * to the model, which sees one flat list of names either way.
+     */
+    group?: string;
+    execute(args: TArgs, tc: ToolContext<TCtx>): unknown | Promise<unknown>;
+}
+/**
+ * Heterogeneous tool lists: every tool has a different `TArgs`, so there is no
+ * single type parameter that fits an array of them. `any` here is deliberate --
+ * `unknown` would make `execute` contravariant and reject concrete tools, and
+ * `never` propagates into `ToolContext<TCtx>` and breaks assignability. Arg
+ * safety is preserved at the definition site by `tool()` below.
+ */
+export type AnyTool<TCtx = unknown> = Tool<any, TCtx>;
+/**
+ * Identity helper. Its only job is inference: written inline, `execute`'s
+ * `args` would be `unknown`; going through `tool<{city: string}>()` types it.
+ */
+export declare function tool<TArgs, TCtx = unknown>(def: Tool<TArgs, TCtx>): Tool<TArgs, TCtx>;
+export interface ToolSelection {
+    /** the config key to name in an error, e.g. `agents.triage.tools` */
+    where: string;
+    /** how the caller should register a tool that is missing */
+    hint?: string;
+}
+/**
+ * Resolves selectors against the tools a host provided, in the order written
+ * and without duplicates. A selector is a tool name, `<group>:*` for every tool
+ * in a group, or `*` for everything; any of them prefixed with `-` removes
+ * what it matches from the selection so far.
+ */
+export declare function selectTools<TCtx>(available: AnyTool<TCtx>[], selectors: string[], opts: ToolSelection): AnyTool<TCtx>[];
+export declare const HANDOFF_PREFIX = "transfer_to_";
+export declare const FORK_TOOL = "fork";
+export declare const FINAL_OUTPUT_TOOL = "final_output";
+export declare const MEMORY_SEARCH_TOOL = "memory_search";
+export declare const MEMORY_WRITE_TOOL = "memory_write";
+export declare const MEMORY_UPDATE_TOOL = "memory_update";
+export declare const MEMORY_DELETE_TOOL = "memory_delete";
+export declare const SKILL_SEARCH_TOOL = "skill_search";
+export declare const SKILL_LOAD_TOOL = "skill_load";
+export declare function parseArgs(raw: string): Record<string, unknown>;
+export declare function asString(v: unknown): string | undefined;
+export declare function stringify(v: unknown): string;
+export {};
+//# sourceMappingURL=types.d.ts.map