@retinue/agentkit 0.1.0

package/dist/telemetry/noop.js

@@ -0,0 +1,143 @@
+/**
+ * Telemetry that does nothing, and the in-memory telemetry the tests assert on.
+ *
+ * `NOOP_TELEMETRY` is why no call site has an `if (telemetry)`. Optional-and-checked would be checked in
+ * nineteen places and forgotten in the twentieth, and the forgotten one is a crash rather than a missing span.
+ *
+ * `createRecordingTelemetry` is the same port over arrays. It is what makes AC-1, AC-2 and AC-5 assertable
+ * without a collector: the redaction test needs to see the *actual bytes* a sink would write, and a mock that
+ * captured the call arguments would prove the caller's intent rather than the output.
+ */
+import { boundMetricAttributes } from "./metrics.js";
+import { formatLogLine, redactFields } from "./redaction.js";
+import { formatTraceparent, parseTraceparent, TRACE_FLAG_SAMPLED } from "./trace-context.js";
+const NOOP_RECORDER = { record: () => { } };
+const NOOP_SPAN = {
+    context: { traceId: "0".repeat(32), spanId: "0".repeat(16), traceFlags: 0 },
+    setAttributes: () => { },
+    recordError: () => { },
+    setStatus: () => { },
+    end: () => { },
+};
+const NOOP_LOGGER = { log: () => { }, child: () => NOOP_LOGGER };
+export const NOOP_TELEMETRY = {
+    tracer: { startSpan: () => NOOP_SPAN },
+    meter: { counter: () => NOOP_RECORDER, histogram: () => NOOP_RECORDER, gauge: () => NOOP_RECORDER },
+    logger: NOOP_LOGGER,
+};
+/**
+ * Deterministic ids.
+ *
+ * A counter, not randomness. The property worth asserting is "the worker's span carries the API host's trace
+ * id", and that is untestable against a random source — you can only check the two happen to be equal, which is
+ * also true of two random values one time in 2^128 and, more usefully, is what a bug producing a *constant* id
+ * would also satisfy.
+ */
+const sequentialIds = () => {
+    let trace = 0;
+    let span = 0;
+    return {
+        traceId: () => (++trace).toString(16).padStart(32, "0"),
+        spanId: () => (++span).toString(16).padStart(16, "0"),
+    };
+};
+export const createRecordingTelemetry = (base = { tenantId: "t1" }, now = () => "2026-08-23T12:00:00.000Z") => {
+    const spans = [];
+    const metrics = [];
+    const logs = [];
+    const lines = [];
+    const ids = sequentialIds();
+    const tracer = {
+        startSpan(name, options = {}) {
+            const parent = parseTraceparent(options.parent);
+            // The parent's trace id, or a new one. This single line is AC-1: the worker passes the job's traceparent
+            // and lands in the API host's trace rather than starting its own.
+            const traceId = parent?.traceId ?? ids.traceId();
+            const spanId = ids.spanId();
+            const record = {
+                name,
+                kind: options.kind ?? "internal",
+                traceId,
+                spanId,
+                parentSpanId: parent?.spanId ?? null,
+                attributes: { ...(options.attributes ?? {}) },
+                status: "unset",
+                errorCode: null,
+                ended: false,
+            };
+            spans.push(record);
+            return {
+                context: { traceId, spanId, traceFlags: parent?.traceFlags ?? TRACE_FLAG_SAMPLED },
+                setAttributes(attributes) {
+                    Object.assign(record.attributes, attributes);
+                },
+                recordError({ code }) {
+                    record.errorCode = code;
+                },
+                setStatus(status) {
+                    record.status = status;
+                },
+                end() {
+                    record.ended = true;
+                },
+            };
+        },
+    };
+    const recorder = (instrument) => ({
+        record(value, attributes) {
+            // Bounded here, in the *implementation*, so a call site that passes a run id cannot create a series. The
+            // test that proves this passes an unbounded attribute deliberately.
+            metrics.push({ instrument, value, attributes: boundMetricAttributes(attributes) });
+        },
+    });
+    const meter = {
+        counter: (name) => recorder(name),
+        histogram: (name) => recorder(name),
+        gauge: (name) => recorder(name),
+    };
+    const makeLogger = (context) => ({
+        log(level, event, raw) {
+            const { fields, dropped } = redactFields(raw);
+            const record = { level, event, context, fields, at: now() };
+            logs.push(record);
+            lines.push(formatLogLine({ ...record, context: context }));
+            if (dropped.length > 0) {
+                // The *names* of what was dropped, never the values, and as its own line rather than a field on this
+                // one: a redaction that quietly removed a field would look to whoever needs it like the field was never
+                // set, and they would go looking in the wrong place.
+                const notice = {
+                    level: "debug",
+                    event: "telemetry.fields-dropped",
+                    context,
+                    fields: { count: dropped.length, reason: dropped.slice(0, 8).join(",").slice(0, 120) },
+                    at: now(),
+                };
+                logs.push(notice);
+                lines.push(formatLogLine({ ...notice, context: context }));
+            }
+        },
+        child(extra) {
+            return makeLogger({ ...context, ...extra });
+        },
+    });
+    return {
+        tracer,
+        meter,
+        logger: makeLogger(base),
+        get spans() {
+            return spans;
+        },
+        get metrics() {
+            return metrics;
+        },
+        get logs() {
+            return logs;
+        },
+        get lines() {
+            return lines;
+        },
+    };
+};
+/** The traceparent for a span, for putting into a job payload or an outbound header. */
+export const traceparentOf = (span) => formatTraceparent(span.context);
+//# sourceMappingURL=noop.js.map

