@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/dist/traces/ids.js

@@ -0,0 +1,85 @@
+/**
+ * A turn's trace ids (R7.2, Q3): derived from the ids the log already holds, so every reader of
+ * the log (the projector, a replay of its slot, the trace route) gives the same ids, and keyed
+ * with the Tenant's trace key, so nobody computes them from a session id. Each is HMAC-SHA256
+ * under the key, cut to 16 bytes (a trace id) or 8 (a span id), as lowercase hex.
+ *
+ * - **trace**: `trace|<tenant>|<session>|<turn>`, unless the turn arrived with a `traceparent`
+ *   (R7.4): then that trace id.
+ * - **turn span**: `span|turn|<turn>`; every crossing's span is its child.
+ * - **effect span**: `span|effect|<effect id>`, for a model or tool call or a flow stage.
+ * - **egress span**: `span|egress|<session>|<seq>`, for one `egress.connection` row.
+ * - **event span**: `span|event|<session>|<seq>`, for a marker or a row without an effect id.
+ */
+import { createHmac } from "node:crypto";
+function hmacHex(key, input, bytes) {
+    const hex = createHmac("sha256", key).update(input).digest().subarray(0, bytes).toString("hex");
+    // An all-zero id is invalid in W3C trace context; one chance in 2^64 or worse.
+    return /^0+$/.test(hex) ? `${hex.slice(0, -1)}1` : hex;
+}
+export function traceIdOf(key, tenantId, sessionId, turnId) {
+    return hmacHex(key, `trace|${tenantId}|${sessionId}|${turnId}`, 16);
+}
+export function turnSpanOf(key, turnId) {
+    return hmacHex(key, `span|turn|${turnId}`, 8);
+}
+export function effectSpanOf(key, effectId) {
+    return hmacHex(key, `span|effect|${effectId}`, 8);
+}
+export function egressSpanOf(key, sessionId, seq) {
+    return hmacHex(key, `span|egress|${sessionId}|${seq}`, 8);
+}
+export function eventSpanOf(key, sessionId, seq) {
+    return hmacHex(key, `span|event|${sessionId}|${seq}`, 8);
+}
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+/**
+ * A `traceparent` as W3C trace context reads it: its trace id and parent span id, or undefined
+ * when it is malformed (version `ff`, an all-zero id, or another shape), which a receiver
+ * ignores. A version above `00` may carry more fields after the flags.
+ */
+export function parseTraceparent(value) {
+    const match = TRACEPARENT.exec(value.trim());
+    if (!match)
+        return undefined;
+    const [, version, traceId, spanId, , rest] = match;
+    if (version === "ff" || (version === "00" && rest !== undefined))
+        return undefined;
+    if (/^0+$/.test(traceId) || /^0+$/.test(spanId))
+        return undefined;
+    return { traceId: traceId, spanId: spanId };
+}
+/** The most `tracestate` the Runtime keeps (W3C: 32 members, 512 characters is enough). */
+const TRACESTATE_MAX = 512;
+/**
+ * The trace context a request's headers carry (R7.4), or undefined without a valid
+ * `traceparent`. A `tracestate` too long or with control characters is dropped, never the
+ * `traceparent`. Kept normalized: `00-<trace>-<span>-<flags>`.
+ */
+export function traceContextOf(headers) {
+    const raw = headers.get("traceparent");
+    if (!raw)
+        return undefined;
+    const parsed = parseTraceparent(raw);
+    if (!parsed)
+        return undefined;
+    const flags = raw.trim().slice(53, 55);
+    const traceparent = `00-${parsed.traceId}-${parsed.spanId}-${flags}`;
+    const state = headers.get("tracestate")?.trim();
+    return {
+        traceparent,
+        ...(state && state.length <= TRACESTATE_MAX && /^[\x20-\x7e]+$/.test(state) ? { tracestate: state } : {}),
+    };
+}
+/** `00-<trace>-<span>-01`: the context a turn or a crossing hands on (sampled). */
+export function traceparentOf(traceId, spanId) {
+    return `00-${traceId}-${spanId}-01`;
+}
+/**
+ * The trace id of turn `turnId`: the one its message arrived with (`inbound`, R7.4), else
+ * derived. The same as `turnTraceOf` reads from the turn's `command.message`.
+ */
+export function turnTraceIdOf(key, ids, inbound) {
+    return ((inbound ? parseTraceparent(inbound.traceparent)?.traceId : undefined) ??
+        traceIdOf(key, ids.tenantId, ids.sessionId, ids.turnId));
+}

