@kuralle-agents/core 0.12.0 → 0.13.0

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;

package/dist/session/testing.js

@@ -21,6 +21,7 @@
  * `bun:test` into runtime bundles.
  */
 import { describe, test, expect, beforeEach } from 'bun:test';
+import { StaleWriteError } from './SessionStore.js';
 const buildSession = (overrides = {}) => {
     const now = new Date();
     return {
@@ -120,3 +121,36 @@ export function runSessionStoreContract(factory) {
         });
     });
 }
+/**
+ * Registers optimistic-concurrency (CAS) contract tests for SessionStore adapters.
+ * Two concurrent saves with the same expected version: exactly one succeeds.
+ */
+export function runSessionStoreCasContract(factory) {
+    describe('SessionStore CAS contract', () => {
+        let store;
+        beforeEach(async () => {
+            store = await factory();
+        });
+        test('concurrent save with same expected version rejects one writer with StaleWriteError', async () => {
+            const session = buildSession({ id: 'cas-sess' });
+            await store.save(session);
+            const firstRead = (await store.get('cas-sess'));
+            const secondRead = (await store.get('cas-sess'));
+            expect(firstRead.version).toBe(1);
+            expect(secondRead.version).toBe(1);
+            firstRead.workingMemory = { writer: 'a' };
+            secondRead.workingMemory = { writer: 'b' };
+            const results = await Promise.allSettled([
+                store.save(firstRead),
+                store.save(secondRead),
+            ]);
+            const fulfilled = results.filter((r) => r.status === 'fulfilled');
+            const rejected = results.filter((r) => r.status === 'rejected');
+            expect(fulfilled).toHaveLength(1);
+            expect(rejected).toHaveLength(1);
+            expect(rejected[0].reason).toBeInstanceOf(StaleWriteError);
+            const final = await store.get('cas-sess');
+            expect(final?.version).toBe(2);
+        });
+    });
+}

package/dist/session/utils.d.ts

@@ -1,4 +1,5 @@
 import type { Session } from '../types/index.js';
+import { type SessionStore } from './SessionStore.js';
 /**
  * Restores a Session from its serialized form.
  *
@@ -17,3 +18,5 @@ import type { Session } from '../types/index.js';
  * untouched in the key fields — callers are expected to have validated shape.
  */
 export declare function reviveSession(raw: unknown): Session;
+/** Apply a session mutation to the latest snapshot and retry it after CAS conflicts. */
+export declare function mutateSessionWithRetry(store: SessionStore, sessionId: string, mutator: (session: Session) => void | Promise<void>): Promise<Session>;

package/dist/session/utils.js

