@kuralle-agents/core 0.12.0 → 0.14.0

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.d.ts

@@ -12,7 +12,8 @@
  * The provider holds no mutable state itself — per-session cache state is
  * stored on RunContext.retrievalCache so it survives agent handoffs.
  */
-import type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrievalResult, HarnessStreamPart, RetrievalCacheAdapter } from '../types/index.js';
+import type { KnowledgeProviderConfig, AgentKnowledgeOverrides, KnowledgeRetrievalResult, RetrievalCacheAdapter } from '../types/index.js';
+import type { StreamPart } from '../types/stream.js';
 export type { RetrievalCacheAdapter } from '../types/index.js';
 interface ResolvedKnowledgeConfig {
     compiledEnabled: boolean;
@@ -72,7 +73,7 @@ export declare class KnowledgeProvider {
      */
     retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
         results: KnowledgeRetrievalResult[];
-        events: HarnessStreamPart[];
+        events: StreamPart[];
     }>;
     /**
      * Run quality check on retrieval results and optionally reformulate.

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
@@ -87,24 +92,33 @@ export class KnowledgeProvider {
             const cacheLatency = Date.now() - cacheStart;
             if (cached.length > 0) {
                 events.push({
+                    channel: 'internal',
                     type: 'knowledge-cache-hit',
-                    query,
-                    resultCount: cached.length,
-                    latencyMs: cacheLatency,
+                    payload: {
+                        query,
+                        resultCount: cached.length,
+                        latencyMs: cacheLatency,
+                    },
                 });
                 events.push({
+                    channel: 'internal',
                     type: 'knowledge-search',
-                    query,
-                    resultCount: cached.length,
-                    latencyMs: cacheLatency,
-                    layer: 'cache',
+                    payload: {
+                        query,
+                        resultCount: cached.length,
+                        latencyMs: cacheLatency,
+                        layer: 'cache',
+                    },
                 });
                 return { results: cached, events };
             }
             events.push({
+                channel: 'internal',
                 type: 'knowledge-cache-miss',
-                query,
-                latencyMs: cacheLatency,
+                payload: {
+                    query,
+                    latencyMs: cacheLatency,
+                },
             });
             // Layer 3: Hybrid search (cache miss)
             const searchStart = Date.now();
@@ -116,11 +130,14 @@ export class KnowledgeProvider {
             });
             const searchLatency = Date.now() - searchStart;
             events.push({
+                channel: 'internal',
                 type: 'knowledge-search',
-                query,
-                resultCount: results.length,
-                latencyMs: searchLatency,
-                layer: 'hybrid',
+                payload: {
+                    query,
+                    resultCount: results.length,
+                    latencyMs: searchLatency,
+                    layer: 'hybrid',
+                },
             });
             // Quality check + optional reformulation
             results = await this.runQualityCheck(query, results, events, isVoice, resolved);
@@ -139,11 +156,14 @@ export class KnowledgeProvider {
         });
         const searchLatency = Date.now() - searchStart;
         events.push({
+            channel: 'internal',
             type: 'knowledge-search',
-            query,
-            resultCount: results.length,
-            latencyMs: searchLatency,
-            layer: 'hybrid',
+            payload: {
+                query,
+                resultCount: results.length,
+                latencyMs: searchLatency,
+                layer: 'hybrid',
+            },
         });
         // Quality check + optional reformulation
         results = await this.runQualityCheck(query, results, events, isVoice, resolved);
@@ -177,12 +197,15 @@ export class KnowledgeProvider {
             quality = 'low';
         }
         events.push({
+            channel: 'internal',
             type: 'knowledge-quality-check',
-            query,
-            quality,
-            topScore,
-            avgScore,
-            coverageEstimate,
+            payload: {
+                query,
+                quality,
+                topScore,
+                avgScore,
+                coverageEstimate,
+            },
         });
         // Only reformulate on low quality with a reformulate callback
         if (quality !== 'low' || !qc.reformulate)
@@ -190,11 +213,14 @@ export class KnowledgeProvider {
         if (isVoice) {
             // Voice: signal background reformulation, don't block
             events.push({
+                channel: 'internal',
                 type: 'knowledge-reformulation',
-                originalQuery: query,
-                reformulatedQuery: '',
-                trigger: 'background',
-                latencyMs: 0,
+                payload: {
+                    originalQuery: query,
+                    reformulatedQuery: '',
+                    trigger: 'background',
+                    latencyMs: 0,
+                },
             });
             return results;
         }
@@ -204,11 +230,14 @@ export class KnowledgeProvider {
             const reformulatedQuery = await qc.reformulate(query, results);
             const reformulateLatency = Date.now() - reformulateStart;
             events.push({
+                channel: 'internal',
                 type: 'knowledge-reformulation',
-                originalQuery: query,
-                reformulatedQuery,
-                trigger: 'inline',
-                latencyMs: reformulateLatency,
+                payload: {
+                    originalQuery: query,
+                    reformulatedQuery,
+                    trigger: 'inline',
+                    latencyMs: reformulateLatency,
+                },
             });
             // Re-retrieve with reformulated query (one attempt, no recursion)
             if (this.retriever) {

package/dist/runtime/Runtime.d.ts

@@ -12,12 +12,25 @@ import type { SignalDelivery } from './durable/types.js';
 import type { ResolvedSelection } from '../types/selection.js';
 import type { ConversationOutcome, ConversationOutcomeMarkedBy } from '../outcomes/types.js';
 import type { classifyHostTarget, selectHostTarget } from './select.js';
-import type { KnowledgeProviderConfig } from '../types/voice.js';
+import type { KnowledgeProviderConfig } from '../types/knowledge.js';
 import type { MemoryService as V1MemoryService } from '../memory/MemoryService.js';
 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,19 @@ 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;
+    /** The agent used when neither the caller nor persisted state names one. */
+    getDefaultAgentId(): string;
     getSessionStore(): SessionStore;
     deleteSession(sessionId: string): Promise<void>;
     abortSession(sessionId: string, reason?: string): void;
@@ -99,6 +141,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.