package/dist/traces/key.d.ts

@@ -0,0 +1,6 @@
+import type { SessionStore, Tx } from "../store/types.js";
+import type { TraceKey } from "./ids.js";
+/** The Tenant's trace key, creating it when the Tenant has none. Call outside a transaction. */
+export declare function traceKey(store: SessionStore): Promise<TraceKey>;
+/** The trace key inside `t`, creating it when the Tenant has none. */
+export declare function traceKeyIn(t: Tx): Promise<TraceKey>;

package/dist/traces/key.js

@@ -0,0 +1,37 @@
+/**
+ * The Tenant's trace key (R7.2, Q3): 32 random bytes in the Tenant setting `trace.key` (base64),
+ * created on first use under the signing keys' lock, as the egress CA is. It is not sealed: it
+ * keys trace ids so nobody computes them from a session id, and anyone who can read the setting
+ * can read the log the ids point at. Core reads it in both process modes; the gateway never
+ * needs it (a tool call's `traceparent` is on its journal row, R7.4).
+ *
+ * Read once per store and kept: a Tenant reset keeps its settings.
+ */
+import { randomBytes } from "node:crypto";
+const SETTING = "trace.key";
+const keys = new WeakMap();
+/** The Tenant's trace key, creating it when the Tenant has none. Call outside a transaction. */
+export function traceKey(store) {
+    let key = keys.get(store);
+    if (!key) {
+        key = store.tx((t) => traceKeyIn(t));
+        // A failed read is tried again by the next caller.
+        key.catch(() => keys.delete(store));
+        keys.set(store, key);
+    }
+    return key;
+}
+/** The trace key inside `t`, creating it when the Tenant has none. */
+export async function traceKeyIn(t) {
+    const existing = await t.getSetting(SETTING);
+    if (existing !== undefined)
+        return Buffer.from(existing, "base64");
+    // Concurrent first uses would both create one: lock, then read what the winner made.
+    await t.lockSigningKeys();
+    const won = await t.getSetting(SETTING);
+    if (won !== undefined)
+        return Buffer.from(won, "base64");
+    const created = randomBytes(32);
+    await t.putSetting(SETTING, created.toString("base64"));
+    return created;
+}

