@kuralle-agents/core 0.12.0 → 0.14.0

package/dist/testing/mocks.js

@@ -37,12 +37,16 @@ export function createMockSession(partial = {}) {
         handoffHistory: partial.handoffHistory ?? [],
     };
 }
+function isAsyncIterable(value) {
+    return Symbol.asyncIterator in value;
+}
 export function createMockRuntime(parts, options = {}) {
     const sessions = options.sessions ?? new Map();
     const run = (opts) => {
         if (typeof parts === 'function') {
             throw parts();
         }
+        const eventSource = parts;
         options.onRun?.({
             sessionId: opts.sessionId,
             input: opts.input,
@@ -50,13 +54,13 @@ export function createMockRuntime(parts, options = {}) {
             seedMessages: opts.seedMessages,
         });
         async function* events() {
-            if (Symbol.asyncIterator in Object(parts)) {
-                for await (const part of parts) {
+            if (isAsyncIterable(eventSource)) {
+                for await (const part of eventSource) {
                     yield part;
                 }
                 return;
             }
-            for (const part of parts) {
+            for (const part of eventSource) {
                 yield part;
             }
         }

package/dist/tools/controlResults.d.ts

@@ -13,3 +13,17 @@ export declare function toolErrorResult(error: unknown): {
     error: true;
     message: string;
 };
+export interface ToolDeniedResult {
+    __denied: true;
+    toolName: string;
+    deniedBy?: string;
+    message: string;
+}
+/**
+ * What the model sees when a human declines a `needsApproval` tool it asked to run.
+ *
+ * A result rather than an error, so the agent can tell the user the request was declined
+ * instead of the turn dying. `__denied` (not `error: true`) keeps it distinguishable from a
+ * genuine failure — nothing malfunctioned.
+ */
+export declare function toolDeniedResult(toolName: string, deniedBy?: string): ToolDeniedResult;

package/dist/tools/controlResults.js

@@ -16,3 +16,18 @@ export function toolErrorResult(error) {
     const message = error instanceof Error ? error.message : String(error);
     return { error: true, message };
 }
+/**
+ * What the model sees when a human declines a `needsApproval` tool it asked to run.
+ *
+ * A result rather than an error, so the agent can tell the user the request was declined
+ * instead of the turn dying. `__denied` (not `error: true`) keeps it distinguishable from a
+ * genuine failure — nothing malfunctioned.
+ */
+export function toolDeniedResult(toolName, deniedBy) {
+    return {
+        __denied: true,
+        toolName,
+        deniedBy,
+        message: `The "${toolName}" action was not approved${deniedBy ? ` by ${deniedBy}` : ''}. Tell the user it was declined; do not retry it.`,
+    };
+}

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

@@ -9,6 +9,11 @@ export interface CoreToolExecutorConfig {
     parallelExecution?: boolean;
     agentId?: string;
     onInterim?: (message: string, toolName: string) => void;
+    /**
+     * Called for each chunk an async-iterable tool yields, as it arrives. The aggregate is
+     * still the tool's result; this is progress, not output.
+     */
+    onChunk?: (chunk: unknown, toolName: string, toolCallId: string) => void;
 }
 export interface CoreExecuteArgs {
     name: string;
@@ -26,6 +31,7 @@ export declare class CoreToolExecutor implements EffectToolExecutor {
     private readonly parallelExecution;
     private readonly agentId;
     private readonly onInterim?;
+    private readonly onChunk?;
     private readonly pairing;
     private executionGate;
     private callHistory;

package/dist/tools/effect/ToolExecutor.js

@@ -3,12 +3,44 @@ import { debug } from '../../debug.js';
 import { cancelledPlaceholder, inProgressPlaceholder, PairingTracker, } from './pairing.js';
 import { ToolTimeoutError } from './errors.js';
 import { ToolValidationError, validateAndSanitize, validateOutput } from './schema.js';
+import { isControlFlowSignal } from '../../runtime/controlFlowSignal.js';
+/**
+ * Merges the caller's abort with a timeout so the tool sees one signal. `AbortSignal.any` is
+ * present on Node 20+, Bun, and workerd; the manual path keeps older runtimes working.
+ * Mirrors `composeSignals` in `@kuralle-agents/fs`.
+ */
+function composeSignals(signal, timeoutSignal) {
+    if (!signal)
+        return timeoutSignal;
+    if (!timeoutSignal)
+        return signal;
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([signal, timeoutSignal]);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    timeoutSignal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted || timeoutSignal.aborted)
+        onAbort();
+    return controller.signal;
+}
+function rejectOnAbort(signal, makeError) {
+    return new Promise((_, reject) => {
+        if (signal.aborted) {
+            reject(makeError());
+            return;
+        }
+        signal.addEventListener('abort', () => reject(makeError()), { once: true });
+    });
+}
 export class CoreToolExecutor {
     tools;
     enforcer;
     parallelExecution;
     agentId;
     onInterim;
+    onChunk;
     pairing = new PairingTracker();
     executionGate = Promise.resolve();
     callHistory = [];
@@ -18,6 +50,7 @@ export class CoreToolExecutor {
         this.parallelExecution = config.parallelExecution ?? false;
         this.agentId = config.agentId ?? 'agent';
         this.onInterim = config.onInterim;
+        this.onChunk = config.onChunk;
     }
     getPairs() {
         return this.pairing.getAllPairs();
@@ -26,7 +59,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);
@@ -94,19 +130,14 @@ export class CoreToolExecutor {
             }
         }
         let interimTimer;
-        let timeoutTimer;
-        let interimSent = false;
         const onAbort = () => {
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
         };
         abortSignal?.addEventListener('abort', onAbort, { once: true });
         try {
             if (def.interim && def.interimAfterMs != null && def.interimAfterMs >= 0) {
                 interimTimer = setTimeout(() => {
-                    interimSent = true;
                     this.onInterim?.(def.interim, name);
                     this.pairing.closePair(requestId, 'in_progress', inProgressPlaceholder(requestId, name, def.interim));
                 }, def.interimAfterMs);
@@ -114,40 +145,36 @@ export class CoreToolExecutor {
                     interimTimer.unref();
                 }
             }
+            const timeoutMs = def.timeoutMs;
+            // The tool receives the timeout as an abort, so a cooperative tool stops working when
+            // we stop waiting for it. Racing alone abandoned the promise while the work continued.
+            const timeoutSignal = timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+            const effectiveSignal = composeSignals(abortSignal, timeoutSignal);
             const executeCtx = toolCtx
-                ? { ...toolCtx, abortSignal }
-                : abortSignal
-                    ? { abortSignal }
+                ? { ...toolCtx, abortSignal: effectiveSignal }
+                : effectiveSignal
+                    ? { abortSignal: effectiveSignal }
                     : undefined;
             const executePromise = Promise.resolve(def.execute(sanitizedArgs, executeCtx)).then(async (result) => {
                 if (result && typeof result[Symbol.asyncIterator] === 'function') {
                     const chunks = [];
                     for await (const chunk of result) {
                         chunks.push(chunk);
+                        // Surface progress as it arrives. Observational only — the journal records the
+                        // aggregate below, so a replayed step emits nothing and stays deterministic.
+                        this.onChunk?.(chunk, name, requestId);
                     }
                     return chunks.length === 1 ? chunks[0] : chunks;
                 }
                 return result;
             });
+            // The signals above cancel a cooperative tool; these racers stop us waiting on one that
+            // ignores them. Both are needed — neither alone bounds the call.
             const abortPromise = abortSignal && def.interruptible !== false
-                ? new Promise((_, reject) => {
-                    if (abortSignal.aborted) {
-                        reject(new DOMException('Aborted', 'AbortError'));
-                        return;
-                    }
-                    abortSignal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), { once: true });
-                })
+                ? rejectOnAbort(abortSignal, () => new DOMException('Aborted', 'AbortError'))
                 : null;
-            const timeoutMs = def.timeoutMs;
-            const timeoutPromise = timeoutMs != null && timeoutMs > 0
-                ? new Promise((_, reject) => {
-                    timeoutTimer = setTimeout(() => {
-                        reject(new ToolTimeoutError(name, timeoutMs));
-                    }, timeoutMs);
-                    if (typeof timeoutTimer === 'object' && 'unref' in timeoutTimer) {
-                        timeoutTimer.unref();
-                    }
-                })
+            const timeoutPromise = timeoutSignal
+                ? rejectOnAbort(timeoutSignal, () => new ToolTimeoutError(name, timeoutMs))
                 : null;
             const racers = [executePromise];
             if (abortPromise)
@@ -157,25 +184,16 @@ export class CoreToolExecutor {
             const rawResult = racers.length > 1 ? await Promise.race(racers) : await executePromise;
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
             const validated = await validateOutput(def.output, rawResult, name);
             callRecord.result = validated;
             callRecord.durationMs = Date.now() - callRecord.timestamp;
             this.callHistory.push(callRecord);
-            if (!interimSent) {
-                this.pairing.closePair(requestId, 'completed', validated);
-            }
-            else {
-                this.pairing.closePair(requestId, 'completed', validated);
-            }
+            this.pairing.closePair(requestId, 'completed', validated);
             return validated;
         }
         catch (error) {
             if (interimTimer)
                 clearTimeout(interimTimer);
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
             if (error instanceof DOMException && error.name === 'AbortError') {
                 const placeholder = cancelledPlaceholder(requestId, name);
                 callRecord.success = false;
@@ -189,6 +207,27 @@ export class CoreToolExecutor {
                 this.pairing.closePair(requestId, 'validation_failed', undefined, error.message);
                 throw error;
             }
+            if (error instanceof ToolTimeoutError || isControlFlowSignal(error)) {
+                // A timeout and a suspend are decisions about the run, not results the tool may
+                // reinterpret. They reach the caller unchanged.
+                throw error;
+            }
+            if (def.onError) {
+                // Recovery runs before the failure is recorded, so a handled error is journaled as
+                // the success it became. A throwing handler falls through to the generic path below.
+                try {
+                    const recovered = await def.onError(error instanceof Error ? error : new Error(String(error)), sanitizedArgs);
+                    const validatedRecovery = await validateOutput(def.output, recovered, name);
+                    callRecord.result = validatedRecovery;
+                    callRecord.durationMs = Date.now() - callRecord.timestamp;
+                    this.callHistory.push(callRecord);
+                    this.pairing.closePair(requestId, 'completed', validatedRecovery);
+                    return validatedRecovery;
+                }
+                catch (recoveryError) {
+                    error = recoveryError;
+                }
+            }
             const err = error instanceof Error ? error : new Error(String(error));
             callRecord.success = false;
             callRecord.error = err;

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

@@ -19,7 +19,18 @@ 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>;
+    /**
+     * Turns a thrown error into a result the model can act on, instead of a generic failure.
+     * Return a value to recover; rethrow (or omit this) to let the error propagate.
+     *
+     * Runs only for genuine failures — never for a timeout, an abort, an input/output schema
+     * violation, or a control-flow signal, all of which must stay distinguishable from a
+     * result the tool chose to return.
+     */
+    onError?: (error: Error, args: InferToolInput<S>) => Promise<R> | R;
 }): Tool<InferToolInput<S>, R>;
 export declare function toolToAiSdk<TInput = unknown, TOutput = unknown>(def: Tool<TInput, TOutput>): AiTool<TInput, TOutput>;
 export declare function buildToolSet(tools: Record<string, AnyTool>): ToolSet;

package/dist/tools/effect/defineTool.js

@@ -11,7 +11,10 @@ export function defineTool(config) {
         interimAfterMs: config.interimAfterMs ?? config.estimatedDurationMs,
         timeoutMs: config.timeoutMs,
         replay: config.replay,
+        parallelSafe: config.parallelSafe,
+        idempotencyKey: config.idempotencyKey,
         execute: config.execute,
+        onError: config.onError,
     };
 }
 export function toolToAiSdk(def) {

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

@@ -1,13 +1,10 @@
-/**
- * Thrown by `ctx.tool(...)` when a tool declared `needsApproval: true` is denied
- * by a human (the `__approval` signal resolves with `approved: false`). Catch it
- * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
- */
+/** Thrown when a tool execution exceeds its configured timeout. */
 export declare class ToolTimeoutError extends Error {
     readonly toolName: string;
     readonly timeoutMs: number;
     constructor(toolName: string, timeoutMs: number);
 }
+/** Thrown when a human denies a tool call that requires approval. */
 export declare class ToolApprovalDeniedError extends Error {
     readonly toolName: string;
     readonly by?: string;

package/dist/tools/effect/errors.js

@@ -1,8 +1,4 @@
-/**
- * Thrown by `ctx.tool(...)` when a tool declared `needsApproval: true` is denied
- * by a human (the `__approval` signal resolves with `approved: false`). Catch it
- * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
- */
+/** Thrown when a tool execution exceeds its configured timeout. */
 export class ToolTimeoutError extends Error {
     toolName;
     timeoutMs;
@@ -13,6 +9,7 @@ export class ToolTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/** Thrown when a human denies a tool call that requires approval. */
 export class ToolApprovalDeniedError extends Error {
     toolName;
     by;

package/dist/tools/index.d.ts

@@ -6,5 +6,4 @@ export { isFinalResult } from './final.js';
 export type { FinalResult } from './final.js';
 export { createHttpTool } from './http.js';
 export type { HttpToolConfig, HttpToolResult, HttpParam, ParamType, HttpMethod, AuthConfig, } from './http.types.js';
-export { withErrorHandling, executeWithRetry, createCircuitBreaker, withTimeout, isPermanentError, isCircuitOpenError, CircuitOpenError, ToolTimeoutError, type ToolErrorConfig, type ToolResult, } from './errorHandling.js';
 export { DEFAULT_ERROR_MESSAGES, getUserFriendlyError, categorizeError, createErrorResponse, type ErrorCategory, } from './errorMessages.js';

package/dist/tools/index.js

@@ -2,5 +2,4 @@ export { createTool, createToolWithFiller } from './Tool.js';
 export { createHandoffTool, isHandoffResult } from './handoff.js';
 export { isFinalResult } from './final.js';
 export { createHttpTool } from './http.js';
-export { withErrorHandling, executeWithRetry, createCircuitBreaker, withTimeout, isPermanentError, isCircuitOpenError, CircuitOpenError, ToolTimeoutError, } from './errorHandling.js';
 export { DEFAULT_ERROR_MESSAGES, getUserFriendlyError, categorizeError, createErrorResponse, } from './errorMessages.js';

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