@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/tracing/TraceStore.d.ts

@@ -0,0 +1,19 @@
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+export interface TraceListWindow {
+    from?: Date;
+    to?: Date;
+    limit?: number;
+}
+export interface TraceSink {
+    write(span: AgentSpan): void | Promise<void>;
+    flush?(): Promise<void>;
+}
+export interface TraceStore extends TraceSink {
+    putSpan(span: AgentSpan): void | Promise<void>;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    cleanup?(maxAgeMs: number): Promise<number>;
+}
+export declare function isTraceStore(sink: TraceSink): sink is TraceStore;
+export declare function traceFromSpans(spans: AgentSpan[]): AgentTrace | null;
+export declare function cloneSpan(span: AgentSpan): AgentSpan;

package/dist/tracing/TraceStore.js

@@ -0,0 +1,32 @@
+export function isTraceStore(sink) {
+    const value = sink;
+    return typeof value.putSpan === 'function' &&
+        typeof value.getTrace === 'function' &&
+        typeof value.listTraces === 'function';
+}
+export function traceFromSpans(spans) {
+    if (spans.length === 0)
+        return null;
+    const ordered = spans.map(cloneSpan).sort((a, b) => a.startTime - b.startTime);
+    const root = ordered.find((span) => span.kind === 'turn') ?? ordered[0];
+    const tools = ordered.filter((span) => span.kind === 'tool');
+    return {
+        traceId: root.traceId,
+        sessionId: root.attributes.sessionId,
+        spans: ordered,
+        answer: typeof root.attributes.output === 'string' ? root.attributes.output : '',
+        usedTool: tools.length > 0,
+        toolCalls: tools.map((span) => ({
+            name: span.attributes.toolName ?? span.name,
+            args: span.attributes.input ?? null,
+        })),
+        toolResults: tools
+            .filter((span) => span.attributes.output !== undefined)
+            .map((span) => ({ name: span.attributes.toolName ?? span.name, result: span.attributes.output })),
+        startedAt: root.startTime,
+        ...(root.endTime !== undefined ? { endedAt: root.endTime } : {}),
+    };
+}
+export function cloneSpan(span) {
+    return structuredClone(span);
+}

package/dist/tracing/index.d.ts

@@ -0,0 +1,3 @@
+export { MemoryTraceStore, type MemoryTraceStoreOptions } from './MemoryTraceStore.js';
+export { isTraceStore, traceFromSpans, type TraceListWindow, type TraceSink, type TraceStore, } from './TraceStore.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, type LangfuseSinkOptions, type OtelTraceSinkOptions, } from './OtelTraceSink.js';

package/dist/tracing/index.js

@@ -0,0 +1,3 @@
+export { MemoryTraceStore } from './MemoryTraceStore.js';
+export { isTraceStore, traceFromSpans, } from './TraceStore.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, } from './OtelTraceSink.js';

package/dist/tracing/testing.d.ts

@@ -0,0 +1,3 @@
+import type { TraceStore } from './TraceStore.js';
+export type TraceStoreFactory = () => TraceStore | Promise<TraceStore>;
+export declare function runTraceStoreContract(factory: TraceStoreFactory): void;

package/dist/tracing/testing.js