package/dist/traces/map.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Row to span (R7.2): a pure function from one committed session event and its turn's trace to
+ * at most one OTLP span, so the projector, a replay of its slot and the trace route (R7.5) give
+ * the same spans. Nothing outside the row and the turn is read.
+ *
+ * | Row | Span |
+ * | --- | --- |
+ * | `turn.completed`, `turn.failed`, `turn.cancelled` | `invoke_agent {agentId}`, the turn's root (INTERNAL) |
+ * | `message.assistant`, `model.failed`, `context.compacted` | `chat {model}` (CLIENT) |
+ * | `tool.completed` | `execute_tool {toolName}` (INTERNAL) |
+ * | `node.completed` | `execute_tool {key}`, a flow's HTTP stage (INTERNAL) |
+ * | `effect.uncertain` | the call's span, with an error status |
+ * | `egress.connection` | `CONNECT {host}` (CLIENT) |
+ * | `turn.paused`, `command.approve`, `command.respond` | a marker with no length |
+ *
+ * Every other row, and every row without a turn, makes none. Every child's parent is the turn's
+ * span, so a child exported before its turn ends still joins it.
+ *
+ * Timing: a span with a gate's own measurement (`gate`, R7.1) is that measurement; any other ends
+ * at the row's time and starts `durationMs` before it (the journal's window, exported as
+ * `nylorun.effect.window_ms`). An egress span is the gate's: `startedAt` plus `durationMs`.
+ *
+ * Attribute names follow the OTel GenAI conventions at `GENAI_SEMCONV` (still in Development
+ * status), recorded on the resource as `nylorun.semconv.genai`; the rest are `nylorun.*`. A span
+ * never carries a person's id (`ownerUserId`, a subject, who approved), an identity header, an
+ * idempotency key or a credential value (the log holds none). Content (what a person said, the
+ * model's output, tool results and error messages) is left out unless the installation opts in
+ * per kind (`TraceContent`), each value cut at 8 KiB. Prompts are not in the log, so never here.
+ */
+import type { LiveEvent } from "@nylorun/core/contracts";
+import { type TraceKey } from "./ids.js";
+/** The commit of open-telemetry/semantic-conventions-genai whose attribute names spans use. */
+export declare const GENAI_SEMCONV = "open-telemetry/semantic-conventions-genai@6fd0d763a092db245a54104fc1124031eb3c51d2";
+/**
+ * The content an installation exports (Q4): `user` (what a person sent, on the turn's span),
+ * `outputs` (the model's text and tool calls, and a turn's output), `tool-results` and `errors`
+ * (error messages; their codes are always exported).
+ */
+export declare const TRACE_CONTENT_KINDS: readonly ["user", "outputs", "tool-results", "errors"];
+export type TraceContentKind = (typeof TRACE_CONTENT_KINDS)[number];
+export type TraceContent = ReadonlySet<TraceContentKind>;
+/** The most bytes of one content attribute or status message. */
+export declare const CONTENT_MAX_BYTES: number;
+/** OTLP span kinds and status codes (opentelemetry-proto `trace.proto`). */
+export declare const SPAN_KIND: {
+    readonly internal: 1;
+    readonly client: 3;
+};
+export declare const STATUS: {
+    readonly unset: 0;
+    readonly ok: 1;
+    readonly error: 2;
+};
+export interface OtlpAnyValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string;
+    doubleValue?: number;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+}
+export interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+/** One span as OTLP/HTTP JSON encodes it: hex ids, times as decimal nanosecond strings. */
+export interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+/**
+ * A turn's trace: its trace id, its span, and the context it arrived with (R7.4). Built from the
+ * turn's `command.message` (`turnTraceOf`), so it is the same wherever the log is read.
+ */
+export interface TurnTrace {
+    readonly traceId: string;
+    readonly spanId: string;
+    /** The span of the caller that sent the turn's message with a `traceparent`. */
+    readonly parentSpanId?: string;
+    /** Who sent the turn's message: its principal's kind, never its id. */
+    readonly principalKind?: string;
+    /** What a person sent, as `gen_ai.input.messages` (only with `user` content). */
+    readonly input?: string;
+}
+/** How spans are made: the trace key and the content the installation exports. */
+export interface SpanSettings {
+    readonly key: TraceKey;
+    readonly content: TraceContent;
+}
+/**
+ * The trace of turn `turnId` of session `sessionId`, from its `command.message` when the log has
+ * it: the inbound `traceparent`'s trace id and parent, else derived ids.
+ */
+export declare function turnTraceOf(settings: SpanSettings, ids: {
+    tenantId: string;
+    sessionId: string;
+    turnId: string;
+}, message?: Pick<LiveEvent, "payload" | "principal"> | undefined): TurnTrace;
+/** The span `row` makes in its turn's trace, or undefined when it makes none. */
+export declare function spanOf(row: LiveEvent, turn: TurnTrace, settings: SpanSettings): OtlpSpan | undefined;
+/** `value` cut to `CONTENT_MAX_BYTES` of UTF-8, never in the middle of a character. */
+export declare function truncate(value: string): string;

package/dist/traces/map.js

