@tangle-network/agent-core 0.2.0 → 0.2.1

package/dist/telemetry-D2XGH5UL.js

@@ -0,0 +1,699 @@
+//#region src/telemetry/content-attributes.ts
+/** Prompt / user message — the writer key OpenCode's user-turn export uses. */
+const CONTENT_PROMPT_KEY = "gen_ai.prompt";
+/** Model completion — the writer key OpenCode's assistant-text export uses. */
+const CONTENT_COMPLETION_KEY = "message.part.text";
+/** Invoked tool's name. */
+const CONTENT_TOOL_NAME_KEY = "tool.name";
+/** Tool call arguments. */
+const CONTENT_TOOL_ARGS_KEY = "tool.input";
+/** Tool call output / result. */
+const CONTENT_TOOL_RESULT_KEY = "tool.output";
+/**
+* The single alias table: content key → normalized field. Ordered by emitter
+* for auditability; resolution order within a field is "first matching key in
+* priority order wins" (see {@link FIELD_KEY_PRIORITY}), NOT table order.
+*
+* Coverage:
+*   - Standard OTel GenAI / OpenInference / our own `tangle.*` conventions.
+*   - Claude Code: the `claude_code.*` event attributes.
+*   - Codex: the `codex.*` event attributes (inner prompt key `prompt`,
+*     verified from codex-rs/otel; looser shim spellings folded in as
+*     low-priority fallbacks).
+*   - OpenCode: the `message.*` / `tool.*` event attributes.
+*
+* Adding an agent = add its rows here. No reader changes.
+*/
+const CONTENT_KEY_ALIASES = {
+	"gen_ai.prompt": "prompt",
+	"gen_ai.request.prompt": "prompt",
+	"gen_ai.completion": "completion",
+	"gen_ai.response.completion": "completion",
+	"input.value": "prompt",
+	"output.value": "completion",
+	"llm.input_messages": "messages",
+	"llm.output_messages": "messages",
+	"user.message": "prompt",
+	prompt: "prompt",
+	"tangle.task": "task",
+	"tangle.declared_intent": "task",
+	"tangle.tool.args": "toolArgs",
+	"tangle.tool.result": "toolResult",
+	"tangle.tool.name": "toolName",
+	"tool.name": "toolName",
+	"tool.args": "toolArgs",
+	"claude_code.user_prompt.prompt": "prompt",
+	"claude_code.tool_result.tool_input": "toolArgs",
+	"claude_code.tool_result.tool_parameters": "toolArgs",
+	"claude_code.tool_result.tool_output": "toolResult",
+	"claude_code.tool.tool.output": "toolResult",
+	"claude_code.tool.output": "toolResult",
+	"claude_code.api_request_body.body": "messages",
+	"claude_code.api_response_body.body": "messages",
+	"codex.user_prompt.prompt": "prompt",
+	"codex.user_prompt.text": "prompt",
+	"codex.user_prompt.message": "prompt",
+	"codex.user_prompt.input": "prompt",
+	"codex.tool_result.output": "toolResult",
+	"codex.tool_result.result": "toolResult",
+	"message.part.text": "completion",
+	"message.text": "completion",
+	"tool.input": "toolArgs",
+	"tool.output": "toolResult"
+};
+/**
+* Reader candidate keys per normalized field, highest-confidence first.
+* When several aliased keys for the same field are present on one bag, the
+* first key in this list that is present wins — so `tangle.task` beats a bare
+* `prompt` for `task`, and the richest source (a full `messages` body) is
+* preferred where it exists. A key not listed here for its field still
+* resolves (it is appended after the explicit order), so adding an alias row
+* without touching this list is safe — it just lands at lowest priority.
+*
+* The `user_request` / `task` / `input` span-only prompt spellings the
+* intent-audit span path historically read are folded in here so the span and
+* log recovery paths resolve intent through ONE vocabulary.
+*/
+const FIELD_KEY_PRIORITY = {
+	task: [
+		"tangle.task",
+		"tangle.declared_intent",
+		"task"
+	],
+	prompt: [
+		"gen_ai.prompt",
+		"gen_ai.request.prompt",
+		"claude_code.user_prompt.prompt",
+		"codex.user_prompt.prompt",
+		"codex.user_prompt.text",
+		"codex.user_prompt.message",
+		"codex.user_prompt.input",
+		"input.value",
+		"user.message",
+		"user_request",
+		"llm.input",
+		"input",
+		"prompt"
+	],
+	completion: [
+		"gen_ai.completion",
+		"gen_ai.response.completion",
+		"output.value",
+		"message.part.text",
+		"message.text"
+	],
+	toolName: ["tangle.tool.name", "tool.name"],
+	toolArgs: [
+		"tangle.tool.args",
+		"claude_code.tool_result.tool_input",
+		"claude_code.tool_result.tool_parameters",
+		"tool.input",
+		"tool.args"
+	],
+	toolResult: [
+		"tangle.tool.result",
+		"claude_code.tool_result.tool_output",
+		"claude_code.tool.tool.output",
+		"claude_code.tool.output",
+		"codex.tool_result.output",
+		"codex.tool_result.result",
+		"tool.output"
+	],
+	messages: [
+		"claude_code.api_request_body.body",
+		"claude_code.api_response_body.body",
+		"llm.input_messages",
+		"llm.output_messages"
+	]
+};
+/**
+* Every content key the alias layer knows about. Callers use this to detect
+* "is there any content on this bag at all" without re-deriving the set.
+* Frozen so a caller can't mutate the shared table. Excludes the span-only
+* prompt spellings, which are intent-recovery candidates rather than
+* content-presence signals.
+*/
+const CONTENT_KEYS = Object.freeze(Object.keys(CONTENT_KEY_ALIASES));
+/** Map of every known content key → its normalized field, exposed read-only
+*  for callers that want to inspect or extend the mapping (e.g. enrichment
+*  joins that need to know which field a matched key feeds). */
+const CONTENT_KEY_FIELD = Object.freeze({ ...CONTENT_KEY_ALIASES });
+/** A non-empty trimmed string, or null. Absent/blank/non-string values are an
+*  honest miss, never "". */
+function asContentField(value) {
+	if (typeof value === "string") {
+		const t = value.trim();
+		return t.length > 0 ? t : null;
+	}
+	return null;
+}
+/** Flatten a tool-args / tool-result value to a string. Strings pass through;
+*  objects/arrays are JSON-stringified so a structured tool payload is still
+*  readable content. Null/empty → null (never "" or "null"). */
+function asContentString(value) {
+	if (value === null || value === void 0) return null;
+	const s = asContentField(value);
+	if (s !== null) return s;
+	if (typeof value === "object") try {
+		const json = JSON.stringify(value);
+		return json && json !== "{}" && json !== "[]" ? json : null;
+	} catch {
+		return null;
+	}
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return null;
+}
+/**
+* Coerce a `messages`-aliased value into an array. Accepts an already-decoded
+* array, a JSON string that parses to an array, or a JSON object (a
+* Claude/Codex api_request_body whose top level is `{ messages: [...] }` or a
+* single message object). Returns null when nothing array-shaped is
+* recoverable — never a fabricated `[]`.
+*/
+function asMessages(value) {
+	let v = value;
+	if (typeof v === "string") {
+		const t = v.trim();
+		if (t.length === 0) return null;
+		try {
+			v = JSON.parse(t);
+		} catch {
+			return null;
+		}
+	}
+	if (Array.isArray(v)) return v.length > 0 ? v : null;
+	if (v && typeof v === "object") {
+		const inner = v.messages;
+		if (Array.isArray(inner)) return inner.length > 0 ? inner : null;
+		if (messageHasText(v)) return [v];
+		return null;
+	}
+	return null;
+}
+/**
+* Recover the human-readable text from a single message-shaped object. The one
+* reader every message-text caller goes through, in priority order:
+*   1. `content` as a plain string;
+*   2. `content` as a LIST OF BLOCKS — the Anthropic / Claude Code message shape
+*      (`content: [{ type: "text", text }, { type: "tool_use", … }]`): the text
+*      of every text-bearing block is concatenated (newline-joined), tool/other
+*      blocks contribute nothing. Without this branch a Claude Code message
+*      whose content is an array is silently invisible to content recovery;
+*   3. a top-level `text` string;
+*   4. a nested `content.text` string (object-wrapped content).
+* Returns the first non-empty result, or null when no usable text exists — a
+* bare/arbitrary object yields null and is not treated as a usable message.
+*/
+function readMessageText(msg) {
+	const direct = asContentField(msg.content);
+	if (direct !== null) return direct;
+	const blocks = msg.content;
+	if (Array.isArray(blocks)) {
+		const parts = [];
+		for (const block of blocks) {
+			if (!block || typeof block !== "object") continue;
+			const text = asContentField(block.text);
+			if (text !== null) parts.push(text);
+		}
+		if (parts.length > 0) return parts.join("\n");
+	}
+	const top = asContentField(msg.text);
+	if (top !== null) return top;
+	return asContentField(msg.content?.text);
+}
+/** True when a single message-shaped object carries recoverable text. A
+*  bare/arbitrary object has none, so it is not treated as a usable message. */
+function messageHasText(msg) {
+	return readMessageText(msg) !== null;
+}
+/**
+* Precomputed resolution order per field: the explicit priority list, then any
+* remaining aliased keys for that field appended at lowest priority. Built once
+* at module load (frozen) so the content-presence hot path (onboarding scans
+* every row) never re-runs an `Object.keys().filter()` over the alias table per
+* row — it reads a fixed array instead.
+*/
+const FIELD_KEY_ORDER = Object.freeze(Object.fromEntries(Object.keys(FIELD_KEY_PRIORITY).map((field) => {
+	const priority = FIELD_KEY_PRIORITY[field];
+	const extras = Object.keys(CONTENT_KEY_ALIASES).filter((k) => CONTENT_KEY_ALIASES[k] === field && !priority.includes(k));
+	return [field, Object.freeze([...priority, ...extras])];
+})));
+/** The resolution order for one field: explicit priority list, then any
+*  remaining aliased keys for that field appended at lowest priority. */
+function fieldKeyOrder(field) {
+	return FIELD_KEY_ORDER[field];
+}
+/** Resolve one normalized field from a bag: walk its priority list, then any
+*  remaining aliased keys for that field, returning the first usable value. */
+function resolveField(bag, field) {
+	for (const key of fieldKeyOrder(field)) {
+		if (!(key in bag)) continue;
+		const raw = bag[key];
+		if (field === "messages") {
+			const msgs = asMessages(raw);
+			if (msgs) return msgs;
+			continue;
+		}
+		if (field === "toolArgs" || field === "toolResult") {
+			const s = asContentString(raw);
+			if (s) return s;
+			continue;
+		}
+		const s = asContentField(raw);
+		if (s) return s;
+	}
+}
+const ALL_FIELDS = [
+	"task",
+	"prompt",
+	"completion",
+	"toolName",
+	"toolArgs",
+	"toolResult",
+	"messages"
+];
+/**
+* Extract normalized content from a flattened attribute bag (span attributes
+* OR a log record's merged attribute bag). Pure: same input → same output, no
+* I/O, no env reads. Returns only the fields actually present; an empty/absent
+* bag returns `{}`.
+*/
+function extractContent(attributes) {
+	const out = {};
+	if (!attributes) return out;
+	for (const field of ALL_FIELDS) {
+		const v = resolveField(attributes, field);
+		if (v !== void 0) out[field] = v;
+	}
+	return out;
+}
+/**
+* The keys whose presence (with a usable value) counts as "this bag carries
+* content". The alias-table keys only — the span-only prompt spellings are
+* deliberately excluded so a metadata row that happens to carry a bare `input`
+* is not mislabelled content-bearing.
+*/
+const PRESENCE_KEYS = Object.keys(CONTENT_KEY_ALIASES);
+/** True when the bag carries ANY known content key with a usable value. A cheap
+*  presence check that SHORT-CIRCUITS on the first usable key — it does not
+*  build the NormalizedContent object or JSON-parse `messages` bodies, so a hot
+*  scan path (onboarding) pays per-row only until the first hit. */
+function hasContent(attributes) {
+	if (!attributes) return false;
+	for (const key of PRESENCE_KEYS) {
+		if (!(key in attributes)) continue;
+		const field = CONTENT_KEY_ALIASES[key];
+		const raw = attributes[key];
+		if (field === "messages") {
+			if (asMessages(raw)) return true;
+			continue;
+		}
+		if (field === "toolArgs" || field === "toolResult") {
+			if (asContentString(raw)) return true;
+			continue;
+		}
+		if (asContentField(raw)) return true;
+	}
+	return false;
+}
+/**
+* Build the content-detection bag for a single OTLP log record. A log carries
+* its content either as flattened attributes (keyed by a content key) OR as the
+* record `body` for a prompt event whose text has no attribute key (a
+* `*.user_prompt` event whose prompt IS the body). This is the ONE place that
+* decides "how a log row becomes a bag `extractContent` can read", so the
+* intent-audit recovery, the trace-analyst log enrichment, and the onboarding
+* content check can never drift on it.
+*
+* The body is surfaced under the standard `prompt` alias ONLY for `*.user_prompt`
+* events (a generic log body is not content); an attribute-carried `prompt`
+* already present is never overwritten.
+*/
+function logRecordContentBag(attributes, body) {
+	const bag = { ...attributes ?? {} };
+	if (typeof body === "string" && body.trim().length > 0) {
+		const eventName = asContentField(bag["event.name"]);
+		if (eventName && /(?:^|\.)user_prompt$/.test(eventName) && !("prompt" in bag)) bag.prompt = body;
+	}
+	return bag;
+}
+/** Known coding-agent service names, mapped to their canonical agent id. An
+*  EXACT match only — a substring guess ('claude-helper-bot') would mislabel a
+*  customer service into a coding-agent bucket and drive a wrong "you missed
+*  THIS gate" onboarding hint. The namespaced-key / gen_ai.system paths above
+*  this remain the reliable identity; this allowlist is the last resort for a
+*  content-less metadata row carrying only service.name. */
+const KNOWN_AGENT_SERVICE_NAMES = {
+	"claude-code": "claude-code",
+	"claude code": "claude-code",
+	claudecode: "claude-code",
+	codex: "codex",
+	"codex-cli": "codex",
+	opencode: "opencode"
+};
+/**
+* Deterministic coding-agent label for an attribute bag, by the namespace of
+* the content/event keys it carries, then the standard `gen_ai.system` /
+* `service.name` identity. Returns a stable lowercase id
+* (`claude-code` | `codex` | `opencode` | the gen_ai.system name) or
+* `"unknown"` when nothing reliably identifies the emitter — never a fabricated
+* default that pretends to know which agent produced the row.
+*
+* `service.name` is matched against a KNOWN-AGENT ALLOWLIST (exact), not a
+* substring guess, so an arbitrary customer service named e.g. `claude-helper`
+* stays `unknown` rather than being mislabelled `claude-code` and driving a
+* wrong onboarding hint.
+*/
+function classifyAgent(bag) {
+	if (!bag) return "unknown";
+	const keys = Object.keys(bag);
+	if (keys.some((k) => k.startsWith("claude_code."))) return "claude-code";
+	if (keys.some((k) => k.startsWith("codex."))) return "codex";
+	const eventName = asContentField(bag["event.name"]);
+	if (eventName?.startsWith("claude_code.")) return "claude-code";
+	if (eventName?.startsWith("codex.")) return "codex";
+	const system = asContentField(bag["gen_ai.system"]);
+	if (system) return system.toLowerCase();
+	if (keys.some((k) => k.startsWith("message."))) return "opencode";
+	const service = asContentField(bag["service.name"]);
+	if (service) {
+		const mapped = KNOWN_AGENT_SERVICE_NAMES[service.toLowerCase()];
+		if (mapped) return mapped;
+	}
+	return "unknown";
+}
+/**
+* Recover the declared intent from a flattened attribute bag through the shared
+* task/prompt/messages vocabulary, reporting WHICH key matched. The span path
+* and the log-record path both call this, so they resolve intent through one
+* key source and a key added to the shared layer is read by both. Walks the
+* `task` field's keys, then the `prompt` field's keys (which include the
+* span-only `user_request` / `input` / `llm.input` spellings folded into the
+* priority list), then the first user message of a messages body. Returns null
+* when nothing usable is present — never a fabricated intent.
+*/
+function resolveDeclaredIntent(bag) {
+	if (!bag) return null;
+	for (const field of ["task", "prompt"]) for (const key of fieldKeyOrder(field)) {
+		if (!(key in bag)) continue;
+		const text = asContentField(bag[key]);
+		if (text) return {
+			text,
+			source: key
+		};
+	}
+	for (const key of fieldKeyOrder("messages")) {
+		if (!(key in bag)) continue;
+		const msgs = asMessages(bag[key]);
+		if (!msgs) continue;
+		const text = declaredTaskText({ messages: msgs });
+		if (text) return {
+			text,
+			source: "messages"
+		};
+	}
+	return null;
+}
+/**
+* Best-effort declared-task text from normalized content, in the order a
+* declared intent is most likely to live: an explicit task, then the prompt,
+* then the first user message in a messages array. Deliberately does NOT
+* consult `completion` — an assistant completion is the agent's OUTPUT, not the
+* declared task; treating it as the task would fabricate intent. Returns null
+* when no genuine declared-task source is present — the caller skips, never
+* fabricates.
+*/
+function declaredTaskText(content) {
+	if (content.task) return content.task;
+	if (content.prompt) return content.prompt;
+	if (content.messages) for (const m of content.messages) {
+		if (!m || typeof m !== "object") continue;
+		const msg = m;
+		const role = asContentField(msg.role);
+		if (role && role !== "user") continue;
+		const text = readMessageText(msg);
+		if (text) return text;
+	}
+	return null;
+}
+//#endregion
+//#region src/telemetry/genai-attributes.ts
+/**
+* OpenTelemetry GenAI semantic-convention span attributes — the single
+* vocabulary every trace producer in the stack emits and the intelligence
+* ingest reads, so model / token / cost attribution is identical regardless of
+* which producer lowered the span (workflow emitter, SDK trace sink, …).
+*
+* Writers emit the PRIMARY keys (`GEN_AI_*`). The ingest reader accepts the
+* wider candidate lists (`GEN_AI_*_KEYS`) because foreign SDKs spell the same
+* field differently (Langfuse, raw OTLP GenAI, our own legacy `model`).
+* Co-locating writer keys and reader candidates here is the drift guard: a
+* writer's key and the reader's first candidate can never silently disagree.
+*
+* Spec: OpenTelemetry GenAI semantic conventions (`gen_ai.*`).
+*/
+/** Model that served a request — the primary key writers emit. */
+const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+/** Model named on a response — a reader fallback; writers prefer request.model. */
+const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+/** Prompt / input token count. */
+const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+/** Completion / output token count. */
+const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+/** Operation name (e.g. `"invoke_agent"`). */
+const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+/** Conversation / session id grouping a multi-turn agent run. */
+const GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id";
+/**
+* Reader candidate keys for the model, highest priority first. The first entry
+* is the writers' primary key; the rest accept foreign-SDK spellings.
+*/
+const GEN_AI_MODEL_KEYS = Object.freeze([
+	GEN_AI_REQUEST_MODEL,
+	GEN_AI_RESPONSE_MODEL,
+	"llm.model_name",
+	"model"
+]);
+/** Reader candidate keys for input tokens, highest priority first. These name
+*  SPAN ATTRIBUTES on a lowered span — for the raw producer `tokenUsage` OBJECT
+*  field names (a distinct layer) see `TOKEN_USAGE_INPUT_KEYS` in
+*  `token-usage.ts`; a new producer shape may need an entry in both. */
+const GEN_AI_INPUT_TOKEN_KEYS = Object.freeze([
+	GEN_AI_USAGE_INPUT_TOKENS,
+	"gen_ai.usage.prompt_tokens",
+	"llm.token_count.prompt"
+]);
+/** Reader candidate keys for output tokens, highest priority first. */
+const GEN_AI_OUTPUT_TOKEN_KEYS = Object.freeze([
+	GEN_AI_USAGE_OUTPUT_TOKENS,
+	"gen_ai.usage.completion_tokens",
+	"llm.token_count.completion"
+]);
+function isNonNegativeFinite(n) {
+	return typeof n === "number" && Number.isFinite(n) && n >= 0;
+}
+/**
+* Lower a usage record to the GenAI semantic-convention attribute bag, OMITTING
+* any unknown field. A synthesized zero token count or empty model would
+* corrupt every downstream token/cost aggregate, so absent stays absent — the
+* ingest then reads "cost not computed", never "free". This is the writer-side
+* mirror of {@link GEN_AI_MODEL_KEYS} / the `*_TOKEN_KEYS` reader candidates.
+*/
+function genAiUsageAttributes(usage) {
+	const attrs = {};
+	if (typeof usage.model === "string" && usage.model.length > 0) attrs[GEN_AI_REQUEST_MODEL] = usage.model;
+	if (isNonNegativeFinite(usage.inputTokens)) attrs[GEN_AI_USAGE_INPUT_TOKENS] = usage.inputTokens;
+	if (isNonNegativeFinite(usage.outputTokens)) attrs[GEN_AI_USAGE_OUTPUT_TOKENS] = usage.outputTokens;
+	return attrs;
+}
+//#endregion
+//#region src/telemetry/spine-attributes.ts
+/**
+* Spine run/subject/tree + trigger span-attribute vocabulary — the single set of
+* `tangle.*` keys that name a run, its parent, its kind, its trigger, and the
+* durable subject it worked on. Co-located here so the WRITER (the platform
+* workflow-trace-emitter) and the READERS (intelligence-api's run-attrs derivers
+* + reconstruct) key off one source and can never silently drift.
+*
+* Writers emit the PRIMARY keys (`*_KEY`). The ingest reader accepts the wider
+* CANDIDATE lists (`*_ATTRS`) because the emit sites disagree on spelling: the
+* workflow emitter writes camel `tangle.runId`, the agent setup prompt documents
+* dotted `tangle.run.id`. Each candidate list's first entry is a writer primary
+* key, so the drift guard (`spine-attributes.test.ts`) can assert writer/reader
+* agreement.
+*
+* The DERIVATION LOGIC (priority resolution, parent!=own-run guard, run-kind
+* inference, subject `'default'` fallback, `source:id` formatting) lives in
+* intelligence-api's `run-attrs.ts`; only the key constants and candidate lists
+* live here. The foreign subject candidates (`symphony.issue.identifier`,
+* `git.repository`, `service.name`) are members of {@link SUBJECT_KEY_ATTRS}.
+*/
+/** Primary run-id key writers stamp; first entry of {@link RUN_KEY_ATTRS}. */
+const TANGLE_RUN_ID_KEY = "tangle.run.id";
+/** Camel run-id key the workflow emitter actually writes on every span. */
+const TANGLE_RUN_ID_CAMEL_KEY = "tangle.runId";
+/** Primary parent-run-id key; first entry of {@link PARENT_RUN_KEY_ATTRS}. */
+const TANGLE_RUN_PARENT_ID_KEY = "tangle.run.parent_id";
+/** Primary run-kind key; the sole entry of {@link RUN_KIND_ATTRS}. */
+const TANGLE_RUN_KIND_KEY = "tangle.run.kind";
+/** Primary subject key; first entry of {@link SUBJECT_KEY_ATTRS}. */
+const TANGLE_SUBJECT_KEY = "tangle.subject.key";
+/** Primary trigger-source key; first entry of {@link TRIGGER_SOURCE_ATTRS}. */
+const TANGLE_TRIGGER_SOURCE_KEY = "tangle.workflow.trigger.source";
+/** Trigger-kind key the workflow emitter writes on the root span. */
+const TANGLE_TRIGGER_KIND_KEY = "tangle.trigger.kind";
+/** Primary trigger-id key; first entry of {@link TRIGGER_ID_ATTRS}. */
+const TANGLE_TRIGGER_ID_KEY = "tangle.workflow.trigger.id";
+/** Workflow-id key the workflow emitter writes on the root span; a
+*  {@link WORKFLOW_MARKER_ATTRS} member. */
+const TANGLE_WORKFLOW_ID_KEY = "tangle.workflowId";
+/** Run-id reader candidates, highest priority first. */
+const RUN_KEY_ATTRS = Object.freeze([TANGLE_RUN_ID_KEY, TANGLE_RUN_ID_CAMEL_KEY]);
+/**
+* Parent-run-id reader candidates, highest priority first. After the explicit
+* parent keys come the workflow-run ids, which name a parent only when this span
+* is a distinct child run (the deriver's own-run guard enforces that).
+*/
+const PARENT_RUN_KEY_ATTRS = Object.freeze([
+	TANGLE_RUN_PARENT_ID_KEY,
+	"tangle.run.parentId",
+	"tangle.workflow.parent.run.id",
+	"tangle.workflow.run.id",
+	"tangle.workflow.runId"
+]);
+/** Trigger-source reader candidates, highest priority first. */
+const TRIGGER_SOURCE_ATTRS = Object.freeze([
+	TANGLE_TRIGGER_SOURCE_KEY,
+	"tangle.trigger.source",
+	TANGLE_TRIGGER_KIND_KEY
+]);
+/** Trigger-id reader candidates, highest priority first. */
+const TRIGGER_ID_ATTRS = Object.freeze([TANGLE_TRIGGER_ID_KEY, "tangle.trigger.id"]);
+/**
+* Subject-key reader candidates, highest priority first: declared subject key /
+* project, else the agent's own work-item identity, else repo, else service. The
+* deriver appends a `'default'` fallback so no run is orphaned.
+*/
+const SUBJECT_KEY_ATTRS = Object.freeze([
+	TANGLE_SUBJECT_KEY,
+	"tangle.project.name",
+	"symphony.issue.identifier",
+	"git.repository",
+	"service.name"
+]);
+/** Explicit run-kind reader candidates (exact `workflow`/`consultant`/`session`
+*  wins in the deriver). */
+const RUN_KIND_ATTRS = Object.freeze([TANGLE_RUN_KIND_KEY]);
+/** Workflow-presence markers — any one present implies a `workflow` run kind. */
+const WORKFLOW_MARKER_ATTRS = Object.freeze([
+	"tangle.workflow.id",
+	TANGLE_WORKFLOW_ID_KEY,
+	"tangle.workflow.name",
+	"tangle.workflow.run.id",
+	"tangle.workflow.runId"
+]);
+//#endregion
+//#region src/telemetry/token-usage.ts
+/**
+* Candidate field names for a producer-supplied `tokenUsage` bag on a
+* `message.updated` trace event. Agents and SDK layers disagree on the
+* spelling: `StreamTokenUsage` emits `inputTokens`/`outputTokens`, the eval and
+* workflow agent.run paths emit `input`/`output`, and persisted / foreign
+* shapes use snake_case or prompt/completion naming. A reader that wants the
+* token counts must try all of them, highest-priority first, or it silently
+* drops usage for the producers it does not name.
+*
+* Shared so every `tokenUsage` reader (the trace sink's root-span aggregation,
+* the signal extractor) keys off the identical set and cannot drift.
+*
+* Distinct layer from `genai-attributes.ts`: those keys (`GEN_AI_*_TOKEN_KEYS`)
+* name OTel SPAN ATTRIBUTES on an already-lowered span; these name the fields of
+* the raw producer `tokenUsage` OBJECT before lowering. A new producer that
+* spells token usage differently may need an entry in BOTH places.
+*/
+const TOKEN_USAGE_INPUT_KEYS = Object.freeze([
+	"inputTokens",
+	"input",
+	"input_tokens",
+	"promptTokens",
+	"prompt_tokens"
+]);
+const TOKEN_USAGE_OUTPUT_KEYS = Object.freeze([
+	"outputTokens",
+	"output",
+	"output_tokens",
+	"completionTokens",
+	"completion_tokens"
+]);
+const TOKEN_USAGE_COST_KEYS = Object.freeze([
+	"totalCostUsd",
+	"costUsd",
+	"total_cost_usd",
+	"cost_usd",
+	"cost"
+]);
+function tokenCount(value) {
+	if (typeof value === "boolean") return void 0;
+	let n;
+	if (typeof value === "number") n = value;
+	else if (typeof value === "string") {
+		const trimmed = value.trim();
+		n = trimmed === "" ? NaN : Number(trimmed);
+	} else n = NaN;
+	if (!Number.isFinite(n) || n < 0) return void 0;
+	return Math.trunc(n);
+}
+function firstTokenCount(source, keys) {
+	if (!source) return void 0;
+	for (const key of keys) {
+		const count = tokenCount(source[key]);
+		if (count !== void 0) return count;
+	}
+}
+function finiteNonNegativeNumber(value) {
+	if (typeof value === "boolean") return void 0;
+	let n;
+	if (typeof value === "number") n = value;
+	else if (typeof value === "string") {
+		const trimmed = value.trim();
+		n = trimmed === "" ? NaN : Number(trimmed);
+	} else n = NaN;
+	return Number.isFinite(n) && n >= 0 ? n : void 0;
+}
+function firstUsageCostUsd(source, keys = TOKEN_USAGE_COST_KEYS) {
+	if (!source) return void 0;
+	for (const key of keys) {
+		const cost = finiteNonNegativeNumber(source[key]);
+		if (cost !== void 0) return cost;
+	}
+}
+function tokenUsageSource(data) {
+	if (data.tokenUsage && typeof data.tokenUsage === "object") return data.tokenUsage;
+	if (data.usage && typeof data.usage === "object") return data.usage;
+	return data;
+}
+function readTokenUsage(data) {
+	const source = tokenUsageSource(data);
+	const inputTokens = firstTokenCount(source, TOKEN_USAGE_INPUT_KEYS);
+	const outputTokens = firstTokenCount(source, TOKEN_USAGE_OUTPUT_KEYS);
+	if (inputTokens === void 0 && outputTokens === void 0) return;
+	return {
+		inputTokens: inputTokens ?? 0,
+		outputTokens: outputTokens ?? 0
+	};
+}
+function readTokenCostUsd(data) {
+	const direct = firstUsageCostUsd(data);
+	if (direct !== void 0) return direct;
+	return firstUsageCostUsd(tokenUsageSource(data));
+}
+function addTokenUsage(current, next) {
+	return current ? {
+		inputTokens: current.inputTokens + next.inputTokens,
+		outputTokens: current.outputTokens + next.outputTokens
+	} : next;
+}
+//#endregion
+export { GEN_AI_OPERATION_NAME as A, CONTENT_PROMPT_KEY as B, TANGLE_WORKFLOW_ID_KEY as C, GEN_AI_CONVERSATION_ID as D, WORKFLOW_MARKER_ATTRS as E, GEN_AI_USAGE_OUTPUT_TOKENS as F, asContentString as G, CONTENT_TOOL_NAME_KEY as H, genAiUsageAttributes as I, extractContent as J, classifyAgent as K, CONTENT_COMPLETION_KEY as L, GEN_AI_REQUEST_MODEL as M, GEN_AI_RESPONSE_MODEL as N, GEN_AI_INPUT_TOKEN_KEYS as O, GEN_AI_USAGE_INPUT_TOKENS as P, CONTENT_KEYS as R, TANGLE_TRIGGER_SOURCE_KEY as S, TRIGGER_SOURCE_ATTRS as T, CONTENT_TOOL_RESULT_KEY as U, CONTENT_TOOL_ARGS_KEY as V, asContentField as W, logRecordContentBag as X, hasContent as Y, resolveDeclaredIntent as Z, TANGLE_RUN_KIND_KEY as _, firstTokenCount as a, TANGLE_TRIGGER_ID_KEY as b, readTokenUsage as c, PARENT_RUN_KEY_ATTRS as d, RUN_KEY_ATTRS as f, TANGLE_RUN_ID_KEY as g, TANGLE_RUN_ID_CAMEL_KEY as h, addTokenUsage as i, GEN_AI_OUTPUT_TOKEN_KEYS as j, GEN_AI_MODEL_KEYS as k, tokenCount as l, SUBJECT_KEY_ATTRS as m, TOKEN_USAGE_INPUT_KEYS as n, firstUsageCostUsd as o, RUN_KIND_ATTRS as p, declaredTaskText as q, TOKEN_USAGE_OUTPUT_KEYS as r, readTokenCostUsd as s, TOKEN_USAGE_COST_KEYS as t, tokenUsageSource as u, TANGLE_RUN_PARENT_ID_KEY as v, TRIGGER_ID_ATTRS as w, TANGLE_TRIGGER_KIND_KEY as x, TANGLE_SUBJECT_KEY as y, CONTENT_KEY_FIELD as z };
+
+//# sourceMappingURL=telemetry-D2XGH5UL.js.map