@@ -0,0 +1,45 @@
+/// <reference types="bun-types" />
+import { beforeEach, describe, expect, test } from 'bun:test';
+export function runTraceStoreContract(factory) {
+    describe('TraceStore contract', () => {
+        let store;
+        beforeEach(async () => { store = await factory(); });
+        test('writes spans and reconstructs a JSON-safe trace', async () => {
+            await store.putSpan(span('trace-a', 'session-a', 'root', 10, 'turn'));
+            await store.putSpan(span('trace-a', 'session-a', 'tool', 11, 'tool'));
+            const trace = await store.getTrace('trace-a');
+            expect(trace?.spans.map((entry) => entry.spanId)).toEqual(['root', 'tool']);
+            expect(trace?.sessionId).toBe('session-a');
+            expect(() => JSON.stringify(trace)).not.toThrow();
+        });
+        test('returns null for a missing trace', async () => {
+            expect(await store.getTrace('missing')).toBeNull();
+        });
+        test('lists newest traces for only the requested session and window', async () => {
+            await store.putSpan(span('old', 'session-a', 'old-root', 10, 'turn'));
+            await store.putSpan(span('new', 'session-a', 'new-root', 30, 'turn'));
+            await store.putSpan(span('other', 'session-b', 'other-root', 40, 'turn'));
+            const traces = await store.listTraces('session-a', { from: new Date(20), limit: 1 });
+            expect(traces.map((trace) => trace.traceId)).toEqual(['new']);
+        });
+        test('upserts a span by trace and span id', async () => {
+            const root = span('trace-a', 'session-a', 'root', 10, 'turn');
+            await store.write(root);
+            await store.putSpan({ ...root, endTime: 25 });
+            expect((await store.getTrace('trace-a'))?.spans).toHaveLength(1);
+            expect((await store.getTrace('trace-a'))?.endedAt).toBe(25);
+        });
+    });
+}
+function span(traceId, sessionId, spanId, startTime, kind) {
+    return {
+        traceId,
+        spanId,
+        name: kind,
+        kind,
+        startTime,
+        endTime: startTime + 5,
+        status: 'ok',
+        attributes: { sessionId },
+    };
+}

package/dist/types/agentConfig.d.ts

@@ -50,7 +50,8 @@ export interface AgentConfig {
     /** Pre-turn refinement policies. Default: none. */
     refine?: RefinementCapability[];
     experimental?: {
-        /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
+        /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1).
+         *  Default ON when the agent declares `flows`; OFF for answering-only agents. Override explicitly to opt out. */
         outOfBandControl?: boolean;
     };
     /** Portable workspace filesystem; auto-registers the durable `workspace` tool when set.

package/dist/types/channel.d.ts

@@ -1,4 +1,4 @@
-import type { ToolSet } from 'ai';
+import type { ModelMessage, ToolSet } from 'ai';
 import type { UserInputContent } from '../runtime/userInput.js';
 import type { RunContext } from './run-context.js';
 import type { FlowNode } from './flow.js';
@@ -34,6 +34,14 @@ export interface ChannelDriver {
      *  back to runAgentTurn, whose text the engine then discards. */
     runExtraction?(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
 }
