@kuralle-agents/core 0.12.0 → 0.13.0

package/dist/runtime/TraceRecorder.js

@@ -0,0 +1,290 @@
+export class TraceRecorder {
+    trace;
+    root;
+    currentFlow;
+    currentNode;
+    openTools = [];
+    toolCallIds = new Map();
+    emitted = new Set();
+    onSpan;
+    constructor(options = {}) {
+        const startedAt = Date.now();
+        const sessionId = options.sessionId ?? '';
+        const traceId = crypto.randomUUID().replaceAll('-', '');
+        this.onSpan = options.onSpan;
+        this.root = {
+            traceId,
+            spanId: newSpanId(),
+            name: 'turn',
+            kind: 'turn',
+            startTime: startedAt,
+            status: 'ok',
+            attributes: {
+                sessionId,
+                ...(options.input !== undefined ? { input: toJsonValue(options.input) } : {}),
+            },
+        };
+        this.trace = {
+            traceId,
+            sessionId,
+            spans: [this.root],
+            answer: '',
+            usedTool: false,
+            toolCalls: [],
+            toolResults: [],
+            startedAt,
+        };
+    }
+    record(part) {
+        try {
+            const at = Date.now();
+            switch (part.type) {
+                case 'text-delta':
+                    this.trace.answer += part.delta;
+                    break;
+                case 'flow-enter':
+                    this.closeNode(at);
+                    this.closeFlow(at);
+                    this.currentFlow = this.openSpan({
+                        name: `flow:${part.flow}`,
+                        kind: 'flow',
+                        parentSpanId: this.root.spanId,
+                        at,
+                        attributes: { activeFlow: part.flow },
+                    });
+                    break;
+                case 'flow-end':
+                    this.closeNode(at);
+                    this.closeFlow(at);
+                    break;
+                case 'node-enter':
+                    this.closeNode(at);
+                    this.currentNode = this.openSpan({
+                        name: `node:${part.nodeName}`,
+                        kind: 'node',
+                        parentSpanId: this.currentFlow?.spanId ?? this.root.spanId,
+                        at,
+                        attributes: {
+                            ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
+                            nodeId: part.nodeName,
+                        },
+                    });
+                    break;
+                case 'node-exit':
+                    this.closeNode(at);
+                    break;
+                case 'tool-call': {
+                    const span = this.openSpan({
+                        name: `tool:${part.toolName}`,
+                        kind: 'tool',
+                        parentSpanId: this.currentNode?.spanId ?? this.root.spanId,
+                        at,
+                        attributes: {
+                            ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
+                            ...(this.currentNode ? { nodeId: nodeName(this.currentNode) } : {}),
+                            toolName: part.toolName,
+                            input: toJsonValue(part.args),
+                        },
+                    });
+                    this.toolCallIds.set(span, part.toolCallId);
+                    this.openTools.push(span);
+                    this.trace.usedTool = true;
+                    this.trace.toolCalls.push({ name: part.toolName, args: toJsonValue(part.args) });
+                    break;
+                }
+                case 'tool-result': {
+                    this.trace.usedTool = true;
+                    const result = toJsonValue(part.result);
+                    this.trace.toolResults.push({ name: part.toolName, result });
+                    const span = this.takeToolSpan(part.toolName, part.toolCallId) ??
+                        this.openSpan({
+                            name: `tool:${part.toolName}`,
+                            kind: 'tool',
+                            parentSpanId: this.currentNode?.spanId ?? this.root.spanId,
+                            at,
+                            attributes: {
+                                ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
+                                ...(this.currentNode ? { nodeId: nodeName(this.currentNode) } : {}),
+                                toolName: part.toolName,
+                            },
+                        });
+                    span.attributes.output = result;
+                    span.endTime = at;
+                    this.emitSpan(span);
+                    break;
+                }
+                case 'handoff': {
+                    const span = this.openSpan({
+                        name: `handoff:${part.targetAgent}`,
+                        kind: 'handoff',
+                        parentSpanId: this.root.spanId,
+                        at,
+                        attributes: { handoffTo: part.targetAgent },
+                    });
+                    span.endTime = at;
+                    this.emitSpan(span);
+                    break;
+                }
+                case 'error': {
+                    const span = this.openTools.at(-1) ?? this.currentNode ?? this.currentFlow ?? this.root;
+                    span.status = 'error';
+                    span.attributes.error = part.error;
+                    this.root.status = 'error';
+                    this.root.attributes.error = part.error;
+                    break;
+                }
+                case 'done':
+                    this.setSessionId(part.sessionId);
+                    this.root.attributes.output = this.trace.answer;
+                    if (part.usage) {
+                        if (typeof part.usage.inputTokens === 'number')
+                            this.root.attributes.tokensIn = part.usage.inputTokens;
+                        if (typeof part.usage.outputTokens === 'number')
+                            this.root.attributes.tokensOut = part.usage.outputTokens;
+                        if (typeof part.usage.contextTokens === 'number')
+                            this.root.attributes.contextTokens = part.usage.contextTokens;
+                    }
+                    this.close(at);
+                    break;
+            }
+        }
+        catch {
+            // Tracing is observational: malformed telemetry must never affect the run.
+        }
+    }
+    finish(result) {
+        try {
+            if (!this.trace.answer) {
+                this.trace.answer = result.text;
+            }
+            this.root.attributes.output = this.trace.answer;
+            this.close(Date.now());
+        }
+        catch {
+            // Returning a partial trace is preferable to changing run behavior.
+        }
+        return this.trace;
+    }
+    openSpan(args) {
+        const span = {
+            traceId: this.trace.traceId,
+            spanId: newSpanId(),
+            parentSpanId: args.parentSpanId,
+            name: args.name,
+            kind: args.kind,
+            startTime: args.at,
+            status: 'ok',
+            attributes: { sessionId: this.trace.sessionId, ...args.attributes },
+        };
+        this.trace.spans.push(span);
+        return span;
+    }
+    takeToolSpan(toolName, toolCallId) {
+        const index = this.openTools.findIndex((span) => {
+            const spanCallId = this.toolCallIds.get(span);
+            return toolCallId ? spanCallId === toolCallId : span.attributes.toolName === toolName;
+        });
+        if (index < 0)
+            return undefined;
+        const span = this.openTools.splice(index, 1)[0];
+        if (span)
+            this.toolCallIds.delete(span);
+        return span;
+    }
+    closeTools(at) {
+        for (const span of this.openTools.splice(0)) {
+            span.endTime ??= at;
+            this.toolCallIds.delete(span);
+            this.emitSpan(span);
+        }
+    }
+    closeNode(at) {
+        this.closeTools(at);
+        if (this.currentNode) {
+            this.currentNode.endTime ??= at;
+            this.emitSpan(this.currentNode);
+            this.currentNode = undefined;
+        }
+    }
+    closeFlow(at) {
+        if (this.currentFlow) {
+            this.currentFlow.endTime ??= at;
+            this.emitSpan(this.currentFlow);
+            this.currentFlow = undefined;
+        }
+    }
+    setSessionId(sessionId) {
+        this.trace.sessionId = sessionId;
+        for (const span of this.trace.spans) {
+            span.attributes.sessionId = sessionId;
+        }
+    }
+    close(at) {
+        this.closeNode(at);
+        this.closeFlow(at);
+        this.trace.endedAt ??= at;
+        this.root.endTime ??= at;
+        this.emitSpan(this.root);
+    }
+    emitSpan(span) {
+        if (this.emitted.has(span.spanId) || span.endTime === undefined)
+            return;
+        this.emitted.add(span.spanId);
+        try {
+            this.onSpan?.(structuredClone(span));
+        }
+        catch {
+            // A tracing callback is never allowed to change run behavior.
+        }
+    }
+}
+export async function runOnce(runtime, opts) {
+    const handle = runtime.run(opts);
+    const recorder = new TraceRecorder({ sessionId: opts.sessionId, input: opts.input });
+    for await (const part of handle.events) {
+        recorder.record(part);
+    }
+    return recorder.finish(await handle);
+}
+function activeFlowName(span) {
+    return span.attributes.activeFlow ?? span.name.slice('flow:'.length);
+}
+function nodeName(span) {
+    return span.attributes.nodeId ?? span.name.slice('node:'.length);
+}
+function newSpanId() {
+    return crypto.randomUUID().replaceAll('-', '').slice(0, 16);
+}
+function toJsonValue(value, seen = new WeakSet()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value === undefined)
+        return null;
+    if (typeof value === 'function' || typeof value === 'symbol')
+        return String(value);
+    if (typeof value !== 'object')
+        return String(value);
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error)
+        return { name: value.name, message: value.message };
+    if (Array.isArray(value))
+        return value.map((entry) => toJsonValue(entry, seen));
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        try {
+            output[key] = toJsonValue(entry, seen);
+        }
+        catch {
+            output[key] = '[Unserializable]';
+        }
+    }
+    return output;
+}

