@kuralle-agents/core 0.12.0 → 0.13.0

package/dist/runtime/Runtime.js

@@ -7,10 +7,16 @@ import { createEventBus, createTurnHandle } from '../events/TurnHandle.js';
 import { CoreToolExecutor } from '../tools/effect/index.js';
 import { buildAgentToolSurface } from './buildAgentToolSurface.js';
 import { hostLoop } from './hostLoop.js';
+import { isHandoffOscillating } from './handoffOscillation.js';
+import { applyHandoffContinuation } from './handoffContinuation.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
 import { adaptHostSelect } from './hostClassifyAdapter.js';
 import { openRun, sessionDerivedRunId } from './openRun.js';
+function resolveOutOfBandControl(agent) {
+    const hasFlows = (agent.flows?.length ?? 0) > 0;
+    return agent.experimental?.outOfBandControl ?? hasFlows;
+}
 import { closeRun } from './closeRun.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
 import { loadRecordedSteps } from './durable/replay.js';
@@ -19,8 +25,15 @@ import { resolveAgentPolicies } from './policies/resolvePolicies.js';
 import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, } from './grounding/index.js';
 import { SessionMutex } from './SessionMutex.js';
 import { compactMessages } from './compaction.js';
+import { readLastPromptTokens, readCumulativeUsage, computeTurnTraceUsage } from './turnTokenUsage.js';
 import { isContextOverflowError, recoverFromContextOverflow } from './contextOverflow.js';
+import { projectGoalsPromptFromState, updateGoalsFromTurn } from './goals.js';
 import { buildEscalationRequest, recordEscalationOutcome, ESCALATION_NOTIFIED_KEY, } from '../escalation/escalation.js';