package/dist/telemetry/redaction.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The redaction boundary — AC-5.
+ *
+ * "No prompt content, message content or credential ever appears in logs" is the failure mode discovered too
+ * late: it is found by someone reading a log aggregator, months after the line was added, and by then the data
+ * is in a third-party index and a backup.
+ *
+ * **An allowlist, not a denylist.** This is the whole design. A denylist has to name every field that must not
+ * be logged, forever, including the one a colleague adds next month. An allowlist names the fields that may be,
+ * and anything else is dropped without being asked about. The failure direction is "an incident is missing a
+ * field", not "a prompt is in Datadog".
+ *
+ * Three properties beyond the list:
+ *
+ * **Primitives only.** A nested object is where content hides — `{ input: {...} }` on a tool log line is one
+ * keystroke from being the whole tool input. An object value is dropped even if its key is allowlisted.
+ *
+ * **Strings are bounded.** An allowlisted key can still be *handed* content: nothing stops a caller passing
+ * prose as `toolName`. A short cap means the leak is a truncated fragment rather than a document, and a value
+ * that hits the cap is visibly truncated, which is how someone notices the bug.
+ *
+ * **A dropped field is reported, not silent.** `redactFields` returns what it removed so the logger can emit
+ * `telemetry.fields-dropped`. Silent dropping turns redaction into invisible data loss, and the person
+ * debugging finds an empty field rather than an explanation.
+ */
+import type { AttributeValue } from "./index.js";
+/**
+ * The fields any log line or span may carry.
+ *
+ * Ids, names from closed sets, counts, durations, and classified codes. Nothing whose value is authored by a
+ * user or a model. Read the list as the answer to "what can this platform tell you about a failure?" — if it is
+ * not here, the answer is a metric or a trace, not a log field.
+ */
+export declare const LOG_FIELD_ALLOWLIST: readonly string[];
+/**
+ * The cap on a string field.
+ *
+ * 120 characters: comfortably longer than every id, model name and error code in the list, and far shorter than
+ * a prompt, a message or a signed URL. Deliberately not generous — the cap is a *bound on a leak*, and a
+ * generous bound is a leak.
+ */
+export declare const MAX_FIELD_LENGTH = 120;
+export declare const TRUNCATION_MARKER = "\u2026[truncated]";
+export type Redacted = {
+    readonly fields: Readonly<Record<string, AttributeValue>>;
+    /** The keys that were removed, so the caller can say so. Names only — never the values. */
+    readonly dropped: readonly string[];
+};
+export declare const redactFields: (input: Readonly<Record<string, unknown>> | undefined) => Redacted;
+/**
+ * A log record as a single line of JSON.
+ *
+ * Serialized here rather than by the sink, so every sink emits the same shape and the redaction cannot be
+ * bypassed by a sink that formats the record itself. The context is spread at the top level, because a query
+ * for `runId:...` in a log aggregator should not need to know it is nested.
+ */
+export declare const formatLogLine: (record: {
+    readonly level: string;
+    readonly event: string;
+    readonly at: string;
+    readonly context: Readonly<Record<string, string | undefined>>;
+    readonly fields: Readonly<Record<string, AttributeValue>>;
+}) => string;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/telemetry/redaction.js

