@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/observability/trace-catalog.js

@@ -1,7 +1,8 @@
-// A key with no entry is still a real attribute: viewers show it under its raw name.
+// invariant: A key with no entry is still a real attribute: viewers show it under its raw name.
+/** Labels and descriptions for each attribute group. */
 const TRACE_ATTRIBUTE_GROUPS = {
     agent: { label: 'Agent', doc: 'Which agent ran, for which conversation, and how it ended.' },
-    request: { label: 'Request', doc: 'What THEOREM asked the provider for.' },
+    request: { label: 'Request', doc: 'What theorem asked the provider for.' },
     response: { label: 'Response', doc: 'What the provider said about its answer.' },
     messages: { label: 'Messages', doc: 'What was read and written, stored by hash.' },
     usage: { label: 'Usage', doc: 'Tokens and cost, as reported or estimated.' },
@@ -16,6 +17,7 @@ const TRACE_ATTRIBUTE_GROUPS = {
     },
     evaluation: { label: 'Evaluation', doc: 'How an eval graded this trace, and by which suite.' },
 };
+/** Labels and descriptions for each span status. */
 const TRACE_STATUS = {
     OK: { label: 'OK', doc: 'Finished as intended.' },
     ERROR: { label: 'Error', doc: 'Failed; the error kind says why.' },
@@ -57,7 +59,7 @@ const STOP_KINDS = {
     },
     gate: {
         label: 'Waiting for approval',
-        doc: 'A tool call needs confirmation, permission or sign-in before it runs; the host resumes it.',
+        doc: 'A tool call needs confirmation, permission, or sign-in before it runs; the host resumes it.',
     },
     filtered: {
         label: 'Filtered',
@@ -65,6 +67,10 @@ const STOP_KINDS = {
     },
     provider_error: { label: 'Provider error', doc: 'The provider reported an error.' },
     cancelled: { label: 'Cancelled', doc: 'The user or host stopped it.' },
+    step_limit: {
+        label: 'Ran out of steps',
+        doc: 'The last model call the profile allows asked for tools, so the turn ended without an answer.',
+    },
     stream_incomplete: {
         label: 'Stream cut off',
         doc: "The provider's stream ended before the answer was complete.",
@@ -81,7 +87,7 @@ const STOP_KINDS = {
 };
 const ERROR_KIND_OPTIONS = {
     config: { label: 'Setup', doc: 'The profile, tool, or schema is set up wrong.' },
-    request: { label: 'Host request', doc: 'The host called THEOREM wrongly.' },
+    request: { label: 'Host request', doc: 'The host called theorem wrongly.' },
     input: { label: 'User input', doc: 'The user sent input the profile does not accept.' },
     action: { label: 'Not allowed', doc: 'The user asked for something the profile does not allow.' },
     auth: {
@@ -97,7 +103,7 @@ const ERROR_KIND_OPTIONS = {
     },
     network: { label: 'Network', doc: 'The request never reached the provider.' },
     timeout: { label: 'Timeout', doc: 'The model took longer than the host allowed.' },
-    safety: { label: 'Safety', doc: 'THEOREM or the provider held the reply back.' },
+    safety: { label: 'Safety', doc: 'theorem or the provider held the reply back.' },
     blocked: {
         label: 'Blocked',
         doc: "A guardrail or host policy stopped one of the agent's steps.",
@@ -105,7 +111,7 @@ const ERROR_KIND_OPTIONS = {
     declined: { label: 'Declined', doc: "The user declined one of the agent's steps." },
     failed: { label: 'Failed', doc: "One of the agent's steps ran and failed." },
     cancelled: { label: 'Cancelled', doc: 'The user or host stopped the turn.' },
-    internal: { label: 'Internal', doc: 'A THEOREM invariant broke.' },
+    internal: { label: 'Internal', doc: 'A theorem invariant broke.' },
 };
 /** `error.type`: an error kind, or the failing stop. An HTTP status or exception shows as is. */
 const ERROR_TYPE_OPTIONS = {
@@ -117,17 +123,17 @@ const ERROR_TYPE_OPTIONS = {
 const TOOL_OUTCOMES = {
     ok: { label: 'Succeeded', doc: 'The tool ran and returned a result.' },
     error: { label: 'Failed', doc: 'The tool ran and failed, or could not run.' },
-    denied: { label: 'Denied', doc: 'A guardrail, a hook or the user refused the call.' },
+    denied: { label: 'Denied', doc: 'A guardrail, a hook, or the user refused the call.' },
     gated: {
         label: 'Waiting for approval',
-        doc: 'The call needs confirmation, permission or sign-in; it has not run.',
+        doc: 'The call needs confirmation, permission, or sign-in; it has not run.',
     },
     paused: { label: 'Paused', doc: 'The call was handed back to the host to finish.' },
     cancelled: { label: 'Cancelled', doc: 'The turn was stopped before the call settled.' },
 };
 const TOOL_ORIGIN_OPTIONS = {
     local: { label: 'Host code', doc: 'TypeScript the host registered, run in-process.' },
-    builtin: { label: 'Built-in', doc: 'A tool THEOREM ships.' },
+    builtin: { label: 'Built-in', doc: 'A tool theorem ships.' },
     http: { label: 'HTTP', doc: 'A remote HTTP endpoint.' },
     mcp: { label: 'MCP', doc: 'A tool on an MCP server.' },
     delegated: { label: 'Another agent', doc: 'A specialist agent the tool ran.' },
@@ -166,11 +172,12 @@ const OPERATIONS = {
     invoke_agent: { label: 'Run agent', doc: 'One turn of an agent, or one Live session.' },
     chat: { label: 'Chat', doc: 'A model call over a chat-completions API.' },
     generate_content: { label: 'Generate content', doc: 'A model call over a Gemini API.' },
-    execute_tool: { label: 'Run tool', doc: 'A tool call THEOREM ran.' },
+    execute_tool: { label: 'Run tool', doc: 'A tool call theorem ran.' },
     decide: {
         label: 'Decide',
         doc: 'One model decision: typed answers to questions over JSON state.',
     },
+    embeddings: { label: 'Embed', doc: 'One embedding call: a vector for each input.' },
 };
 const OUTPUT_TYPES = {
     text: { label: 'Text', doc: 'The model answers in text.' },
@@ -210,6 +217,11 @@ const AFFORDANCES = {
     deny: { label: 'Denied', doc: 'Refused a tool call.' },
     confirm: { label: 'Asked to confirm', doc: 'Required confirmation before a tool call.' },
     mutate: { label: 'Changed', doc: 'Changed the tool call or its result.' },
+    labelFailed: {
+        label: 'Labelled failed',
+        doc: "Showed the tool's failed label for a call that completed.",
+    },
+    waitFor: { label: 'Waited', doc: 'Held a tool call until other calls in its step settled.' },
 };
 const GUARDRAIL_STAGE_OPTIONS = {
     input: { label: 'User input', doc: 'Text the user sent.' },
@@ -229,84 +241,64 @@ const GUARDRAIL_STAGE_OPTIONS = {
 /**
  * What each of Theorem's own guardrail rules caught. Keyed by every
  * {@link GuardrailRule}, so a new rule is described here before it compiles.
- * A host's own egress rules have no entry and show as their id.
+ * A host's own detectors have no entry and show as their label.
  */
 const GUARDRAIL_RULE_OPTIONS = {
-    'sanitize.injection': {
-        label: 'Injection phrasing',
-        doc: 'Text that tries to override the agent\'s instructions, such as "ignore previous instructions". Removed before the model read it.',
-    },
-    'sanitize.sensitive': {
-        label: 'Sensitive data',
-        doc: 'A credential or personal identifier, such as an API key, card or ID number. Redacted before the model read it.',
-    },
-    'egress.canary-leak': {
-        label: 'Instructions leaked',
-        doc: "The reply contained the turn's canary, a secret marker planted in the instructions, so the model was repeating them.",
+    'detect.ids': {
+        label: 'IDs',
+        doc: 'A US SSN, ITIN, or EIN number. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.prompt-echo': {
-        label: 'Instructions repeated',
-        doc: 'The reply repeated 12 or more words in a row of the instructions.',
-    },
-    'egress.provider-tool-leak': {
-        label: 'Instructions sent to a provider tool',
-        doc: "A provider's built-in tool, such as search, was sent the canary or the instructions. It ran before Theorem saw it, so the data had already left.",
+    'detect.financial': {
+        label: 'Financial',
+        doc: 'An IBAN or card number. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.image-exfil': {
-        label: 'Image from an unknown address',
-        doc: 'The reply showed an image from an address the model was not given, on a host the profile does not allow. Loading it could send data out.',
+    'detect.network': {
+        label: 'Network',
+        doc: 'An IPv4 or IPv6 address. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.link-exfil': {
-        label: 'Link to an unknown address',
-        doc: 'The reply linked an address the model was not given, on a host the profile does not allow.',
+    'detect.credentials': {
+        label: 'Credentials',
+        doc: 'An API key, token, password assignment, or private key. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.sensitive-echo': {
-        label: 'Sensitive data in reply',
-        doc: 'The reply contained a credential or personal identifier.',
+    'detect.injection': {
+        label: 'Injection',
+        doc: 'Text that tries to override the agent\'s instructions, such as "ignore previous instructions". The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.system-boundary': {
-        label: 'Internal markers in reply',
-        doc: 'The reply contained the markers Theorem uses to fence user data or name the canary.',
+    'detect.tool_instructions': {
+        label: 'Tool instructions',
+        doc: 'A tool\'s text instructed the agent: it told it to set its instructions aside, such as "ignore your instructions", or beside an address it named a tool the model can call, gave an order such as "you must now…", or claimed to speak for the user, the system, or an admin. Each match says which in its signal. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.injection-echo': {
-        label: 'Injection phrasing in reply',
-        doc: "The reply repeated text that tries to override the agent's instructions.",
+    'detect.canary_leak': {
+        label: 'Canary leak',
+        doc: "The turn's canary, a secret marker planted in the instructions, so the model was repeating them. The decision names the boundary it was crossing and what was done with it.",
     },
-    'egress.unscannable': {
-        label: 'Reply could not be checked',
-        doc: 'Structured output could not be turned into text to check, so it was treated as unsafe.',
+    'detect.prompt_leak': {
+        label: 'Prompt leak',
+        doc: '12 or more words in a row of the private instructions. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.enforcer-error': {
-        label: 'Output check failed',
-        doc: "The host's output check threw or returned no clear verdict, so the reply was treated as blocked.",
+    'detect.marker_leak': {
+        label: 'Marker leak',
+        doc: 'The markers Theorem fences user data with, or the words of the canary note. The decision names the boundary it was crossing and what was done with it.',
     },
-    'egress.blocked': {
-        label: 'Stopped while streaming',
-        doc: "The host's output check stopped the reply mid-stream without naming a rule.",
+    'detect.ungiven_images': {
+        label: 'Ungiven images',
+        doc: 'An image whose address the model was not given, on a host the profile does not allow. Loading it could send data out. The decision names the boundary it was crossing and what was done with it.',
     },
-    'tool_result.names-callable-tool': {
-        label: 'Named a callable tool',
-        doc: 'Remote tool content named a tool the model can call, a common way to steer its next step.',
+    'detect.ungiven_links': {
+        label: 'Ungiven links',
+        doc: 'A link to an address the model was not given, on a host the profile does not allow. The decision names the boundary it was crossing and what was done with it.',
     },
-    'tool_result.imperative': {
-        label: 'Gave the agent an order',
-        doc: 'Remote tool content addressed the agent with an instruction, such as "you must now…" or "next steps:".',
+    'detect.tool_leak': {
+        label: 'Tool leak',
+        doc: "The name of one of the profile's own tools, or of a tool's parameter written as a quoted key. The decision names the boundary it was crossing and what was done with it.",
     },
-    'tool_result.authority-claim': {
-        label: 'Claimed authority',
-        doc: 'Remote tool content claimed to speak for the user, the system or an admin, such as "the user has already approved".',
-    },
-    'tool_result.redacted': {
-        label: 'Tool result redacted',
-        doc: "Injection phrasing or sensitive data was removed from a tool's result before the model read it.",
-    },
-    'tool_failure.redacted': {
-        label: 'Tool error redacted',
-        doc: "Injection phrasing or sensitive data was removed from a tool's error message.",
+    'egress.provider-tool-leak': {
+        label: 'Instructions sent to a provider tool',
+        doc: "A provider's built-in tool, such as search, was sent the canary or the instructions. It ran before Theorem saw it, so the data had already left.",
     },
-    'tool_call.sensitive-argument': {
-        label: 'Sensitive data in arguments',
-        doc: 'The model passed a credential or personal identifier to a tool. The call still ran.',
+    'egress.unscannable': {
+        label: 'Reply could not be checked',
+        doc: 'Structured output could not be turned into text to check, so it was treated as unsafe.',
     },
     'tool_call.tainted-turn': {
         label: 'Change after remote content',
@@ -316,9 +308,13 @@ const GUARDRAIL_RULE_OPTIONS = {
         label: 'Change after a remote instruction',
         doc: 'A tool that writes or deletes was called after the turn read remote content that also looked like instructions to the agent.',
     },
+    'tool_call.remote-destination': {
+        label: 'Destination from remote content',
+        doc: "A tool call's argument carried an address that only a remote tool's result named.",
+    },
     'network.blocked': {
         label: 'Address blocked',
-        doc: 'A tool tried to reach a private, local or disallowed address. The request was never made.',
+        doc: 'A tool tried to reach a private, local, or disallowed address. The request was never made.',
     },
 };
 const GUARDRAIL_CHECK_OPTIONS = {
@@ -329,6 +325,10 @@ const GUARDRAIL_CHECK_OPTIONS = {
         label: 'Remote-content gate',
         doc: 'Checked whether a tool that writes or deletes was called after the turn read remote content.',
     },
+    destination: {
+        label: 'Destination check',
+        doc: "Checked whether the call sends to an address that only a remote tool's result named.",
+    },
     tool_result: {
         label: 'Result check',
         doc: 'Checked what a tool returned before the model read it.',
@@ -350,6 +350,10 @@ const GUARDRAIL_CHECK_OPTIONS = {
         label: 'Streamed leak check',
         doc: "Checked each streamed tool call and other non-text output for the system prompt's canary.",
     },
+    tool_draft: {
+        label: 'Tool call preview check',
+        doc: 'Checked a tool call piece by piece as the model wrote it, before the host saw each piece.',
+    },
     live_input: { label: 'Live input check', doc: 'Checked text the host sent into a live session.' },
     live_output: {
         label: 'Live output check',
@@ -376,10 +380,15 @@ const SEVERITY_OPTIONS = {
     medium: { label: 'Medium', doc: 'Medium risk.' },
     high: { label: 'High', doc: 'High risk.' },
 };
+const EMBEDDING_TASKS = {
+    query: { label: 'Query', doc: 'The input is what a search looks for.' },
+    document: { label: 'Document', doc: 'The input is what a search looks through.' },
+};
 const GATE_KINDS = {
     confirmation: { label: 'Confirmation', doc: 'The user must confirm this call.' },
     permission: { label: 'Permission', doc: 'The user must allow this tool.' },
     auth: { label: 'Sign-in', doc: 'The tool needs a credential the user must provide.' },
+    page: { label: 'Page', doc: 'The call waits for the page that answers this tool.' },
 };
 const RETRY_REASONS = {
     egress: {
@@ -396,7 +405,7 @@ const COMPACTION_METER_OPTIONS = {
     history: { label: 'History', doc: 'Counts tokens across earlier turns.' },
     input: {
         label: 'Whole input',
-        doc: "Counts the turn's whole input: instructions, history and attachments.",
+        doc: "Counts the turn's whole input: instructions, history, and attachments.",
     },
 };
 const COMPACTION_OUTCOME_OPTIONS = {
@@ -432,7 +441,7 @@ const SESSION_KINDS = {
 const CLOSE_INITIATORS = {
     host: { label: 'Host', doc: 'The host closed the session.' },
     provider: { label: 'Provider', doc: 'The provider closed the socket.' },
-    theorem: { label: 'THEOREM', doc: 'THEOREM closed the socket.' },
+    theorem: { label: 'theorem', doc: 'theorem closed the socket.' },
 };
 const CLOCK_OPTIONS = {
     io: {
@@ -458,7 +467,7 @@ const SPAN_ATTRIBUTES = {
     'theorem.stop.kind': attr('agent', 'Stop reason', 'text', 'Why it ended. Absent when it failed before any stop.', STOP_KINDS),
     'theorem.attempts': attr('agent', 'Attempts', 'number', 'Times the turn ran its model calls, counting a retry after a guardrail or invalid JSON.'),
     'theorem.steps': attr('agent', 'Model calls', 'number', 'Model calls made (Live: responses).'),
-    'theorem.turn.time_to_first_text': attr('agent', 'Time to first visible text', 'seconds', 'From the start of the turn to the first reply text the host received, after every guardrail and holdback.'),
+    'theorem.turn.time_to_first_text': attr('agent', 'Time to first visible text', 'seconds', 'From the start of the turn to the first reply text the host received, after every guardrail and held tail.'),
     'theorem.guardrail.stream_ms': attr('agent', 'Stream guardrail time', 'milliseconds', "Time every check on this call's streamed output took, together; each check's own time is on its `theorem.guardrail` event."),
     'theorem.step': attr('agent', 'Step', 'number', 'Which model call of the turn this is, from 1.'),
     'theorem.attempt': attr('agent', 'Attempt', 'number', 'Which attempt of the turn made this call.'),
@@ -476,7 +485,6 @@ const SPAN_ATTRIBUTES = {
     'gen_ai.request.temperature': attr('request', 'Temperature', 'number', 'As requested.'),
     'gen_ai.request.max_tokens': attr('request', 'Max output tokens', 'tokens', 'As requested.'),
     'gen_ai.request.reasoning.level': attr('request', 'Thinking level', 'text', 'As requested.'),
-    'gen_ai.request.previous_response.id': attr('request', 'Continues response', 'id', 'The stored response this call continues.'),
     'gen_ai.output.type': attr('request', 'Output type', 'text', 'What kind of answer was asked for.', OUTPUT_TYPES),
     'theorem.key_slot': attr('request', 'API key', 'text', 'The vault key slot that finally answered, by the name the profile gave it.'),
     'theorem.request.builtins': attr('request', 'Provider tools', 'list', 'Tools the provider runs itself (search, maps, code), as requested.'),
@@ -496,6 +504,7 @@ const SPAN_ATTRIBUTES = {
     }),
     'theorem.request.speech': fields('request', 'Speech settings', 'The audio asked for.', {
         voice: attr('request', 'Voice', 'text', 'The voice.'),
+        speed: attr('request', 'Speed', 'number', "The speaking rate; 1 is the voice's own pace."),
         format: attr('request', 'Format', 'text', 'The audio format.'),
     }),
     'theorem.request.live': fields('request', 'Live settings', 'The Live session setup, as sent.', {
@@ -543,7 +552,7 @@ const SPAN_ATTRIBUTES = {
     'theorem.usage.cost_usd': attr('usage', 'Cost', 'usd', "As the provider reported it, or priced from Jev's fixed price for a decision. Absent when no call reported a cost."),
     'theorem.usage.upstream_cost_usd': attr('usage', 'Upstream cost', 'usd', "The upstream provider's cost, as a gateway reported it."),
     'theorem.usage.cost_partial': attr('usage', 'Cost is partial', 'boolean', 'Only some calls reported a cost.'),
-    'theorem.usage.estimated': attr('usage', 'Estimated', 'list', 'Sides whose token counts THEOREM estimated rather than the provider reporting them.', USAGE_SIDES),
+    'theorem.usage.estimated': attr('usage', 'Estimated', 'list', 'Sides whose token counts theorem estimated rather than the provider reporting them.', USAGE_SIDES),
     'theorem.usage.unknown_media': fields('usage', 'Uncounted media', 'Media items no counting rule covered, so their tokens are missing from the estimate.', {
         input: attr('usage', 'Input', 'number', 'Uncounted media the model read.'),
         output: attr('usage', 'Output', 'number', 'Uncounted media the model wrote.'),
@@ -567,7 +576,7 @@ const SPAN_ATTRIBUTES = {
     'url.path': attr('http', 'Path', 'id', 'The URL path. The query is never recorded.'),
     'http.response.status_code': attr('http', 'Status code', 'number', 'The HTTP status returned.'),
     'http.request.resend_count': attr('http', 'Retry number', 'number', '0 for the first try, then 1, 2, … for each retry.'),
-    'theorem.retry.backoff_ms': attr('http', 'Wait before retry', 'milliseconds', 'How long THEOREM waited after the previous try.'),
+    'theorem.retry.backoff_ms': attr('http', 'Wait before retry', 'milliseconds', 'How long theorem waited after the previous try.'),
     'error.type': {
         ...attr('error', 'Error kind', 'text', 'Why it failed: an error kind, the failing stop, or on an HTTP try its status or exception name.', ERROR_TYPE_OPTIONS),
         open: true,
@@ -580,12 +589,15 @@ const SPAN_ATTRIBUTES = {
     'theorem.clock': attr('record', 'Clock', 'text', 'How the times in this record were taken.', CLOCK_OPTIONS),
     'theorem.source': attr('part', 'Source', 'text', 'Where this text came from, when it is not the model’s own.', TRANSCRIPT_SOURCES),
     'theorem.interim': attr('part', 'Interim', 'boolean', 'An interim transcript, not the final one.'),
-    'theorem.observed_end': attr('part', 'Seen at', 'time', 'When THEOREM saw this provider-run step whole.'),
+    'theorem.observed_end': attr('part', 'Seen at', 'time', 'When theorem saw this provider-run step whole.'),
     'theorem.partial': attr('part', 'Incomplete', 'boolean', 'The provider sent this step incomplete.'),
+    'theorem.embedding.inputs': attr('request', 'Inputs', 'number', 'How many inputs the call embedded, one vector each.'),
+    'theorem.embedding.task': attr('request', 'Task', 'text', 'Whether the inputs are queries or documents, as the request said.', EMBEDDING_TASKS),
     'theorem.decision.contract': attr('decision', 'Contract', 'id', "The host's decision contract the profile names."),
     'theorem.decision.state': attr('decision', 'State', 'json', 'The JSON state the decision read.'),
-    'theorem.decision.questions': attr('decision', 'Questions', 'json', 'Each question by id: its kind, instructions and criteria.'),
-    'theorem.decision.answers': attr('decision', 'Answers', 'json', 'Each answer by question id: the choice or score, its confidence and probabilities.'),
+    'theorem.decision.questions': attr('decision', 'Questions', 'json', 'Each question by id: its kind, instructions, and criteria.'),
+    'theorem.decision.assets': attr('decision', 'Images', 'json', 'Each image by reference: its type and size. The image itself is never recorded.'),
+    'theorem.decision.answers': attr('decision', 'Answers', 'json', 'Each answer by question id: the choice, score, number or box, its confidence, and probabilities.'),
     'gen_ai.evaluation.name': attr('evaluation', 'Grader', 'id', 'The grader that produced this result.'),
     'gen_ai.evaluation.score.value': attr('evaluation', 'Score', 'number', 'The score, 0–1 unless the grader says otherwise.'),
     'gen_ai.evaluation.score.label': attr('evaluation', 'Label', 'text', "The grader's label for this trial, one of the labels it declares."),
@@ -623,7 +635,7 @@ function traceAttributeMeta(key) {
     const header = HEADER.exec(key);
     if (header) {
         const [, direction = '', name = ''] = header;
-        return attr('http', `${capitalize(direction)} header ${name}`, 'list', `The ${direction} header, as sent. A key, auth, cookie, secret or token header is [redacted].`);
+        return attr('http', `${capitalize(direction)} header ${name}`, 'list', `The ${direction} header, as sent. A key, auth, cookie, secret, or token header is [redacted].`);
     }
     return undefined;
 }
@@ -677,9 +689,19 @@ const TRACE_EVENTS = {
             reason: attr('agent', 'Reason', 'text', 'Why it retried.', RETRY_REASONS),
         },
     },
+    'theorem.step.resume': {
+        label: 'Sent again',
+        doc: 'A model call failed with no reply, and the turn sent it again.',
+        attributes: {
+            step: attr('agent', 'Step', 'number', 'The step whose model call was sent again.'),
+            resume: attr('agent', 'Re-send', 'number', 'How many calls the turn has sent again so far.'),
+            stop: attr('agent', 'Stop', 'text', 'How the failed call ended.'),
+            error: attr('error', 'Detail', 'content', "The provider's internal reason."),
+        },
+    },
     'theorem.compaction': {
         label: 'Compaction',
-        doc: 'THEOREM decided whether to summarize earlier messages.',
+        doc: 'theorem decided whether to summarize earlier messages.',
         attributes: {
             timing: attr('agent', 'Timing', 'text', 'When compaction runs.', COMPACTION_TIMING_OPTIONS),
             meter: attr('agent', 'Counts', 'text', 'What the threshold counts.', COMPACTION_METER_OPTIONS),
@@ -818,18 +840,34 @@ function traceEventMeta(name) {
 function traceEventAttributeMeta(event, key) {
     return TRACE_EVENTS[event]?.attributes[key] ?? traceAttributeMeta(key);
 }
+/** Labels and descriptions for each span type. */
 const TRACE_SPAN_TYPES = {
     turn: { label: 'Turn', doc: 'One exchange: the model calls and tool calls it took to answer.' },
     session: { label: 'Live session', doc: 'A Live session, from setup to close.' },
     call: { label: 'Model call', doc: 'One request to a model and its answer.' },
     response: { label: 'Live response', doc: 'One spoken response in a Live session.' },
-    tool: { label: 'Tool call', doc: 'One tool call THEOREM ran, from its hooks to settlement.' },
+    tool: { label: 'Tool call', doc: 'One tool call theorem ran, from its hooks to settlement.' },
     http: { label: 'HTTP try', doc: 'One HTTP attempt of a model call.' },
     cutout: { label: 'Cutout', doc: 'A side effect the host recorded after the turn.' },
     decision: { label: 'Decision', doc: 'One typed decision over JSON state.' },
     evaluation: { label: 'Evaluation', doc: 'An eval graded this trace, or a suite ran.' },
     host: { label: 'Host span', doc: 'A step the host recorded itself.' },
 };
+/**
+ * Every trace field and span type, named by the record they belong to: `trace.resource`, and a
+ * span type by the field it fills, `trace.type.turn`.
+ */
+function traceCatalogRows() {
+    const fields = Object.entries(TRACE_FIELDS).map(([key, meta]) => ({
+        name: `trace.${key}`,
+        ...meta,
+    }));
+    const spans = Object.entries(TRACE_SPAN_TYPES).map(([key, meta]) => ({
+        name: `trace.type.${key}`,
+        ...meta,
+    }));
+    return [...spans, ...fields];
+}
 function stringAttribute(span, key) {
     const value = span.attributes[key];
     return typeof value === 'string' ? value : undefined;
@@ -838,6 +876,7 @@ function withSubject(type, subject) {
     const meta = { type, ...TRACE_SPAN_TYPES[type] };
     return subject ? { ...meta, subject } : meta;
 }
+/** The label, subject, and description to show for a span. */
 function traceSpanMeta(span) {
     switch (stringAttribute(span, 'gen_ai.operation.name')) {
         case 'invoke_agent':
@@ -849,6 +888,8 @@ function traceSpanMeta(span) {
             return withSubject('tool', stringAttribute(span, 'gen_ai.tool.name'));
         case 'decide':
             return withSubject('decision', stringAttribute(span, 'gen_ai.agent.name'));
+        case 'embeddings':
+            return withSubject('call', stringAttribute(span, 'gen_ai.request.model'));
         default:
             break;
     }
@@ -862,4 +903,4 @@ function traceSpanMeta(span) {
     }
     return withSubject('host', span.name);
 }
-export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, };
+export { TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceCatalogRows, traceEventAttributeMeta, traceEventMeta, traceSpanMeta, };

package/esm/src/observability/trace-record.js

@@ -1,8 +1,10 @@
-// Include flags drop whole attribute families or events here, in one place, so a missing field
+// why: Include flags drop whole attribute families or events here, in one place, so a missing field
 // reads as "not recorded" and the root says which policy applied (`theorem.record.include`).
-import { redactSensitiveOnly, sanitizeText } from '../guardrails/sanitize.js';
+import { storedHostSpans, storedSpans } from '../guardrails/detect-at.js';
+import { SENSITIVE_GROUPS } from '../guardrails/sensitive-groups.js';
 import { sha256, sha256Base64 } from '../kernel/engine/hash.js';
 import { removeCanaries, tapeUpstream } from '../providers/shared/upstream-tape.js';
+import { applySpans } from './spans.js';
 import { TRACE_VERSION } from './trace-schema.js';
 import { isTraceBytes, isTraceContent, isTraceJson, } from './trace-span.js';
 /** Pinned OpenTelemetry GenAI semantic conventions the attribute names follow. */
@@ -19,17 +21,19 @@ const EVENT_INCLUDE = {
 const RAW_ATTRIBUTE = 'raw';
 /** Guardrail hits keep the matched text only under `guardrailMatchPreview`. */
 const MATCH_ATTRIBUTE = 'match';
-function scrubStoredText(text, scrub) {
-    if (scrub.sensitive && scrub.injection) {
-        return sanitizeText(text);
-    }
-    if (scrub.sensitive) {
-        return redactSensitiveOnly(text);
-    }
-    if (scrub.injection) {
-        return sanitizeText(text, { sanitizeInput: true, redactSensitive: false });
-    }
-    return text;
+/** The detectors `scrub.injection` cleans a record with. */
+const INSTRUCTION_DETECTORS = ['injection', 'tool_instructions'];
+/** Whether a switch cleans with one side's patterns, when it names its sides. */
+function sideOn(on, side) {
+    return on === true || (on !== false && on[side]);
+}
+function scrubStoredText(text, { scrub, detect }) {
+    const { sensitive, injection } = scrub;
+    return applySpans(text, [
+        ...(sensitive ? storedSpans(text, SENSITIVE_GROUPS, sensitive, detect) : []),
+        ...(sideOn(sensitive, 'host') ? storedHostSpans(text, detect) : []),
+        ...(injection ? storedSpans(text, INSTRUCTION_DETECTORS, injection, detect) : []),
+    ]);
 }
 async function storeText(text, resolver) {
     const hash = await sha256(text);
@@ -44,13 +48,13 @@ function markerRest(value, key) {
 /** Pass 1: text and bytes. `$json` waits for pass 2, when every text is known. */
 async function resolveContent(value, resolver) {
     if (isTraceContent(value)) {
-        const text = removeCanaries(scrubStoredText(value.$content, resolver.scrub), resolver.canaries);
+        const text = removeCanaries(scrubStoredText(value.$content, resolver), resolver.canaries);
         return { ...markerRest(value, '$content'), [TEXT_REF]: await storeText(text, resolver) };
     }
     if (isTraceBytes(value)) {
         const rest = markerRest(value, '$bytes');
         const digest = await sha256Base64(value.$bytes);
-        // Not base64: hash the text as given and say so, rather than lose the record.
+        // why: Not base64: hash the text as given and say so, rather than lose the record.
         return digest
             ? { ...rest, content_sha256: digest.hash, bytes: digest.bytes }
             : { ...rest, invalid_base64: true, text_sha256: await sha256(value.$bytes) };
@@ -75,7 +79,7 @@ function mapStrings(value, rewrite) {
 /** Scrub a row's strings, then reference any string pass 1 already stored. */
 function internRow(row, resolver) {
     return mapStrings(row, (text) => {
-        const scrubbed = scrubStoredText(text, resolver.scrub);
+        const scrubbed = scrubStoredText(text, resolver);
         const hash = resolver.known.get(scrubbed);
         return hash ? { [TEXT_REF]: hash } : scrubbed;
     });
@@ -158,7 +162,8 @@ async function buildRecord(args) {
     const { policy } = args;
     const resolver = {
         scrub: policy.scrub,
-        canaries: policy.scrub.canary ? (args.canaries ?? []) : [],
+        detect: policy.detect,
+        canaries: sideOn(policy.scrub.canary, 'theorem') ? (args.canaries ?? []) : [],
         content: {},
         known: new Map(),
     };

package/esm/src/observability/trace-schema.d.ts

@@ -4,6 +4,7 @@ export declare const TRACE_VERSION = 3;
 export type TraceAttributeValue = null | string | number | boolean | TraceAttributeValue[] | {
     [key: string]: TraceAttributeValue;
 };
+/** A span's or event's attributes, by name. */
 export type TraceAttributes = Record<string, TraceAttributeValue>;
 export declare const traceAttributesSchema: z.ZodType<TraceAttributes>;
 /** OTLP span kind. THEOREM emits INTERNAL (agent, tool) and CLIENT (model call). */
@@ -19,11 +20,13 @@ export interface TraceSpanLink {
     spanId: string;
     attributes: TraceAttributes;
 }
+/** A timestamped event on a span, with its attributes. */
 export interface TraceSpanEvent {
     name: string;
     timeUnixNano: string;
     attributes: TraceAttributes;
 }
+/** One span of a trace: its ids, name, kind, times, attributes, events, links, and status. */
 export interface TraceSpan {
     traceId: string;
     spanId: string;

package/esm/src/observability/trace-schema.js

@@ -1,4 +1,4 @@
-// Each type is checked against its zod schema (`Equals`), so a field in one and not the other fails
+// invariant: Each type is checked against its zod schema (`Equals`), so a field in one and not the other fails
 // the build. A record crosses a wire, so a reader parses it with `traceRecordSchema` first.
 import { z } from 'zod';
 export const TRACE_VERSION = 3;

package/esm/src/observability/trace-sink.d.ts

@@ -6,6 +6,7 @@ export interface TraceWriteContext {
     /** Size at which a file-based destination starts a new file. */
     rotateAfterMiB: number;
 }
+/** Where trace records go: `write` takes each record, and `onError` is told when building or writing one failed. */
 export interface TraceSink {
     write: (record: TraceRecord, context: TraceWriteContext) => Promise<void>;
     /** Called when `writeTrace` catches a build or write failure. Must not throw. */

package/esm/src/observability/trace-sink.js

@@ -1,3 +1,3 @@
-// Type-only so programs that never write files (browser bundles, Workers) never pull the JSONL
+// why: Type-only so programs that never write files (browser bundles, Workers) never pull the JSONL
 // file sink into their module graph.
 export {};

package/esm/src/observability/trace-span.d.ts

@@ -9,15 +9,17 @@ interface TraceBytes {
     [key: string]: TraceAttributeValue;
     $bytes: string;
 }
-/** In-memory provider row or wire body awaiting scrub, intern and hash at record build. */
+/** In-memory provider row or wire body awaiting scrub, intern, and hash at record build. */
 interface TraceJson {
     [key: string]: TraceAttributeValue;
     $json: TraceAttributeValue;
 }
+/** A link from a span to another trace, by its `traceparent`. */
 interface SpanLinkInput {
     traceparent: string;
     attributes?: TraceAttributes;
 }
+/** Options for starting a span: its kind, attributes, and links. */
 interface SpanOptions {
     kind?: TraceSpanKind;
     attributes?: TraceAttributes;
@@ -48,6 +50,7 @@ interface SpanHandle {
     /** Now on the trace's clock, as span timestamps are written. */
     nowUnixNano: () => string;
 }
+/** A trace being built: its root span and the clock it shares. */
 interface TraceTree {
     root: SpanHandle;
     /** The trace's clock; pass it to `startTrace` so related trees share one timeline. */
@@ -55,6 +58,7 @@ interface TraceTree {
     /** Closes anything still open as `ERROR` / `unclosed`; returns root first, then start order. */
     collect: () => TraceSpan[];
 }
+/** The clock a trace reads its timestamps from. */
 interface TraceClock {
     nowUnixNano: () => bigint;
 }
@@ -73,7 +77,9 @@ declare function parseTraceparent(value: string): {
     spanId: string;
 };
 declare function formatTraceparent(traceId: string, spanId: string): string;
+/** Marks text as message content, which the trace stores by hash. */
 declare function traceContent(text: string): TraceContent;
+/** Marks base64 data as bytes, which the trace stores by hash. */
 declare function traceBytes(base64: string): TraceBytes;
 /** `undefined` members and non-JSON values are dropped the way `JSON.stringify` drops them. */
 declare function traceJson(value: unknown): TraceJson;