+import { runOnce as recordRunOnce } from './TraceRecorder.js';
+import { TraceRecorder } from './TraceRecorder.js';
+import { MemoryTraceStore } from '../tracing/MemoryTraceStore.js';
+import { mutateSessionWithRetry } from '../session/utils.js';
+import { isTraceStore } from '../tracing/TraceStore.js';
 export class Runtime {
     config;
     agentsById;
@@ -31,6 +44,9 @@ export class Runtime {
     hooks;
     activeTurnAborts = new Map();
     sessionMutex = new SessionMutex();
+    traceStore;
+    traceSinks;
+    pendingTraceWrites = new Set();
     constructor(config) {
         this.config = config;
         this.agentsById = indexAgents(config.agents);
@@ -39,12 +55,27 @@ export class Runtime {
         this.maxHandoffs = config.maxHandoffs ?? 5;
         this.terminalHandoffTargets = new Set(config.terminalHandoffTargets ?? ['human']);
         this.hooks = config.hooks;
+        const configuredSinks = config.tracing?.sinks ?? [];
+        const configuredStore = config.tracing?.store ?? configuredSinks.find(isTraceStore);
+        this.traceStore = config.tracing?.enabled === false
+            ? undefined
+            : configuredStore ?? new MemoryTraceStore();
+        this.traceSinks = this.traceStore
+            ? [this.traceStore, ...configuredSinks.filter((sink) => sink !== this.traceStore)]
+            : [];
     }
     run(opts) {
         if (opts.wake && opts.input !== undefined) {
             throw new Error('RunOptions.wake and RunOptions.input are mutually exclusive');
         }
         const sessionId = opts.sessionId || randomUUID();
+        const recorder = this.shouldTrace(sessionId, opts.input)
+            ? new TraceRecorder({
+                sessionId,
+                input: opts.input,
+                onSpan: (span) => this.writeSpan(span),
+            })
+            : undefined;
         const bus = createEventBus();
         const abortController = new AbortController();
         this.activeTurnAborts.set(sessionId, abortController);
@@ -54,6 +85,9 @@ export class Runtime {
         const execute = async () => {
             let runCtx;
             const emit = (part) => {
+                recorder?.record(part);
+                if (part.type === 'done')
+                    this.flushTraceSinks();
                 bus.emit(part);
                 void this.hooks?.onStreamPart?.(runCtx, part);
             };
@@ -67,6 +101,7 @@ export class Runtime {
                 seedMessages: opts.seedMessages,
                 historyDelta: opts.historyDelta,
                 signalDelivery: opts.signalDelivery,
+                idempotencyKey: opts.idempotencyKey,
                 transcriptionModel: this.config.transcriptionModel,
                 defaultAgentId: this.config.defaultAgentId,
                 sessionStore: this.sessionStore,
@@ -93,6 +128,10 @@ export class Runtime {
             });
             const steps = await loadRecordedSteps(opened.runStore, opened.runState.runId);
             const freshRunState = (await opened.runStore.getRunState(opened.runState.runId)) ?? opened.runState;
+            // Snapshot cumulative token usage as this turn opens, so the trace can report
+            // THIS turn's consumption (delta), not the running session total (see the
+            // per-turn scope requirement in the observability guide).
+            const usageBaseline = readCumulativeUsage(freshRunState.state);
             const model = opened.agent.model ?? this.defaultModel;
             if (!model) {
                 throw new Error('Runtime requires agent.model or config.defaultModel');
@@ -120,12 +159,16 @@ export class Runtime {
                     : undefined,
                 fs: openingSurface.resolvedWorkspace?.fs,
             });
+            // Session retrieval cache (G6): created once per run, persists across
+            // in-session handoffs (runCtx survives the handoff branch). RAG-only —
+            // a knowledge-less runtime leaves it undefined.
+            runCtx.retrievalCache = knowledgeProvider?.createSessionCache();
             // Agent base layer (ADR 0001): composed into every node turn by the drivers.
             runCtx.baseInstructions = opened.agent.instructions;
             runCtx.globalTools = openingSurface.globalTools;
-            runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
+            runCtx.outOfBandControl = resolveOutOfBandControl(opened.agent);
             runCtx.skillPrompt = openingSurface.skillPrompt;
-            runCtx.workingMemoryPrompt = openingSurface.workingMemoryPrompt;
+            runCtx.workingMemoryPrompt = appendGoalsPrompt(openingSurface.workingMemoryPrompt, opened.session.workingMemory);
             runCtx.workingMemoryTools = openingSurface.workingMemoryTools;
             await this.hooks?.onStart?.(runCtx);
             if (opts.wake) {
@@ -169,6 +212,14 @@ export class Runtime {
                         if (handoffCount > this.maxHandoffs) {
                             throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
                         }
+                        // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
+                        // can't catch A↔B oscillation spread across turns). This is a bound
+                        // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
+                        // check above; oscillation only fires for same-pair accumulation in the
+                        // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
+                        if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
+                            throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
+                        }
                         const target = this.agentsById.get(loopResult.to);
                         if (!target) {
                             throw new Error(`Handoff target agent not found: ${loopResult.to}`);
@@ -179,6 +230,20 @@ export class Runtime {
                             reason: loopResult.reason ?? 'handoff',
                             timestamp: new Date(),
                         });
+                        const handoffTarget = loopResult.to;
+                        const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
+                        const inputFilter = routeFilter ?? this.config.handoffInputFilter;
+                        if (inputFilter) {
+                            const filtered = await inputFilter({
+                                messages: runCtx.runState.messages,
+                                workingMemory: runCtx.session.workingMemory,
+                                sourceAgentId: runCtx.runState.activeAgentId,
+                                targetAgentId: handoffTarget,
+                                reason: loopResult.reason,
+                            });
+                            runCtx.runState.messages = filtered.messages;
+                            runCtx.session.workingMemory = filtered.workingMemory;
+                        }
                         runCtx.runState.activeAgentId = loopResult.to;
                         activeAgent = target;
                         const targetSurface = await buildAgentToolSurface(target, opened.session, {
@@ -191,12 +256,40 @@ export class Runtime {
                             : undefined;
                         runCtx.globalTools = targetSurface.globalTools;
                         runCtx.skillPrompt = targetSurface.skillPrompt;
-                        runCtx.workingMemoryPrompt = targetSurface.workingMemoryPrompt;
+                        runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
                         runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
                         runCtx.fs = targetSurface.resolvedWorkspace?.fs;
                         runCtx.memoryService = this.config.memoryService
                             ? buildMemoryService(this.config.memoryService, target)
                             : undefined;
+                        const targetPolicies = resolveAgentPolicies(target);
+                        const targetModel = target.model ?? this.defaultModel;
+                        if (!targetModel) {
+                            throw new Error('Runtime requires agent.model or config.defaultModel');
+                        }
+                        runCtx.baseInstructions =
+                            (this.config.silentHandoff ?? true)
+                                ? applyHandoffContinuation(target.instructions)
+                                : target.instructions;
+                        runCtx.model = targetModel;
+                        runCtx.controlModel = target.controlModel ?? targetModel;
+                        runCtx.outOfBandControl = resolveOutOfBandControl(target);
+                        runCtx.limits = targetPolicies.limits;
+                        runCtx.refinementPolicies = targetPolicies.refinementPolicies;
+                        runCtx.validationPolicies = targetPolicies.validationPolicies;
+                        runCtx.inputProcessors = targetPolicies.inputProcessors;
+                        runCtx.outputProcessors = targetPolicies.outputProcessors;
+                        runCtx.toolExecutor = new CoreToolExecutor({
+                            tools: targetSurface.executorTools,
+                            enforcer: targetPolicies.enforcer,
+                            agentId: target.id,
+                            onInterim: (message) => {
+                                const id = crypto.randomUUID();
+                                emit({ type: 'text-start', id });
+                                emit({ type: 'text-delta', id, delta: message });
+                                emit({ type: 'text-end', id });
+                            },
+                        });
                         await runCtx.runStore.putRunState(runCtx.runState);
                         continue;
                     }
@@ -254,10 +347,19 @@ export class Runtime {
                     outcomeReason: loopResult.kind === 'ended' ? loopResult.reason : undefined,
                     memoryIngest: async () => {
                         await runMemoryIngest(runCtx);
+                        if (this.config.trackGoals) {
+                            const controlModel = this.agentsById.get(runCtx.runState.activeAgentId)?.controlModel ??
+                                runCtx.controlModel;
+                            await updateGoalsFromTurn(runCtx, controlModel);
+                        }
                     },
                 });
                 await this.hooks?.onEnd?.(runCtx);
-                emit({ type: 'done', sessionId: opened.session.id });
+                emit({
+                    type: 'done',
+                    sessionId: opened.session.id,
+                    usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
+                });
             }
             return { text: collectAssistantText(runCtx.runState.messages), toolResults: [] };
         };
@@ -276,12 +378,26 @@ export class Runtime {
             run: gated,
         });
     }
+    runOnce(opts) {
+        return recordRunOnce(this, opts);
+    }
     stream(opts) {
         return this.run(opts);
     }
     async getSession(sessionId) {
         return this.sessionStore.get(sessionId);
     }
+    async getTrace(traceId) {
+        await this.settleTraceWrites();
+        return this.traceStore?.getTrace(traceId) ?? null;
+    }
+    async listTraces(sessionId) {
+        await this.settleTraceWrites();
+        return this.traceStore?.listTraces(sessionId) ?? [];
+    }
+    getTraceStore() {
+        return this.traceStore;
+    }
     getSessionStore() {
         return this.sessionStore;
     }
@@ -308,6 +424,65 @@ export class Runtime {
             markedBy: opts?.markedBy ?? 'http',
         });
     }
+    shouldTrace(sessionId, input) {
+        if (this.traceSinks.length === 0)
+            return false;
+        const sampling = this.config.tracing?.sampling;
+        if (typeof sampling === 'function') {
+            try {
+                return sampling({ sessionId, input });
+            }
+            catch {
+                return false;
+            }
+        }
+        if (sampling === undefined)
+            return true;
+        return sampling > 0 && (sampling >= 1 || Math.random() < sampling);
+    }
+    writeSpan(original) {
+        let span = original;
+        try {
+            if (this.config.tracing?.redact) {
+                span = this.config.tracing.redact(structuredClone(original));
+            }
+        }
+        catch {
+            return;
+        }
+        if (!span)
+            return;
+        for (const sink of this.traceSinks) {
+            try {
+                const result = sink.write(span);
+                if (result instanceof Promise) {
+                    const pending = result.catch(() => { }).finally(() => this.pendingTraceWrites.delete(pending));
+                    this.pendingTraceWrites.add(pending);
+                }
+            }
+            catch {
+                // Traces are derived observability and never participate in run correctness.
+            }
+        }
+    }
+    async settleTraceWrites() {
+        await Promise.allSettled([...this.pendingTraceWrites]);
+        await Promise.allSettled(this.traceSinks.map((sink) => sink.flush?.()));
+    }
+    flushTraceSinks() {
+        for (const sink of this.traceSinks) {
+            try {
+                const result = sink.flush?.();
+                if (result) {
+                    const pending = result.catch(() => { }).finally(() => this.pendingTraceWrites.delete(pending));
+                    this.pendingTraceWrites.add(pending);
+                }
+            }
+            catch {
+                // Export flushes are observational and never affect the run.
+            }
+        }
+    }
     /**
      * Compact `runState.messages` when over the configured trigger (or always,
      * when `force`). Persists both the run state and the session message mirror.
@@ -327,6 +502,7 @@ export class Runtime {
             model,
             config,
             force,
+            lastPromptTokens: readLastPromptTokens(runCtx.runState.state),
         });
         if (!result.compacted) {
             if (force) {
@@ -337,11 +513,9 @@ export class Runtime {
         runCtx.runState.messages = result.messages;
         runCtx.runState.updatedAt = Date.now();
         await runCtx.runStore.putRunState(runCtx.runState);
-        const latest = await this.sessionStore.get(runCtx.session.id);
-        if (latest) {
+        await mutateSessionWithRetry(this.sessionStore, runCtx.session.id, (latest) => {
             latest.messages = [...result.messages];
-            await this.sessionStore.save(latest);
-        }
+        });
         runCtx.session.messages = [...result.messages];
         emit({
             type: 'context-compacted',
@@ -409,12 +583,14 @@ export class Runtime {
                 error: error instanceof Error ? error.message : String(error),
             };
         }
-        recordEscalationOutcome(runCtx.session, info.category ?? 'user-request', outcome);
         if (opts.setLatch) {
             runCtx.runState.state[ESCALATION_NOTIFIED_KEY] = true;
         }
         await runCtx.runStore.putRunState(runCtx.runState);
-        await this.sessionStore.save(runCtx.session);
+        const latestSession = await mutateSessionWithRetry(this.sessionStore, runCtx.session.id, (latest) => {
+            recordEscalationOutcome(latest, info.category ?? 'user-request', outcome);
+        });
+        runCtx.session.metadata = latestSession.metadata;
         emit({
             type: 'escalation',
             reason: info.reason,
@@ -451,9 +627,9 @@ export class Runtime {
         delete runState.state[ESCALATION_NOTIFIED_KEY];
         runState.updatedAt = Date.now();
         await runStore.putRunState(runState);
-        const latest = (await this.sessionStore.get(sessionId)) ?? session;
-        latest.messages = [...runState.messages];
-        await this.sessionStore.save(latest);
+        await mutateSessionWithRetry(this.sessionStore, sessionId, (latest) => {
+            latest.messages = [...runState.messages];
+        });
     }
 }
 export function createRuntime(config) {
@@ -476,3 +652,10 @@ function collectAssistantText(messages) {
     }
     return '';
 }
+function appendGoalsPrompt(workingMemoryPrompt, workingMemory) {
+    const goalsPrompt = projectGoalsPromptFromState(workingMemory);
+    if (!goalsPrompt) {
+        return workingMemoryPrompt;
+    }
+    return [workingMemoryPrompt, goalsPrompt].filter((part) => part && part.trim()).join('\n\n');
+}

package/dist/runtime/TokenAccumulator.d.ts

@@ -12,6 +12,13 @@ export declare class TokenAccumulator {
     private _peakUtil;
     private _cumCacheRead;
     constructor(contextWindow?: number | undefined);
+    /** Rehydrate cumulative totals from persisted session state (cross-turn). */
+    restoreCumulative(saved: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens?: number;
+    }): void;
     record(usage: TurnUsageInput): TurnUsage;
     get cumulative(): {
         inputTokens: number;

package/dist/runtime/TokenAccumulator.js

@@ -12,6 +12,13 @@ export class TokenAccumulator {
     constructor(contextWindow) {
         this.contextWindow = contextWindow;
     }
+    /** Rehydrate cumulative totals from persisted session state (cross-turn). */
+    restoreCumulative(saved) {
+        this._cumInput = saved.inputTokens;
+        this._cumOutput = saved.outputTokens;
+        this._cumTotal = saved.totalTokens;
+        this._cumCacheRead = saved.cacheReadTokens ?? 0;
+    }
     record(usage) {
         this._cumInput += usage.inputTokens;
         this._cumOutput += usage.outputTokens;

package/dist/runtime/TraceRecorder.d.ts

@@ -0,0 +1,33 @@
+import type { TurnResult } from '../types/channel.js';
+import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+import type { RunOptions } from './Runtime.js';
+export interface TraceRecorderOptions {
+    sessionId?: string;
+    input?: unknown;
+    onSpan?: (span: AgentSpan) => void;
+}
+export declare class TraceRecorder {
+    private readonly trace;
+    private readonly root;
+    private currentFlow?;
+    private currentNode?;
+    private readonly openTools;
+    private readonly toolCallIds;
+    private readonly emitted;
+    private readonly onSpan?;
+    constructor(options?: TraceRecorderOptions);
+    record(part: HarnessStreamPart): void;
+    finish(result: TurnResult): AgentTrace;
+    private openSpan;
+    private takeToolSpan;
+    private closeTools;
+    private closeNode;
+    private closeFlow;
+    private setSessionId;
+    private close;
+    private emitSpan;
+}
+export declare function runOnce(runtime: {
+    run(opts: RunOptions): TurnHandle;
+}, opts: RunOptions): Promise<AgentTrace>;