@@ -0,0 +1,153 @@
+/**
+ * The redaction boundary — AC-5.
+ *
+ * "No prompt content, message content or credential ever appears in logs" is the failure mode discovered too
+ * late: it is found by someone reading a log aggregator, months after the line was added, and by then the data
+ * is in a third-party index and a backup.
+ *
+ * **An allowlist, not a denylist.** This is the whole design. A denylist has to name every field that must not
+ * be logged, forever, including the one a colleague adds next month. An allowlist names the fields that may be,
+ * and anything else is dropped without being asked about. The failure direction is "an incident is missing a
+ * field", not "a prompt is in Datadog".
+ *
+ * Three properties beyond the list:
+ *
+ * **Primitives only.** A nested object is where content hides — `{ input: {...} }` on a tool log line is one
+ * keystroke from being the whole tool input. An object value is dropped even if its key is allowlisted.
+ *
+ * **Strings are bounded.** An allowlisted key can still be *handed* content: nothing stops a caller passing
+ * prose as `toolName`. A short cap means the leak is a truncated fragment rather than a document, and a value
+ * that hits the cap is visibly truncated, which is how someone notices the bug.
+ *
+ * **A dropped field is reported, not silent.** `redactFields` returns what it removed so the logger can emit
+ * `telemetry.fields-dropped`. Silent dropping turns redaction into invisible data loss, and the person
+ * debugging finds an empty field rather than an explanation.
+ */
+/**
+ * The fields any log line or span may carry.
+ *
+ * Ids, names from closed sets, counts, durations, and classified codes. Nothing whose value is authored by a
+ * user or a model. Read the list as the answer to "what can this platform tell you about a failure?" — if it is
+ * not here, the answer is a metric or a trace, not a log field.
+ */
+export const LOG_FIELD_ALLOWLIST = [
+    // Correlation. Also present on the record's `context`; allowed here so a line about a *different* run than
+    // the bound one can name it.
+    "tenantId",
+    "conversationId",
+    "runId",
+    "principalId",
+    "requestId",
+    "traceId",
+    "spanId",
+    "interactionId",
+    "jobId",
+    "workerId",
+    // What happened, from closed sets
+    "status",
+    "outcome",
+    "decision",
+    "reason",
+    "eventType",
+    "partType",
+    "riskCategory",
+    "toolName",
+    "modelId",
+    "providerId",
+    "agentId",
+    "skillId",
+    "graderId",
+    "sourceType",
+    "period",
+    // Classified failures. A *code*, never a message.
+    "errorCode",
+    "retryable",
+    "attempt",
+    "maxAttempts",
+    // Numbers
+    "durationMs",
+    "waitMs",
+    "latencyMs",
+    "queueDepth",
+    "count",
+    "sequence",
+    "stepCount",
+    "toolCallCount",
+    "inputTokens",
+    "outputTokens",
+    "cachedInputTokens",
+    "reasoningTokens",
+    "costMinorUnits",
+    "currency",
+    "byteSize",
+    "version",
+    "expectedVersion",
+    "limit",
+    "chunkCount",
+    "resultCount",
+    "score",
+];
+const ALLOWED = new Set(LOG_FIELD_ALLOWLIST);
+/**
+ * The cap on a string field.
+ *
+ * 120 characters: comfortably longer than every id, model name and error code in the list, and far shorter than
+ * a prompt, a message or a signed URL. Deliberately not generous — the cap is a *bound on a leak*, and a
+ * generous bound is a leak.
+ */
+export const MAX_FIELD_LENGTH = 120;
+export const TRUNCATION_MARKER = "…[truncated]";
+export const redactFields = (input) => {
+    if (input === undefined)
+        return { fields: {}, dropped: [] };
+    const fields = {};
+    const dropped = [];
+    for (const [key, value] of Object.entries(input)) {
+        if (!ALLOWED.has(key)) {
+            dropped.push(key);
+            continue;
+        }
+        if (typeof value === "number") {
+            // NaN and Infinity serialize as `null` in JSON, which reads as "no value" rather than "a bad value".
+            if (!Number.isFinite(value)) {
+                dropped.push(key);
+                continue;
+            }
+            fields[key] = value;
+            continue;
+        }
+        if (typeof value === "boolean") {
+            fields[key] = value;
+            continue;
+        }
+        if (typeof value === "string") {
+            fields[key] =
+                value.length > MAX_FIELD_LENGTH ? `${value.slice(0, MAX_FIELD_LENGTH)}${TRUNCATION_MARKER}` : value;
+            continue;
+        }
+        // Everything else — objects, arrays, functions, null, undefined, symbols, bigint. An object is dropped even
+        // under an allowlisted key, because the key says nothing about what a nested value contains.
+        dropped.push(key);
+    }
+    return { fields, dropped };
+};
+/**
+ * A log record as a single line of JSON.
+ *
+ * Serialized here rather than by the sink, so every sink emits the same shape and the redaction cannot be
+ * bypassed by a sink that formats the record itself. The context is spread at the top level, because a query
+ * for `runId:...` in a log aggregator should not need to know it is nested.
+ */
+export const formatLogLine = (record) => {
+    const flat = { at: record.at, level: record.level, event: record.event };
+    for (const [key, value] of Object.entries(record.context))
+        if (value !== undefined)
+            flat[key] = value;
+    // Fields last, but they cannot overwrite `event` or `level`: a field named `event` would make a line claim to
+    // be a different event than the one that was logged, which is the one lie a log must not be able to tell.
+    for (const [key, value] of Object.entries(record.fields))
+        if (key !== "at" && key !== "level" && key !== "event")
+            flat[key] = value;
+    return JSON.stringify(flat);
+};
+//# sourceMappingURL=redaction.js.map

