@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/runtime/hostLoop.js

@@ -9,6 +9,7 @@ import { hasHostControlTargets } from './hostControlTools.js';
 import { isValidControl, resolveHostControl, startHostControlGuard, } from './hostControlGuard.js';
 import { resolveDispatchMode, isAdvisoryDispatch } from './dispatchMode.js';
 import { adaptHostSelect } from './hostClassifyAdapter.js';
+import { persistTurnUsageFromTurn } from './turnTokenUsage.js';
 export async function hostLoop(options) {
     const { agent, run, driver, ctx } = options;
     const classify = options.classify ??
@@ -35,7 +36,7 @@ export async function hostLoop(options) {
             return { kind: 'paused' };
         }
         if (error instanceof LimitsExceededError) {
-            ctx.emit({ type: 'error', error: error.message });
+            ctx.emit({ channel: 'client', type: 'error', payload: { error: error.message } });
             return { kind: 'ended', reason: error.message };
         }
         throw error;
@@ -67,6 +68,12 @@ async function runActiveFlow(flow, run, driver, ctx, agent) {
     ctx.resetCallsites();
     const result = await runFlow(flow, run, driver, ctx, agent);
     if (result.kind === 'handoff') {
+        // A handoff fired from inside a flow: the source flow is abandoned for this turn.
+        // Clear the active-flow pointers so the target agent does not try (and fail) to
+        // resume a flow that belongs to the source agent (G17).
+        run.activeFlow = undefined;
+        run.activeNode = undefined;
+        await ctx.runStore.putRunState(run);
         return { kind: 'handoff', to: result.to, reason: result.reason };
     }
     if (result.kind === 'awaitingUser') {
@@ -111,12 +118,16 @@ async function runFreeConversation(agent, run, driver, ctx, classify) {
         resolved.hostControl = { dispatchMode, advisoryDispatch };
     }
     const turn = await driver.runAgentTurn(resolved, ctx);
+    await persistTurnUsageFromTurn(ctx, turn);
     if (turn.control && isValidControl(turn.control, agent, run)) {
         emitHostGuardTelemetry(ctx, { invoked: false, reason: 'main-control' });
         return await executeHostControl(agent, run, driver, ctx, turn.control);
     }
     if (turn.text.trim()) {
         emitHostGuardTelemetry(ctx, { invoked: false, reason: 'answered' });
+        if (turn.toolMessages?.length) {
+            run.messages = [...run.messages, ...turn.toolMessages];
+        }
         const message = { role: 'assistant', content: turn.text };
         run.messages = [...run.messages, message];
         await ctx.runStore.putRunState(run);
@@ -149,7 +160,11 @@ function guardVerdictToTelemetryVerdict(verdict) {
     return 'keep';
 }
 function emitHostGuardTelemetry(ctx, data) {
-    ctx.emit({ type: 'custom', name: 'host-guard', data });
+    ctx.emit({
+        channel: 'internal',
+        type: 'custom',
+        payload: { name: 'host-guard', data },
+    });
 }
 function guardVerdictToControl(verdict, agent) {
     const selection = verdictToSelection(verdict, agent);
@@ -163,7 +178,11 @@ function guardVerdictToControl(verdict, agent) {
 }
 async function executeHostControl(agent, run, driver, ctx, control) {
     if (!control) {
-        ctx.emit({ type: 'error', error: 'No valid host control target resolved' });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: 'No valid host control target resolved' },
+        });
         return { kind: 'ended', reason: 'dispatch_failed' };
     }
     if (control.type === 'enterFlow') {
@@ -171,18 +190,30 @@ async function executeHostControl(agent, run, driver, ctx, control) {
         if (flow) {
             return await runActiveFlow(flow, run, driver, ctx, agent);
         }
-        ctx.emit({ type: 'error', error: `Flow not found: ${control.flowName}` });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: `Flow not found: ${control.flowName}` },
+        });
         return { kind: 'ended', reason: 'flow_not_found' };
     }
     if (control.type === 'handoff') {
-        ctx.emit({ type: 'handoff', targetAgent: control.target, reason: control.reason });
+        ctx.emit({
+            channel: 'internal',
+            type: 'handoff',
+            payload: { targetAgent: control.target, reason: control.reason },
+        });
         return { kind: 'handoff', to: control.target, reason: control.reason };
     }
     if (control.type === 'end') {
         return { kind: 'ended', reason: control.reason };
     }
     if (control.type === 'escalate') {
-        ctx.emit({ type: 'handoff', targetAgent: 'human', reason: control.reason });
+        // No handoff part is emitted here. Runtime owns it: it emits one for any
+        // target in `terminalHandoffTargets` (default ['human']) on this exact
+        // return value. Emitting here too produced two handoff spans per escalation
+        // and a meaningless `human -> human` self-edge, which then mis-attributed
+        // every later span in the turn to `human`.
         return { kind: 'handoff', to: 'human', reason: control.reason, category: control.category };
     }
     if (control.type === 'recover') {

package/dist/runtime/index.d.ts

@@ -1,8 +1,9 @@
-export { createRuntime, Runtime, type HarnessConfig, type RunOptions, } from './Runtime.js';
+export { createRuntime, Runtime, type HarnessConfig, type RunOptions, type TracingConfig, } from './Runtime.js';
 export type { RuntimeLike } from './RuntimeLike.js';
+export { TraceRecorder, runOnce, type TraceRecorderOptions } from './TraceRecorder.js';
+export type { AgentSpan, AgentTrace, SpanKind } from '../types/trace.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
-export type { VoiceDriverConfig } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -1,6 +1,7 @@
 export { createRuntime, Runtime, } from './Runtime.js';
+export { TraceRecorder, runOnce } from './TraceRecorder.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to
 // implement awaitUser the same FIFO-aware way the built-in drivers do (the
 // buffer is an ordered queue since 0.3.13/H3, not a single slot).

package/dist/runtime/openRun.d.ts

@@ -21,6 +21,8 @@ export interface OpenRunOptions {
     seedMessages?: ModelMessage[];
     historyDelta?: ModelMessage[];
     signalDelivery?: SignalDelivery;
+    /** Stable key for this inbound user message; duplicate webhook retries are ignored (H2). */
+    idempotencyKey?: string;
     transcriptionModel?: TranscriptionModel;
     defaultAgentId: string;
     sessionStore: SessionStore;

package/dist/runtime/openRun.js

@@ -3,6 +3,8 @@ import { transcribeAudioParts } from './userInput.js';
 import { setPendingUserInput } from './channels/inputBuffer.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
 import { recordSignalDelivery } from './durable/replay.js';
+import { resetTurnCount } from './policies/limits.js';
+import { mutateSessionWithRetry } from '../session/utils.js';
 export function sessionDerivedRunId(sessionId) {
     return sessionId;
 }
@@ -26,16 +28,18 @@ export async function openRun(agentsById, options) {
         };
         await runStore.initRun(runState);
         if (initialMessages.length > 0) {
-            session.messages = [...initialMessages];
-            await options.sessionStore.save(session);
+            await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+                latest.messages = [...initialMessages];
+            });
         }
     }
     if (options.historyDelta?.length) {
         runState.messages = [...runState.messages, ...options.historyDelta];
         runState.updatedAt = Date.now();
         await runStore.putRunState(runState);
-        session.messages = [...session.messages, ...options.historyDelta];
-        await options.sessionStore.save(session);
+        await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+            latest.messages = [...latest.messages, ...options.historyDelta];
+        });
     }
     if (options.signalDelivery) {
         await recordSignalDelivery(runStore, runState, options.signalDelivery);
@@ -53,22 +57,47 @@ export async function openRun(agentsById, options) {
     const hasInput = typeof effectiveInput === 'string'
         ? effectiveInput.length > 0
         : Array.isArray(effectiveInput) && effectiveInput.length > 0;
+    const isResume = Boolean(options.signalDelivery);
+    const isFlowContinuation = Boolean(runState.activeFlow);
+    const isFreshLogicalRun = (hasInput || Boolean(options.wake)) && !isResume && !isFlowContinuation;
+    if (isFreshLogicalRun) {
+        runState.runEpoch = (runState.runEpoch ?? 0) + 1;
+        await runStore.pruneStepsBeforeEpoch(runId, runState.runEpoch);
+        resetTurnCount(runState);
+        if (Array.isArray(runState.state.__completedFlows)) {
+            runState.state.__completedFlows = [];
+        }
+        runState.updatedAt = Date.now();
+        await runStore.putRunState(runState);
+    }
     if (hasInput && effectiveInput !== undefined) {
+        if (options.idempotencyKey) {
+            const processed = runState.processedInboundKeys ?? [];
+            if (processed.includes(options.idempotencyKey)) {
+                const agent = agentsById.get(runState.activeAgentId);
+                if (!agent) {
+                    throw new Error(`Unknown activeAgentId "${runState.activeAgentId}"`);
+                }
+                const latestSession = (await options.sessionStore.get(options.sessionId)) ?? session;
+                return { session: latestSession, runState, runStore, agent };
+            }
+            runState.processedInboundKeys = [...processed, options.idempotencyKey];
+        }
         runState.updatedAt = Date.now();
         if (runState.activeFlow) {
             await runStore.putRunState(runState);
-            const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
-            setPendingUserInput(sessionAfterPersist, effectiveInput);
-            await options.sessionStore.save(sessionAfterPersist);
+            await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+                setPendingUserInput(latest, effectiveInput);
+            });
         }
         else {
             const userMessage = { role: 'user', content: effectiveInput };
             runState.messages = [...runState.messages, userMessage];
             runState.updatedAt = Date.now();
             await runStore.putRunState(runState);
-            const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
-            sessionAfterPersist.messages = [...sessionAfterPersist.messages, userMessage];
-            await options.sessionStore.save(sessionAfterPersist);
+            await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+                latest.messages = [...latest.messages, userMessage];
+            });
         }
     }
     if (options.wake && !hasInput) {
@@ -84,18 +113,18 @@ export async function openRun(agentsById, options) {
         runState.messages = [...runState.messages, wakeMessage];
         runState.updatedAt = Date.now();
         await runStore.putRunState(runState);
-        const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
-        sessionAfterPersist.messages = [...sessionAfterPersist.messages, wakeMessage];
-        await options.sessionStore.save(sessionAfterPersist);
+        await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+            latest.messages = [...latest.messages, wakeMessage];
+        });
     }
     const agent = agentsById.get(runState.activeAgentId);
     if (!agent) {
         throw new Error(`Unknown activeAgentId "${runState.activeAgentId}"`);
     }