@@ -1,3 +1,5 @@
+import { StaleWriteError } from './SessionStore.js';
+const CAS_RETRIES = 8;
 /**
  * Restores a Session from its serialized form.
  *
@@ -45,3 +47,24 @@ export function reviveSession(raw) {
     ]));
     return session;
 }
+/** Apply a session mutation to the latest snapshot and retry it after CAS conflicts. */
+export async function mutateSessionWithRetry(store, sessionId, mutator) {
+    for (let attempt = 0; attempt < CAS_RETRIES; attempt++) {
+        const session = await store.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        await mutator(session);
+        try {
+            await store.save(session);
+            return (await store.get(sessionId)) ?? session;
+        }
+        catch (error) {
+            if (error instanceof StaleWriteError && attempt < CAS_RETRIES - 1) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error(`CAS retry limit exceeded for session: ${sessionId}`);
+}

package/dist/tools/effect/ToolExecutor.js

@@ -26,7 +26,10 @@ export class CoreToolExecutor {
         return this.tools.get(name);
     }
     async execute(args) {
-        if (!this.parallelExecution) {
+        const registryDef = this.tools.get(args.name);
+        const def = args.def ?? registryDef;
+        const parallelSafe = def?.parallelSafe === true || def?.replay === false;
+        if (!this.parallelExecution && !parallelSafe) {
             return this.withSerialGate(() => this.executeInner(args));
         }
         return this.executeInner(args);

package/dist/tools/effect/defineTool.d.ts

@@ -19,6 +19,8 @@ export declare function defineTool<S extends z.ZodTypeAny | StandardSchemaV1 | u
     estimatedDurationMs?: number;
     timeoutMs?: number;
     replay?: boolean;
+    parallelSafe?: boolean;
+    idempotencyKey?: (args: InferToolInput<S>) => string;
     execute: (args: InferToolInput<S>, ctx?: ToolContext) => Promise<R> | AsyncIterable<R>;
 }): Tool<InferToolInput<S>, R>;
 export declare function toolToAiSdk<TInput = unknown, TOutput = unknown>(def: Tool<TInput, TOutput>): AiTool<TInput, TOutput>;

package/dist/tools/effect/defineTool.js

@@ -11,6 +11,8 @@ export function defineTool(config) {
         interimAfterMs: config.interimAfterMs ?? config.estimatedDurationMs,
         timeoutMs: config.timeoutMs,
         replay: config.replay,
+        parallelSafe: config.parallelSafe,
+        idempotencyKey: config.idempotencyKey,
         execute: config.execute,
     };
 }

package/dist/tracing/MemoryTraceStore.d.ts

@@ -0,0 +1,16 @@
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+import { type TraceListWindow, type TraceStore } from './TraceStore.js';
+export interface MemoryTraceStoreOptions {
+    retentionMs?: number;
+}
+export declare class MemoryTraceStore implements TraceStore {
+    private readonly options;
+    private readonly spans;
+    constructor(options?: MemoryTraceStoreOptions);
+    write(span: AgentSpan): void;
+    putSpan(span: AgentSpan): void;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    cleanup(maxAgeMs: number): Promise<number>;
+    private cleanupSync;
+}

package/dist/tracing/MemoryTraceStore.js

@@ -0,0 +1,56 @@
+import { cloneSpan, traceFromSpans, } from './TraceStore.js';
+export class MemoryTraceStore {
+    options;
+    spans = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    write(span) {
+        this.putSpan(span);
+    }
+    putSpan(span) {
+        let trace = this.spans.get(span.traceId);
+        if (!trace) {
+            trace = new Map();
+            this.spans.set(span.traceId, trace);
+        }
+        trace.set(span.spanId, cloneSpan(span));
+        if (this.options.retentionMs !== undefined)
+            this.cleanupSync(this.options.retentionMs);
+    }
+    async getTrace(traceId) {
+        const spans = this.spans.get(traceId);
+        return traceFromSpans(spans ? [...spans.values()] : []);
+    }
+    async listTraces(sessionId, window) {
+        const traces = [...this.spans.values()]
+            .map((spans) => traceFromSpans([...spans.values()]))
+            .filter((trace) => trace !== null)
+            .filter((trace) => trace.sessionId === sessionId)
+            .filter((trace) => inWindow(trace.startedAt, window))
+            .sort((a, b) => b.startedAt - a.startedAt);
+        return window?.limit === undefined ? traces : traces.slice(0, window.limit);
+    }
+    async cleanup(maxAgeMs) {
+        return this.cleanupSync(maxAgeMs);
+    }
+    cleanupSync(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let removed = 0;
+        for (const [traceId, spans] of this.spans) {
+            const root = [...spans.values()].find((span) => span.kind === 'turn');
+            if ((root?.endTime ?? root?.startTime ?? 0) < cutoff) {
+                this.spans.delete(traceId);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+}
+function inWindow(timestamp, window) {
+    if (window?.from && timestamp < window.from.getTime())
+        return false;
+    if (window?.to && timestamp > window.to.getTime())
+        return false;
+    return true;
+}

package/dist/tracing/OtelTraceSink.d.ts

@@ -0,0 +1,127 @@
+import type { AgentSpan } from '../types/trace.js';
+import type { TraceSink } from './TraceStore.js';
+export interface OtelTraceSinkOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    serviceName?: string;
+    batchSize?: number;
+    fetch?: typeof fetch;
+}
+export declare class OtelTraceSink implements TraceSink {
+    private readonly options;
+    private readonly pending;
+    private exporting?;
+    constructor(options: OtelTraceSinkOptions);
+    write(span: AgentSpan): Promise<void> | void;
+    flush(): Promise<void>;
+    private export;
+}
+export declare function otelSink(options: OtelTraceSinkOptions): OtelTraceSink;
+export interface LangfuseSinkOptions {
+    endpoint?: string;
+    publicKey: string;
+    secretKey: string;
+    serviceName?: string;
+    batchSize?: number;
+    fetch?: typeof fetch;
+}
+export declare function langfuseSink(options: LangfuseSinkOptions): OtelTraceSink;
+export declare function toOtlpPayload(spans: AgentSpan[], serviceName?: string): {
+    resourceSpans: {
+        resource: {
+            attributes: {
+                key: string;
+                value: {
+                    stringValue: string;
+                };
+            }[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+            };
+            spans: {
+                name: string;
+                kind: number;
+                startTimeUnixNano: string;
+                endTimeUnixNano: string;
+                attributes: ({
+                    key: string;
+                    value: {
+                        boolValue: boolean;
+                        intValue?: undefined;
+                        doubleValue?: undefined;
+                        stringValue?: undefined;
+                    };
+                } | {
+                    key: string;
+                    value: {
+                        intValue: string;
+                        boolValue?: undefined;
+                        doubleValue?: undefined;
+                        stringValue?: undefined;
+                    };
+                } | {
+                    key: string;
+                    value: {
+                        doubleValue: number;
+                        boolValue?: undefined;
+                        intValue?: undefined;
+                        stringValue?: undefined;
+                    };
+                } | {
+                    key: string;
+                    value: {
+                        stringValue: string;
+                        boolValue?: undefined;
+                        intValue?: undefined;
+                        doubleValue?: undefined;
+                    };
+                })[];
+                events: {
+                    name: string;
+                    timeUnixNano: string;
+                    attributes: ({
+                        key: string;
+                        value: {
+                            boolValue: boolean;
+                            intValue?: undefined;
+                            doubleValue?: undefined;
+                            stringValue?: undefined;
+                        };
+                    } | {
+                        key: string;
+                        value: {
+                            intValue: string;
+                            boolValue?: undefined;
+                            doubleValue?: undefined;
+                            stringValue?: undefined;
+                        };
+                    } | {
+                        key: string;
+                        value: {
+                            doubleValue: number;
+                            boolValue?: undefined;
+                            intValue?: undefined;
+                            stringValue?: undefined;
+                        };
+                    } | {
+                        key: string;
+                        value: {
+                            stringValue: string;
+                            boolValue?: undefined;
+                            intValue?: undefined;
+                            doubleValue?: undefined;
+                        };
+                    })[];
+                }[];
+                status: {
+                    code: number;
+                };
+                parentSpanId?: string | undefined;
+                traceId: string;
+                spanId: string;
+            }[];
+        }[];
+    }[];
+};

package/dist/tracing/OtelTraceSink.js

@@ -0,0 +1,101 @@
+export class OtelTraceSink {
+    options;
+    pending = [];
+    exporting;
+    constructor(options) {
+        this.options = options;
+    }
+    write(span) {
+        this.pending.push(structuredClone(span));
+        if (this.pending.length >= (this.options.batchSize ?? 32))
+            return this.flush();
+    }
+    async flush() {
+        if (this.exporting)
+            await this.exporting;
+        if (this.pending.length === 0)
+            return;
+        const spans = this.pending.splice(0);
+        this.exporting = this.export(spans).finally(() => { this.exporting = undefined; });
+        await this.exporting;
+    }
+    async export(spans) {
+        const transport = this.options.fetch ?? globalThis.fetch;
+        const response = await transport(otlpUrl(this.options.endpoint), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...this.options.headers },
+            body: JSON.stringify(toOtlpPayload(spans, this.options.serviceName)),
+        });
+        if (!response.ok)
+            throw new Error(`OTLP trace export failed: ${response.status}`);
+    }
+}
+export function otelSink(options) {
+    return new OtelTraceSink(options);
+}
+export function langfuseSink(options) {
+    return new OtelTraceSink({
+        endpoint: options.endpoint ?? 'https://cloud.langfuse.com/api/public/otel',
+        headers: {
+            Authorization: `Basic ${btoa(`${options.publicKey}:${options.secretKey}`)}`,
+            'x-langfuse-ingestion-version': '4',
+        },
+        serviceName: options.serviceName,
+        batchSize: options.batchSize,
+        fetch: options.fetch,
+    });
+}
+export function toOtlpPayload(spans, serviceName = 'kuralle-agent') {
+    return {
+        resourceSpans: [{
+                resource: { attributes: [{ key: 'service.name', value: { stringValue: serviceName } }] },
+                scopeSpans: [{
+                        scope: { name: '@kuralle-agents/core' },
+                        spans: spans.map(toOtlpSpan),
+                    }],
+            }],
+    };
+}
+function toOtlpSpan(span) {
+    return {
+        traceId: normalizeHex(span.traceId, 32),
+        spanId: normalizeHex(span.spanId, 16),
+        ...(span.parentSpanId ? { parentSpanId: normalizeHex(span.parentSpanId, 16) } : {}),
+        name: span.name,
+        kind: 1,
+        startTimeUnixNano: millisecondsToNanos(span.startTime),
+        endTimeUnixNano: millisecondsToNanos(span.endTime ?? span.startTime),
+        attributes: [
+            otlpAttribute('kuralle.kind', span.kind),
+            ...Object.entries(span.attributes)
+                .filter(([, value]) => value !== undefined)
+                .map(([key, value]) => otlpAttribute(`kuralle.${key}`, value)),
+        ],
+        events: (span.events ?? []).map((event) => ({
+            name: event.name,
+            timeUnixNano: millisecondsToNanos(event.time),
+            attributes: Object.entries(event.attributes ?? {}).map(([key, value]) => otlpAttribute(`kuralle.${key}`, value)),
+        })),
+        status: { code: span.status === 'error' ? 2 : 1 },
+    };
+}
+function otlpAttribute(key, value) {
+    if (typeof value === 'boolean')
+        return { key, value: { boolValue: value } };
+    if (typeof value === 'number' && Number.isInteger(value))
+        return { key, value: { intValue: String(value) } };
+    if (typeof value === 'number')
+        return { key, value: { doubleValue: value } };
+    return { key, value: { stringValue: typeof value === 'string' ? value : JSON.stringify(value) } };
+}
+function normalizeHex(value, length) {
+    const hex = value.toLowerCase().replace(/[^0-9a-f]/g, '');
+    return hex.padStart(length, '0').slice(-length);
+}
+function millisecondsToNanos(value) {
+    return (BigInt(Math.trunc(value)) * 1000000n).toString();
+}
+function otlpUrl(endpoint) {
+    const trimmed = endpoint.replace(/\/$/, '');
+    return trimmed.endsWith('/v1/traces') ? trimmed : `${trimmed}/v1/traces`;
+}

package/dist/tracing/TraceStore.d.ts

@@ -0,0 +1,19 @@
+import type { AgentSpan, AgentTrace } from '../types/trace.js';
+export interface TraceListWindow {
+    from?: Date;
+    to?: Date;
+    limit?: number;
+}
+export interface TraceSink {
+    write(span: AgentSpan): void | Promise<void>;
+    flush?(): Promise<void>;
+}
+export interface TraceStore extends TraceSink {
+    putSpan(span: AgentSpan): void | Promise<void>;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    cleanup?(maxAgeMs: number): Promise<number>;
+}
+export declare function isTraceStore(sink: TraceSink): sink is TraceStore;
+export declare function traceFromSpans(spans: AgentSpan[]): AgentTrace | null;
+export declare function cloneSpan(span: AgentSpan): AgentSpan;

package/dist/tracing/TraceStore.js

@@ -0,0 +1,32 @@
+export function isTraceStore(sink) {
+    const value = sink;
+    return typeof value.putSpan === 'function' &&
+        typeof value.getTrace === 'function' &&
+        typeof value.listTraces === 'function';
+}
+export function traceFromSpans(spans) {
+    if (spans.length === 0)
+        return null;
+    const ordered = spans.map(cloneSpan).sort((a, b) => a.startTime - b.startTime);
+    const root = ordered.find((span) => span.kind === 'turn') ?? ordered[0];
+    const tools = ordered.filter((span) => span.kind === 'tool');
+    return {
+        traceId: root.traceId,
+        sessionId: root.attributes.sessionId,
+        spans: ordered,
+        answer: typeof root.attributes.output === 'string' ? root.attributes.output : '',
+        usedTool: tools.length > 0,
+        toolCalls: tools.map((span) => ({
+            name: span.attributes.toolName ?? span.name,
+            args: span.attributes.input ?? null,
+        })),
+        toolResults: tools
+            .filter((span) => span.attributes.output !== undefined)
+            .map((span) => ({ name: span.attributes.toolName ?? span.name, result: span.attributes.output })),
+        startedAt: root.startTime,
+        ...(root.endTime !== undefined ? { endedAt: root.endTime } : {}),
+    };
+}
+export function cloneSpan(span) {
+    return structuredClone(span);
+}

package/dist/tracing/index.d.ts

@@ -0,0 +1,3 @@
+export { MemoryTraceStore, type MemoryTraceStoreOptions } from './MemoryTraceStore.js';
+export { isTraceStore, traceFromSpans, type TraceListWindow, type TraceSink, type TraceStore, } from './TraceStore.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, type LangfuseSinkOptions, type OtelTraceSinkOptions, } from './OtelTraceSink.js';

package/dist/tracing/index.js

@@ -0,0 +1,3 @@
+export { MemoryTraceStore } from './MemoryTraceStore.js';
+export { isTraceStore, traceFromSpans, } from './TraceStore.js';
+export { OtelTraceSink, langfuseSink, otelSink, toOtlpPayload, } from './OtelTraceSink.js';

package/dist/tracing/testing.d.ts

@@ -0,0 +1,3 @@
+import type { TraceStore } from './TraceStore.js';
+export type TraceStoreFactory = () => TraceStore | Promise<TraceStore>;
+export declare function runTraceStoreContract(factory: TraceStoreFactory): void;

package/dist/tracing/testing.js

@@ -0,0 +1,45 @@
+/// <reference types="bun-types" />
+import { beforeEach, describe, expect, test } from 'bun:test';
+export function runTraceStoreContract(factory) {
+    describe('TraceStore contract', () => {
+        let store;
+        beforeEach(async () => { store = await factory(); });
+        test('writes spans and reconstructs a JSON-safe trace', async () => {
+            await store.putSpan(span('trace-a', 'session-a', 'root', 10, 'turn'));
+            await store.putSpan(span('trace-a', 'session-a', 'tool', 11, 'tool'));
+            const trace = await store.getTrace('trace-a');
+            expect(trace?.spans.map((entry) => entry.spanId)).toEqual(['root', 'tool']);
+            expect(trace?.sessionId).toBe('session-a');
+            expect(() => JSON.stringify(trace)).not.toThrow();
+        });
+        test('returns null for a missing trace', async () => {
+            expect(await store.getTrace('missing')).toBeNull();
+        });
+        test('lists newest traces for only the requested session and window', async () => {
+            await store.putSpan(span('old', 'session-a', 'old-root', 10, 'turn'));
+            await store.putSpan(span('new', 'session-a', 'new-root', 30, 'turn'));
+            await store.putSpan(span('other', 'session-b', 'other-root', 40, 'turn'));
+            const traces = await store.listTraces('session-a', { from: new Date(20), limit: 1 });
+            expect(traces.map((trace) => trace.traceId)).toEqual(['new']);
+        });
+        test('upserts a span by trace and span id', async () => {
+            const root = span('trace-a', 'session-a', 'root', 10, 'turn');
+            await store.write(root);
+            await store.putSpan({ ...root, endTime: 25 });
+            expect((await store.getTrace('trace-a'))?.spans).toHaveLength(1);
+            expect((await store.getTrace('trace-a'))?.endedAt).toBe(25);
+        });
+    });
+}
+function span(traceId, sessionId, spanId, startTime, kind) {
+    return {
+        traceId,
+        spanId,
+        name: kind,
+        kind,
+        startTime,
+        endTime: startTime + 5,
+        status: 'ok',
+        attributes: { sessionId },
+    };
+}

package/dist/types/agentConfig.d.ts

@@ -50,7 +50,8 @@ export interface AgentConfig {
     /** Pre-turn refinement policies. Default: none. */
     refine?: RefinementCapability[];
     experimental?: {
-        /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
+        /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1).
+         *  Default ON when the agent declares `flows`; OFF for answering-only agents. Override explicitly to opt out. */
         outOfBandControl?: boolean;
     };
     /** Portable workspace filesystem; auto-registers the durable `workspace` tool when set.

package/dist/types/channel.d.ts

@@ -1,4 +1,4 @@
-import type { ToolSet } from 'ai';
+import type { ModelMessage, ToolSet } from 'ai';
 import type { UserInputContent } from '../runtime/userInput.js';
 import type { RunContext } from './run-context.js';
 import type { FlowNode } from './flow.js';
@@ -34,6 +34,14 @@ export interface ChannelDriver {
      *  back to runAgentTurn, whose text the engine then discards. */
     runExtraction?(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;
 }
+export interface TurnUsageSnapshot {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+    /** Input tokens on the final model call, i.e. current context-window occupancy. */
+    contextTokens?: number;
+}
 export interface TurnResult {
     text: string;
     toolResults: ToolResultRecord[];
@@ -43,6 +51,11 @@ export interface TurnResult {
     confidence?: number;
     /** Native realtime post-hoc gate: provider audio already played; gate is advisory only. */
     gateScope?: 'advisory';
+    /** AI-SDK tool round-trip messages (assistant tool-call + tool-result) produced this turn,
+     *  so the host loop can persist them to history in free conversation (G18). */
+    toolMessages?: ModelMessage[];
+    /** Real token usage from the AI SDK when the driver captured it. */
+    usage?: TurnUsageSnapshot;
 }
 export type UserSignal = {
     type: 'message';

package/dist/types/effectTool.d.ts

@@ -12,6 +12,10 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
     timeoutMs?: number;
     /** When false, the durable journal always re-executes this tool instead of returning a cached step result — for observation/mutation tools (fs, shell) whose result must be fresh. Default true. */
     replay?: boolean;
+    /** When true, the tool may run concurrently with other parallel-safe tools in the same model turn. */
+    parallelSafe?: boolean;
+    /** Override the auto-derived effect key (`idempotencyKey(logicalRunId, callsite, {name,args})`). Use when args are not a stable identity (e.g. a nonce). */
+    idempotencyKey?: (args: TInput) => string;
     execute: (args: TInput, ctx?: ToolContext) => Promise<TOutput> | AsyncIterable<TOutput>;
 }
 export type AnyTool = Tool<any, any>;

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './tool.js';
 export * from './effectTool.js';
 export * from './voice.js';
 export * from './runtime.js';
+export * from './trace.js';
 export type * from '../audit/types.js';
 export type * from '../outcomes/index.js';
 export type * from '../channels/index.js';

package/dist/types/index.js

@@ -10,3 +10,4 @@ export * from './tool.js';
 export * from './effectTool.js';
 export * from './voice.js';
 export * from './runtime.js';
+export * from './trace.js';