package/dist/telemetry/spans.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Span names — AC-2: "spans align with the existing run event types, so traces and event history correspond".
+ *
+ * The alignment is a **total map keyed by `RunEventType`**, so adding an event type without deciding on its span
+ * is a compile error. A `Record<string, string>` here would let a new event type land with no span and the
+ * mismatch would only be found by someone comparing a trace against an event log during an incident — which is
+ * exactly when they can least afford to.
+ *
+ * Names follow the event names, which is not laziness: an operator holding a trace and an event history is
+ * matching them by eye, and a span called `agent.inference` next to a `model.called` event costs a lookup every
+ * time. The same word means the same thing in both places.
+ */
+import { type RunEventType } from "../core/events.js";
+/**
+ * Every run event's span name.
+ *
+ * Several events map to the *same* span deliberately — `part.added` and `part.updated` are both activity within
+ * a run, not boundaries worth their own span, and a span per streamed part would produce thousands per run and
+ * bury the ones that matter. They still get a span *name* rather than being excluded, because "this event has
+ * no span" is a decision that must be visible, and an omission looks identical to an oversight.
+ */
+export declare const SPAN_FOR_RUN_EVENT: Readonly<Record<RunEventType, string>>;
+/**
+ * The spans that are *not* run events.
+ *
+ * The request and the claim have no event type — a run event exists once there is a run, and these happen
+ * before or around that. Listed here so the full set of span names has one home; a name invented at a call site
+ * is a name nothing can check.
+ */
+export declare const BOUNDARY_SPANS: {
+    /** The inbound GraphQL operation. `server` kind — the root of the trace. */
+    readonly request: "http.request";
+    /** Quota and authorization, before anything is claimed or enqueued. */
+    readonly admission: "run.admit";
+    /** The producer side of the queue. Where the `traceparent` is written into the job. */
+    readonly enqueue: "run.enqueue";
+    /** The consumer side. Where the `traceparent` is read back and the trace continues. */
+    readonly claim: "run.claim";
+    /** One model call. */
+    readonly model: "model.call";
+    /** One tool call. */
+    readonly tool: "tool.call";
+    /** Waiting for a human. Often the longest span in a trace, and the one an operator most wants to see. */
+    readonly approvalWait: "hitl.approval";
+};
+export type BoundarySpan = (typeof BOUNDARY_SPANS)[keyof typeof BOUNDARY_SPANS];
+/** Every span name the platform emits. Used by the test that asserts the two sets agree. */
+export declare const ALL_SPAN_NAMES: readonly string[];
+/**
+ * The span a run event belongs to.
+ *
+ * A function rather than direct map access, so a caller holding a `RunEventType` from a store — where the type
+ * is a string at runtime — cannot index into `undefined` and produce a span named "undefined".
+ */
+export declare const spanForRunEvent: (type: string) => string | null;
+//# sourceMappingURL=spans.d.ts.map