@@ -0,0 +1,317 @@
+import { effectSpanOf, egressSpanOf, eventSpanOf, parseTraceparent, traceIdOf, turnSpanOf } from "./ids.js";
+/** The commit of open-telemetry/semantic-conventions-genai whose attribute names spans use. */
+export const GENAI_SEMCONV = "open-telemetry/semantic-conventions-genai@6fd0d763a092db245a54104fc1124031eb3c51d2";
+/**
+ * The content an installation exports (Q4): `user` (what a person sent, on the turn's span),
+ * `outputs` (the model's text and tool calls, and a turn's output), `tool-results` and `errors`
+ * (error messages; their codes are always exported).
+ */
+export const TRACE_CONTENT_KINDS = ["user", "outputs", "tool-results", "errors"];
+/** The most bytes of one content attribute or status message. */
+export const CONTENT_MAX_BYTES = 8 * 1024;
+/** OTLP span kinds and status codes (opentelemetry-proto `trace.proto`). */
+export const SPAN_KIND = { internal: 1, client: 3 };
+export const STATUS = { unset: 0, ok: 1, error: 2 };
+/**
+ * The trace of turn `turnId` of session `sessionId`, from its `command.message` when the log has
+ * it: the inbound `traceparent`'s trace id and parent, else derived ids.
+ */
+export function turnTraceOf(settings, ids, message) {
+    const payload = (message?.payload ?? {});
+    const inbound = typeof payload.trace?.traceparent === "string" ? parseTraceparent(payload.trace.traceparent) : undefined;
+    const input = settings.content.has("user") && message ? userMessages(payload) : undefined;
+    return {
+        traceId: inbound?.traceId ?? traceIdOf(settings.key, ids.tenantId, ids.sessionId, ids.turnId),
+        spanId: turnSpanOf(settings.key, ids.turnId),
+        ...(inbound ? { parentSpanId: inbound.spanId } : {}),
+        ...(message?.principal ? { principalKind: message.principal.kind } : {}),
+        ...(input === undefined ? {} : { input }),
+    };
+}
+/** The span `row` makes in its turn's trace, or undefined when it makes none. */
+export function spanOf(row, turn, settings) {
+    if (row.turnId === null || row.visibility === "internal")
+        return undefined;
+    const p = (row.payload ?? {});
+    const base = new Attributes()
+        .str("gen_ai.conversation.id", row.sessionId)
+        .str("nylorun.turn.id", row.turnId)
+        .str("nylorun.event.cursor", row.cursor)
+        .str("nylorun.source.kind", row.source.kind)
+        // A client's source id is its principal, a person's id when it acts for one: never exported.
+        .str("nylorun.source.id", row.source.kind === "client" ? undefined : row.source.id)
+        .str("nylorun.evidence", row.evidence)
+        .str("nylorun.run.id", row.runId ?? undefined);
+    const child = (spanId, name, kind) => ({
+        traceId: turn.traceId,
+        spanId,
+        parentSpanId: turn.spanId,
+        name,
+        kind,
+    });
+    const effectSpan = (effectId) => typeof effectId === "string" && effectId.length > 0
+        ? effectSpanOf(settings.key, effectId)
+        : eventSpanOf(settings.key, row.sessionId, row.seq);
+    const content = (kind, value) => settings.content.has(kind) && value !== undefined ? truncate(typeof value === "string" ? value : JSON.stringify(value)) : undefined;
+    switch (row.type) {
+        case "turn.completed":
+        case "turn.failed":
+        case "turn.cancelled": {
+            const status = row.type.slice("turn.".length);
+            const totals = p.totals;
+            const error = row.type === "turn.failed" ? (p.error ?? {}) : undefined;
+            const attributes = base
+                .str("gen_ai.operation.name", "invoke_agent")
+                .str("gen_ai.agent.id", p.agentId)
+                .str("nylorun.turn.status", status)
+                .int("nylorun.turn.paused_ms", p.pausedMs)
+                .int("nylorun.turn.steps", totals?.steps)
+                .int("nylorun.turn.tokens", totals?.tokens)
+                .double("nylorun.usage.cost_usd", totals?.costUsd)
+                .str("nylorun.principal.kind", turn.principalKind)
+                .str("error.type", error ? (error.code ?? "turn.failed") : undefined)
+                .str("gen_ai.input.messages", turn.input)
+                .str("gen_ai.output.messages", row.type === "turn.completed" && p.output !== undefined && p.output !== null
+                ? content("outputs", [{ role: "assistant", parts: [textPart(p.output)] }])
+                : undefined);
+            return {
+                traceId: turn.traceId,
+                spanId: turn.spanId,
+                ...(turn.parentSpanId ? { parentSpanId: turn.parentSpanId } : {}),
+                name: typeof p.agentId === "string" ? `invoke_agent ${p.agentId}` : "invoke_agent",
+                kind: SPAN_KIND.internal,
+                ...window(row.time, p.durationMs),
+                attributes: attributes.list,
+                status: row.type === "turn.failed"
+                    ? errorStatus(content("errors", error?.message ?? p.message))
+                    : row.type === "turn.completed"
+                        ? { code: STATUS.ok }
+                        : { code: STATUS.unset },
+            };
+        }
+        case "message.assistant":
+        case "model.failed":
+        case "context.compacted": {
+            const model = p.model;
+            const metered = p.meteredUsage;
+            const reported = p.usage;
+            const usage = metered ?? reported;
+            const mismatch = metered !== undefined &&
+                reported !== undefined &&
+                (metered.inputTokens !== reported.inputTokens || metered.outputTokens !== reported.outputTokens);
+            const output = row.type === "message.assistant"
+                ? content("outputs", [
+                    {
+                        role: "assistant",
+                        parts: [
+                            ...(typeof p.text === "string" && p.text !== "" ? [{ type: "text", content: p.text }] : []),
+                            ...(p.toolCalls ?? []).map((call) => ({
+                                type: "tool_call",
+                                id: call.callId,
+                                name: call.name,
+                                arguments: call.input,
+                            })),
+                        ],
+                        ...(typeof p.finishReason === "string" ? { finish_reason: p.finishReason } : {}),
+                    },
+                ])
+                : undefined;
+            const attributes = base
+                .str("gen_ai.operation.name", "chat")
+                .str("gen_ai.provider.name", model?.provider)
+                .str("gen_ai.response.model", model?.model)
+                .strings("gen_ai.response.finish_reasons", typeof p.finishReason === "string" ? [p.finishReason] : undefined)
+                .int("gen_ai.usage.input_tokens", usage?.inputTokens)
+                .int("gen_ai.usage.output_tokens", usage?.outputTokens)
+                .int("gen_ai.usage.cache_read.input_tokens", metered?.cachedTokens)
+                .double("nylorun.usage.cost_usd", metered?.costUsd)
+                .str("nylorun.usage.source", metered ? "gate" : reported ? "harness" : undefined)
+                .bool("nylorun.usage.mismatch", mismatch ? true : undefined)
+                .double("gen_ai.response.time_to_first_chunk", typeof p.firstTokenMs === "number" ? p.firstTokenMs / 1000 : undefined)
+                .str("gen_ai.agent.id", p.agent?.id)
+                .str("nylorun.effect.id", p.effectId)
+                .int("nylorun.effect.window_ms", p.durationMs)
+                .str("nylorun.compaction.trigger", row.type === "context.compacted" ? p.trigger : undefined)
+                .bool("nylorun.compaction.partial", row.type === "context.compacted" && p.partial === true ? true : undefined)
+                .str("error.type", row.type === "model.failed" ? p.code : undefined)
+                .str("gen_ai.output.messages", output);
+            return {
+                ...child(effectSpan(p.effectId), model?.model ? `chat ${model.model}` : "chat", SPAN_KIND.client),
+                ...timesOf(row.time, p.gate, p.durationMs),
+                attributes: attributes.list,
+                status: row.type === "model.failed" ? errorStatus(content("errors", p.message)) : { code: STATUS.ok },
+            };
+        }
+        case "tool.completed":
+        case "node.completed": {
+            const node = row.type === "node.completed";
+            const name = String(node ? p.key : p.toolName);
+            const kind = p.kind;
+            const error = p.error;
+            const failed = p.status === "failed" || p.status === "cancelled" || error !== undefined;
+            const policy = p.policy;
+            const attributes = base
+                .str("gen_ai.operation.name", "execute_tool")
+                .str("gen_ai.tool.name", name)
+                .str("gen_ai.tool.call.id", node ? undefined : p.callId)
+                .str("gen_ai.tool.type", kind === "mcp" || kind === "http" ? "extension" : kind ? "function" : undefined)
+                .str("gen_ai.agent.id", p.agent?.id)
+                .str("nylorun.tool.kind", kind)
+                .str("nylorun.tool.server", p.server)
+                .str("nylorun.tool.status", p.status)
+                .int("nylorun.tool.attempts", p.attempts)
+                .int("nylorun.tool.redacted", p.redacted)
+                .str("nylorun.flow.path", node ? p.path : undefined)
+                .str("nylorun.policy.decision", policy?.decision)
+                .str("nylorun.policy.reason", policy?.reason)
+                .str("nylorun.effect.id", p.effectId)
+                .int("nylorun.effect.window_ms", p.durationMs)
+                .str("error.type", failed ? (error?.code ?? `tool.${p.status}`) : undefined)
+                .str("gen_ai.tool.call.result", node || p.output === undefined ? undefined : content("tool-results", p.output));
+            return {
+                ...child(effectSpan(p.effectId), `execute_tool ${name}`, SPAN_KIND.internal),
+                ...timesOf(row.time, p.gate, p.durationMs),
+                attributes: attributes.list,
+                status: failed ? errorStatus(content("errors", error?.message)) : { code: STATUS.ok },
+            };
+        }
+        case "effect.uncertain": {
+            const effectId = String(p.effectId ?? "");
+            const operation = effectId.includes(":tool:") ? "execute_tool" : "chat";
+            return {
+                ...child(effectSpan(effectId), operation, operation === "chat" ? SPAN_KIND.client : SPAN_KIND.internal),
+                ...window(row.time, undefined),
+                attributes: base
+                    .str("gen_ai.operation.name", operation)
+                    .str("nylorun.effect.id", effectId)
+                    .str("error.type", "effect.uncertain").list,
+                status: errorStatus(content("errors", p.message)),
+            };
+        }
+        case "egress.connection": {
+            const refused = p.outcome === "refused";
+            const started = Date.parse(String(p.startedAt));
+            const attributes = base
+                .str("server.address", p.host)
+                .int("server.port", p.port)
+                .str("nylorun.environment.id", p.environmentId)
+                .str("nylorun.egress.outcome", p.outcome)
+                .str("nylorun.egress.mode", p.mode)
+                .bool("nylorun.egress.credential_bound", p.credentialBound)
+                .strings("nylorun.egress.credential_ids", p.credentialIds)
+                .int("nylorun.egress.requests", p.requests)
+                .int("nylorun.egress.bytes_up", p.bytesUp)
+                .int("nylorun.egress.bytes_down", p.bytesDown)
+                .int("nylorun.egress.status", p.status)
+                .str("error.type", refused ? (p.reason ?? "refused") : undefined);
+            const times = Number.isFinite(started)
+                ? { start: started, end: started + Math.max(0, Math.round(Number(p.durationMs) || 0)) }
+                : undefined;
+            return {
+                ...child(egressSpanOf(settings.key, row.sessionId, row.seq), `CONNECT ${String(p.host)}`, SPAN_KIND.client),
+                ...(times
+                    ? { startTimeUnixNano: nanos(times.start), endTimeUnixNano: nanos(times.end) }
+                    : window(row.time, undefined)),
+                attributes: attributes.list,
+                status: refused ? errorStatus(undefined) : { code: STATUS.unset },
+            };
+        }
+        case "turn.paused":
+        case "command.approve":
+        case "command.respond": {
+            const interactions = (p.interactions ?? []);
+            const attributes = base
+                .str("nylorun.interaction.id", row.type === "turn.paused" ? undefined : p.interactionId)
+                .bool("nylorun.interaction.approved", row.type === "command.approve" ? p.approved === true : undefined)
+                .strings("nylorun.interaction.kinds", row.type === "turn.paused" ? interactions.map((entry) => String(entry.interaction?.kind ?? "")) : undefined)
+                .str("nylorun.principal.kind", row.type === "turn.paused" ? undefined : row.principal?.kind);
+            return {
+                ...child(eventSpanOf(settings.key, row.sessionId, row.seq), row.type, SPAN_KIND.internal),
+                ...window(row.time, undefined),
+                attributes: attributes.list,
+                status: { code: STATUS.unset },
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+/** Builds a span's attributes in order, leaving out absent values. */
+class Attributes {
+    list = [];
+    str(key, value) {
+        if (typeof value === "string" && value !== "")
+            this.list.push({ key, value: { stringValue: value } });
+        return this;
+    }
+    int(key, value) {
+        if (typeof value === "number" && Number.isFinite(value))
+            this.list.push({ key, value: { intValue: String(Math.round(value)) } });
+        return this;
+    }
+    double(key, value) {
+        if (typeof value === "number" && Number.isFinite(value))
+            this.list.push({ key, value: { doubleValue: value } });
+        return this;
+    }
+    bool(key, value) {
+        if (typeof value === "boolean")
+            this.list.push({ key, value: { boolValue: value } });
+        return this;
+    }
+    strings(key, value) {
+        if (Array.isArray(value) && value.length > 0)
+            this.list.push({ key, value: { arrayValue: { values: value.map((item) => ({ stringValue: String(item) })) } } });
+        return this;
+    }
+}
+/** Unix milliseconds as OTLP's decimal nanoseconds. */
+function nanos(ms) {
+    return (BigInt(Math.round(ms)) * 1000000n).toString();
+}
+/** Ends at the row's time and starts `durationMs` before it (no length without one). */
+function window(time, durationMs) {
+    const end = Date.parse(time);
+    const length = typeof durationMs === "number" && durationMs > 0 ? durationMs : 0;
+    return { startTimeUnixNano: nanos(end - length), endTimeUnixNano: nanos(end) };
+}
+/** The gate's own start and end when it measured the call, else the journal's window. */
+function timesOf(time, gate, durationMs) {
+    const measured = gate;
+    const start = Date.parse(String(measured?.startedAt));
+    const end = Date.parse(String(measured?.endedAt));
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start)
+        return { startTimeUnixNano: nanos(start), endTimeUnixNano: nanos(end) };
+    return window(time, durationMs);
+}
+function errorStatus(message) {
+    return { code: STATUS.error, ...(message ? { message } : {}) };
+}
+/** A GenAI message part for a value: text as is, anything else as JSON text. */
+function textPart(value) {
+    return { type: "text", content: typeof value === "string" ? value : JSON.stringify(value) };
+}
+/** What a person sent (`command.message`), as `gen_ai.input.messages`. */
+function userMessages(payload) {
+    const parts = typeof payload.content === "string"
+        ? [{ type: "text", content: payload.content }]
+        : Array.isArray(payload.parts)
+            ? payload.parts.map((part) => part.type === "text"
+                ? { type: "text", content: part.text ?? "" }
+                : { type: "file", artifact_id: part.artifactId, ...(part.version ? { version: part.version } : {}) })
+            : payload.data !== undefined
+                ? [textPart(payload.data)]
+                : undefined;
+    return parts ? truncate(JSON.stringify([{ role: "user", parts }])) : undefined;
+}
+/** `value` cut to `CONTENT_MAX_BYTES` of UTF-8, never in the middle of a character. */
+export function truncate(value) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length <= CONTENT_MAX_BYTES)
+        return value;
+    let end = CONTENT_MAX_BYTES;
+    // Back up over continuation bytes (10xxxxxx) to the start of the cut character.
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return bytes.subarray(0, end).toString("utf8");
+}

package/dist/traces/options.d.ts

@@ -0,0 +1,7 @@
+/** How spans are made beyond the log (R7.2): what they say of their source and what content they carry. */
+import type { TraceContent } from "./map.js";
+import type { TraceResource } from "./otlp.js";
+export interface TraceOptions {
+    readonly resource: TraceResource;
+    readonly content: TraceContent;
+}

package/dist/traces/options.js

@@ -0,0 +1 @@
+export {};

package/dist/traces/otlp.d.ts

@@ -0,0 +1,42 @@
+import { type OtlpKeyValue, type OtlpSpan } from "./map.js";
+/** What every batch says about its source: `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`. */
+export interface TraceResource {
+    /** `service.name`; default `nylorun`. */
+    readonly serviceName: string;
+    /** More resource attributes, as `OTEL_RESOURCE_ATTRIBUTES` sets them. */
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+export declare const DEFAULT_SERVICE_NAME = "nylorun";
+/** A batch of spans as an OTLP `ExportTraceServiceRequest` in JSON. */
+export declare function resourceSpans(resource: TraceResource, spans: readonly OtlpSpan[]): {
+    resourceSpans: {
+        resource: {
+            attributes: OtlpKeyValue[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: OtlpSpan[];
+        }[];
+    }[];
+};
+export interface OtlpPosterOptions {
+    /** The traces URL: `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, or the endpoint plus `/v1/traces`. */
+    readonly url: string;
+    /** `OTEL_EXPORTER_OTLP_HEADERS`. */
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly resource: TraceResource;
+    /** Tries after the first, for a `429`, a `5xx` or a lost connection. Default 3. */
+    readonly retries?: number;
+    /** The wait before the first retry, doubled for each one after. Default 500 ms. */
+    readonly backoffMs?: number;
+    /** How long one request may take. Default 10 s. */
+    readonly timeoutMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+/** Posts one batch; resolves `posted` or `dropped`, never rejects. */
+export type OtlpPoster = (spans: readonly OtlpSpan[], signal?: AbortSignal) => Promise<"posted" | "dropped">;
+export declare function createOtlpPoster(options: OtlpPosterOptions): OtlpPoster;