@kuralle-agents/core 0.12.0 → 0.13.0

package/dist/runtime/goals.js

@@ -0,0 +1,158 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+export const GOALS_KEY = '__goals';
+const goalPatchSchema = z.object({
+    add: z
+        .array(z.object({
+        topic: z.string(),
+        note: z.union([z.string(), z.null()]),
+    }))
+        .default([]),
+    resolve: z.array(z.string()).default([]),
+});
+function isTrackedGoal(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const goal = value;
+    return (typeof goal.topic === 'string' &&
+        (goal.status === 'open' || goal.status === 'resolved') &&
+        typeof goal.lastTurn === 'number');
+}
+function normalizeTopic(topic) {
+    return topic.trim().toLowerCase();
+}
+export function getGoals(state) {
+    const raw = state[GOALS_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter(isTrackedGoal);
+}
+export function addGoal(state, topic, lastTurn = 0, note) {
+    const trimmed = topic.trim();
+    if (!trimmed) {
+        return state;
+    }
+    const goals = getGoals(state);
+    const key = normalizeTopic(trimmed);
+    const existingIndex = goals.findIndex((goal) => normalizeTopic(goal.topic) === key);
+    if (existingIndex >= 0) {
+        const next = [...goals];
+        const existing = next[existingIndex];
+        next[existingIndex] = {
+            ...existing,
+            topic: trimmed,
+            status: 'open',
+            lastTurn,
+            note: note ?? existing.note,
+        };
+        return { ...state, [GOALS_KEY]: next };
+    }
+    const entry = { topic: trimmed, status: 'open', lastTurn };
+    if (note) {
+        entry.note = note;
+    }
+    return { ...state, [GOALS_KEY]: [...goals, entry] };
+}
+export function resolveGoal(state, topic, lastTurn = 0) {
+    const trimmed = topic.trim();
+    if (!trimmed) {
+        return state;
+    }
+    const key = normalizeTopic(trimmed);
+    const goals = getGoals(state);
+    let changed = false;
+    const next = goals.map((goal) => {
+        if (normalizeTopic(goal.topic) !== key) {
+            return goal;
+        }
+        changed = true;
+        return { ...goal, status: 'resolved', lastTurn };
+    });
+    if (!changed) {
+        return state;
+    }
+    return { ...state, [GOALS_KEY]: next };
+}
+export function listOpenGoals(state) {
+    return getGoals(state)
+        .filter((goal) => goal.status === 'open')
+        .map((goal) => goal.topic);
+}
+export function projectGoalsPrompt(goals) {
+    const open = goals.filter((goal) => goal.status === 'open');
+    if (open.length === 0) {
+        return '';
+    }
+    const parts = open.map((goal) => goal.note ? `${goal.topic} (${goal.status}, ${goal.note})` : `${goal.topic} (${goal.status})`);
+    return `Open threads: ${parts.join('; ')}`;
+}
+export function projectGoalsPromptFromState(state) {
+    return projectGoalsPrompt(getGoals(state));
+}
+function readSessionTurn(state) {
+    const value = state['__ariaSessionTurn'];
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function latestExchange(messages) {
+    let assistant = '';
+    let user = '';
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!assistant && message?.role === 'assistant' && typeof message.content === 'string') {
+            assistant = message.content;
+            continue;
+        }
+        if (assistant && message?.role === 'user' && typeof message.content === 'string') {
+            user = message.content;
+            break;
+        }
+    }
+    if (!user || !assistant) {
+        return null;
+    }
+    return { user, assistant };
+}
+function applyGoalPatch(state, patch) {
+    let next = state;
+    const turn = readSessionTurn(state);
+    for (const topic of patch.resolve) {
+        next = resolveGoal(next, topic, turn);
+    }
+    for (const entry of patch.add) {
+        const note = entry.note ?? undefined;
+        next = addGoal(next, entry.topic, turn, note);
+    }
+    return next;
+}
+export async function updateGoalsFromTurn(ctx, model) {
+    const exchange = latestExchange(ctx.runState.messages);
+    if (!exchange) {
+        return;
+    }
+    const currentGoals = getGoals(ctx.session.workingMemory);
+    const goalsSummary = currentGoals.length === 0
+        ? 'none'
+        : currentGoals
+            .map((goal) => goal.note
+            ? `${goal.topic} [${goal.status}] — ${goal.note}`
+            : `${goal.topic} [${goal.status}]`)
+            .join('\n');
+    const { object } = await generateObject({
+        model,
+        schema: goalPatchSchema,
+        temperature: 0,
+        system: 'You track conversational threads (goals/topics the user may circle back to). ' +
+            'Given the latest exchange and current tracked threads, return only schema fields. ' +
+            'Add a topic when the user opens a new thread or revisits one not yet tracked. ' +
+            'Resolve a topic when the exchange clearly completes or abandons it. ' +
+            'Keep topics short labels (1-4 words). Do not invent threads unrelated to the exchange.',
+        prompt: `Current tracked threads:\n${goalsSummary}\n\n` +
+            `Latest user message:\n${exchange.user}\n\n` +
+            `Latest assistant message:\n${exchange.assistant}\n\n` +
+            'Return add[] for new/reopened open topics and resolve[] for completed topics.',
+    });
+    const patched = applyGoalPatch(ctx.session.workingMemory, object);
+    ctx.session.workingMemory = patched;
+}