package/dist/telemetry/spans.js

@@ -0,0 +1,78 @@
+/**
+ * Span names — AC-2: "spans align with the existing run event types, so traces and event history correspond".
+ *
+ * The alignment is a **total map keyed by `RunEventType`**, so adding an event type without deciding on its span
+ * is a compile error. A `Record<string, string>` here would let a new event type land with no span and the
+ * mismatch would only be found by someone comparing a trace against an event log during an incident — which is
+ * exactly when they can least afford to.
+ *
+ * Names follow the event names, which is not laziness: an operator holding a trace and an event history is
+ * matching them by eye, and a span called `agent.inference` next to a `model.called` event costs a lookup every
+ * time. The same word means the same thing in both places.
+ */
+import { RUN_EVENT_TYPES } from "../core/events.js";
+/**
+ * Every run event's span name.
+ *
+ * Several events map to the *same* span deliberately — `part.added` and `part.updated` are both activity within
+ * a run, not boundaries worth their own span, and a span per streamed part would produce thousands per run and
+ * bury the ones that matter. They still get a span *name* rather than being excluded, because "this event has
+ * no span" is a decision that must be visible, and an omission looks identical to an oversight.
+ */
+export const SPAN_FOR_RUN_EVENT = {
+    "run.queued": "run.enqueue",
+    "run.started": "run.execute",
+    "run.checkpointed": "run.checkpoint",
+    "run.completed": "run.execute",
+    "run.failed": "run.execute",
+    "run.cancelled": "run.execute",
+    "run.retry-pending": "run.retry",
+    "part.added": "run.step",
+    "part.updated": "run.step",
+    "tool.started": "tool.call",
+    "tool.completed": "tool.call",
+    "tool.failed": "tool.call",
+    "question.requested": "hitl.question",
+    "question.answered": "hitl.question",
+    "approval.requested": "hitl.approval",
+    "approval.decided": "hitl.approval",
+    "usage.updated": "run.step",
+    "context.compacted": "context.compact",
+};
+/**
+ * The spans that are *not* run events.
+ *
+ * The request and the claim have no event type — a run event exists once there is a run, and these happen
+ * before or around that. Listed here so the full set of span names has one home; a name invented at a call site
+ * is a name nothing can check.
+ */
+export const BOUNDARY_SPANS = {
+    /** The inbound GraphQL operation. `server` kind — the root of the trace. */
+    request: "http.request",
+    /** Quota and authorization, before anything is claimed or enqueued. */
+    admission: "run.admit",
+    /** The producer side of the queue. Where the `traceparent` is written into the job. */
+    enqueue: "run.enqueue",
+    /** The consumer side. Where the `traceparent` is read back and the trace continues. */
+    claim: "run.claim",
+    /** One model call. */
+    model: "model.call",
+    /** One tool call. */
+    tool: "tool.call",
+    /** Waiting for a human. Often the longest span in a trace, and the one an operator most wants to see. */
+    approvalWait: "hitl.approval",
+};
+/** Every span name the platform emits. Used by the test that asserts the two sets agree. */
+export const ALL_SPAN_NAMES = [
+    ...new Set([...Object.values(SPAN_FOR_RUN_EVENT), ...Object.values(BOUNDARY_SPANS)]),
+];
+/**
+ * The span a run event belongs to.
+ *
+ * A function rather than direct map access, so a caller holding a `RunEventType` from a store — where the type
+ * is a string at runtime — cannot index into `undefined` and produce a span named "undefined".
+ */
+export const spanForRunEvent = (type) => RUN_EVENT_TYPES.includes(type)
+    ? SPAN_FOR_RUN_EVENT[type]
+    : null;
+//# sourceMappingURL=spans.js.map