package/dist/runtime/channels/TextDriver.js

@@ -1,7 +1,7 @@
 import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
-import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
+import { dispatchModelToolCalls, toolResultMessage } from './executeModelTool.js';
 import { consumeAllPendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -44,6 +44,7 @@ export class TextDriver {
         const scope = resolveNodeGatherScope(replyNode, ctx.runState.state, ctx.runState.messages);
         const gather = await runGatherPhase(ctx, scope);
         const out = { text: '', toolResults: [] };
+        const toolMessages = [];
         const model = replyNode.model ?? ctx.model;
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
         const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
@@ -54,6 +55,7 @@ export class TextDriver {
         const toolCallsMade = [];
         const mode = resolveStreamMode(ctx, node);
         const turnId = crypto.randomUUID();
+        let turnUsage;
         const source = {
             async *[Symbol.asyncIterator]() {
                 for (let step = 0; step < maxSteps; step += 1) {
@@ -79,23 +81,26 @@ export class TextDriver {
                     }
                     const finishReason = await result.finishReason;
                     const response = await result.response;
-                    messages.push(...response.messages);
+                    if (result.totalUsage) {
+                        const stepUsage = await result.totalUsage;
+                        if (stepUsage) {
+                            turnUsage = addTurnUsage(turnUsage, stepUsage);
+                        }
+                    }
                     if (finishReason !== 'tool-calls') {
+                        messages.push(...response.messages);
                         break;
                     }
+                    messages.push(...response.messages);
+                    toolMessages.push(...response.messages);
                     const toolCalls = await result.toolCalls;
-                    for (const call of toolCalls) {
-                        ctx.emit({
-                            type: 'tool-call',
-                            toolName: call.toolName,
-                            args: call.input,
-                            toolCallId: call.toolCallId,
-                        });
-                        const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, {
-                            ...ctx.globalTools,
-                            ...(ctx.workingMemoryTools ?? {}),
-                            ...node.localTools,
-                        });
+                    const mergedTools = {
+                        ...ctx.globalTools,
+                        ...(ctx.workingMemoryTools ?? {}),
+                        ...node.localTools,
+                    };
+                    await dispatchModelToolCalls(ctx, toolCalls, mergedTools, ({ call, outcome }) => {
+                        const { result: toolResult, control, failed } = outcome;
                         out.toolResults.push({
                             name: call.toolName,
                             args: call.input,
@@ -111,14 +116,10 @@ export class TextDriver {
                             timestamp: Date.now(),
                         });
                         out.control ??= control;
-                        ctx.emit({
-                            type: 'tool-result',
-                            toolName: call.toolName,
-                            result: toolResult,
-                            toolCallId: call.toolCallId,
-                        });
-                        messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
-                    }
+                        const resultMessage = toolResultMessage(call, toolResult);
+                        messages.push(resultMessage);
+                        toolMessages.push(resultMessage);
+                    });
                 }
             },
         };
@@ -153,6 +154,12 @@ export class TextDriver {
         out.text = spoken.text;
         out.control = spoken.control ?? out.control;
         out.confidence = spoken.confidence;
+        if (toolMessages.length > 0) {
+            out.toolMessages = toolMessages;
+        }
+        if (turnUsage && turnUsage.totalTokens > 0) {
+            out.usage = turnUsage;
+        }
         ctx.emit({ type: 'turn-end' });
         return out;
     }
@@ -210,4 +217,20 @@ export class TextDriver {
         return aiTools;
     }
 }
+function addTurnUsage(current, usage) {
+    const inputTokens = usage.inputTokens ?? 0;
+    const outputTokens = usage.outputTokens ?? 0;
+    const totalTokens = usage.totalTokens ?? inputTokens + outputTokens;
+    const cacheReadTokens = usage.inputTokenDetails?.cacheReadTokens ?? 0;
+    if (!current) {
+        return { inputTokens, outputTokens, totalTokens, cacheReadTokens, contextTokens: inputTokens };
+    }
+    return {
+        inputTokens: current.inputTokens + inputTokens,
+        outputTokens: current.outputTokens + outputTokens,
+        totalTokens: current.totalTokens + totalTokens,
+        cacheReadTokens: (current.cacheReadTokens ?? 0) + cacheReadTokens,
+        contextTokens: inputTokens,
+    };
+}
 export { buildNodePrompt };

package/dist/runtime/channels/executeModelTool.d.ts

@@ -12,7 +12,14 @@ export interface ModelToolCallOutcome {
     control?: TurnControl;
     failed: boolean;
 }
-export declare function executeModelToolCall(ctx: RunContext, call: ModelToolCall, localTools?: Record<string, AnyTool>): Promise<ModelToolCallOutcome>;
+export declare function executeModelToolCall(ctx: RunContext, call: ModelToolCall, localTools?: Record<string, AnyTool>, durableOpts?: {
+    callsite?: string;
+    index?: number;
+}): Promise<ModelToolCallOutcome>;
+export declare function dispatchModelToolCalls(ctx: RunContext, toolCalls: ModelToolCall[], localTools: Record<string, AnyTool>, onEach: (args: {
+    call: ModelToolCall;
+    outcome: ModelToolCallOutcome;
+}) => void): Promise<void>;
 export declare function toolResultMessage(call: ModelToolCall, result: unknown): {
     role: 'tool';
     content: [

package/dist/runtime/channels/executeModelTool.js

@@ -1,10 +1,14 @@
 import { classifyControl } from '../../flow/classifyControl.js';
 import { toolErrorResult } from '../../tools/controlResults.js';
-export async function executeModelToolCall(ctx, call, localTools) {
+import { idempotencyKey, logicalRunId } from '../durable/idempotency.js';
+import { findStepByKey } from '../durable/replay.js';
+export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
     try {
         const localTool = localTools?.[call.toolName];
         const toolResult = await ctx.tool(call.toolName, call.input, {
             toolCallId: call.toolCallId,
+            callsite: durableOpts?.callsite,
+            index: durableOpts?.index,
             ...(localTool && {
                 def: localTool,
                 toolCtx: {
@@ -25,6 +29,71 @@ export async function executeModelToolCall(ctx, call, localTools) {
         return { result: toolErrorResult(error), failed: true };
     }
 }
+function isParallelSafeTool(def) {
+    return def?.parallelSafe === true || def?.replay === false;
+}
+export async function dispatchModelToolCalls(ctx, toolCalls, localTools, onEach) {
+    const runOne = async (call, durableOpts) => {
+        ctx.emit({
+            type: 'tool-call',
+            toolName: call.toolName,
+            args: call.input,
+            toolCallId: call.toolCallId,
+        });
+        const outcome = await executeModelToolCall(ctx, call, localTools, durableOpts);
+        onEach({ call, outcome });
+        ctx.emit({
+            type: 'tool-result',
+            toolName: call.toolName,
+            result: outcome.result,
+            toolCallId: call.toolCallId,
+        });
+    };
+    const runParallel = async (parallel) => {
+        const callsites = ctx.reserveCallsites(parallel.length);
+        const steps = await ctx.runStore.getSteps(ctx.runState.runId);
+        const logicalId = logicalRunId(ctx.runState.runId, ctx.runState.runEpoch);
+        const unresolved = parallel.filter((call, i) => {
+            const def = localTools[call.toolName];
+            const key = def?.idempotencyKey != null
+                ? def.idempotencyKey(call.input)
+                : idempotencyKey(logicalId, callsites[i], { name: call.toolName, args: call.input });
+            const hit = findStepByKey(steps, key);
+            return !hit || hit.status === 'running';
+        });
+        let indices;
+        if (unresolved.length > 0 && ctx.runStore.reserveSteps) {
+            indices = await ctx.runStore.reserveSteps(ctx.runState.runId, unresolved.length);
+        }
+        let unresolvedCursor = 0;
+        const assignments = parallel.map((call, i) => {
+            const def = localTools[call.toolName];
+            const key = def?.idempotencyKey != null
+                ? def.idempotencyKey(call.input)
+                : idempotencyKey(logicalId, callsites[i], { name: call.toolName, args: call.input });
+            const hit = findStepByKey(steps, key);
+            const needsIndex = !hit || hit.status === 'running';
+            const index = needsIndex ? indices?.[unresolvedCursor++] : hit?.index;
+            return { call, callsite: callsites[i], index };
+        });
+        await Promise.all(assignments.map(({ call, callsite, index }) => runOne(call, { callsite, index })));
+    };
+    for (let cursor = 0; cursor < toolCalls.length;) {
+        const call = toolCalls[cursor];
+        if (!isParallelSafeTool(localTools[call.toolName])) {
+            await runOne(call);
+            cursor += 1;
+            continue;
+        }
+        const parallel = [];
+        while (cursor < toolCalls.length &&
+            isParallelSafeTool(localTools[toolCalls[cursor].toolName])) {
+            parallel.push(toolCalls[cursor]);
+            cursor += 1;
+        }
+        await runParallel(parallel);
+    }
+}
 export function toolResultMessage(call, result) {
     return {
         role: 'tool',

package/dist/runtime/channels/inputBuffer.d.ts

@@ -7,3 +7,4 @@ export declare function consumePendingUserInput(session: Session): UserInputCont
 export declare function consumeAllPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function peekPendingUserInput(session: Session): UserInputContent | undefined;
 export declare function hasPendingUserInput(session: Session): boolean;
+export declare function syncPendingUserInput(source: Session, target: Session): void;

package/dist/runtime/channels/inputBuffer.js

@@ -33,3 +33,12 @@ export function peekPendingUserInput(session) {
 export function hasPendingUserInput(session) {
     return queue(session).length > 0;
 }
+export function syncPendingUserInput(source, target) {
+    const pending = queue(source);
+    if (pending.length > 0) {
+        target.workingMemory[PENDING_INPUT_KEY] = [...pending];
+    }
+    else {
+        delete target.workingMemory[PENDING_INPUT_KEY];
+    }
+}

package/dist/runtime/closeRun.js

@@ -1,4 +1,6 @@
 import { isTerminalOutcome, markSessionOutcome } from './outcomeMarking.js';
+import { mutateSessionWithRetry } from '../session/utils.js';
+import { syncPendingUserInput } from './channels/inputBuffer.js';
 export async function closeRun(options) {
     const { session, runState, runStore, sessionStore, hooks, ctx } = options;
     runState.updatedAt = Date.now();
@@ -19,12 +21,13 @@ export async function closeRun(options) {
             outcome: outcomeRecord,
         });
     }
-    const latest = (await sessionStore.get(session.id)) ?? session;
-    latest.currentAgent = runState.activeAgentId;
-    latest.activeAgentId = runState.activeAgentId;
-    // Sync the session-level message mirror to the canonical run record — it
-    // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
-    // user input written at openRun.
-    latest.messages = [...runState.messages];
-    await sessionStore.save(latest);
+    await mutateSessionWithRetry(sessionStore, session.id, (latest) => {
+        latest.currentAgent = runState.activeAgentId;
+        latest.activeAgentId = runState.activeAgentId;
+        // Sync the session-level message mirror to the canonical run record — it
+        // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
+        // user input written at openRun.
+        latest.messages = [...runState.messages];
+        syncPendingUserInput(ctx.session, latest);
+    });
 }

package/dist/runtime/compaction.d.ts

@@ -42,6 +42,8 @@ export interface CompactMessagesOptions {
     /** Skip the threshold check (overflow recovery). */
     force?: boolean;
     abortSignal?: AbortSignal;
+    /** Real last-turn prompt tokens when available (replaces chars/4 for threshold). */
+    lastPromptTokens?: number;
 }
 /**
  * Pure compaction step: returns a new message list when compaction applied.

package/dist/runtime/compaction.js

@@ -64,10 +64,11 @@ function truncate(text, max) {
  * pairs are never split across the summary boundary.
  */
 export async function compactMessages(options) {
-    const { messages, model, config, force, abortSignal } = options;
+    const { messages, model, config, force, abortSignal, lastPromptTokens } = options;
     const triggerTokens = config.triggerTokens ?? DEFAULT_COMPACTION_TRIGGER_TOKENS;
     const keepRecent = config.keepRecentMessages ?? DEFAULT_COMPACTION_KEEP_RECENT;
-    const beforeTokens = estimateMessagesTokens(messages);
+    const estimatedTokens = estimateMessagesTokens(messages);
+    const beforeTokens = lastPromptTokens ?? estimatedTokens;
     if (!force && beforeTokens < triggerTokens) {
         return { compacted: false, reason: 'under-threshold', beforeTokens };
     }