@zenera/neo 1.1.0

package/dist/prompt.d.ts

@@ -0,0 +1,66 @@
+import type { Payload } from './payload.ts';
+import type { RunSpec } from './state.ts';
+/**
+ * A block of prompt text, optionally tagged with where it came from.
+ *
+ * `path` is metadata, not an instruction to go and read something: the text is
+ * already here. It exists so the trajectory can answer "which file do I edit to
+ * change this?" — the one question a rendered prompt cannot answer by itself.
+ */
+export interface PromptText {
+    text: string;
+    /** the editable document this text came from, if any */
+    path?: string;
+    /** opt-in wrapper tag, e.g. `intent` → `<intent>…</intent>` */
+    section?: string;
+}
+/**
+ * One contributor to a system prompt: literal text, text computed from the run
+ * context, or a tagged block (usually a file loaded by `promptFile`).
+ *
+ * The function form gets `RunSpec`, not `AgentState`, on purpose. The system
+ * prompt is the provider's cache prefix; one that varied with mutable state
+ * would invalidate that prefix every turn and append a node every turn. A
+ * `RunSpec` is fixed at `createState`, so `forkDepth` and the output contract
+ * are available while "prompt that grows with the conversation" is not
+ * expressible — per-turn content belongs at the tail, as input and results.
+ */
+export type PromptPart<TCtx = unknown> = string | ((ctx: TCtx, spec: RunSpec) => string) | PromptText;
+export type Instructions<TCtx = unknown> = string | ((ctx: TCtx, spec: RunSpec) => string) | PromptPart<TCtx>[];
+/**
+ * Loads a prompt file and remembers where it came from.
+ *
+ * Read once, at agent construction, and synchronously: this is setup, the same
+ * moment a module is imported or a config parsed, so a bad path fails at
+ * startup with a stack trace pointing at the agent — not on the first LLM call
+ * of a run in production. It also keeps the prompt genuinely constant for the
+ * life of the agent, which is what the provider's cache assumes anyway.
+ *
+ * A prompt that must change without a restart is a different feature: rebuild
+ * the agent, or use the function form.
+ */
+export declare function promptFile(path: string, section?: string): PromptText;
+/** A document that fed a prompt, with the exact bytes it contributed. */
+export interface PromptSource {
+    path: string;
+    content: Payload;
+}
+export interface ComposedPrompt {
+    /** exactly what the provider will receive */
+    text: string;
+    /** the editable contributors, in the order they were rendered */
+    sources: PromptSource[];
+}
+/**
+ * Renders the authored parts, then the kernel's derived text, into one string —
+ * and reports which documents went into it.
+ *
+ * `derived` (the skill index, the `final_output` instruction) is appended last
+ * so the volatile tail never invalidates the cacheable prefix, and it is *not*
+ * reported as a source: neither is a file anyone edits.
+ *
+ * The only async here is `put`: the composer does no I/O of its own, because by
+ * this point every part already carries its text.
+ */
+export declare function composePrompt<TCtx>(instructions: Instructions<TCtx> | undefined, ctx: TCtx, spec: RunSpec, put: (text: string) => Promise<Payload>, derived?: string[]): Promise<ComposedPrompt>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.js

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Loads a prompt file and remembers where it came from.
+ *
+ * Read once, at agent construction, and synchronously: this is setup, the same
+ * moment a module is imported or a config parsed, so a bad path fails at
+ * startup with a stack trace pointing at the agent — not on the first LLM call
+ * of a run in production. It also keeps the prompt genuinely constant for the
+ * life of the agent, which is what the provider's cache assumes anyway.
+ *
+ * A prompt that must change without a restart is a different feature: rebuild
+ * the agent, or use the function form.
+ */
+export function promptFile(path, section) {
+    const text = readFileSync(path, 'utf8');
+    return section === undefined ? { text, path } : { text, path, section };
+}
+const SEPARATOR = '\n\n';
+/**
+ * Markers are opt-in because they are tokens the model reads: a wrapper that
+ * "does not influence the content" does not exist for an LLM.
+ */
+function wrap(part) {
+    return part.section ? `<${part.section}>\n${part.text}\n</${part.section}>` : part.text;
+}
+/**
+ * Renders the authored parts, then the kernel's derived text, into one string —
+ * and reports which documents went into it.
+ *
+ * `derived` (the skill index, the `final_output` instruction) is appended last
+ * so the volatile tail never invalidates the cacheable prefix, and it is *not*
+ * reported as a source: neither is a file anyone edits.
+ *
+ * The only async here is `put`: the composer does no I/O of its own, because by
+ * this point every part already carries its text.
+ */
+export async function composePrompt(instructions, ctx, spec, put, derived = []) {
+    const parts = instructions === undefined
+        ? []
+        : Array.isArray(instructions)
+            ? instructions
+            : [instructions];
+    const chunks = [];
+    const sources = [];
+    for (const part of parts) {
+        if (typeof part === 'string') {
+            chunks.push(part);
+        }
+        else if (typeof part === 'function') {
+            chunks.push(part(ctx, spec));
+        }
+        else {
+            if (part.path && part.text) {
+                sources.push({ path: part.path, content: await put(part.text) });
+            }
+            chunks.push(wrap(part));
+        }
+    }
+    chunks.push(...derived);
+    return { text: chunks.filter(Boolean).join(SEPARATOR), sources };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/runner.d.ts

@@ -0,0 +1,103 @@
+import type { z } from 'zod';
+import { Agent, AgentRegistry, type AgentOptions } from './agent.ts';
+import { type Architecture } from './architecture.ts';
+import { RunStream } from './events.ts';
+import { type IdClock } from './ids.ts';
+import type { MemoryStore } from './memory.ts';
+import type { Model } from './model.ts';
+import { PayloadResolver, type PayloadStore } from './payload.ts';
+import { Services } from './services.ts';
+import { type SkillProvider } from './skills.ts';
+import { type AgentState } from './state.ts';
+import { type HandoffNode, type TrajectoryNode } from './trajectory.ts';
+import { type Input, type TokenUsage } from './types.ts';
+/**
+ * Collapsing history is two decisions, and they belong on different sides of
+ * the I/O line: *which* nodes go (pure, so the kernel can stay pure) and *how*
+ * they are rendered (a model call, so the driver owns it).
+ */
+export interface HandoffPolicy {
+    /** nodes the outgoing agent leaves behind, or null to keep everything */
+    select(state: AgentState, handoff: HandoffNode): TrajectoryNode[] | null;
+}
+export type Summary = string | {
+    text: string;
+    usage?: TokenUsage;
+};
+export interface Summarizer {
+    summarize(nodes: TrajectoryNode[], reason: string, services: Services): Promise<Summary>;
+}
+export interface JoinPolicy {
+    /** what the parent sees for this branch */
+    summarize(child: AgentState, services: Services): Promise<string>;
+    /** whether one branch's failure aborts the others */
+    onBranchError?: 'continue' | 'abort_siblings';
+}
+/** A summarizer that asks a model, so the compaction node holds real prose. */
+export declare function modelSummarizer(model: Model, instructions?: string): Summarizer;
+export interface RunnerOptions<TCtx = unknown> {
+    /** default model for agents that do not pin their own */
+    model?: Model;
+    context?: TCtx;
+    services?: Services;
+    payloads?: PayloadStore | PayloadResolver;
+    memory?: MemoryStore[];
+    skills?: SkillProvider[];
+    handoffPolicy?: HandoffPolicy;
+    /** renders the nodes a policy selected; defaults to a structural note */
+    summarizer?: Summarizer;
+    joinPolicy?: JoinPolicy;
+    /** use `Model.stream` when the model implements it (default: true) */
+    stream?: boolean;
+    /**
+     * Store the exact request behind every `llm_call` node, so a finished run
+     * can be inspected (see `renderRunReport`) instead of guessed at. Off by
+     * default: it re-stores the whole projected transcript once per turn, which
+     * is quadratic in run length and defeats the point of a compact state.
+     */
+    recordRequests?: boolean;
+    clock?: IdClock;
+}
+export interface RunOptions<T = string, TCtx = unknown> {
+    context?: TCtx;
+    /** typed result: the schema drives both validation and `RunResult<T>` */
+    output?: z.ZodType<T>;
+    signal?: AbortSignal;
+    maxForkDepth?: number;
+}
+/**
+ * The driver: it owns all nondeterminism and all I/O, and calls the kernel to
+ * advance the state. Every checkpoint event carries a complete snapshot, so a
+ * consumer can persist it and later `resume()` from exactly that point.
+ *
+ * There is no turn budget. A run ends on a final answer, an abort or an
+ * unrecoverable error.
+ */
+export declare class AgentRunner<TCtx = unknown> {
+    #private;
+    readonly registry: AgentRegistry<TCtx>;
+    readonly services: Services;
+    constructor(opts?: RunnerOptions<TCtx>);
+    /** Registers agents; chainable. */
+    add(...agents: Agent<TCtx>[]): this;
+    /** Creates + registers + returns an agent in one call. */
+    agent(opts: AgentOptions<TCtx>): Agent<TCtx>;
+    get(name: string): Agent<TCtx>;
+    /**
+     * The declared wiring as plain JSON: agents, their tools, skills, memory
+     * and hand-offs. It lives here rather than on the registry because three
+     * of those answers are the runner's: the fallback model, the skill
+     * catalogs behind `services`, and the context that resolves memory scopes.
+     */
+    describe(): Promise<Architecture>;
+    /**
+     * Starts a new run. State creation is explicit inside, so the first event a
+     * consumer sees (`run_created`) already carries a persistable snapshot.
+     */
+    run<T = string>(agent: Agent<TCtx> | string, input?: Input, opts?: RunOptions<T, TCtx>): RunStream<T>;
+    /** Continues a persisted run from its own snapshot. */
+    resume<T = string>(state: AgentState, opts?: RunOptions<T, TCtx>): RunStream<T>;
+    /** Adds a follow-up message to a finished (or paused) run and continues it. */
+    send<T = string>(state: AgentState, input: Input, opts?: RunOptions<T, TCtx>): RunStream<T>;
+}
+//# sourceMappingURL=runner.d.ts.map