package/dist/telemetry/trace-context.d.ts

@@ -0,0 +1,55 @@
+/**
+ * W3C trace context — the wire format that makes AC-1 possible.
+ *
+ * A run is enqueued by the API host and executed by a worker in a different process, possibly minutes later.
+ * The only thing that can join them into one trace is a `traceparent` travelling in the job payload, so this is
+ * the parsing and formatting of that string and nothing else.
+ *
+ * Chosen over a bespoke correlation id because the format is what every collector already understands. A
+ * home-grown id would work exactly as well right up to the point a customer pointed their own tooling at it,
+ * which is AC-6.
+ */
+/** Only version 00 exists. A future version must be *ignored*, not guessed at — see `parseTraceparent`. */
+export declare const TRACEPARENT_VERSION = "00";
+export declare const TRACE_ID_LENGTH = 32;
+export declare const SPAN_ID_LENGTH = 16;
+/**
+ * The sampled bit, as W3C defines it.
+ *
+ * A number rather than a boolean because the field is a bitfield and only bit 0 is assigned; keeping it numeric
+ * means an unrecognised flag survives a round trip instead of being flattened to false by us.
+ */
+export type TraceFlags = number;
+export declare const TRACE_FLAG_SAMPLED = 1;
+export type TraceparentParts = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: TraceFlags;
+};
+export declare const formatTraceparent: (parts: TraceparentParts) => string;
+/**
+ * Parse a `traceparent`, or return `null`.
+ *
+ * `null` rather than a throw, and this is the important decision: a malformed or absent header means *start a
+ * new trace*, never fail the request. Telemetry that can break a run is worse than no telemetry, and this
+ * function sits on the hot path of every request and every job.
+ *
+ * Strict about what it accepts, though. An all-zero trace id or span id is invalid per the spec, and accepting
+ * one produces a trace that silently merges unrelated requests — every caller that failed to propagate lands in
+ * the same "trace 000…0", which looks like a working trace and is worse than a missing one.
+ */
+export declare const parseTraceparent: (value: string | undefined | null) => TraceparentParts | null;
+export declare const isSampled: (flags: TraceFlags) => boolean;
+/**
+ * Fresh ids.
+ *
+ * `randomHex` is injected rather than reaching for `crypto` here, so a test can pin ids and assert that a
+ * child span really carries its parent's trace id — which is the one property of propagation that matters and
+ * the one that is untestable against a random source.
+ */
+export type IdGenerator = {
+    readonly traceId: () => string;
+    readonly spanId: () => string;
+};
+export declare const createIdGenerator: (randomHex: (bytes: number) => string) => IdGenerator;
+//# sourceMappingURL=trace-context.d.ts.map

package/dist/telemetry/trace-context.js