-    const latestSession = (await options.sessionStore.get(options.sessionId)) ?? session;
-    latestSession.currentAgent = runState.activeAgentId;
-    latestSession.activeAgentId = runState.activeAgentId;
-    await options.sessionStore.save(latestSession);
+    const latestSession = await mutateSessionWithRetry(options.sessionStore, session.id, (latest) => {
+        latest.currentAgent = runState.activeAgentId;
+        latest.activeAgentId = runState.activeAgentId;
+    });
     return { session: latestSession, runState, runStore, agent };
 }
 async function loadOrCreateSession(options) {

package/dist/runtime/outcomeMarking.d.ts

@@ -1,9 +1,9 @@
 import type { Session } from '../types/session.js';
 import type { SessionStore } from '../session/SessionStore.js';
 import type { ConversationOutcome, ConversationOutcomeMarkedBy, ConversationOutcomeRecord } from '../outcomes/types.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export declare function isTerminalOutcome(outcome: ConversationOutcome): boolean;
 export declare function markSessionOutcome(sessionStore: SessionStore, session: Session, outcome: ConversationOutcome, opts?: {
     reason?: string;
     markedBy?: ConversationOutcomeMarkedBy;
-}, emit?: (part: HarnessStreamPart) => void): Promise<ConversationOutcomeRecord>;
+}, emit?: (part: StreamPart) => void): Promise<ConversationOutcomeRecord>;