+export interface TurnUsageSnapshot {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+    /** Input tokens on the final model call, i.e. current context-window occupancy. */
+    contextTokens?: number;
+}
 export interface TurnResult {
     text: string;
     toolResults: ToolResultRecord[];
@@ -43,6 +51,11 @@ export interface TurnResult {
     confidence?: number;
     /** Native realtime post-hoc gate: provider audio already played; gate is advisory only. */
     gateScope?: 'advisory';
+    /** AI-SDK tool round-trip messages (assistant tool-call + tool-result) produced this turn,
+     *  so the host loop can persist them to history in free conversation (G18). */
+    toolMessages?: ModelMessage[];
+    /** Real token usage from the AI SDK when the driver captured it. */
+    usage?: TurnUsageSnapshot;
 }
 export type UserSignal = {
     type: 'message';

package/dist/types/effectTool.d.ts

@@ -12,7 +12,13 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
     timeoutMs?: number;
     /** When false, the durable journal always re-executes this tool instead of returning a cached step result — for observation/mutation tools (fs, shell) whose result must be fresh. Default true. */
     replay?: boolean;
+    /** When true, the tool may run concurrently with other parallel-safe tools in the same model turn. */
+    parallelSafe?: boolean;
+    /** Override the auto-derived effect key (`idempotencyKey(logicalRunId, callsite, {name,args})`). Use when args are not a stable identity (e.g. a nonce). */
+    idempotencyKey?: (args: TInput) => string;
     execute: (args: TInput, ctx?: ToolContext) => Promise<TOutput> | AsyncIterable<TOutput>;
+    /** Recover from a thrown error by returning a result the model can act on. Not called for timeouts, aborts, schema violations, or control-flow signals. */
+    onError?: (error: Error, args: TInput) => Promise<TOutput> | TOutput;
 }
 export type AnyTool = Tool<any, any>;
 export { defineTool } from '../tools/effect/defineTool.js';

package/dist/types/flow.d.ts

@@ -1,6 +1,6 @@
 import type { LanguageModel, ModelMessage, ToolSet } from 'ai';
 import type { Instructions } from './agentConfig.js';
-import type { AgentKnowledgeOverrides } from './voice.js';
+import type { AgentKnowledgeOverrides } from './knowledge.js';
 import type { StandardSchemaV1 } from './standard-schema.js';
 import type { ContextStrategy } from './context.js';
 import type { TurnResult } from './channel.js';

package/dist/types/guardrails.d.ts

@@ -11,4 +11,9 @@ export interface Limits {
     maxSteps?: number;
     toolMaxSteps?: number;
     maxOscillations?: number;
+    /**
+     * Ceiling on parallel-safe tools executing at once within one model-emitted batch.
+     * Unset means unbounded — the model's batch size decides how many run concurrently.
+     */
+    maxToolConcurrency?: number;
 }

package/dist/types/hooks.d.ts

@@ -1,11 +1,11 @@
 import type { ConversationOutcomeRecord } from '../outcomes/types.js';
-import type { HarnessStreamPart } from './stream.js';
+import type { StreamPart } from './stream.js';
 import type { RunContext } from './run-context.js';
 import type { Session } from './session.js';
 import type { TurnUsage } from './telemetry.js';
 export interface Hooks {
     onStart?: (ctx: RunContext) => void | Promise<void>;
-    onStreamPart?: (ctx: RunContext, part: HarnessStreamPart) => void | Promise<void>;
+    onStreamPart?: (ctx: RunContext, part: StreamPart) => void | Promise<void>;
     onEnd?: (ctx: RunContext) => void | Promise<void>;
     onConversationEnd?: (args: {
         session: Session;

package/dist/types/index.d.ts

@@ -1,15 +1,25 @@
-export * from './selection.js';
-export * from './telemetry.js';
-export * from './processors.js';
-export * from './agentConfig.js';
-export * from './filesystem.js';
-export * from './skills.js';
-export * from './flow.js';
-export * from './session.js';
-export * from './tool.js';
-export * from './effectTool.js';
-export * from './voice.js';
-export * from './runtime.js';
-export type * from '../audit/types.js';
-export type * from '../outcomes/index.js';
-export type * from '../channels/index.js';
+export type { ChoiceOption, ResolvedSelection } from './selection.js';
+export type { TurnUsage, TraceStreamEvent, TracingConfig, Span, SpanEvent, MetricsConfig, ObservabilityMetrics, Metrics, SessionTelemetry, SessionEndMetadata, SessionTrace, } from './telemetry.js';
+export type { ProcessorAction, FlowPromptContext, ProcessorContext, InputProcessorResult, OutputProcessorResult, InputProcessor, OutputProcessor, HandoffInputData, HandoffInputResult, HandoffInputFilter, AgentRoute, RouteCondition, AgentCapabilityDescriptor, } from './processors.js';
+export { defineAgent } from './agentConfig.js';
+export type { AgentWorkspaceConfig, Instructions, AgentConfig } from './agentConfig.js';
+export { fsErrorCode } from './filesystem.js';
+export type { FileSystemEntryType, BufferEncoding, FileContent, FsStat, FileSystemDirent, MkdirOptions, RmOptions, CpOptions, FileSystem, ReadFileOptions, WriteFileOptions, FileEntry, DirectoryEntry, SymlinkEntry, LazyFileEntry, FsEntry, FileInit, LazyFileProvider, InitialFiles, FsError, } from './filesystem.js';
+export type { SkillMeta, SkillLike, SkillStoreLike, SkillSource } from './skills.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './flow.js';
+export type { FlowState, Flow, FlowNode, NodeGrounding, Transition, ReplyNode, CollectNode, ActionNode, ConfirmGate, DecideNode, } from './flow.js';
+export type { ChannelId, GoalStatus, TrackedGoal, WorkingMemory, AgentContext, Session, SessionMetadata, AgentState, HandoffRecord, ToolCallRecord, RunContext, } from './session.js';
+export type { ToolSet, ToolPolicy, EnforcementContext, EnforcementResult, EnforcementRule, InjectionPriority, InjectionLevel, Injection, } from './tool.js';
+export { defineTool } from './effectTool.js';
+export type { Tool, AnyTool } from './effectTool.js';
+export type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrieverAdapter, KnowledgeEmbedderAdapter, SourceRef, KnowledgeRetrievalResult, KnowledgeChunk, RetrievalCacheAdapter, HttpCallbackConfig, StreamCallbackPayload, StreamCallbackSink, StreamCallbackConfig, } from './knowledge.js';
+export { PART_CHANNEL } from './stream.js';
+export type { StreamChannel, StreamPartBase, TextStartPayload, TextDeltaPayload, TextEndPayload, TextCancelPayload, ToolCallPayload, ToolResultPayload, FlowEnterPayload, FlowEndPayload, NodeEnterPayload, NodeExitPayload, FlowTransitionPayload, HandoffPayload, InterruptedPayload, PausedPayload, ConversationOutcomePayload, InteractivePayload, TurnEndPayload, PipelineValidationBlockPayload, SafetyBlockedPayload, WakePayload, EscalationPayload, ContextCompactedPayload, CompactionSkippedPayload, ContextOverflowRecoveredPayload, ErrorPayload, CustomPayload, DonePayload, KnowledgeCacheHitPayload, KnowledgeCacheMissPayload, KnowledgeSearchPayload, KnowledgeQualityCheckPayload, KnowledgeReformulationPayload, StreamPart, TurnHandle, } from './stream.js';
+export { isAbortSignal } from './runtime.js';
+export type { RefinementStageResult, ValidationStageResult, Hook, StopConditionResult, StopCondition, StreamOptions, AbortOptions, InterruptionEvent, CancellationReason, } from './runtime.js';
+export type { SpanKind, AgentSpan, AgentTrace } from './trace.js';
+export type { AuditEntryBase, AuditEscalationReason, ConversationAuditEntry, ConversationAuditLog, AuditEntryType, AuditListOptions, AuditReplayOptions, AuditConfig, } from '../audit/types.js';
+export { toConversationOutcomeStreamPart, buildMarkOutcomeTool, OUTCOMES_MARK_TOOL_NAME } from '../outcomes/index.js';
+export type { ConversationOutcome, ConversationOutcomeMarkedBy, ConversationOutcomeRecord, CsatRecord, MarkOutcomeToolResult, } from '../outcomes/index.js';
+export { DEFAULT_CHANNEL_POLICIES, getDefaultChannelPolicy, applyChannelPolicy, resolveChannelPolicy } from '../channels/index.js';
+export type { ChannelPolicy, ChannelPolicyChange, ChannelPolicyResult } from '../channels/index.js';

package/dist/types/index.js

@@ -1,12 +1,8 @@
-export * from './selection.js';
-export * from './telemetry.js';
-export * from './processors.js';
-export * from './agentConfig.js';
-export * from './filesystem.js';
-export * from './skills.js';
-export * from './flow.js';
-export * from './session.js';
-export * from './tool.js';
-export * from './effectTool.js';
-export * from './voice.js';
-export * from './runtime.js';
+export { defineAgent } from './agentConfig.js';
+export { fsErrorCode } from './filesystem.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './flow.js';
+export { defineTool } from './effectTool.js';
+export { PART_CHANNEL } from './stream.js';
+export { isAbortSignal } from './runtime.js';
+export { toConversationOutcomeStreamPart, buildMarkOutcomeTool, OUTCOMES_MARK_TOOL_NAME } from '../outcomes/index.js';
+export { DEFAULT_CHANNEL_POLICIES, getDefaultChannelPolicy, applyChannelPolicy, resolveChannelPolicy } from '../channels/index.js';

package/dist/types/knowledge.d.ts

@@ -0,0 +1,213 @@
+import type { StreamPart } from './stream.js';
+/**
+ * Runtime-level knowledge configuration. Configured once on the Runtime,
+ * inherited by all agents. Per-agent overrides via `AgentKnowledgeOverrides`
+ * can only reduce capabilities (e.g., disable compiled knowledge, restrict
+ * topK, filter by metadata).
+ */
+export interface KnowledgeProviderConfig {
+    /**
+     * Retriever for hybrid search (Layer 3). Any object implementing the
+     * Retriever interface from `@kuralle-agents/rag`. When not provided,
+     * only compiled knowledge and cache are available.
+     */
+    retriever?: KnowledgeRetrieverAdapter;
+    /**
+     * Embedder for cache similarity lookup. Required when `retriever` is
+     * provided (needed for cache population and query embedding).
+     */
+    embedder?: KnowledgeEmbedderAdapter;
+    /**
+     * Pre-compiled knowledge content (Layer 1). Injected into the system
+     * prompt every turn with zero search latency. Produced offline by
+     * KnowledgeCompiler.
+     */
+    compiled?: string;
+    /**
+     * Retrieval cache configuration. When omitted, a default configuration
+     * is used (maxEntries: 256, ttlMs: 300000, similarityThreshold: 0.85).
+     */
+    cache?: {
+        /** Maximum entries in the LRU cache. Default: 256. */
+        maxEntries?: number;
+        /** Cache entry TTL in milliseconds. Default: 300000 (5 minutes). */
+        ttlMs?: number;
+        /** Minimum cosine similarity for a cache hit. Default: 0.85. */
+        similarityThreshold?: number;
+    };
+    /**
+     * Predictive pre-fetch configuration. When enabled, the system
+     * predicts follow-up topics from the conversation window and
+     * pre-fetches relevant content into the session cache.
+     */
+    prefetch?: {
+        /** Enable predictive pre-fetching. Default: false. */
+        enabled?: boolean;
+        /** Number of keywords to extract per prediction. Default: 3. */
+        maxKeywords?: number;
+        /** Number of recent messages to analyze. Default: 5. */
+        conversationWindow?: number;
+    };
+    /**
+     * Default retrieval options applied to all agents unless overridden.
+     */
+    defaults?: {
+        /** Maximum results from Layer 3 search. Default: 5. */
+        topK?: number;
+        /** Maximum tokens for retrieval context in the system prompt. Default: 2000. */
+        maxOutputTokens?: number;
+        /** Whether to include embedding vectors in results (for cache writeback). Default: true. */
+        includeEmbeddings?: boolean;
+    };
+    /**
+     * Retrieval quality checking configuration. When configured, retrieval
+     * results are evaluated using score distribution (sub-millisecond).
+     * For text agents, low-quality results trigger inline reformulation.
+     * For voice agents, low-quality results trigger background reformulation
+     * via the pre-fetcher.
+     */
+    qualityCheck?: {
+        /** Minimum top-result score to consider quality "high". Default: 0.5. */
+        highThreshold?: number;
+        /** Minimum top-result score to consider quality "medium". Default: 0.3. */
+        mediumThreshold?: number;
+        /**
+         * Query reformulator callback. When provided and quality is "low",
+         * the system rewrites the query and re-retrieves.
+         */
+        reformulate?: (query: string, results: KnowledgeRetrievalResult[]) => Promise<string>;
+    };
+    /**
+     * How retrieved source references should be rendered into the model prompt.
+     * Defaults to 'footnotes'.
+     */
+    renderCitations?: 'inline' | 'footnotes' | 'off';
+}
+/**
+ * Per-agent knowledge overrides. Can only reduce capabilities — cannot
+ * add a retriever that doesn't exist at the Runtime level.
+ */
+export interface AgentKnowledgeOverrides {
+    /** Disable compiled knowledge injection for this agent. */
+    compiledEnabled?: boolean;
+    /** Disable retrieval tool for this agent. */
+    toolEnabled?: boolean;
+    /** Override topK (must be <= Runtime default). */
+    topK?: number;
+    /** Override max output tokens (must be <= Runtime default). */
+    maxOutputTokens?: number;
+    /** Metadata filter restricting which documents this agent can access. */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Adapter interface for retrievers used by KnowledgeProvider.
+ * Mirrors the Retriever interface from `@kuralle-agents/rag` without
+ * creating a dependency from core → rag.
+ */
+export interface KnowledgeRetrieverAdapter {
+    retrieve(query: string, options?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        queryEmbedding?: readonly number[];
+        includeEmbeddings?: boolean;
+    }): Promise<KnowledgeRetrievalResult[]>;
+}
+/**
+ * Adapter interface for embedders used by KnowledgeProvider.
+ * Mirrors the Embedder interface from `@kuralle-agents/rag`.
+ */
+export interface KnowledgeEmbedderAdapter {
+    embed(text: string): Promise<readonly number[]>;
+}
+export interface SourceRef {
+    readonly id: string;
+    readonly title?: string;
+    readonly url?: string;
+    readonly lastModified?: string;
+    readonly score?: number;
+}
+/**
+ * A single result from knowledge retrieval, used across the pipeline.
+ */
+export interface KnowledgeRetrievalResult {
+    id: string;
+    text: string;
+    sourceId: string;
+    score?: number;
+    relevanceScore?: number;
+    snippet?: string;
+    metadata?: Record<string, unknown>;
+    embedding?: readonly number[];
+}
+export type KnowledgeChunk = KnowledgeRetrievalResult;
+/**
+ * Interface for the session-level retrieval cache. Implemented by
+ * `RetrievalCache` from `@kuralle-agents/rag`. Defined here so
+ * `RunContext.retrievalCache` can be properly typed without core
+ * depending on rag.
+ */
+export interface RetrievalCacheAdapter {
+    lookup(queryEmbedding: readonly number[], topK?: number): KnowledgeRetrievalResult[];
+    populate(results: KnowledgeRetrievalResult[], queryEmbedding?: readonly number[]): void;
+    readonly size: number;
+}
+export interface HttpCallbackConfig {
+    url: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    allowList?: string[];
+    denyList?: string[];
+    includeFullText?: boolean;
+    timeoutMs?: number;
+}
+export interface StreamCallbackPayload {
+    sessionId: string;
+    agentId: string;
+    timestamp: string;
+    part: StreamPart;
+    fullText?: string;
+}
+export interface StreamCallbackSink {
+    name?: string;
+    write: (payload: StreamCallbackPayload) => Promise<void>;
+    close?: () => Promise<void>;
+}
+export interface StreamCallbackConfig {
+    sinks?: StreamCallbackSink[];
+    /**
+     * Events to emit when no explicit allowList is provided.
+     * - message: emit terminal events plus tool/transition events per toggles
+     * - all: emit every runtime event
+     * Default: message
+     */
+    eventMode?: 'message' | 'all';
+    /**
+     * Emit streaming text-delta events.
+     * Default: false (final text is emitted on terminal events via fullText)
+     */
+    emitTextDeltas?: boolean;
+    /**
+     * Emit tool lifecycle events (tool-call/tool-result) in message mode.
+     * Default: true
+     */
+    emitToolEvents?: boolean;
+    /**
+     * Emit transition lifecycle events (flow-transition/handoff) in message mode.
+     * Default: true
+     */
+    emitTransitionEvents?: boolean;
+    /**
+     * Attach accumulated assistant text as fullText on terminal events.
+     * Default: true
+     */
+    emitFinalText?: boolean;
+    allowList?: string[];
+    denyList?: string[];
+    includeFullText?: boolean;
+    maxQueueSize?: number;
+    dropPolicy?: 'drop_oldest' | 'drop_newest';
+    logDroppedEvents?: boolean;
+    /** If true, wait for sink queue drain when a stream call ends. Default: false. */
+    flushOnEnd?: boolean;
+    flushTimeoutMs?: number;
+}

package/dist/types/processors.d.ts

@@ -70,61 +70,3 @@ export interface AgentCapabilityDescriptor {
     handlesIntents?: string[];
     doesNotHandle?: string[];
 }
-export type AgentStreamPart = {
-    type: 'text-start';
-    id: string;
-} | {
-    type: 'text-delta';
-    id: string;
-    delta: string;
-} | {
-    type: 'text-end';
-    id: string;
-} | {
-    type: 'text-cancel';
-    id: string;
-    reason: string;
-} | {
-    type: 'tool-call';
-    toolName: string;
-    args: unknown;
-    toolCallId?: string;
-} | {
-    type: 'tool-result';
-    toolName: string;
-    result: unknown;
-    toolCallId?: string;
-} | {
-    type: 'tool-error';
-    toolName: string;
-    error: string;
-    toolCallId?: string;
-} | {
-    type: 'handoff';
-    targetAgent: string;
-    reason?: string;
-} | {
-    type: 'node-enter';
-    nodeName: string;
-} | {
-    type: 'node-exit';
-    nodeName: string;
-} | {
-    type: 'flow-transition';
-    from: string;
-    to: string;
-} | {
-    type: 'flow-end';
-    reason: string;
-} | {
-    type: 'custom';
-    name: string;
-    data: unknown;
-    timestamp?: Date;
-} | {
-    type: 'turn-end';
-    metadata?: Record<string, unknown>;
-} | {
-    type: 'error';
-    error: string;
-};

package/dist/types/run-context.d.ts

@@ -3,14 +3,14 @@ import type { Session } from './session.js';
 import type { InputProcessor, OutputProcessor } from './processors.js';
 import type { RunState } from '../runtime/durable/types.js';
 import type { RunStore } from '../runtime/durable/RunStore.js';
-import type { HarnessStreamPart } from './stream.js';
+import type { StreamPart } from './stream.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
 import type { FileSystem } from './filesystem.js';
 import type { Instructions } from './agentConfig.js';
-import type { AgentKnowledgeOverrides, SourceRef } from './voice.js';
+import type { AgentKnowledgeOverrides, SourceRef, RetrievalCacheAdapter } from './knowledge.js';
 export interface GatherScope {
     query?: string;
     knowledge?: AgentKnowledgeOverrides & {
@@ -45,16 +45,12 @@ export interface MemoryService {
     preload?(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
     ingest?(ctx: RunContext): Promise<void>;
 }
-export interface HookRunner {
-    onStreamPart?(ctx: RunContext, part: HarnessStreamPart): void | Promise<void>;
-}
 export interface RunContext {
     session: Session;
     runState: RunState;
     runStore: RunStore;
-    emit: (part: HarnessStreamPart) => void;
+    emit: (part: StreamPart) => void;
     toolExecutor: EffectToolExecutor;
-    hookRunner: HookRunner;
     model: LanguageModel;
     /** Control-path model (routing, decide, extraction) at temperature 0. */
     controlModel: LanguageModel;
@@ -80,6 +76,13 @@ export interface RunContext {
     turnInputConsumed?: boolean;
     /** Citations from the latest gather-phase retrieval on this turn. */
     lastRetrievalCitations?: SourceRef[];
+    /**
+     * Session retrieval cache (G6): created once per run by the KnowledgeProvider,
+     * persists across in-session agent handoffs (this RunContext survives the
+     * handoff branch). Keyed by query embedding; RAG-only, undefined without a
+     * configured knowledge provider + embedder.
+     */
+    retrievalCache?: RetrievalCacheAdapter;
     /** Agent base layer (ADR 0001), set when entering a flow. `baseInstructions`
      *  is composed as a prefix into every node turn's system prompt (persona /
      *  safety / grounding floor); `globalTools` are safe tools made model-visible
@@ -98,6 +101,10 @@ export interface RunContext {
         toolCallId?: string;
         def?: AnyTool;
         toolCtx?: ToolContext;
+        /** Pre-reserved callsite ordinal for parallel-safe tool batches (G9). */
+        callsite?: string;
+        /** Pre-reserved journal index for parallel-safe tool batches (G9). */
+        index?: number;
     }): Promise<unknown>;
     approve(req: {
         title: string;
@@ -116,6 +123,8 @@ export interface RunContext {
      *  a flow's durable callsites are anchored to the flow — identical on fresh entry
      *  (after an answering turn) and on resume (where that turn does not re-run). */
     resetCallsites(): void;
+    /** Reserve N contiguous effect callsite ordinals for parallel-safe tool batches (G9). */
+    reserveCallsites(count: number): string[];
 }
 export type ActionContext = Pick<RunContext, 'tool' | 'approve' | 'signal' | 'now' | 'uuid' | 'emit' | 'fs'>;
 export type ToolContext = Pick<RunContext, 'session' | 'runState' | 'tool' | 'now' | 'uuid' | 'emit' | 'fs' | 'abortSignal'>;