@kuralle-agents/core 0.11.0 → 0.13.0

package/README.md

@@ -60,6 +60,91 @@ for await (const part of handle.events) {           // events is a property, not
 await handle;   // resolves to TurnResult once the stream is consumed
 ```
 
+## Single-run trace / `runOnce`
+
+Use `runOnce` when an evaluator needs one complete, JSON-serializable turn instead
+of a live stream. The trace includes the answer, tool roll-up, and nested spans.
+
+```ts
+const trace = await runtime.runOnce({
+  sessionId: 'grounding-eval-42',
+  input: 'What was my last invoice total?',
+});
+
+const judgeContext = {
+  answer: trace.answer,
+  evidence: trace.toolResults.map(({ name, result }) => ({ name, result })),
+};
+
+const verdict = await groundingJudge(judgeContext);
+console.log(verdict, trace.usedTool, trace.traceId);
+```
+
+`runOnce` executes exactly one normal runtime turn and observes its existing event
+stream. Runtime tracing also captures normal `run()` calls; trace persistence is
+physically separate from the session store and durable effect journal.
+
+## Observability
+
+Tracing is enabled by default with an in-process `MemoryTraceStore`. Supply a native
+store for durable reads and add any number of export sinks independently of
+`sessionStore`:
+
+```ts
+import { createRuntime } from '@kuralle-agents/core';
+import { RedisTraceStore } from '@kuralle-agents/redis-store';
+
+const traceStore = new RedisTraceStore({
+  client,
+  traceTtlSeconds: 7 * 24 * 60 * 60,
+});
+
+const runtime = createRuntime({
+  agents: [agent],
+  defaultAgentId: 'support',
+  tracing: {
+    store: traceStore,
+    sampling: 0.1,
+    sinks: [externalSink],
+    redact: (span) => ({
+      ...span,
+      attributes: { ...span.attributes, input: undefined, output: undefined },
+    }),
+  },
+});
+
+const latest = (await runtime.listTraces('session-42'))[0];
+const trace = latest ? await runtime.getTrace(latest.traceId) : null;
+```
+
+Sink failures are swallowed and never change the run result. Redaction is off by
+default for useful local debugging; use the hook above before persisting sensitive
+tool inputs or outputs. Set `tracing.enabled: false` to disable capture.
+
+### OTLP and Langfuse
+
+The built-in exporter uses HTTP/JSON over `fetch`, so it runs in Bun, Node.js, and
+Cloudflare Workers without a Node OpenTelemetry SDK:
+
+```ts
+import { langfuseSink, otelSink } from '@kuralle-agents/core';
+
+const runtime = createRuntime({
+  agents: [agent],
+  defaultAgentId: 'support',
+  tracing: {
+    store: traceStore,
+    sinks: [
+      otelSink({ endpoint: 'https://collector.example.com', headers: { Authorization: 'Bearer token' } }),
+      langfuseSink({ publicKey: env.LANGFUSE_PUBLIC_KEY, secretKey: env.LANGFUSE_SECRET_KEY }),
+    ],
+  },
+});
+```
+
+Endpoints may include `/v1/traces`; otherwise the sink appends it. For self-hosted
+Langfuse, pass its OTLP base URL as `endpoint`.
+
 ## Flows
 
 A flow is a node graph that enforces a multi-step procedure without embedding a 600-line SOP in a system prompt.

package/dist/capabilities/LivePromptAssembler.js

@@ -47,6 +47,7 @@ const INTERNAL_MEMORY_KEYS = [
     'flowStateByAgent',
     '__ariaAssistantText',
     '__ariaContextBudget',
+    '__goals',
 ];
 /**
  * Default LivePromptAssembler implementation.

package/dist/flow/collectDigression.d.ts

@@ -1,6 +1,5 @@
 import type { AgentConfig } from '../types/agentConfig.js';
 import type { ChannelDriver } from '../types/channel.js';
-import type { CollectNode } from '../types/flow.js';
 import type { RunContext } from '../types/run-context.js';
 import type { RunState } from '../runtime/durable/types.js';
 import type { NormalizedTransition } from './normalizeTransition.js';
@@ -9,11 +8,15 @@ export interface FlowPark {
     flow: string;
     node: string;
 }
+export declare function pushFlowPark(state: Record<string, unknown>, park: FlowPark): void;
+export declare function popFlowPark(state: Record<string, unknown>): FlowPark | undefined;
 export declare function getFlowPark(state: Record<string, unknown>): FlowPark | undefined;
 export declare function looksLikeOffScriptQuestion(input: string): boolean;
 export interface CollectDigressionOptions {
     agent: AgentConfig;
-    node: CollectNode;
+    node: {
+        id: string;
+    };
     activeFlowName: string;
     run: RunState;
     driver: ChannelDriver;

package/dist/flow/collectDigression.js

@@ -1,20 +1,57 @@
 import { resolveReplyNode } from './nodeBuilders.js';
 import { selectHostTarget } from '../runtime/select.js';
-const FLOW_PARK_KEY = '__flowPark';
-export function getFlowPark(state) {
-    const raw = state[FLOW_PARK_KEY];
+import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
+const FLOW_PARK_STACK_KEY = '__flowParkStack';
+const LEGACY_FLOW_PARK_KEY = '__flowPark';
+const MAX_FLOW_PARK_DEPTH = 8;
+function isFlowPark(raw) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return undefined;
+        return false;
     }
     const flow = raw.flow;
     const node = raw.node;
-    if (typeof flow === 'string' && typeof node === 'string') {
-        return { flow, node };
+    return typeof flow === 'string' && typeof node === 'string';
+}
+function getFlowParkStack(state) {
+    const raw = state[FLOW_PARK_STACK_KEY];
+    if (!Array.isArray(raw)) {
+        return undefined;
     }
-    return undefined;
+    const stack = raw.filter(isFlowPark);
+    return stack.length > 0 ? stack : undefined;
+}
+export function pushFlowPark(state, park) {
+    const stack = getFlowParkStack(state) ?? [];
+    stack.push(park);
+    while (stack.length > MAX_FLOW_PARK_DEPTH) {
+        stack.shift();
+    }
+    state[FLOW_PARK_STACK_KEY] = stack;
 }
-function setFlowPark(state, park) {
-    state[FLOW_PARK_KEY] = park;
+export function popFlowPark(state) {
+    const stack = getFlowParkStack(state);
+    if (!stack) {
+        return undefined;
+    }
+    const park = stack.pop();
+    if (stack.length === 0) {
+        delete state[FLOW_PARK_STACK_KEY];
+    }
+    else {
+        state[FLOW_PARK_STACK_KEY] = stack;
+    }
+    return park;
+}
+export function getFlowPark(state) {
+    const stack = getFlowParkStack(state);
+    if (stack) {
+        return stack[stack.length - 1];
+    }
+    const legacy = state[LEGACY_FLOW_PARK_KEY];
+    if (isFlowPark(legacy)) {
+        return legacy;
+    }
+    return undefined;
 }
 function appendAssistantMessage(run, text) {
     if (!text.trim()) {
@@ -53,7 +90,7 @@ export async function runCollectDigression(options) {
         };
     }
     if (selection.kind === 'enterFlow') {
-        setFlowPark(run.state, { flow: activeFlowName, node: node.id });
+        pushFlowPark(run.state, { flow: activeFlowName, node: node.id });
         return {
             kind: 'transition',
             transition: {
@@ -74,6 +111,7 @@ export async function runCollectDigression(options) {
         tools: ctx.globalTools,
     };
     const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
+    await persistTurnUsageFromTurn(ctx, turn);
     if (turn.text.trim()) {
         appendAssistantMessage(run, turn.text);
     }

package/dist/flow/collectUntilComplete.js

@@ -1,4 +1,5 @@
 import { runCollectDigression } from './collectDigression.js';
+import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { resolveCollectExtractionNode } from './nodeBuilders.js';
@@ -16,8 +17,13 @@ function appendUserMessage(run, input) {
     run.messages = [...run.messages, message];
 }
 export async function collectUntilComplete(node, run, driver, ctx, options) {
+    // A satisfied collect defers completion for ONE pass when there is pending input,
+    // so a correction ("no, Tuesday") is re-extracted and overwrites before completing
+    // (G14). Bounded to a single pass so the loop cannot spin if a driver's awaitUser
+    // does not clear the pending buffer — completion no longer depends on that.
+    let pendingConsumed = false;
     for (;;) {
-        if (schemaSatisfied(node, run.state)) {
+        if (schemaSatisfied(node, run.state) && (!hasPendingUserInput(ctx.session) || pendingConsumed)) {
             const data = projectCollectData(node, run.state);
             return normalizeTransition(await node.onComplete(data, run.state));
         }
@@ -32,6 +38,7 @@ export async function collectUntilComplete(node, run, driver, ctx, options) {
         if (hasPendingUserInput(ctx.session)) {
             const signal = await driver.awaitUser(ctx);
             appendUserMessage(run, signal.input);
+            pendingConsumed = true;
         }
         else if (ctx.turnInputConsumed) {
             // No fresh input to extract this turn: ask (deterministically) for the
@@ -59,6 +66,7 @@ export async function collectUntilComplete(node, run, driver, ctx, options) {
         const turn = await (driver.runExtraction
             ? driver.runExtraction(resolved, ctx)
             : driver.runAgentTurn(resolved, ctx));
+        await persistTurnUsageFromTurn(ctx, turn);
         mergeExtractionFromTurn(node, run, turn, ctx);
         const missingAfter = computeMissingFields(node, getCollectData(run.state, node.id));
         const advanced = missingAfter.length < missingBefore.length || schemaSatisfied(node, run.state);

package/dist/flow/extraction.d.ts

@@ -1,6 +1,7 @@
 import type { CollectNode, FlowState } from '../types/flow.js';
 import type { Tool } from '../types/effectTool.js';
 import type { HarnessStreamPart } from '../types/stream.js';
+export declare function resetCollect(state: FlowState, nodeId: string): void;
 export declare function getCollectData(state: FlowState, nodeId: string): Record<string, unknown>;
 export declare function incrementCollectTurns(state: FlowState, nodeId: string): number;
 export declare function computeMissingFields(node: CollectNode, data: Record<string, unknown>): string[];

package/dist/flow/extraction.js

@@ -6,6 +6,10 @@ function collectDataKey(nodeId) {
 function collectTurnsKey(nodeId) {
     return `__collectTurns_${nodeId}`;
 }
+export function resetCollect(state, nodeId) {
+    delete state[collectDataKey(nodeId)];
+    delete state[collectTurnsKey(nodeId)];
+}
 export function getCollectData(state, nodeId) {
     const raw = state[collectDataKey(nodeId)];
     if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {

package/dist/flow/runFlow.js

@@ -1,6 +1,6 @@
-import { getFlowPark } from './collectDigression.js';
+import { popFlowPark, runCollectDigression } from './collectDigression.js';
 import { parseConfirmation } from './confirmParse.js';
-import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
+import { hasPendingUserInput, setPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
 import { isActionNode, isCollectNode, isDecideNode, isReplyNode, } from './nodeKinds.js';
@@ -10,6 +10,7 @@ import { resolveReplyNode } from './nodeBuilders.js';
 import { evaluateReplyControl } from './controlEvaluator.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
+import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
 import { SuspendError } from '../runtime/durable/RunStore.js';
 import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
@@ -68,16 +69,24 @@ async function dispatchConfirmGate(node, run, driver, ctx) {
         return { kind: 'stay' };
     }
     let input = '';
+    let rawInput = '';
     if (hasPendingUserInput(ctx.session)) {
         const signal = await driver.awaitUser(ctx);
+        rawInput = signal.input;
         input = userInputToText(signal.input);
         appendUserMessage(run, signal.input);
     }
     else {
         input = latestUserText(run);
+        rawInput = input;
     }
-    ctx.turnInputConsumed = true;
     const verdict = parseConfirmation(input);
+    if (verdict === 'decline') {
+        setPendingUserInput(ctx.session, rawInput);
+    }
+    else {
+        ctx.turnInputConsumed = true;
+    }
     const branch = verdict === 'affirm'
         ? gate.onConfirm
         : verdict === 'decline'
@@ -136,7 +145,40 @@ async function dispatchNode(node, run, driver, ctx, agent, flow) {
         return normalizeTransition(await node.decide(structured, run.state));
     }
     if (isReplyNode(node)) {
+        // Consume input here ONLY to feed the out-of-band digression check below, and
+        // only for input this turn genuinely fresh to THIS reply — gated on both:
+        //   !turnInputConsumed: a prior node (e.g. a collect) already took the turn's
+        //     input, so a terminal reply like `done` (next→end) must not re-digress on
+        //     the leftover — otherwise it returns `stay`, the main loop's stay+pending
+        //     branch re-dispatches, and completion hangs on a driver clearing the buffer.
+        //   outOfBandControl: with OOB off there is no digression, so the reply must not
+        //     swallow input here — it returns its transition (`next: () => 'stay'`) and the
+        //     main loop's stay-branch owns awaitUser.
+        let freshUserInput = false;
+        if (hasPendingUserInput(ctx.session) && !ctx.turnInputConsumed && ctx.outOfBandControl) {
+            const signal = await driver.awaitUser(ctx);
+            appendUserMessage(run, signal.input);
+            ctx.turnInputConsumed = true;
+            freshUserInput = true;
+        }
+        if (freshUserInput && agent) {
+            const digression = await runCollectDigression({
+                agent,
+                node,
+                activeFlowName: flow.name,
+                run,
+                driver,
+                ctx,
+            });
+            if (digression.kind === 'transition') {
+                return digression.transition;
+            }
+            if (digression.kind === 'answeredThenResume') {
+                return { kind: 'stay' };
+            }
+        }
         const turn = await driver.runAgentTurn(resolveReplyNode(node, run.state), ctx);
+        await persistTurnUsageFromTurn(ctx, turn);
         if (ctx.outOfBandControl) {
             const decision = await evaluateReplyControl({
                 node,
@@ -147,6 +189,23 @@ async function dispatchNode(node, run, driver, ctx, agent, flow) {
             if (decision.kind === 'redispatch') {
                 const signal = await driver.awaitUser(ctx);
                 appendUserMessage(run, signal.input);
+                ctx.turnInputConsumed = true;
+                if (agent) {
+                    const digression = await runCollectDigression({
+                        agent,
+                        node,
+                        activeFlowName: flow.name,
+                        run,
+                        driver,
+                        ctx,
+                    });
+                    if (digression.kind === 'transition') {
+                        return digression.transition;
+                    }
+                    if (digression.kind === 'answeredThenResume') {
+                        return { kind: 'stay' };
+                    }
+                }
                 return dispatchNode(node, run, driver, ctx, agent, flow);
             }
             appendAssistantMessage(run, turn.text);
@@ -232,9 +291,8 @@ export async function runFlow(flow, run, driver, ctx, agent) {
             return runFlow(transition.flow, run, driver, ctx, agent);
         }
         if (transition.kind === 'end') {
-            const park = getFlowPark(run.state);
+            const park = popFlowPark(run.state);
             if (park && agent) {
-                delete run.state.__flowPark;
                 const parkedFlow = agent.flows?.find((candidate) => candidate.name === park.flow);
                 if (parkedFlow) {
                     run.activeFlow = park.flow;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { createFlowTransition, createFlowTransitionWithNode, isFlowTransition, createFlowUpdate, isFlowUpdate, } from './flows/index.js';
 export { SessionManager } from './session/SessionManager.js';
 export type { SessionStore } from './session/SessionStore.js';
+export { StaleWriteError } from './session/SessionStore.js';
 export { MemoryStore } from './session/stores/MemoryStore.js';
 export { reviveSession } from './session/utils.js';
 export { DEFAULT_CHANNEL_POLICIES, applyChannelPolicy, getDefaultChannelPolicy, resolveChannelPolicy, } from './channels/index.js';
@@ -94,6 +95,9 @@ export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
 export { createFsTool } from './tools/fs/createFsTool.js';
 export type { CreateFsToolOptions, GrepHit } from './tools/fs/createFsTool.js';
+export { createShellTool } from './tools/fs/createShellTool.js';
+export type { CreateShellToolOptions } from './tools/fs/createShellTool.js';
+export type { Shell, ShellResult, ShellExecOptions } from './types/shell.js';
 export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
 export type { WiredAgentSkills, SkillWireAgent } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
@@ -106,6 +110,10 @@ export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
 export type { TurnHandle } from './types/stream.js';
 export type { HarnessStreamPart } from './types/stream.js';
+export type { AgentSpan, AgentTrace, SpanKind } from './types/trace.js';
+export { MemoryTraceStore, isTraceStore, type MemoryTraceStoreOptions, type TraceListWindow, type TraceSink, type TraceStore, } from './tracing/index.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, type LangfuseSinkOptions, type OtelTraceSinkOptions, } from './tracing/index.js';
+export { TraceRecorder, runOnce, type TraceRecorderOptions } from './runtime/TraceRecorder.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export type { KuralleMetadata, KuralleDataParts, KuralleUIMessage, } from './ai-sdk/uiMessageStream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';
@@ -116,7 +124,7 @@ export type { ChannelDriver, TextDriver } from './runtime/channels/index.js';
 export type { TurnResult } from './types/channel.js';
 export type { RunContext, ToolContext, ActionContext } from './types/run-context.js';
 export type { AnyTool } from './types/effectTool.js';
-export { createRuntime, Runtime, type HarnessConfig, type RunOptions, } from './runtime/Runtime.js';
+export { createRuntime, Runtime, type HarnessConfig, type RunOptions, type TracingConfig, } from './runtime/Runtime.js';
 export type { RuntimeLike } from './runtime/RuntimeLike.js';
 export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './runtime/userInput.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './runtime/channels/inputBuffer.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createFlowTransition, createFlowTransitionWithNode, isFlowTransition, createFlowUpdate, isFlowUpdate, } from './flows/index.js';
 export { SessionManager } from './session/SessionManager.js';
+export { StaleWriteError } from './session/SessionStore.js';
 export { MemoryStore } from './session/stores/MemoryStore.js';
 export { reviveSession } from './session/utils.js';
 export { DEFAULT_CHANNEL_POLICIES, applyChannelPolicy, getDefaultChannelPolicy, resolveChannelPolicy, } from './channels/index.js';
@@ -53,9 +54,13 @@ export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, }
 export { defineTool } from './types/effectTool.js';
 export { fsErrorCode } from './types/filesystem.js';
 export { createFsTool } from './tools/fs/createFsTool.js';
+export { createShellTool } from './tools/fs/createShellTool.js';
 export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, InlineSkillStore, } from './skills/index.js';
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
+export { MemoryTraceStore, isTraceStore, } from './tracing/index.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, } from './tracing/index.js';
+export { TraceRecorder, runOnce } from './runtime/TraceRecorder.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export { DURABLE_RUNS_KEY } from './runtime/durable/types.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/prompts/PromptBuilder.js

@@ -235,6 +235,13 @@ export class PromptBuilder {
                 priority: LAYER_PRIORITIES.CONVERSATION_SUMMARY,
             });
         }
+        if (memory.openGoalsPrompt) {
+            sections.push({
+                type: 'conversation_summary',
+                content: memory.openGoalsPrompt,
+                priority: LAYER_PRIORITIES.CONVERSATION_SUMMARY,
+            });
+        }
         return sections;
     }
     formatSection(section) {

package/dist/prompts/types.d.ts

@@ -49,6 +49,8 @@ export interface SessionMemory {
         label: string;
         content: string;
     }>;
+    /** Compact open-thread note projected from session.workingMemory.__goals (G5). */
+    openGoalsPrompt?: string;
 }
 export interface AgentDefinition {
     identity: string;

package/dist/runtime/InMemoryRetrievalCache.d.ts

@@ -0,0 +1,25 @@
+import type { KnowledgeRetrievalResult, RetrievalCacheAdapter } from '../types/voice.js';
+/**
+ * Zero-config, in-process session retrieval cache (G6). Keyed by the query
+ * embedding: a lookup returns the cached results of the most-similar recent
+ * query (cosine ≥ threshold, within TTL). LRU-bounded. Needs only the embedder
+ * the KnowledgeProvider already requires — no external dependency. Apps that
+ * want a shared/vector-backed cache can inject their own `RetrievalCacheAdapter`
+ * via the KnowledgeProvider's `cacheFactory` instead.
+ */
+export interface InMemoryRetrievalCacheOptions {
+    maxEntries?: number;
+    ttlMs?: number;
+    similarityThreshold?: number;
+}
+export declare class InMemoryRetrievalCache implements RetrievalCacheAdapter {
+    /** Ordered oldest → newest (LRU front, MRU back). */
+    private entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly threshold;
+    constructor(options?: InMemoryRetrievalCacheOptions);
+    get size(): number;
+    lookup(queryEmbedding: readonly number[], topK?: number): KnowledgeRetrievalResult[];
+    populate(results: KnowledgeRetrievalResult[], queryEmbedding?: readonly number[]): void;
+}

package/dist/runtime/InMemoryRetrievalCache.js

@@ -0,0 +1,59 @@
+function cosineSimilarity(a, b) {
+    const n = Math.min(a.length, b.length);
+    if (n === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+export class InMemoryRetrievalCache {
+    /** Ordered oldest → newest (LRU front, MRU back). */
+    entries = [];
+    maxEntries;
+    ttlMs;
+    threshold;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 256;
+        this.ttlMs = options.ttlMs ?? 300_000;
+        this.threshold = options.similarityThreshold ?? 0.85;
+    }
+    get size() {
+        return this.entries.length;
+    }
+    lookup(queryEmbedding, topK) {
+        const now = Date.now();
+        let best;
+        let bestSim = this.threshold;
+        for (const entry of this.entries) {
+            if (now - entry.at > this.ttlMs)
+                continue;
+            const sim = cosineSimilarity(queryEmbedding, entry.embedding);
+            if (sim >= bestSim) {
+                bestSim = sim;
+                best = entry;
+            }
+        }
+        if (!best)
+            return [];
+        // Touch: move to MRU.
+        this.entries = this.entries.filter((e) => e !== best);
+        this.entries.push(best);
+        const results = best.results;
+        return topK === undefined ? results : results.slice(0, topK);
+    }
+    populate(results, queryEmbedding) {
+        if (!queryEmbedding || queryEmbedding.length === 0 || results.length === 0)
+            return;
+        this.entries.push({ embedding: queryEmbedding, results: [...results], at: Date.now() });
+        while (this.entries.length > this.maxEntries)
+            this.entries.shift();
+    }
+}

package/dist/runtime/KnowledgeProvider.js

@@ -12,6 +12,7 @@
  * The provider holds no mutable state itself — per-session cache state is
  * stored on RunContext.retrievalCache so it survives agent handoffs.
  */
+import { InMemoryRetrievalCache } from './InMemoryRetrievalCache.js';
 export class KnowledgeProvider {
     config;
     retriever;
@@ -21,7 +22,11 @@ export class KnowledgeProvider {
         this.config = options.config;
         this.retriever = options.config.retriever;
         this.embedder = options.config.embedder;
-        this.cacheFactory = options.cacheFactory;
+        // Default to a zero-config in-process cache when an embedder is available
+        // (the cache is keyed by query embedding). Apps can inject their own adapter.
+        this.cacheFactory =
+            options.cacheFactory ??
+                (this.embedder ? () => new InMemoryRetrievalCache(options.config.cache) : undefined);
     }
     /**
      * Create a new session-level cache instance. Called once per session

package/dist/runtime/Runtime.d.ts

@@ -18,6 +18,19 @@ import type { PersistentMemoryStore } from '../memory/blocks/types.js';
 import { type CompactionConfig } from './compaction.js';
 import type { EscalationConfig } from '../escalation/types.js';
 import type { WakeOptions } from '../scheduler/index.js';
+import type { HandoffInputFilter } from './handoffFilters.js';
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+import { type TraceSink, type TraceStore } from '../tracing/TraceStore.js';
+export interface TracingConfig {
+    enabled?: boolean;
+    store?: TraceStore;
+    sinks?: TraceSink[];
+    redact?: (span: AgentSpan) => AgentSpan | null;
+    sampling?: number | ((context: {
+        sessionId: string;
+        input?: unknown;
+    }) => boolean);
+}
 export interface HarnessConfig {
     agents: AgentConfig[];
     defaultAgentId: string;
@@ -56,6 +69,24 @@ export interface HarnessConfig {
      * invokes the handler. Resume with `runtime.resumeFromEscalation()`.
      */
     escalation?: EscalationConfig;
+    /** Default handoff input filter when a route does not define `filter`. */
+    handoffInputFilter?: HandoffInputFilter;
+    /**
+     * Silent handoff (default `true`). A transfer between agents reads as one
+     * continuous assistant: the transfer is a silent control tool call, and the
+     * target is given a continuation directive so it does not greet or
+     * re-introduce itself. Set `false` for an explicit visible transfer (the
+     * target follows its own instructions, e.g. "Bill here").
+     */
+    silentHandoff?: boolean;
+    /**
+     * Structured goal/thread tracking (G5). When enabled, a cheap control-model
+     * pass at turn end patches `session.workingMemory.__goals` and open threads
+     * are projected into the next turn's prompt. Default off — opt-in cost/latency.
+     */
+    trackGoals?: boolean;
+    /** Read-only observability, configured independently from durable session state. */
+    tracing?: TracingConfig;
 }
 export interface RunOptions {
     sessionId?: string;
@@ -75,6 +106,8 @@ export interface RunOptions {
     historyDelta?: ModelMessage[];
     driver?: ChannelDriver;
     signalDelivery?: SignalDelivery;
+    /** Stable key for this inbound user message; duplicate webhook retries are ignored (H2). */
+    idempotencyKey?: string;
     abortSignal?: AbortSignal;
 }
 export declare class Runtime {
@@ -87,10 +120,17 @@ export declare class Runtime {
     private readonly hooks?;
     private readonly activeTurnAborts;
     private readonly sessionMutex;
+    private readonly traceStore?;
+    private readonly traceSinks;
+    private readonly pendingTraceWrites;
     constructor(config: HarnessConfig);
     run(opts: RunOptions): TurnHandle;
+    runOnce(opts: RunOptions): Promise<AgentTrace>;
     stream(opts: RunOptions): TurnHandle;
     getSession(sessionId: string): Promise<Session | null>;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string): Promise<AgentTrace[]>;
+    getTraceStore(): TraceStore | undefined;
     getSessionStore(): SessionStore;
     deleteSession(sessionId: string): Promise<void>;
     abortSession(sessionId: string, reason?: string): void;
@@ -99,6 +139,10 @@ export declare class Runtime {
         reason?: string;
         markedBy?: ConversationOutcomeMarkedBy;
     }): Promise<void>;
+    private shouldTrace;
+    private writeSpan;
+    private settleTraceWrites;
+    private flushTraceSinks;
     /**
      * Compact `runState.messages` when over the configured trigger (or always,
      * when `force`). Persists both the run state and the session message mirror.