package/dist/runtime/outcomeMarking.js

@@ -22,8 +22,9 @@ export async function markSessionOutcome(sessionStore, session, outcome, opts =
     await sessionStore.save(session);
     if (emit) {
         emit({
+            channel: 'client',
             type: 'conversation-outcome',
-            outcome: record.outcome,
+            payload: { outcome: record.outcome },
         });
     }
     return record;

package/dist/runtime/policies/agentTurn.d.ts

@@ -1,6 +1,6 @@
 import type { TurnControl } from '../../types/channel.js';
 import type { ToolCallRecord } from '../../types/session.js';
-import type { SourceRef } from '../../types/voice.js';
+import type { SourceRef } from '../../types/knowledge.js';
 import type { RunContext } from '../../types/run-context.js';
 export interface PreTurnResult {
     proceed: boolean;

package/dist/runtime/policies/limits.d.ts

@@ -4,5 +4,6 @@ export declare class LimitsExceededError extends Error {
     constructor(message: string);
 }
 export declare function incrementTurnCount(run: RunState): number;
+export declare function resetTurnCount(run: RunState): void;
 export declare function assertWithinTurnLimit(run: RunState, limits?: Limits): void;
 export declare function resolveMaxSteps(limits: Limits | undefined, fallback: number): number;

package/dist/runtime/policies/limits.js

@@ -15,6 +15,9 @@ export function incrementTurnCount(run) {
     run.updatedAt = Date.now();
     return next;
 }
+export function resetTurnCount(run) {
+    run.state[TURN_COUNT_KEY] = 0;
+}
 export function assertWithinTurnLimit(run, limits) {
     const maxTurns = limits?.maxTurns;
     if (maxTurns == null) {

package/dist/runtime/runHookSafely.d.ts

@@ -0,0 +1,3 @@
+type HookCallback = () => void | Promise<void>;
+export declare function runHookSafely(name: string, callback: HookCallback | undefined): Promise<void>;
+export {};

package/dist/runtime/runHookSafely.js

@@ -0,0 +1,19 @@
+export function runHookSafely(name, callback) {
+    if (!callback)
+        return Promise.resolve();
+    try {
+        return Promise.resolve(callback()).catch((error) => reportHookError(name, error));
+    }
+    catch (error) {
+        reportHookError(name, error);
+        return Promise.resolve();
+    }
+}
+function reportHookError(name, error) {
+    try {
+        console.error(`Hook ${name} failed`, error);
+    }
+    catch {
+        // Hook failure reporting must not affect run correctness.
+    }
+}

package/dist/runtime/select.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageModel } from 'ai';
+import type { LanguageModel, ModelMessage } from 'ai';
 import type { AgentConfig } from '../types/agentConfig.js';
 import type { Flow } from '../types/flow.js';
 import type { RunState } from './durable/types.js';
@@ -20,12 +20,15 @@ export interface HostGuardVerdict {
     reason?: string;
     confidence?: number;
 }
+export declare const DEFAULT_CLASSIFIER_CONTEXT_MESSAGES = 6;
 export interface ClassifyHostOptions {
     agent: AgentConfig;
     run: RunState;
     model: LanguageModel;
     allowKeep: boolean;
     excludeFlowNames?: string[];
+    /** How many recent messages to include in the classifier prompt. Default: 6. */
+    contextMessageLimit?: number;
 }
 export declare function classifyHostTarget(options: ClassifyHostOptions): Promise<HostGuardVerdict>;
 /** @deprecated Use classifyHostTarget — kept as alias for test injection. */
@@ -33,4 +36,5 @@ export declare function selectHostTarget(options: Omit<ClassifyHostOptions, 'all
     alwaysRoute?: boolean;
 }): Promise<HostSelection>;
 export declare function verdictToSelection(verdict: HostGuardVerdict, agent: AgentConfig): HostSelection | undefined;
+export declare function formatRecentConversation(messages: ModelMessage[], limit?: number): string;
 export { availableHostFlows };

package/dist/runtime/select.js

@@ -14,11 +14,13 @@ const dispatcherSchema = z.object({
     agentId: z.union([z.string(), z.null()]),
     reason: z.union([z.string(), z.null()]),
 });
+export const DEFAULT_CLASSIFIER_CONTEXT_MESSAGES = 6;
 export async function classifyHostTarget(options) {
     const { agent, run, model, allowKeep } = options;
     const flows = agent.flows ?? [];
     const routes = agent.routes ?? [];
     const latestUser = latestUserMessage(run.messages);
+    const recentContext = formatRecentConversation(run.messages, options.contextMessageLimit ?? DEFAULT_CLASSIFIER_CONTEXT_MESSAGES);
     if (!latestUser) {
         return { action: 'keep', confidence: 1 };
     }
@@ -51,7 +53,9 @@ export async function classifyHostTarget(options) {
         system: 'You are an internal routing classifier. Choose exactly one action. ' +
             'Output schema fields only — never user-facing prose. ' +
             'Reason over semantic descriptions only; never match keywords or substrings.',
-        prompt: `User message:\n${latestUser}\n\n` +
+        prompt: (recentContext
+            ? `Recent conversation:\n${recentContext}\n\n`
+            : `User message:\n${latestUser}\n\n`) +
             (completedFlows.length > 0 ? `Completed flows: ${completedFlows.join(', ')}\n\n` : '') +
             (flowLines ? `Available flows:\n${flowLines}\n\n` : '') +
             (routeLines ? `Routes:\n${routeLines}\n\n` : '') +
@@ -159,6 +163,31 @@ function formatRouteLine(route, index) {
     const target = route.agent ? `agent "${route.agent}"` : route.flow ? `flow "${route.flow}"` : 'keep';
     return `- route ${index + 1} → ${target} when: ${route.when}`;
 }
+function formatMessageContent(message) {
+    if (typeof message.content === 'string') {
+        return message.content;
+    }
+    if (Array.isArray(message.content)) {
+        return message.content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text)
+            .join('');
+    }
+    return '';
+}
+export function formatRecentConversation(messages, limit = DEFAULT_CLASSIFIER_CONTEXT_MESSAGES) {
+    const slice = messages.slice(-limit);
+    return slice
+        .map((message) => {
+        const content = formatMessageContent(message);
+        if (!content.trim()) {
+            return undefined;
+        }
+        return `${message.role}: ${content}`;
+    })
+        .filter((line) => line != null)
+        .join('\n');
+}
 function latestUserMessage(messages) {
     for (let i = messages.length - 1; i >= 0; i -= 1) {
         const message = messages[i];

package/dist/runtime/turnTokenUsage.d.ts

@@ -0,0 +1,28 @@
+import type { TurnResult } from '../types/channel.js';
+import type { RunContext } from '../types/run-context.js';
+export declare const TOKEN_USAGE_STATE_KEY = "__tokenUsage";
+export declare const LAST_PROMPT_TOKENS_KEY = "__lastPromptTokens";
+export interface PersistedTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+}
+/** Record real turn usage onto run state (survives across turns via persistence). */
+export declare function persistTurnUsageFromTurn(ctx: RunContext, turn: TurnResult): Promise<void>;
+export declare function readLastPromptTokens(state: Record<string, unknown>): number | undefined;
+/** The session-cumulative usage persisted on run state (or undefined before any turn). */
+export declare function readCumulativeUsage(state: Record<string, unknown>): PersistedTokenUsage | undefined;
+export interface TraceTurnUsage {
+    /** Input tokens consumed by THIS turn (cumulative delta since the turn opened). */
+    inputTokens?: number;
+    /** Output tokens generated by THIS turn (cumulative delta since the turn opened). */
+    outputTokens?: number;
+    /** Context-window occupancy — the last prompt's token count (not a per-turn delta). */
+    contextTokens?: number;
+}
+/** Per-turn token usage for a trace's `done` event. `baseline` is the cumulative
+ *  usage captured when the turn OPENED, so input/output are strictly this turn's
+ *  consumption (correct for cost attribution — never the running session total).
+ *  `contextTokens` is the current window occupancy, which is inherently a snapshot. */
+export declare function computeTurnTraceUsage(baseline: PersistedTokenUsage | undefined, state: Record<string, unknown>): TraceTurnUsage;

package/dist/runtime/turnTokenUsage.js

@@ -0,0 +1,70 @@
+import { TokenAccumulator } from './TokenAccumulator.js';
+export const TOKEN_USAGE_STATE_KEY = '__tokenUsage';
+export const LAST_PROMPT_TOKENS_KEY = '__lastPromptTokens';
+function readPersistedUsage(state) {
+    const saved = state[TOKEN_USAGE_STATE_KEY];
+    if (!saved || typeof saved !== 'object') {
+        return undefined;
+    }
+    const usage = saved;
+    if (typeof usage.inputTokens !== 'number' ||
+        typeof usage.outputTokens !== 'number' ||
+        typeof usage.totalTokens !== 'number') {
+        return undefined;
+    }
+    return usage;
+}
+function hydrateAccumulator(state) {
+    const acc = new TokenAccumulator();
+    const saved = readPersistedUsage(state);
+    if (saved) {
+        acc.restoreCumulative(saved);
+    }
+    return acc;
+}
+/** Record real turn usage onto run state (survives across turns via persistence). */
+export async function persistTurnUsageFromTurn(ctx, turn) {
+    if (!turn.usage) {
+        return;
+    }
+    const acc = hydrateAccumulator(ctx.runState.state);
+    const turnIndex = acc.turns.length + 1;
+    acc.record({
+        turn: turnIndex,
+        inputTokens: turn.usage.inputTokens,
+        outputTokens: turn.usage.outputTokens,
+        totalTokens: turn.usage.totalTokens,
+        cacheReadTokens: turn.usage.cacheReadTokens,
+        latencyMs: 0,
+    });
+    ctx.runState.state[TOKEN_USAGE_STATE_KEY] = acc.cumulative;
+    ctx.runState.state[LAST_PROMPT_TOKENS_KEY] =
+        turn.usage.contextTokens ?? turn.usage.inputTokens;
+    ctx.runState.updatedAt = Date.now();
+    await ctx.runStore.putRunState(ctx.runState);
+}
+export function readLastPromptTokens(state) {
+    const value = state[LAST_PROMPT_TOKENS_KEY];
+    return typeof value === 'number' ? value : undefined;
+}
+/** The session-cumulative usage persisted on run state (or undefined before any turn). */
+export function readCumulativeUsage(state) {
+    return readPersistedUsage(state);
+}
+/** Per-turn token usage for a trace's `done` event. `baseline` is the cumulative
+ *  usage captured when the turn OPENED, so input/output are strictly this turn's
+ *  consumption (correct for cost attribution — never the running session total).
+ *  `contextTokens` is the current window occupancy, which is inherently a snapshot. */
+export function computeTurnTraceUsage(baseline, state) {
+    const contextTokens = readLastPromptTokens(state);
+    const now = readPersistedUsage(state);
+    if (!now) {
+        return contextTokens === undefined ? {} : { contextTokens };
+    }
+    const base = baseline ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    return {
+        inputTokens: Math.max(0, now.inputTokens - base.inputTokens),
+        outputTokens: Math.max(0, now.outputTokens - base.outputTokens),
+        ...(contextTokens === undefined ? {} : { contextTokens }),
+    };
+}

package/dist/scheduler/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { Tool } from '../types/effectTool.js';
-import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
 /**
  * Deferred-work scheduling for proactive (agent-initiated) turns.
  *
@@ -51,7 +51,7 @@ export interface WakeDelivery {
     reason: string;
     payload?: Record<string, unknown>;
     /** Full stream of the wake turn (text, tool events, interactive parts…). */
-    parts: HarnessStreamPart[];
+    parts: StreamPart[];
     /** Concatenated assistant text of the wake turn. */
     text: string;
 }

package/dist/scheduler/index.js

@@ -60,7 +60,7 @@ export function createWakeJobRunner(runtime, opts) {
             for await (const part of handle.events) {
                 parts.push(part);
                 if (part.type === 'text-delta') {
-                    text += part.delta;
+                    text += part.payload.delta;
                 }
             }
             const result = await handle;

package/dist/services/TracingService.js

@@ -11,9 +11,8 @@ export class TracingService {
     }
     startSpan(name, attributes, parentSpanId) {
         if (!this.config) {
-            // Fallback or throw? Helpers threw.
-            // We will throw to maintain behavior, but maybe warn in future.
-            throw new Error('Tracing not initialized. Call initTracing() first.');
+            throw new Error('TracingService not initialized. Construct it with a config — ' +
+                'new TracingService(config) — or call .init(config) before startSpan().');
         }
         const span = {
             id: this.generateSpanId(),

package/dist/session/SessionStore.d.ts

@@ -1,5 +1,11 @@
 import type { Session } from '../types/index.js';
 import type { AuditListOptions, ConversationAuditEntry } from '../audit/types.js';
+export declare class StaleWriteError extends Error {
+    readonly sessionId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    constructor(sessionId: string, expectedVersion: number, actualVersion: number);
+}
 export interface SessionListWindow {
     from?: Date;
     to?: Date;

package/dist/session/SessionStore.js

@@ -1 +1,12 @@
-export {};
+export class StaleWriteError extends Error {
+    sessionId;
+    expectedVersion;
+    actualVersion;
+    constructor(sessionId, expectedVersion, actualVersion) {
+        super(`Stale write for session ${sessionId}: expected version ${expectedVersion}, stored version is ${actualVersion}`);
+        this.name = 'StaleWriteError';
+        this.sessionId = sessionId;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+    }
+}

package/dist/session/stores/MemoryStore.d.ts

@@ -1,6 +1,6 @@
 import type { Session } from '../../types/index.js';
 import type { AuditListOptions, ConversationAuditEntry } from '../../audit/types.js';
-import type { SessionListWindow, SessionStore } from '../SessionStore.js';
+import { type SessionListWindow, type SessionStore } from '../SessionStore.js';
 export declare class MemoryStore implements SessionStore {
     private sessions;
     get(id: string): Promise<Session | null>;

package/dist/session/stores/MemoryStore.js

@@ -1,3 +1,4 @@
+import { StaleWriteError } from '../SessionStore.js';
 export class MemoryStore {
     sessions = new Map();
     async get(id) {
@@ -5,8 +6,21 @@ export class MemoryStore {
         return session ? safeClone(session) : null;
     }
     async save(session) {
-        session.updatedAt = new Date();
-        this.sessions.set(session.id, safeClone(session));
+        const existing = this.sessions.get(session.id);
+        const expected = session.version ?? 0;
+        if (existing !== undefined) {
+            const stored = existing.version ?? 0;
+            if (stored !== expected) {
+                throw new StaleWriteError(session.id, expected, stored);
+            }
+        }
+        else if (expected !== 0) {
+            throw new StaleWriteError(session.id, expected, 0);
+        }
+        const toSave = safeClone(session);
+        toSave.updatedAt = new Date();
+        toSave.version = expected + 1;
+        this.sessions.set(session.id, toSave);
     }
     async delete(id) {
         this.sessions.delete(id);

package/dist/session/testing.d.ts

@@ -1,7 +1,12 @@
-import type { SessionStore } from './SessionStore.js';
+import { type SessionStore } from './SessionStore.js';
 export type SessionStoreFactory = () => SessionStore | Promise<SessionStore>;
 /**
  * Registers the shared SessionStore contract tests. Must be invoked at the
  * top level of a bun test file.
  */
 export declare function runSessionStoreContract(factory: SessionStoreFactory): void;
+/**
+ * Registers optimistic-concurrency (CAS) contract tests for SessionStore adapters.
+ * Two concurrent saves with the same expected version: exactly one succeeds.
+ */
+export declare function runSessionStoreCasContract(factory: SessionStoreFactory): void;