@@ -0,0 +1,60 @@
+/**
+ * W3C trace context — the wire format that makes AC-1 possible.
+ *
+ * A run is enqueued by the API host and executed by a worker in a different process, possibly minutes later.
+ * The only thing that can join them into one trace is a `traceparent` travelling in the job payload, so this is
+ * the parsing and formatting of that string and nothing else.
+ *
+ * Chosen over a bespoke correlation id because the format is what every collector already understands. A
+ * home-grown id would work exactly as well right up to the point a customer pointed their own tooling at it,
+ * which is AC-6.
+ */
+/** Only version 00 exists. A future version must be *ignored*, not guessed at — see `parseTraceparent`. */
+export const TRACEPARENT_VERSION = "00";
+export const TRACE_ID_LENGTH = 32;
+export const SPAN_ID_LENGTH = 16;
+export const TRACE_FLAG_SAMPLED = 0x01;
+const INVALID_TRACE_ID = "0".repeat(TRACE_ID_LENGTH);
+const INVALID_SPAN_ID = "0".repeat(SPAN_ID_LENGTH);
+const isLowerHex = (value, length) => value.length === length && /^[0-9a-f]+$/.test(value);
+export const formatTraceparent = (parts) => `${TRACEPARENT_VERSION}-${parts.traceId}-${parts.spanId}-${(parts.traceFlags & 0xff).toString(16).padStart(2, "0")}`;
+/**
+ * Parse a `traceparent`, or return `null`.
+ *
+ * `null` rather than a throw, and this is the important decision: a malformed or absent header means *start a
+ * new trace*, never fail the request. Telemetry that can break a run is worse than no telemetry, and this
+ * function sits on the hot path of every request and every job.
+ *
+ * Strict about what it accepts, though. An all-zero trace id or span id is invalid per the spec, and accepting
+ * one produces a trace that silently merges unrelated requests — every caller that failed to propagate lands in
+ * the same "trace 000…0", which looks like a working trace and is worse than a missing one.
+ */
+export const parseTraceparent = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const parts = value.trim().split("-");
+    // A version above 00 may carry *extra* fields, which the spec says to tolerate; fewer than four is malformed
+    // whatever the version.
+    if (parts.length < 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    if (version === undefined || traceId === undefined || spanId === undefined || flags === undefined)
+        return null;
+    // Version ff is explicitly forbidden. Any other unknown version is *forward* compatible: the first four
+    // fields keep their meaning, so a newer producer's context still joins our trace rather than being dropped.
+    if (!isLowerHex(version, 2) || version === "ff")
+        return null;
+    if (!isLowerHex(traceId, TRACE_ID_LENGTH) || traceId === INVALID_TRACE_ID)
+        return null;
+    if (!isLowerHex(spanId, SPAN_ID_LENGTH) || spanId === INVALID_SPAN_ID)
+        return null;
+    if (!isLowerHex(flags, 2))
+        return null;
+    return { traceId, spanId, traceFlags: Number.parseInt(flags, 16) };
+};
+export const isSampled = (flags) => (flags & TRACE_FLAG_SAMPLED) !== 0;
+export const createIdGenerator = (randomHex) => ({
+    traceId: () => randomHex(TRACE_ID_LENGTH / 2),
+    spanId: () => randomHex(SPAN_ID_LENGTH / 2),
+});
+//# sourceMappingURL=trace-context.js.map

package/dist/toolkit/compute.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Time and arithmetic — REQ-039 (#188).
+ *
+ * The two things a model is reliably bad at and a two-line function is reliably good at. Both are pure, so both
+ * are here as functions and the tool envelopes over them are trivial.
+ */
+/**
+ * Evaluate an arithmetic expression, without `eval`.
+ *
+ * `eval` on a string a model produced is remote code execution with extra steps, and `new Function` is the same
+ * thing wearing a hat. So this is a small recursive-descent parser over a closed grammar: numbers, `+ - * / % ^`,
+ * parentheses, unary minus, and a fixed set of named functions and constants. Anything else is a syntax error
+ * rather than a silent success.
+ *
+ * Precision is IEEE-754 double, like every other number in this runtime. It is not a decimal library, and
+ * `0.1 + 0.2` is documented rather than hidden, because a tool that quietly rounds is a tool that disagrees with
+ * the spreadsheet the person is comparing it against.
+ */
+export type CalculationResult = {
+    readonly ok: true;
+    readonly expression: string;
+    readonly value: number;
+} | {
+    readonly ok: false;
+    readonly expression: string;
+    readonly reason: string;
+};
+export declare const MAX_EXPRESSION_CHARS = 500;
+export declare const calculate: (expression: string) => CalculationResult;
+export type TimeResult = {
+    readonly ok: true;
+    readonly iso: string;
+    readonly formatted: string;
+    readonly timeZone: string;
+    readonly epochMs: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The current time, in a named zone.
+ *
+ * A model has no clock -- it has a training cutoff, and it will answer "what is today's date" with something
+ * plausible and wrong. The zone is a parameter because "today" is a different day depending on where the person
+ * asking is, and the caller is often not in UTC.
+ *
+ * The clock is injected so a test can pin it, which is the convention everywhere else in this runtime.
+ */
+export declare const currentTime: (input?: {
+    readonly timeZone?: string;
+    readonly now?: () => Date;
+}) => TimeResult;
+//# sourceMappingURL=compute.d.ts.map