@zenera/neo 1.1.0

package/dist/kernel.js

@@ -0,0 +1,929 @@
+import { z } from 'zod';
+import { Agent, AgentRegistry, handoffTarget, handoffTool } from "./agent.js";
+import { systemClock } from "./ids.js";
+import { memoryTools } from "./memory.js";
+import { hash } from "./payload.js";
+import { composePrompt } from "./prompt.js";
+import { allows, lockedSkillTools, renderSkillIndex, renderSkills, skillContentHash, skillTools, } from "./skills.js";
+import { lastOfType, projectMessages, projected, totalUsage, } from "./trajectory.js";
+import { FINAL_OUTPUT_TOOL, FORK_TOOL, addUsage, parseArgs, toContent, zeroUsage, } from "./types.js";
+const FINAL_OUTPUT_INSTRUCTIONS = `When you have the complete answer, deliver it by calling the \`${FINAL_OUTPUT_TOOL}\` ` +
+    `tool with arguments matching its schema. Plain prose is not accepted as the final answer.`;
+/**
+ * Every `apply*` returns a *new* state object; old snapshots stay valid, which
+ * is exactly what a checkpointing caller needs. Nodes carry no index: the array
+ * *is* the order.
+ */
+function begin(state, env) {
+    const clock = env.clock ?? systemClock;
+    const nodes = [];
+    return {
+        add(body, agent = state.agentName) {
+            const node = {
+                id: clock.newId(),
+                ts: clock.now(),
+                agent,
+                ...body,
+            };
+            nodes.push(node);
+            return node;
+        },
+        commit(patch) {
+            const trajectory = [...state.trajectory, ...nodes];
+            return { ...state, ...patch, trajectory, usage: ownUsage(state, trajectory) };
+        },
+    };
+}
+/**
+ * What *this* run consumed. A branch starts from a copy of the parent's prefix,
+ * whose `llm_call` nodes were paid for by the parent, so they are excluded.
+ */
+function ownUsage(state, trajectory) {
+    return totalUsage(trajectory.slice(state.spec.prefixLength ?? 0));
+}
+function put(env, value) {
+    return env.services.payloads.put(value);
+}
+function get(env, payload) {
+    return env.services.payloads.get(payload);
+}
+async function toPayloadParts(env, input) {
+    return Promise.all(toContent(input).map(async (p) => p.type === 'text'
+        ? { type: 'text', text: await put(env, p.text) }
+        : { type: p.type, url: p.url, mimeType: p.mimeType }));
+}
+/**
+ * The only way to obtain a state. Starting a run is explicit; the loop then
+ * only ever *advances* an existing state.
+ */
+export async function createState(opts, env) {
+    const clock = env.clock ?? systemClock;
+    const spec = {
+        startAgent: opts.agent,
+        forkDepth: 0,
+        maxForkDepth: opts.maxForkDepth ?? 2,
+    };
+    if (opts.output) {
+        const { schema, wrapped } = outputJsonSchema(opts.output);
+        spec.outputSchema = schema;
+        spec.outputSchemaHash = hash(JSON.stringify(schema));
+        spec.outputWrapped = wrapped;
+    }
+    const state = {
+        version: 1,
+        runId: opts.runId ?? clock.newId(),
+        spec,
+        agentName: opts.agent,
+        phase: 'created',
+        trajectory: [],
+        pendingToolCalls: [],
+        usage: zeroUsage(),
+        context: opts.context,
+    };
+    const b = begin(state, env);
+    if (opts.systemPrompt !== undefined) {
+        b.add({
+            type: 'system_prompt',
+            prompt: await put(env, opts.systemPrompt),
+        });
+    }
+    if (opts.input !== undefined) {
+        b.add({
+            type: 'user_input',
+            content: await toPayloadParts(env, opts.input),
+        });
+    }
+    return b.commit({ phase: opts.input === undefined ? 'created' : 'awaiting_llm' });
+}
+/**
+ * A Zod schema is a live object with functions, so it cannot live in a
+ * JSON-serializable state; its JSON Schema projection can, and must, because it
+ * is part of the prompt (the `final_output` tool's parameters).
+ */
+function outputJsonSchema(schema) {
+    let json;
+    try {
+        json = z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' });
+    }
+    catch (e) {
+        // Transforms, refinements and z.custom have no JSON Schema equivalent:
+        // the model sees the looser shape and safeParse enforces the rest.
+        console.warn(`output schema is only partly representable as JSON Schema: ${String(e)}`);
+        json = z.toJSONSchema(schema, {
+            target: 'draft-2020-12',
+            io: 'input',
+            unrepresentable: 'any',
+        });
+    }
+    const obj = json;
+    if (obj.type === 'object') {
+        return { schema: obj, wrapped: false };
+    }
+    // Non-object roots (a bare string, array, union …) cannot be tool
+    // parameters, so they travel in a single `value` property.
+    return {
+        schema: {
+            type: 'object',
+            properties: { value: obj },
+            required: ['value'],
+            additionalProperties: false,
+        },
+        wrapped: true,
+    };
+}
+/** A persisted run must not silently change its contract on resume. */
+export function checkOutputSchema(state, env) {
+    if (!env.output) {
+        return;
+    }
+    const { schema } = outputJsonSchema(env.output);
+    const given = hash(JSON.stringify(schema));
+    if (state.spec.outputSchemaHash && given !== state.spec.outputSchemaHash) {
+        throw new Error(`output schema mismatch: run ${state.runId} was created with a different schema`);
+    }
+}
+/** Pure inspection: what must happen next. No I/O, no payload resolution. */
+export function nextAction(state) {
+    if (state.phase === 'failed') {
+        throw new Error(`run ${state.runId} failed: ${state.error ?? 'unknown error'}`);
+    }
+    if (state.phase === 'done') {
+        const output = lastOfType(state.trajectory, 'final_output');
+        if (!output) {
+            throw new Error(`run ${state.runId} is done but has no final output`);
+        }
+        return { kind: 'done', output };
+    }
+    // Tool results are what unblock the next model call, so they come first even
+    // when a fork is also pending.
+    if (state.pendingToolCalls.length) {
+        const byId = new Map(state.trajectory.flatMap((n) => n.type === 'tool_call' ? [[n.callId, n]] : []));
+        const calls = state.pendingToolCalls.flatMap((id) => {
+            const n = byId.get(id);
+            return n ? [{ callId: n.callId, name: n.name, args: n.args }] : [];
+        });
+        if (calls.length) {
+            return { kind: 'tools', calls };
+        }
+    }
+    const pendingFork = state.pendingFork;
+    if (pendingFork?.branches.length) {
+        // Looked up by call id, not by "the last fork node": with two forks in
+        // one run the most recent one is not necessarily the pending one.
+        const fork = state.trajectory.find((n) => n.type === 'fork' && n.callId === pendingFork.callId);
+        if (fork) {
+            const branches = fork.branches
+                .filter((b) => pendingFork.branches.includes(b.name))
+                .map(({ name, agent, childRunId }) => ({ name, agent, childRunId }));
+            return { kind: 'fork', forkId: fork.callId, branches };
+        }
+    }
+    return { kind: 'llm' };
+}
+// ---------------------------------------------------------------------------
+// Tool set — derived from the state, not a static agent property
+// ---------------------------------------------------------------------------
+/** Agents a branch of this fork may run, in registration order. */
+function forkAgents(state, reg) {
+    const allowed = reg.find(state.agentName)?.fork?.agents;
+    if (!allowed) {
+        return reg.names();
+    }
+    const known = allowed.filter((n) => reg.find(n));
+    return known.length ? known : [state.agentName];
+}
+/**
+ * Derived from the state rather than a constant, because the one thing a weak
+ * model reliably gets wrong here is inventing an agent name. An `enum` of the
+ * agents that actually exist is a constraint the provider enforces during
+ * decoding, which no amount of prose in the description can match.
+ *
+ * `minItems`/`maxItems` are stated too, but they are advisory — most providers
+ * ignore them under strict decoding — so `parseForkArgs` and `forkProblem`
+ * still check both, and their messages are written to be read by the model.
+ */
+function forkParameters(agents, self, maxBranches) {
+    const max = maxBranches ?? 0;
+    // When the author's list excludes the current agent there is no sane
+    // default, so the model has to name one.
+    const selfAllowed = agents.includes(self);
+    return {
+        type: 'object',
+        properties: {
+            branches: {
+                type: 'array',
+                minItems: 2,
+                ...(max >= 2 ? { maxItems: max } : {}),
+                description: `At least two branches${max >= 2 ? `, at most ${max}` : ''}. ` +
+                    'One branch is never valid: if the work does not split, do it yourself ' +
+                    'instead of calling this tool.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Short, unique label for this branch, e.g. "eu-tariffs".',
+                        },
+                        instructions: {
+                            type: 'string',
+                            description: 'The complete assignment for this branch. It runs in a separate ' +
+                                'conversation and cannot ask questions, so state everything it ' +
+                                'needs and exactly what it must return.',
+                        },
+                        agent: {
+                            type: 'string',
+                            enum: agents,
+                            description: 'Which agent runs this branch. Must be one of: ' +
+                                agents.join(', ') +
+                                (selfAllowed ? `. Omit to use "${self}".` : '.'),
+                        },
+                    },
+                    required: selfAllowed
+                        ? ['name', 'instructions']
+                        : ['name', 'instructions', 'agent'],
+                    additionalProperties: false,
+                },
+            },
+            context: {
+                type: 'string',
+                enum: ['inherit', 'compact', 'none'],
+                description: 'How much of this conversation each branch starts with: "inherit" (all of ' +
+                    'it, the default), "compact" (messages only, no tool traffic), "none" ' +
+                    '(nothing but its own instructions).',
+            },
+        },
+        required: ['branches'],
+        additionalProperties: false,
+    };
+}
+const FORK_DESCRIPTION = [
+    'Split the work into independent branches that run in parallel and rejoin into one result.',
+    '',
+    'Call it when two or more parts of the task can be worked on without seeing each ' +
+        "other's findings — separate documents, regions, candidates, hypotheses. Do not call it " +
+        'to break one line of reasoning into steps: branches cannot talk to each other, and a ' +
+        "step that needs the previous step's answer must stay in this conversation.",
+    '',
+    'Every call needs at least two branches, each with a unique name and self-contained ' +
+        'instructions. Their answers come back to you as the result of this call, and you ' +
+        'decide what the final answer is.',
+].join('\n');
+/**
+ * tools(state) = agent tools + handoffs + memory + skills + fork +
+ * final_output. Computed from the state so a rehydrated run offers exactly the
+ * tools it had before the crash.
+ *
+ * Skill-owned tools are declared here whether or not their skill is active: the
+ * gate `lockedSkillTools` installs reads the trajectory when the tool is called,
+ * not when it is declared, so the array the model is sent never mutates
+ * mid-conversation and the provider's prompt cache survives a `skill_load`.
+ */
+export async function resolveTools(state, reg, env) {
+    const agent = reg.get(state.agentName);
+    const ctx = state.context;
+    const tools = [...agent.tools];
+    for (const name of agent.handoffs) {
+        tools.push(handoffTool(name, reg.find(name)?.description));
+    }
+    tools.push(...memoryTools(agent.memoryBindings(ctx)));
+    if (agent.skills) {
+        const binding = agent.skills;
+        tools.push(...skillTools(binding));
+        const provider = env.services.skillProvider(binding.provider);
+        // An agent-level tool of the same name wins, and is never gated.
+        const own = new Set(agent.tools.map((t) => t.name));
+        tools.push(...(await lockedSkillTools(binding, provider, own)));
+    }
+    if (agent.fork && state.spec.forkDepth < state.spec.maxForkDepth) {
+        tools.push({
+            name: FORK_TOOL,
+            description: FORK_DESCRIPTION,
+            parameters: forkParameters(forkAgents(state, reg), state.agentName, agent.fork.maxBranches),
+            // Never executed as a tool: the runner drives branches and the join
+            // becomes the tool result.
+            execute: () => 'fork scheduled',
+        });
+    }
+    if (state.spec.outputSchema) {
+        tools.push({
+            name: FINAL_OUTPUT_TOOL,
+            description: 'Deliver the final answer. Ends the run.',
+            parameters: state.spec.outputSchema,
+            execute: () => 'final output accepted',
+        });
+    }
+    return tools;
+}
+function toSchema(t) {
+    return { name: t.name, description: t.description, parameters: t.parameters };
+}
+/**
+ * Prompt text the runtime owns rather than the author: the skill index and the
+ * `final_output` instruction. Both used to be appended inside `buildRequest`,
+ * which meant part of the system prompt existed in no node and showed up in no
+ * audit. Composed in now, always last, so the volatile tail never invalidates
+ * the cacheable prefix.
+ */
+async function derivedPrompt(agent, state, env) {
+    const out = [];
+    if (agent.skills?.discovery === 'index') {
+        const binding = agent.skills;
+        const provider = env.services.skillProvider(binding.provider);
+        // Preloaded skills are left out: the index is a menu of what can be
+        // fetched, and offering something the agent already has invites a
+        // wasted `skill_load`. Filtering on the binding rather than on the
+        // trajectory keeps the prompt a function of config, so it stays
+        // byte-stable across turns.
+        const preloaded = new Set(binding.preload ?? []);
+        const index = (await provider.list()).filter((s) => allows(binding, s) && !preloaded.has(s.name));
+        const rendered = renderSkillIndex(index, binding.maxIndexEntries ?? 50);
+        if (rendered) {
+            out.push(rendered);
+        }
+    }
+    if (state.spec.outputSchema) {
+        out.push(FINAL_OUTPUT_INSTRUCTIONS);
+    }
+    return out;
+}
+/**
+ * Projection + tool schemas + system prompt for the active agent. The only
+ * place in the kernel that dereferences payloads — everything else works on
+ * refs alone.
+ *
+ * Nothing is appended to the system prompt here: what the model reads is
+ * exactly the `system_prompt` node `applySystemPrompt` recorded, which is what
+ * makes `requestDigest` a meaningful replay check for the prompt.
+ */
+export async function buildRequest(state, reg, env) {
+    const { system, messages } = await projectMessages(state.trajectory, env.services.payloads);
+    const tools = await resolveTools(state, reg, env);
+    return {
+        system,
+        messages,
+        tools: tools.map(toSchema),
+        toolChoice: 'auto',
+    };
+}
+/** Stable fingerprint of a request, for replay divergence detection. */
+export function requestDigest(req) {
+    return hash(JSON.stringify({
+        system: req.system ?? '',
+        messages: req.messages,
+        tools: req.tools.map((t) => t.name),
+    }));
+}
+/**
+ * A request as it goes onto an `llm_call` node: everything that shaped the
+ * call, minus the `signal`, which is machinery rather than content and is not
+ * JSON anyway. Pretty-printed, since the whole point of keeping it is that a
+ * human reads it later.
+ */
+export function serializeRequest(req) {
+    const { signal: _signal, ...rest } = req;
+    return JSON.stringify(rest, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Advancing the state
+// ---------------------------------------------------------------------------
+export async function applyUserInput(state, input, env, synthetic = false) {
+    const b = begin(state, env);
+    b.add({
+        type: 'user_input',
+        content: await toPayloadParts(env, input),
+        synthetic: synthetic || undefined,
+    });
+    return b.commit({ phase: 'awaiting_llm' });
+}
+/**
+ * Renders the active agent's instructions into the trajectory. Idempotent: a
+ * matching prompt already in force produces no node, so re-entering the loop
+ * (or resuming) does not litter the history.
+ *
+ * The rendered bytes are the identity. Two compositions that render the same
+ * string *are* the same prompt to the model, the provider cache and replay, so
+ * there is nothing else to hash and no renderer version to pin: a change that
+ * matters changes the bytes, and one that does not, does not.
+ */
+export async function applySystemPrompt(state, reg, env) {
+    const agent = reg.get(state.agentName);
+    const { text, sources } = await composePrompt(agent.instructions, state.context, state.spec, (value) => put(env, value), await derivedPrompt(agent, state, env));
+    if (!text) {
+        return state;
+    }
+    const current = lastOfType(projected(state.trajectory), 'system_prompt');
+    if (current && current.agent === state.agentName && current.prompt.sha256 === hash(text)) {
+        return state;
+    }
+    const b = begin(state, env);
+    b.add({
+        type: 'system_prompt',
+        prompt: await put(env, text),
+        ...(sources.length ? { sources } : {}),
+    });
+    return b.commit({});
+}
+function parseForkArgs(raw) {
+    const args = parseArgs(raw);
+    const branches = args.branches;
+    // Spelled out rather than "invalid arguments": this string is fed back to
+    // the model as the tool result, and it is the only chance it gets to work
+    // out what to do differently.
+    if (!Array.isArray(branches) || branches.length === 0) {
+        return 'the "branches" argument is missing or empty; it must be an array of at least two branches';
+    }
+    if (branches.length < 2) {
+        return ('a fork needs at least two branches, and this call has one. Either add the other ' +
+            'independent branches, or do not fork at all and carry out the work in this ' +
+            'conversation.');
+    }
+    const parsed = [];
+    for (const b of branches) {
+        if (typeof b?.name !== 'string' || !b.name.trim()) {
+            return 'every branch needs a non-empty "name"';
+        }
+        if (typeof b?.instructions !== 'string' || !b.instructions.trim()) {
+            return `branch "${b.name}" needs non-empty "instructions" saying what it must do`;
+        }
+        parsed.push({
+            name: b.name,
+            instructions: b.instructions,
+            agent: typeof b.agent === 'string' ? b.agent : undefined,
+        });
+    }
+    if (new Set(parsed.map((b) => b.name)).size !== parsed.length) {
+        return 'branch names must be unique';
+    }
+    const mode = args.context;
+    return {
+        branches: parsed,
+        context: mode === 'inherit' || mode === 'compact' || mode === 'none' ? mode : 'inherit',
+    };
+}
+/**
+ * Appends the `llm_call` node (plus the nodes its tool calls imply) and moves
+ * the phase on. Typed runs are resolved here too: `final_output` never reaches
+ * tool execution, it is validated against the run's schema on the spot.
+ */
+export async function applyLlmResponse(state, res, model, env, opts = {}) {
+    const reg = opts.registry;
+    const b = begin(state, env);
+    const toolCalls = await Promise.all(res.toolCalls.map(async (c) => ({
+        callId: c.id,
+        name: c.name,
+        args: await put(env, c.args),
+        signature: c.signature,
+    })));
+    b.add({
+        type: 'llm_call',
+        model,
+        requestDigest: opts.digest ?? (opts.request ? requestDigest(opts.request) : ''),
+        request: opts.request ? await put(env, serializeRequest(opts.request)) : undefined,
+        text: await put(env, res.text),
+        thinking: res.thinking ? await put(env, res.thinking) : undefined,
+        toolCalls,
+        usage: res.usage ?? zeroUsage(),
+        stopReason: res.stopReason ?? (res.toolCalls.length ? 'tool_calls' : 'stop'),
+    });
+    // --- no tool calls: either the run is over, or the model owes us a call ---
+    if (!res.toolCalls.length) {
+        if (!state.spec.outputSchema) {
+            b.add({ type: 'final_output', output: await put(env, res.text) });
+            return b.commit({ phase: 'done', pendingToolCalls: [] });
+        }
+        b.add({
+            type: 'user_input',
+            content: [
+                {
+                    type: 'text',
+                    text: await put(env, `Your answer must be delivered through the \`${FINAL_OUTPUT_TOOL}\` tool.`),
+                },
+            ],
+            synthetic: true,
+        });
+        return b.commit({ phase: 'awaiting_llm', pendingToolCalls: [] });
+    }
+    const pending = [];
+    let pendingFork = state.pendingFork;
+    let done = false;
+    for (let i = 0; i < res.toolCalls.length; i++) {
+        const call = res.toolCalls[i];
+        const ref = toolCalls[i];
+        if (call.name === FINAL_OUTPUT_TOOL && state.spec.outputSchema) {
+            const parsed = validateOutput(state, env, call.args);
+            if (parsed.ok) {
+                b.add({
+                    type: 'final_output',
+                    output: await put(env, stringifyOutput(parsed.value)),
+                    parsed: parsed.value,
+                });
+                done = true;
+            }
+            else {
+                // Repairable: the model sees its own mistake and tries again.
+                b.add({
+                    type: 'tool_result',
+                    callId: call.id,
+                    name: call.name,
+                    result: await put(env, parsed.message),
+                    isError: true,
+                });
+            }
+            continue;
+        }
+        if (call.name === FORK_TOOL) {
+            const args = parseForkArgs(call.args);
+            const problem = typeof args === 'string' ? args : forkProblem(state, args, reg);
+            if (typeof args === 'string' || problem) {
+                b.add({
+                    type: 'tool_result',
+                    callId: call.id,
+                    name: call.name,
+                    result: await put(env, `error: ${problem ?? args}`),
+                    isError: true,
+                });
+                continue;
+            }
+            const clock = env.clock ?? systemClock;
+            const branches = await Promise.all(args.branches.map(async (br) => ({
+                name: br.name,
+                agent: br.agent ?? state.agentName,
+                instructions: await put(env, br.instructions),
+                childRunId: clock.newId(),
+            })));
+            b.add({
+                type: 'fork',
+                callId: call.id,
+                contextMode: args.context ?? 'inherit',
+                branches,
+            });
+            pendingFork = { callId: call.id, branches: branches.map((br) => br.name) };
+            continue;
+        }
+        b.add({
+            type: 'tool_call',
+            callId: call.id,
+            name: call.name,
+            args: ref.args,
+        });
+        pending.push(call.id);
+    }
+    if (done) {
+        return b.commit({ phase: 'done', pendingToolCalls: [], pendingFork: undefined });
+    }
+    const phase = pending.length
+        ? 'awaiting_tools'
+        : pendingFork?.branches.length
+            ? 'awaiting_branches'
+            : 'awaiting_llm';
+    return b.commit({ phase, pendingToolCalls: pending, pendingFork });
+}
+function forkProblem(state, args, reg) {
+    const agent = reg?.find(state.agentName);
+    if (agent && !agent.fork) {
+        return 'this agent cannot fork';
+    }
+    const max = agent?.fork?.maxBranches;
+    if (max && args.branches.length > max) {
+        return `at most ${max} branches are allowed, and this call has ${args.branches.length}`;
+    }
+    // Hallucinated agent names are the common failure, so the answer always
+    // carries the list of real ones — a retry then has nothing left to guess.
+    const allowed = reg ? forkAgents(state, reg) : undefined;
+    for (const b of args.branches) {
+        const name = b.agent ?? state.agentName;
+        if (allowed && !allowed.includes(name)) {
+            return (`branch "${b.name}" names an agent that cannot run it: "${name}". ` +
+                `Use one of: ${allowed.join(', ')} — or omit "agent" to use ${state.agentName}.`);
+        }
+    }
+    return undefined;
+}
+function stringifyOutput(v) {
+    return typeof v === 'string' ? v : JSON.stringify(v, null, 2);
+}
+/**
+ * Validation uses the Zod schema when the caller supplied one — transforms,
+ * defaults and refinements included. A run resumed by generic tooling without
+ * the original schema degrades to a structural JSON Schema check.
+ */
+function validateOutput(state, env, raw) {
+    let args;
+    try {
+        args = JSON.parse(raw || '{}');
+    }
+    catch (e) {
+        return { ok: false, message: `error: arguments are not valid JSON: ${String(e)}` };
+    }
+    const payload = state.spec.outputWrapped ? args?.value : args;
+    if (env.output) {
+        const parsed = env.output.safeParse(payload);
+        return parsed.success
+            ? { ok: true, value: parsed.data }
+            : {
+                ok: false,
+                message: `error: output does not match the schema:\n${z.prettifyError(parsed.error)}`,
+            };
+    }
+    const schema = state.spec.outputSchema;
+    if (!state.spec.outputWrapped && schema?.required?.length) {
+        const obj = (payload ?? {});
+        const missing = schema.required.filter((k) => obj[k] === undefined);
+        if (missing.length) {
+            return { ok: false, message: `error: missing required fields: ${missing.join(', ')}` };
+        }
+    }
+    return { ok: true, value: payload };
+}
+/**
+ * Appends the tool result, folds in whatever the tool did to memory or skills,
+ * and performs a hand-off when the call was a `transfer_to_*`.
+ */
+export async function applyToolResult(state, callId, outcome, env) {
+    const call = state.trajectory.find((n) => n.type === 'tool_call' && n.callId === callId);
+    if (!call) {
+        throw new Error(`no pending tool call ${callId} in run ${state.runId}`);
+    }
+    const b = begin(state, env);
+    b.add({
+        type: 'tool_result',
+        callId,
+        name: call.name,
+        result: await put(env, outcome.output),
+        isError: outcome.isError,
+        durationMs: outcome.durationMs,
+    });
+    for (const effect of outcome.effects ?? []) {
+        if (effect.kind === 'memory_op') {
+            await addMemoryOp(b, env, effect.spec);
+        }
+        else {
+            await addSkillLoad(b, env, effect.spec);
+        }
+    }
+    const target = outcome.isError ? undefined : handoffTarget(call.name);
+    let agentName = state.agentName;
+    if (target) {
+        b.add({
+            type: 'handoff',
+            from: state.agentName,
+            to: target,
+            reason: asReason(call),
+        });
+        agentName = target;
+    }
+    const pendingToolCalls = state.pendingToolCalls.filter((id) => id !== callId);
+    const phase = pendingToolCalls.length
+        ? 'awaiting_tools'
+        : state.pendingFork?.branches.length
+            ? 'awaiting_branches'
+            : 'awaiting_llm';
+    return b.commit({ phase, pendingToolCalls, agentName });
+}
+function asReason(call) {
+    // The reason travels in the call arguments, which are behind a payload; the
+    // preview is enough for a human-readable trace and costs no I/O.
+    const preview = call.args.preview;
+    if (!preview) {
+        return undefined;
+    }
+    const reason = parseArgs(preview).reason;
+    return typeof reason === 'string' ? reason : undefined;
+}
+async function addMemoryOp(b, env, spec) {
+    b.add({
+        type: 'memory_op',
+        op: spec.op,
+        store: spec.store,
+        scope: spec.scope,
+        opId: spec.opId,
+        recordId: spec.recordId,
+        revision: spec.revision,
+        before: spec.before === undefined ? undefined : await put(env, spec.before),
+        after: spec.after === undefined ? undefined : await put(env, spec.after),
+    });
+}
+async function addSkillLoad(b, env, spec) {
+    b.add({
+        type: 'load_skills',
+        provider: spec.provider,
+        skills: spec.skills.map((s) => ({
+            name: s.name,
+            version: s.version,
+            contentHash: skillContentHash(s),
+            file: s.file,
+        })),
+        content: await put(env, renderSkills(spec.skills)),
+        toolNames: [...new Set(spec.skills.flatMap((s) => (s.tools ?? []).map((t) => t.name)))],
+    });
+}
+/** Records a memory recall or mutation performed by the driver. */
+export async function applyMemoryEffect(state, effect, env) {
+    const b = begin(state, env);
+    if (effect.kind === 'op') {
+        await addMemoryOp(b, env, effect);
+    }
+    else {
+        b.add({
+            type: 'memory_recall',
+            store: effect.store,
+            scope: effect.scope,
+            query: effect.query,
+            hits: effect.hits,
+            content: await put(env, effect.content),
+        });
+    }
+    return b.commit({});
+}
+/** Records a skill activation and the tools it unlocked. */
+export async function applySkillLoad(state, provider, skills, env) {
+    const b = begin(state, env);
+    await addSkillLoad(b, env, { kind: 'skill_load', provider, skills });
+    return b.commit({});
+}
+/**
+ * Containment, not deletion: the covered nodes stay in the trajectory for audit
+ * and replay, and only the projection skips them. The log stays append-only.
+ */
+export async function applyCompaction(state, spec, env) {
+    const clock = env.clock ?? systemClock;
+    const b = begin(state, env);
+    b.add({
+        type: 'compaction',
+        callId: spec.callId ?? `compact_${clock.newId()}`,
+        covers: spec.covers,
+        summary: await put(env, spec.summary),
+        reason: spec.reason,
+        usage: spec.usage ?? zeroUsage(),
+    });
+    return b.commit({});
+}
+export function applyFailure(state, error) {
+    return { ...state, phase: 'failed', error };
+}
+// ---------------------------------------------------------------------------
+// Fork / join
+// ---------------------------------------------------------------------------
+/**
+ * Derives a child state seeded with *real nodes* copied from the parent, not a
+ * frozen `Message[]` blob: the branch can compact its own inherited context,
+ * and at join those nodes splice back into one trajectory. The copy is a
+ * snapshot, so the branch can execute in another process.
+ */
+export async function createChildState(state, forkId, branch, env) {
+    const fork = state.trajectory.find((n) => n.type === 'fork' && n.callId === forkId);
+    const plan = fork?.branches.find((b) => b.name === branch);
+    if (!fork || !plan) {
+        throw new Error(`unknown branch ${branch} of fork ${forkId}`);
+    }
+    const prefix = branchPrefix(state, fork, plan.agent);
+    const child = {
+        version: 1,
+        runId: plan.childRunId,
+        spec: {
+            startAgent: plan.agent,
+            parent: { runId: state.runId, forkId, branch },
+            forkDepth: state.spec.forkDepth + 1,
+            maxForkDepth: state.spec.maxForkDepth,
+            // Where the branch's own history begins: the parent already holds
+            // the prefix, so only what follows is spliced back at join.
+            prefixLength: prefix.length,
+        },
+        agentName: plan.agent,
+        phase: 'created',
+        trajectory: prefix,
+        pendingToolCalls: [],
+        usage: zeroUsage(),
+        context: state.context,
+    };
+    const b = begin(child, env);
+    if (prefix.length) {
+        // The branch inherited the turn that called `fork`, so the honest way to
+        // hand it its assignment is to answer that call: the model sees a tool
+        // result for a tool it just called, instead of a second user message
+        // appearing after its own. It also keeps the fork call itself in the
+        // prompt — otherwise `repairToolCalls` strips it as unanswered and the
+        // branch never learns that it fanned out at all.
+        b.add({
+            type: 'tool_result',
+            callId: fork.callId,
+            name: FORK_TOOL,
+            result: await put(env, branchBrief(fork, plan, await get(env, plan.instructions))),
+            isError: false,
+        });
+    }
+    else {
+        // Nothing to answer: a `context: 'none'` branch has no history, so its
+        // assignment arrives the only way it can, as the opening message.
+        b.add({
+            type: 'user_input',
+            // Reuses the instructions payload already written by the fork node.
+            content: [{ type: 'text', text: plan.instructions }],
+        });
+    }
+    return b.commit({ phase: 'awaiting_llm' });
+}
+/**
+ * What an inheriting branch is told when its own `fork` call comes back. The
+ * parent's fork arguments are already in the prompt above it, so the siblings'
+ * assignments need no repeating — but which of the branches this run *is*, and
+ * what happens to what it produces, exist nowhere else. Without them a branch
+ * re-derives work a sibling already owns and writes an answer shaped for a user
+ * rather than for a merge.
+ */
+function branchBrief(fork, plan, instructions) {
+    const siblings = fork.branches.filter((b) => b.name !== plan.name).map((b) => `"${b.name}"`);
+    return [
+        `You are branch "${plan.name}" of the fork above. Your assignment, and your only one:`,
+        '',
+        instructions,
+        '',
+        `Running in parallel, on the assignments the call above gave them: ${siblings.join(', ')}. ` +
+            'You cannot see their work and they cannot see yours, so anything you do on their ' +
+            'part is duplicated effort, and anything you leave to them will be there. This branch ' +
+            'ends with your final answer; that answer alone rejoins the conversation above, ' +
+            'merged with theirs.',
+    ].join('\n');
+}
+/** The parent history a branch starts from, as decided by `contextMode`. */
+function branchPrefix(state, fork, agent) {
+    if (fork.contextMode === 'none') {
+        return [];
+    }
+    const visible = projected(state.trajectory);
+    const at = visible.findIndex((n) => n.id === fork.id);
+    const before = at === -1 ? visible : visible.slice(0, at);
+    return before.filter((n) => {
+        // Skills are agent-scoped. Carrying the instructions text across an
+        // agent change would leave the branch reading about tools it cannot
+        // call, so text and tools have to disappear together.
+        if (n.type === 'load_skills') {
+            return n.agent === agent;
+        }
+        // 'compact': start from the conversation, not the parent's tool chatter.
+        // The now-unanswered tool calls are dropped by `repairToolCalls`.
+        if (fork.contextMode === 'compact') {
+            return n.type !== 'tool_call' && n.type !== 'tool_result' && n.type !== 'memory_recall';
+        }
+        return true;
+    });
+}
+/**
+ * Folds branches back into the parent. Each branch's history is nested inside
+ * its row of the join, in *declared* branch order — so the result is identical
+ * regardless of completion order, and a walk of the parent array never trips
+ * over someone else's nodes.
+ */
+export async function applyJoin(state, forkId, results, env) {
+    const fork = state.trajectory.find((n) => n.type === 'fork' && n.callId === forkId);
+    if (!fork) {
+        throw new Error(`unknown fork ${forkId} in run ${state.runId}`);
+    }
+    const byName = new Map(results.map((r) => [r.name, r]));
+    const b = begin(state, env);
+    const rows = [];
+    let usage = zeroUsage();
+    for (const plan of fork.branches) {
+        const r = byName.get(plan.name);
+        if (!r) {
+            continue;
+        }
+        rows.push({
+            name: plan.name,
+            agent: plan.agent,
+            status: r.status,
+            output: await put(env, r.output),
+            error: r.error,
+            usage: r.usage,
+            // Only what the branch itself did: the inherited prefix is the
+            // parent's own history and is already right there in the array.
+            nodes: r.childState.trajectory.slice(r.childState.spec.prefixLength ?? 0),
+        });
+        usage = addUsage(usage, r.usage);
+    }
+    b.add({ type: 'join', callId: forkId, branches: rows, usage });
+    const remaining = (state.pendingFork?.branches ?? []).filter((n) => !byName.has(n));
+    return b.commit({
+        pendingFork: remaining.length ? { callId: forkId, branches: remaining } : undefined,
+        phase: remaining.length
+            ? 'awaiting_branches'
+            : state.pendingToolCalls.length
+                ? 'awaiting_tools'
+                : 'awaiting_llm',
+    });
+}
+// ---------------------------------------------------------------------------
+// Small read helpers used by drivers
+// ---------------------------------------------------------------------------
+export function lastUserInput(state) {
+    const nodes = state.trajectory;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+        const n = nodes[i];
+        if (n.type === 'user_input' && !n.synthetic) {
+            return n;
+        }
+    }
+    return undefined;
+}
+export { Agent, AgentRegistry };
+//# sourceMappingURL=kernel.js.map