package/dist/runtime/grounding/knowledge.js

@@ -42,7 +42,7 @@ export function buildAutoRetrieveProvider(provider, agent) {
         retrieve: async (ctx, scope) => {
             const query = scope?.query ?? latestUserMessage(ctx);
             const merged = scope?.knowledge ? { ...overrides, ...scope.knowledge } : overrides;
-            const cache = undefined;
+            const cache = ctx.retrievalCache;
             const { results, events } = await provider.retrieve(query || ' ', cache, merged, false);
             for (const event of events) {
                 ctx.emit(event);

package/dist/runtime/handoffContinuation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Silent handoff: a transfer between agents should read as one continuous
+ * assistant to the user. The transfer itself is already a silent control tool
+ * call, but the TARGET agent's own instructions may tell it to introduce itself
+ * ("Bill here"), which leaks the switch. On a silent handoff we append a strong
+ * continuation directive to the target's system prompt so it does not greet or
+ * re-introduce — mirroring the OpenAI Agents SDK's `nest_handoff_history`
+ * context-note approach. Off (visible handoff) leaves the target's instructions
+ * untouched.
+ */
+import type { Instructions } from '../types/agentConfig.js';
+export declare const HANDOFF_CONTINUATION_DIRECTIVE: string;
+/**
+ * Append the continuation directive to a target agent's instructions on a silent
+ * handoff. Handles every `Instructions` form: a string is suffixed; a (sync)
+ * function is wrapped so the directive is appended to its resolved text; an
+ * `AgentPrompt` object is left untouched (it cannot be safely suffixed, and is
+ * rare as a base layer); `undefined` yields the directive alone.
+ */
+export declare function applyHandoffContinuation(base: Instructions | undefined): Instructions;

package/dist/runtime/handoffContinuation.js

@@ -0,0 +1,30 @@
+export const HANDOFF_CONTINUATION_DIRECTIVE = 'You are seamlessly continuing an ongoing conversation with the same user — this is ' +
+    'not a new conversation. Do NOT greet the user, introduce yourself, state your name ' +
+    'or role, say "hello", or mention any transfer, connection, or that a different ' +
+    'assistant is now helping. Ignore any earlier instruction to open with a greeting or ' +
+    'self-introduction. Continue as one uninterrupted assistant and answer the request directly.';
+const SUFFIX = `\n\n[Handoff continuation]\n${HANDOFF_CONTINUATION_DIRECTIVE}`;
+/**
+ * Append the continuation directive to a target agent's instructions on a silent
+ * handoff. Handles every `Instructions` form: a string is suffixed; a (sync)
+ * function is wrapped so the directive is appended to its resolved text; an
+ * `AgentPrompt` object is left untouched (it cannot be safely suffixed, and is
+ * rare as a base layer); `undefined` yields the directive alone.
+ */
+export function applyHandoffContinuation(base) {
+    if (typeof base === 'string') {
+        return `${base}${SUFFIX}`;
+    }
+    if (typeof base === 'function') {
+        return (ctx) => {
+            const inner = base(ctx);
+            if (typeof inner !== 'string') {
+                // resolveInstructions only supports sync-string functions; match that contract.
+                throw new Error('handoff continuation: instructions function must return a string synchronously');
+            }
+            return `${inner}${SUFFIX}`;
+        };
+    }
+    // AgentPrompt object → preserve as-is (do not drop the persona); undefined → directive only.
+    return base ?? HANDOFF_CONTINUATION_DIRECTIVE;
+}

package/dist/runtime/handoffOscillation.d.ts

@@ -0,0 +1,6 @@
+/** True when the recent handoff history shows A↔B oscillation at/above `threshold` hops
+ *  between the same unordered pair, counting the pending from→to as the latest hop. */
+export declare function isHandoffOscillating(history: Array<{
+    from: string;
+    to: string;
+}>, pendingFrom: string, pendingTo: string, threshold: number): boolean;

package/dist/runtime/handoffOscillation.js

@@ -0,0 +1,17 @@
+/** True when the recent handoff history shows A↔B oscillation at/above `threshold` hops
+ *  between the same unordered pair, counting the pending from→to as the latest hop. */
+export function isHandoffOscillating(history, pendingFrom, pendingTo, threshold) {
+    const pairKey = (a, b) => [a, b].sort().join('\0');
+    const target = pairKey(pendingFrom, pendingTo);
+    let count = 1; // the pending hop
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const h = history[i];
+        if (!h)
+            break;
+        if (pairKey(h.from, h.to) === target)
+            count += 1;
+        else
+            break; // only CONSECUTIVE same-pair hops count as oscillation
+    }
+    return count >= threshold;
+}

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 ??
@@ -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);

package/dist/runtime/index.d.ts

@@ -1,5 +1,7 @@
-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';

package/dist/runtime/index.js

@@ -1,4 +1,5 @@
 export { createRuntime, Runtime, } from './Runtime.js';
+export { TraceRecorder, runOnce } from './TraceRecorder.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
 export { TextDriver, VoiceDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to

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/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/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/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;
+    }
+}