autotel-genai 0.3.1 → 0.3.2

package/README.md

@@ -68,7 +68,8 @@ export const chat = traceGenAI({
 | **Trace** | `autotel-genai/trace` | `traceGenAI()`, `recordGenAiResponse/Usage` |
 | **Guard** | `autotel-genai/guard` | inline cost/token/loop kill-switch — `createGenAiBudget`, `createGenAiGuard`, `parseGuardRules` |
 | **Streaming** | `autotel-genai/streaming` | TTFC, throughput, inter-chunk distribution — `createStreamTimer`, `recordStreamTiming` |
-| **AI SDK** | `autotel-genai/ai-sdk` | Vercel `ai.*` → `gen_ai.*` mapping + cost |
+| **AI SDK** | `autotel-genai/observer` | `autotelTelemetry()` — `registerTelemetry()` integration: live `gen_ai.*` spans + cost + streaming + nested traces + opt-in content. `subscribeAiTelemetry()` — zero-config `ai:telemetry` channel path |
+| **AI SDK (legacy)** | `autotel-genai/ai-sdk` | `ai.*` → `gen_ai.*` mapping + cost for `LegacyOpenTelemetry`/older versions; `autotelEnrich()` for `@ai-sdk/otel` `enrichSpan` |
 | **Agents** | `autotel-genai/agent` | identity, delegation, policy, audit, privacy, non-repudiation |
 
 ### Cost
@@ -201,9 +202,75 @@ It honours spec breaking change #242 (`gen_ai.agent.id` is dropped on internal
 
 ### Vercel AI SDK
 
-The current AI SDK (`@ai-sdk/otel`'s `OpenTelemetry` integration) already emits
-`gen_ai.*` — nothing to map. For `LegacyOpenTelemetry`/older versions, or to add
-cost:
+Register `autotelTelemetry()` once and every `generateText` / `streamText` /
+`embed` call streams a canonical `gen_ai.*` span tree — live, as it runs:
+
+```ts
+import { registerTelemetry } from 'ai';
+import { autotelTelemetry } from 'autotel-genai/observer';
+
+registerTelemetry(autotelTelemetry()); // once, at startup
+```
+
+See `apps/example-ai-sdk-observer` for a runnable AI SDK + Ollama demo
+(generateText, tool loop, streamText timing, embeddings).
+
+It implements the AI SDK's stable `Telemetry` lifecycle interface (ai v7+), so
+it slots in exactly where `@ai-sdk/otel`'s `OpenTelemetry` does — but it also,
+on every `chat` span:
+
+- **prices the call** (`gen_ai.usage.cost.usd`) from `MODEL_PRICING`;
+- records **streaming throughput** (`time_to_first_chunk`, `time_to_finish`,
+  `output_tokens_per_second`);
+- keeps token usage on leaf `chat` spans only, so the `invoke_agent` root never
+  double-counts.
+
+It is push-based and concurrency-safe (every event carries the SDK `callId`),
+and it pulls in **no** dependency on `ai` — the returned object satisfies the
+`Telemetry` interface structurally, so the snippet above type-checks as-is.
+`rerank` has no canonical `gen_ai` operation and is intentionally not mapped.
+
+**Nested traces.** It implements the SDK's `executeTool` / `executeLanguageModelCall`
+context runners, so a tool whose `execute` calls `generateText` — and the
+provider's own auto-instrumented HTTP spans — nest under the right span
+automatically.
+
+**Content capture (opt-in).** Off by default for privacy. Turn it on to record
+prompts, responses, system instructions, and tool I/O, mapped to the
+[GenAI SemConv message format](#genai-message-format). The SDK's per-call
+`recordInputs` / `recordOutputs` are honored, and `exportContent` lets you redact
+or drop content per event:
+
+```ts
+registerTelemetry(
+  autotelTelemetry({
+    captureContent: true,
+    exportContent: (event) => redact(event), // optional: redact before write
+  }),
+);
+```
+
+**Zero-config (no `registerTelemetry`).** Subscribe to the SDK's `ai:telemetry`
+Node tracing channel instead. The SDK publishes operation spans as soon as the
+channel has a subscriber:
+
+```ts
+import { subscribeAiTelemetry } from 'autotel-genai/observer';
+
+const unsubscribe = subscribeAiTelemetry(); // once, at startup
+```
+
+The channel path gives you the same `invoke_agent › chat › execute_tool` tree
+with usage and cost, but not the per-call streaming timing (which only the
+lifecycle `onLanguageModelCallEnd` event carries) — prefer
+`registerTelemetry(autotelTelemetry())` when you can.
+
+Register globally, or pass per-call via `telemetry.integrations` to scope it to
+one call. For the **legacy** `LegacyOpenTelemetry`/older-version path, or to
+enrich spans another integration already emitted, the attribute bridge maps
+`ai.*` → `gen_ai.*` and adds cost; for versions before the `Telemetry` interface,
+walk the finished result with `observeAiSdkResult` (see
+[Observer](#observer-event-stream--spans)):
 
 ```ts
 import { mapAiSdkAttributes, recordAiSdkCost } from 'autotel-genai/ai-sdk';
@@ -212,6 +279,40 @@ const canonical = mapAiSdkAttributes(span.attributes); // ai.* → gen_ai.*
 recordAiSdkCost(ctx, span.attributes);                 // sets gen_ai.usage.cost.usd
 ```
 
+#### Already using `@ai-sdk/otel`?
+
+Drop `autotelEnrich()` into its `enrichSpan` to stamp autotel provenance and
+promote your `runtimeContext` onto every span:
+
+```ts
+import { OpenTelemetry } from '@ai-sdk/otel';
+import { autotelEnrich } from 'autotel-genai/ai-sdk';
+
+registerTelemetry(new OpenTelemetry({ enrichSpan: autotelEnrich() }));
+```
+
+`enrichSpan` **cannot add cost** — the SDK passes it only
+`{ spanType, operationId, callId, runtimeContext }` (no usage, no model), and its
+own attributes win over custom keys. To get `gen_ai.usage.cost.usd` on the model
+span, use `autotelTelemetry()` (it owns span creation). Either way,
+[`autotel-devtools`](../autotel-devtools) prices `gen_ai` spans on render, so cost
+shows there regardless of which integration emitted them.
+
+#### Local devtools, one line
+
+Point an OTLP exporter at a running `autotel-devtools` receiver and you get a
+live GenAI run view — cost, token breakdown, tool timeline, and a narrated
+"Explain run" walkthrough — that works in production too (unlike
+`@ai-sdk/devtools`, which is dev-only):
+
+```ts
+import { registerTelemetry } from 'ai';
+import { autotelTelemetry } from 'autotel-genai/observer';
+
+registerTelemetry(autotelTelemetry()); // → your OTLP pipeline → autotel-devtools
+// npx autotel-devtools  →  http://localhost:4318
+```
+
 ### Observer (event-stream → spans)
 
 When you instrument a framework that emits its own lifecycle stream (agent

package/dist/agent/index.js

@@ -1,3 +1,4 @@
-import { A as withAgentAction, C as withAgentSession, D as defineAgentToolCall, E as defineAgentAction, F as canonicalizeForHash, I as hashPayload, L as AGENT_AUDIT_SCHEMA_VERSION, M as flattenAgentAttributes, N as setAgentAttributes, O as recordDecisionBasis, P as createAgentAuditMetadata, S as createAgentIdentityRegistry, T as recordAgentHandoff, _ as withScopedTool, a as heuristicPlanRiskClassifier, b as resolvePrivacyProfile, c as recordControllerId, d as recordMemoryAccess, f as recordPlanRiskAssessment, g as tryRecordHumanApproval, h as runAgentPlanClassifier, i as deriveActionRiskClass, j as withAgentToolCall, k as recordPolicyDecision, l as recordHumanApproval, m as recordRenderOutput, n as AGENT_SECURITY_ATTR, o as recordActionRiskClass, p as recordPlanStep, r as agentContextFromSpan, s as recordActiveScopes, t as AGENT_PLAN_RISK_ATTR, u as recordInputProvenance, v as createSignedEventEnvelope, w as delegateToAgent, x as sanitizeAuditPayload, y as verifyEventEnvelopeHash } from "../agent-DthMDQbW.js";
+import { a as recordControllerId, c as recordMemoryAccess, d as tryRecordHumanApproval, i as recordActiveScopes, l as recordPlanStep, n as deriveActionRiskClass, o as recordHumanApproval, p as agentContextFromSpan, r as recordActionRiskClass, s as recordInputProvenance, t as AGENT_SECURITY_ATTR, u as recordRenderOutput } from "../agent-security-ChL0rIh-.js";
+import { C as canonicalizeForHash, S as createAgentAuditMetadata, T as AGENT_AUDIT_SCHEMA_VERSION, _ as recordPolicyDecision, a as withScopedTool, b as flattenAgentAttributes, c as resolvePrivacyProfile, d as withAgentSession, f as delegateToAgent, g as recordDecisionBasis, h as defineAgentToolCall, i as runAgentPlanClassifier, l as sanitizeAuditPayload, m as defineAgentAction, n as heuristicPlanRiskClassifier, o as createSignedEventEnvelope, p as recordAgentHandoff, r as recordPlanRiskAssessment, s as verifyEventEnvelopeHash, t as AGENT_PLAN_RISK_ATTR, u as createAgentIdentityRegistry, v as withAgentAction, w as hashPayload, x as setAgentAttributes, y as withAgentToolCall } from "../agent-yHB-GF6g.js";
 
 export { AGENT_AUDIT_SCHEMA_VERSION, AGENT_PLAN_RISK_ATTR, AGENT_SECURITY_ATTR, agentContextFromSpan, canonicalizeForHash, createAgentAuditMetadata, createAgentIdentityRegistry, createSignedEventEnvelope, defineAgentAction, defineAgentToolCall, delegateToAgent, deriveActionRiskClass, flattenAgentAttributes, hashPayload, heuristicPlanRiskClassifier, recordActionRiskClass, recordActiveScopes, recordAgentHandoff, recordControllerId, recordDecisionBasis, recordHumanApproval, recordInputProvenance, recordMemoryAccess, recordPlanRiskAssessment, recordPlanStep, recordPolicyDecision, recordRenderOutput, resolvePrivacyProfile, runAgentPlanClassifier, sanitizeAuditPayload, setAgentAttributes, tryRecordHumanApproval, verifyEventEnvelopeHash, withAgentAction, withAgentSession, withAgentToolCall, withScopedTool };

package/dist/agent-security-ChL0rIh-.js

@@ -0,0 +1,181 @@
+import { getTraceContext, otelTrace } from "autotel";
+import { hashIdentifier } from "autotel-audit";
+
+//#region src/agent/context.ts
+const MISSING_CONTEXT_MESSAGE = "[autotel-genai] No active trace context. Wrap the call in trace()/instrument(), pass options.ctx, or set options.onMissingContext to \"warn\"/\"skip\" to degrade gracefully instead of throwing.";
+/**
+* Resolve an agent context without throwing. Returns `null` when no trace context
+* is available, so callers can degrade gracefully (best-effort instrumentation).
+*/
+const INVALID_TRACE_ID = "00000000000000000000000000000000";
+function resolveContextSafe(ctx) {
+	if (ctx) return ctx;
+	const span = otelTrace.getActiveSpan();
+	if (!span) return null;
+	const ids = getTraceContext();
+	const sc = span.spanContext();
+	const traceId = ids?.traceId ?? sc.traceId;
+	if (!traceId || traceId === INVALID_TRACE_ID) return null;
+	return {
+		traceId,
+		spanId: ids?.spanId ?? sc.spanId,
+		correlationId: ids?.correlationId ?? traceId.slice(0, 16),
+		setAttribute: (key, value) => span.setAttribute(key, value),
+		setAttributes: (attrs) => span.setAttributes(attrs)
+	};
+}
+function resolveContext(ctx) {
+	const resolved = resolveContextSafe(ctx);
+	if (resolved) return resolved;
+	throw new Error(MISSING_CONTEXT_MESSAGE);
+}
+const warnedMissingContext = /* @__PURE__ */ new Set();
+/** Warn (once per action) that an agent action is running without a trace context. */
+function warnMissingContextOnce(action) {
+	if (warnedMissingContext.has(action)) return;
+	warnedMissingContext.add(action);
+	console.warn(`[autotel-genai] No active trace context for "${action}" — running un-audited. Wrap the call in trace()/instrument() or pass options.ctx to capture agent audit telemetry. (set options.onMissingContext: "throw" to fail fast, or "skip" to silence this warning)`);
+}
+/** Adapt an OpenTelemetry span (or span-like object) to {@link AgentContext}. */
+function agentContextFromSpan(span) {
+	const sc = span.spanContext();
+	return {
+		traceId: sc.traceId,
+		spanId: sc.spanId,
+		correlationId: sc.traceId.slice(0, 16),
+		setAttribute: (key, value) => span.setAttribute(key, value),
+		setAttributes: (attrs) => span.setAttributes(attrs)
+	};
+}
+function toAttributeValue(value) {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	if (Array.isArray(value)) {
+		if (value.every((entry) => typeof entry === "string")) return value;
+		if (value.every((entry) => typeof entry === "number")) return value;
+		if (value.every((entry) => typeof entry === "boolean")) return value;
+		try {
+			return JSON.stringify(value);
+		} catch {
+			return "<serialization-failed>";
+		}
+	}
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "bigint") return value.toString(10);
+	if (value === null || value === void 0) return;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return "<serialization-failed>";
+	}
+}
+
+//#endregion
+//#region src/agent/agent-security.ts
+/** Canonical agent security attribute keys (Google SAIF / human-control aligned). */
+const AGENT_SECURITY_ATTR = {
+	controllerId: "agent.controller.id",
+	inputProvenance: "agent.input.provenance",
+	actionRiskClass: "agent.action.risk_class",
+	consentRequired: "agent.consent.required",
+	consentOutcome: "agent.consent.outcome",
+	scopeActive: "agent.scope.active",
+	memoryOperation: "agent.memory.operation",
+	memoryIsolationKey: "agent.memory.isolation_key",
+	memoryContentHash: "agent.memory.content_hash",
+	planStepIndex: "agent.plan.step_index",
+	planToolIntents: "agent.plan.tool_intents",
+	planPolicyIds: "agent.plan.policy_ids",
+	outputFormat: "agent.output.format",
+	outputContainsUrl: "agent.output.contains_url",
+	outputUrlCount: "agent.output.url_count"
+};
+function setSecurityAttr(ctx, key, value) {
+	const attr = toAttributeValue(value);
+	if (attr === void 0) return;
+	const traceCtx = resolveContext(ctx);
+	if (Array.isArray(attr)) {
+		traceCtx.setAttributes({ [key]: attr });
+		return;
+	}
+	traceCtx.setAttribute(key, attr);
+}
+function setSecurityAttrs(ctx, attrs) {
+	const traceCtx = resolveContext(ctx);
+	const mapped = {};
+	for (const [key, value] of Object.entries(attrs)) {
+		const attr = toAttributeValue(value);
+		if (attr !== void 0) mapped[key] = attr;
+	}
+	if (Object.keys(mapped).length > 0) traceCtx.setAttributes(mapped);
+}
+/**
+* Derive a coarse action risk class from MCP tool hints or explicit overrides.
+*/
+function deriveActionRiskClass(hints, override) {
+	if (override) return override;
+	if (hints.financial) return "financial";
+	if (hints.exfiltrationCapable || hints.openWorldHint) return "exfiltration_capable";
+	if (hints.destructiveHint) return "destructive";
+	if (hints.readOnlyHint) return "read";
+	if (hints.untrustedContentHint) return "read";
+	return "write";
+}
+function recordControllerId(input) {
+	const id = input.hash === false ? input.controllerId : hashIdentifier(input.controllerId, { salt: input.hashSalt });
+	setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.controllerId, id);
+}
+function recordInputProvenance(input) {
+	setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.inputProvenance, input.provenance);
+}
+function recordHumanApproval(input) {
+	const attrs = {
+		[AGENT_SECURITY_ATTR.consentRequired]: input.required ?? true,
+		[AGENT_SECURITY_ATTR.consentOutcome]: input.approved ? "approved" : "denied",
+		"tool.call.id": input.toolCallId
+	};
+	if (input.toolName) attrs["tool.name"] = input.toolName;
+	if (input.controllerId) attrs[AGENT_SECURITY_ATTR.controllerId] = hashIdentifier(input.controllerId, { salt: input.hashSalt });
+	setSecurityAttrs(input.ctx, attrs);
+}
+function recordActiveScopes(input) {
+	setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.scopeActive, input.scopes);
+}
+function recordActionRiskClass(riskClass, options = {}) {
+	setSecurityAttr(options.ctx, AGENT_SECURITY_ATTR.actionRiskClass, riskClass);
+}
+function recordMemoryAccess(input) {
+	setSecurityAttrs(input.ctx, {
+		[AGENT_SECURITY_ATTR.memoryOperation]: input.operation,
+		[AGENT_SECURITY_ATTR.memoryIsolationKey]: input.isolationKey,
+		...input.contentHash !== void 0 && { [AGENT_SECURITY_ATTR.memoryContentHash]: input.contentHash }
+	});
+}
+function recordPlanStep(input) {
+	setSecurityAttrs(input.ctx, {
+		[AGENT_SECURITY_ATTR.planStepIndex]: input.stepIndex,
+		...input.toolIntents !== void 0 && { [AGENT_SECURITY_ATTR.planToolIntents]: input.toolIntents },
+		...input.policyIds !== void 0 && { [AGENT_SECURITY_ATTR.planPolicyIds]: input.policyIds },
+		...input.summary !== void 0 && { "decision.summary": input.summary }
+	});
+}
+function recordRenderOutput(input) {
+	setSecurityAttrs(input.ctx, {
+		...input.format !== void 0 && { [AGENT_SECURITY_ATTR.outputFormat]: input.format },
+		...input.containsUrl !== void 0 && { [AGENT_SECURITY_ATTR.outputContainsUrl]: input.containsUrl },
+		...input.urlCount !== void 0 && { [AGENT_SECURITY_ATTR.outputUrlCount]: input.urlCount }
+	});
+}
+/** Best-effort variant — no throw when trace context is missing. */
+function tryRecordHumanApproval(input) {
+	const ctx = resolveContextSafe(input.ctx);
+	if (!ctx) return false;
+	recordHumanApproval({
+		...input,
+		ctx
+	});
+	return true;
+}
+
+//#endregion
+export { warnMissingContextOnce as _, recordControllerId as a, recordMemoryAccess as c, tryRecordHumanApproval as d, MISSING_CONTEXT_MESSAGE as f, toAttributeValue as g, resolveContextSafe as h, recordActiveScopes as i, recordPlanStep as l, resolveContext as m, deriveActionRiskClass as n, recordHumanApproval as o, agentContextFromSpan as p, recordActionRiskClass as r, recordInputProvenance as s, AGENT_SECURITY_ATTR as t, recordRenderOutput as u };
+//# sourceMappingURL=agent-security-ChL0rIh-.js.map

package/dist/agent-security-ChL0rIh-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-security-ChL0rIh-.js","names":[],"sources":["../src/agent/context.ts","../src/agent/agent-security.ts"],"sourcesContent":["import { getTraceContext, otelTrace } from 'autotel';\n\nexport interface AgentContext {\n  traceId: string;\n  spanId: string;\n  correlationId: string;\n  setAttribute(key: string, value: string | number | boolean): void;\n  setAttributes(\n    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,\n  ): void;\n}\n\nexport const MISSING_CONTEXT_MESSAGE =\n  '[autotel-genai] No active trace context. Wrap the call in trace()/instrument(), pass options.ctx, ' +\n  'or set options.onMissingContext to \"warn\"/\"skip\" to degrade gracefully instead of throwing.';\n\n/**\n * Resolve an agent context without throwing. Returns `null` when no trace context\n * is available, so callers can degrade gracefully (best-effort instrumentation).\n */\nconst INVALID_TRACE_ID = '00000000000000000000000000000000';\n\nexport function resolveContextSafe(ctx?: AgentContext): AgentContext | null {\n  if (ctx) return ctx;\n\n  const span = otelTrace.getActiveSpan();\n  if (!span) return null;\n\n  // Resolve trace ids from autotel's context when available, otherwise from the\n  // active OTel span itself. This makes agent audit work in *any* OTel setup —\n  // @effect/opentelemetry, a vanilla NodeSDK, autotel-cloudflare's instrumented\n  // fetch handler — not just inside autotel's own `trace()`.\n  const ids = getTraceContext();\n  const sc = span.spanContext();\n  const traceId = ids?.traceId ?? sc.traceId;\n  if (!traceId || traceId === INVALID_TRACE_ID) return null;\n\n  return {\n    traceId,\n    spanId: ids?.spanId ?? sc.spanId,\n    correlationId: ids?.correlationId ?? traceId.slice(0, 16),\n    setAttribute: (key, value) => span.setAttribute(key, value),\n    setAttributes: (attrs) => span.setAttributes(attrs),\n  };\n}\n\nexport function resolveContext(ctx?: AgentContext): AgentContext {\n  const resolved = resolveContextSafe(ctx);\n  if (resolved) return resolved;\n  throw new Error(MISSING_CONTEXT_MESSAGE);\n}\n\nconst warnedMissingContext = new Set<string>();\n\n/** Warn (once per action) that an agent action is running without a trace context. */\nexport function warnMissingContextOnce(action: string): void {\n  if (warnedMissingContext.has(action)) return;\n  warnedMissingContext.add(action);\n  console.warn(\n    `[autotel-genai] No active trace context for \"${action}\" — running un-audited. ` +\n      'Wrap the call in trace()/instrument() or pass options.ctx to capture agent audit telemetry. ' +\n      '(set options.onMissingContext: \"throw\" to fail fast, or \"skip\" to silence this warning)',\n  );\n}\n\n/** A no-op {@link AgentContext} whose attribute setters do nothing. */\nexport function noopAgentContext(): AgentContext {\n  return {\n    traceId: '',\n    spanId: '',\n    correlationId: '',\n    setAttribute() {},\n    setAttributes() {},\n  };\n}\n\n/** Adapt an OpenTelemetry span (or span-like object) to {@link AgentContext}. */\nexport function agentContextFromSpan(span: {\n  spanContext(): { traceId: string; spanId: string };\n  setAttribute(key: string, value: string | number | boolean): void;\n  setAttributes(\n    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,\n  ): void;\n}): AgentContext {\n  const sc = span.spanContext();\n  return {\n    traceId: sc.traceId,\n    spanId: sc.spanId,\n    correlationId: sc.traceId.slice(0, 16),\n    setAttribute: (key, value) => span.setAttribute(key, value),\n    setAttributes: (attrs) => span.setAttributes(attrs),\n  };\n}\n\nexport function toAttributeValue(\n  value: unknown,\n): string | number | boolean | string[] | number[] | boolean[] | undefined {\n  if (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  ) {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    if (value.every((entry) => typeof entry === 'string')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'number')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'boolean')) {\n      return value;\n    }\n\n    try {\n      return JSON.stringify(value);\n    } catch {\n      return '<serialization-failed>';\n    }\n  }\n\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  if (typeof value === 'bigint') {\n    return value.toString(10);\n  }\n\n  if (value === null || value === undefined) {\n    return undefined;\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return '<serialization-failed>';\n  }\n}\n","import { hashIdentifier } from 'autotel-audit';\nimport { resolveContext, resolveContextSafe, toAttributeValue, type AgentContext } from './context.js';\n\n/** Canonical agent security attribute keys (Google SAIF / human-control aligned). */\nexport const AGENT_SECURITY_ATTR = {\n  controllerId: 'agent.controller.id',\n  inputProvenance: 'agent.input.provenance',\n  actionRiskClass: 'agent.action.risk_class',\n  consentRequired: 'agent.consent.required',\n  consentOutcome: 'agent.consent.outcome',\n  scopeActive: 'agent.scope.active',\n  memoryOperation: 'agent.memory.operation',\n  memoryIsolationKey: 'agent.memory.isolation_key',\n  memoryContentHash: 'agent.memory.content_hash',\n  planStepIndex: 'agent.plan.step_index',\n  planToolIntents: 'agent.plan.tool_intents',\n  planPolicyIds: 'agent.plan.policy_ids',\n  outputFormat: 'agent.output.format',\n  outputContainsUrl: 'agent.output.contains_url',\n  outputUrlCount: 'agent.output.url_count',\n} as const;\n\nexport type AgentInputProvenance =\n  | 'user_direct'\n  | 'user_voice'\n  | 'rag'\n  | 'memory'\n  | 'tool_result'\n  | 'external_untrusted';\n\nexport type AgentActionRiskClass =\n  | 'read'\n  | 'write'\n  | 'destructive'\n  | 'financial'\n  | 'exfiltration_capable';\n\nexport type AgentConsentOutcome = 'approved' | 'denied' | 'timeout' | 'revoked';\n\nexport type AgentMemoryOperation = 'read' | 'write' | 'delete' | 'search';\n\nexport type AgentOutputFormat = 'text' | 'markdown' | 'html' | 'json' | 'mixed';\n\nexport interface AgentSecurityRecordOptions {\n  ctx?: AgentContext;\n}\n\nexport interface RecordControllerInput extends AgentSecurityRecordOptions {\n  /** Controlling human user id — hashed before emission unless already a digest. */\n  controllerId: string;\n  /** Pass a stable per-deployment salt to `hashIdentifier`. */\n  hashSalt?: string;\n  /** When false, emit the id as given (must not be raw PII). Default true. */\n  hash?: boolean;\n}\n\nexport interface RecordInputProvenanceInput extends AgentSecurityRecordOptions {\n  provenance: AgentInputProvenance;\n}\n\nexport interface RecordHumanApprovalInput extends AgentSecurityRecordOptions {\n  toolCallId: string;\n  toolName?: string;\n  approved: boolean;\n  required?: boolean;\n  controllerId?: string;\n  hashSalt?: string;\n}\n\nexport interface RecordActiveScopesInput extends AgentSecurityRecordOptions {\n  scopes: string[];\n}\n\nexport interface RecordMemoryAccessInput extends AgentSecurityRecordOptions {\n  operation: AgentMemoryOperation;\n  isolationKey: string;\n  contentHash?: string;\n}\n\nexport interface RecordPlanStepInput extends AgentSecurityRecordOptions {\n  stepIndex: number;\n  toolIntents?: string[];\n  policyIds?: string[];\n  summary?: string;\n}\n\nexport interface RecordRenderOutputInput extends AgentSecurityRecordOptions {\n  format?: AgentOutputFormat;\n  containsUrl?: boolean;\n  urlCount?: number;\n}\n\nexport interface ActionRiskHints {\n  readOnlyHint?: boolean;\n  destructiveHint?: boolean;\n  openWorldHint?: boolean;\n  untrustedContentHint?: boolean;\n  financial?: boolean;\n  exfiltrationCapable?: boolean;\n}\n\nfunction setSecurityAttr(\n  ctx: AgentContext | undefined,\n  key: string,\n  value: unknown,\n): void {\n  const attr = toAttributeValue(value);\n  if (attr === undefined) return;\n  const traceCtx = resolveContext(ctx);\n  if (Array.isArray(attr)) {\n    traceCtx.setAttributes({ [key]: attr });\n    return;\n  }\n  traceCtx.setAttribute(key, attr);\n}\n\nfunction setSecurityAttrs(\n  ctx: AgentContext | undefined,\n  attrs: Record<string, unknown>,\n): void {\n  const traceCtx = resolveContext(ctx);\n  const mapped: Record<string, string | number | boolean | string[] | number[] | boolean[]> =\n    {};\n  for (const [key, value] of Object.entries(attrs)) {\n    const attr = toAttributeValue(value);\n    if (attr !== undefined) {\n      mapped[key] = attr;\n    }\n  }\n  if (Object.keys(mapped).length > 0) {\n    traceCtx.setAttributes(mapped);\n  }\n}\n\n/**\n * Derive a coarse action risk class from MCP tool hints or explicit overrides.\n */\nexport function deriveActionRiskClass(\n  hints: ActionRiskHints,\n  override?: AgentActionRiskClass,\n): AgentActionRiskClass {\n  if (override) return override;\n  if (hints.financial) return 'financial';\n  if (hints.exfiltrationCapable || hints.openWorldHint) {\n    return 'exfiltration_capable';\n  }\n  if (hints.destructiveHint) return 'destructive';\n  if (hints.readOnlyHint) return 'read';\n  if (hints.untrustedContentHint) return 'read';\n  return 'write';\n}\n\nexport function recordControllerId(input: RecordControllerInput): void {\n  const id =\n    input.hash === false\n      ? input.controllerId\n      : hashIdentifier(input.controllerId, { salt: input.hashSalt });\n  setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.controllerId, id);\n}\n\nexport function recordInputProvenance(input: RecordInputProvenanceInput): void {\n  setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.inputProvenance, input.provenance);\n}\n\nexport function recordHumanApproval(input: RecordHumanApprovalInput): void {\n  const attrs: Record<string, unknown> = {\n    [AGENT_SECURITY_ATTR.consentRequired]: input.required ?? true,\n    [AGENT_SECURITY_ATTR.consentOutcome]: input.approved ? 'approved' : 'denied',\n    'tool.call.id': input.toolCallId,\n  };\n  if (input.toolName) {\n    attrs['tool.name'] = input.toolName;\n  }\n  if (input.controllerId) {\n    attrs[AGENT_SECURITY_ATTR.controllerId] = hashIdentifier(input.controllerId, {\n      salt: input.hashSalt,\n    });\n  }\n  setSecurityAttrs(input.ctx, attrs);\n}\n\nexport function recordActiveScopes(input: RecordActiveScopesInput): void {\n  setSecurityAttr(input.ctx, AGENT_SECURITY_ATTR.scopeActive, input.scopes);\n}\n\nexport function recordActionRiskClass(\n  riskClass: AgentActionRiskClass,\n  options: AgentSecurityRecordOptions = {},\n): void {\n  setSecurityAttr(options.ctx, AGENT_SECURITY_ATTR.actionRiskClass, riskClass);\n}\n\nexport function recordMemoryAccess(input: RecordMemoryAccessInput): void {\n  setSecurityAttrs(input.ctx, {\n    [AGENT_SECURITY_ATTR.memoryOperation]: input.operation,\n    [AGENT_SECURITY_ATTR.memoryIsolationKey]: input.isolationKey,\n    ...(input.contentHash !== undefined && {\n      [AGENT_SECURITY_ATTR.memoryContentHash]: input.contentHash,\n    }),\n  });\n}\n\nexport function recordPlanStep(input: RecordPlanStepInput): void {\n  setSecurityAttrs(input.ctx, {\n    [AGENT_SECURITY_ATTR.planStepIndex]: input.stepIndex,\n    ...(input.toolIntents !== undefined && {\n      [AGENT_SECURITY_ATTR.planToolIntents]: input.toolIntents,\n    }),\n    ...(input.policyIds !== undefined && {\n      [AGENT_SECURITY_ATTR.planPolicyIds]: input.policyIds,\n    }),\n    ...(input.summary !== undefined && { 'decision.summary': input.summary }),\n  });\n}\n\nexport function recordRenderOutput(input: RecordRenderOutputInput): void {\n  setSecurityAttrs(input.ctx, {\n    ...(input.format !== undefined && {\n      [AGENT_SECURITY_ATTR.outputFormat]: input.format,\n    }),\n    ...(input.containsUrl !== undefined && {\n      [AGENT_SECURITY_ATTR.outputContainsUrl]: input.containsUrl,\n    }),\n    ...(input.urlCount !== undefined && {\n      [AGENT_SECURITY_ATTR.outputUrlCount]: input.urlCount,\n    }),\n  });\n}\n\n/** Best-effort variant — no throw when trace context is missing. */\nexport function tryRecordHumanApproval(input: RecordHumanApprovalInput): boolean {\n  const ctx = resolveContextSafe(input.ctx);\n  if (!ctx) return false;\n  recordHumanApproval({ ...input, ctx });\n  return true;\n}\n"],"mappings":"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"}

package/dist/{agent-DthMDQbW.js → agent-yHB-GF6g.js}

@@ -1,6 +1,6 @@
 import { estimateLLMCost } from "./cost.js";
 import { i as genAiResponseAttributes, r as genAiRequestAttributes, s as genAiUsageAttributes } from "./attributes-DU-PmLqZ.js";
-import { a as toAttributeValue, i as resolveContextSafe, o as warnMissingContextOnce, r as resolveContext, t as MISSING_CONTEXT_MESSAGE } from "./context-B2wjX3O1.js";
+import { _ as warnMissingContextOnce, f as MISSING_CONTEXT_MESSAGE, g as toAttributeValue, h as resolveContextSafe, m as resolveContext } from "./agent-security-ChL0rIh-.js";
 import { createNoopRequestLogger, createStructuredError, getRequestLoggerSafe } from "autotel";
 import { forceKeepAuditEvent, securityEvent, withAudit } from "autotel-audit";
 import { createHash } from "node:crypto";
@@ -903,5 +903,98 @@ async function withScopedTool(definition, input, fn, options = {}) {
 }
 
 //#endregion
-export { withAgentAction as A, withAgentSession as C, defineAgentToolCall as D, defineAgentAction as E, canonicalizeForHash as F, hashPayload as I, AGENT_AUDIT_SCHEMA_VERSION as L, flattenAgentAttributes as M, setAgentAttributes as N, recordDecisionBasis as O, createAgentAuditMetadata as P, createAgentIdentityRegistry as S, recordAgentHandoff as T, withScopedTool as _, heuristicPlanRiskClassifier as a, resolvePrivacyProfile as b, recordControllerId as c, recordMemoryAccess as d, recordPlanRiskAssessment as f, tryRecordHumanApproval as g, runAgentPlanClassifier as h, deriveActionRiskClass as i, withAgentToolCall as j, recordPolicyDecision as k, recordHumanApproval as l, recordRenderOutput as m, AGENT_SECURITY_ATTR as n, recordActionRiskClass as o, recordPlanStep as p, agentContextFromSpan as r, recordActiveScopes as s, AGENT_PLAN_RISK_ATTR as t, recordInputProvenance as u, createSignedEventEnvelope as v, delegateToAgent as w, sanitizeAuditPayload as x, verifyEventEnvelopeHash as y };
-//# sourceMappingURL=agent-DthMDQbW.js.map
+//#region src/agent/agent-plan-classifier.ts
+/** Canonical plan-risk attribute keys (Google SAIF plan-risk predictor aligned). */
+const AGENT_PLAN_RISK_ATTR = {
+	verdict: "agent.plan.risk.verdict",
+	score: "agent.plan.risk.score",
+	categories: "agent.plan.risk.categories",
+	toolSequence: "agent.plan.risk.tool_sequence"
+};
+function setPlanRiskAttrs(ctx, attrs) {
+	const traceCtx = resolveContext(ctx);
+	const mapped = {};
+	for (const [key, value] of Object.entries(attrs)) {
+		const attr = toAttributeValue(value);
+		if (attr !== void 0) mapped[key] = attr;
+	}
+	if (Object.keys(mapped).length > 0) traceCtx.setAttributes(mapped);
+}
+/**
+* Stamp plan-risk assessment attrs on the active span.
+*/
+function recordPlanRiskAssessment(options) {
+	const { assessment, toolSequence } = options;
+	setPlanRiskAttrs(options.ctx, {
+		[AGENT_PLAN_RISK_ATTR.verdict]: assessment.verdict,
+		...assessment.score !== void 0 && { [AGENT_PLAN_RISK_ATTR.score]: assessment.score },
+		...assessment.categories?.length && { [AGENT_PLAN_RISK_ATTR.categories]: assessment.categories },
+		...toolSequence?.length && { [AGENT_PLAN_RISK_ATTR.toolSequence]: toolSequence },
+		...assessment.reason !== void 0 && { "decision.summary": assessment.reason }
+	});
+	if (options.emitSecurityEvent && assessment.verdict !== "low") securityEvent({
+		name: "llm.plan.risk.elevated",
+		category: "llm",
+		outcome: assessment.verdict === "critical" ? "blocked" : "denied",
+		severity: assessment.verdict === "critical" ? "critical" : assessment.verdict === "high" ? "error" : "warning",
+		reason: assessment.reason ?? assessment.verdict,
+		...assessment.score !== void 0 && { score: assessment.score },
+		...assessment.categories?.length && { categories: assessment.categories.join(",") }
+	}, { ctx: options.ctx });
+}
+/**
+* Run a pluggable plan-risk classifier and record its verdict on the span.
+* Classifier failures degrade quietly (no assessment recorded).
+*/
+async function runAgentPlanClassifier(classifier, input, options = {}) {
+	let assessment;
+	try {
+		assessment = await classifier(input);
+	} catch {
+		return;
+	}
+	if (!assessment) return void 0;
+	recordPlanRiskAssessment({
+		...options,
+		assessment,
+		toolSequence: input.toolSequence
+	});
+	return assessment;
+}
+const DESTRUCTIVE_TOOL = /\b(delete|remove|send|post|transfer|pay|upload|execute)\b/i;
+const UNTRUSTED_READ = /\b(read|fetch|get|search|load|parse|inbox|email|web|scrape)\b/i;
+/**
+* Dependency-free first-pass plan-risk heuristic. Opt-in — pass as
+* `AgentPlanClassifier` or wrap your own Model Armor / Llama Guard adapter.
+*/
+function heuristicPlanRiskClassifier() {
+	return ({ toolSequence }) => {
+		if (toolSequence.length === 0) return {
+			verdict: "low",
+			score: 0
+		};
+		const normalized = toolSequence.map((name) => name.replaceAll("_", " "));
+		const hasDestructive = normalized.some((name) => DESTRUCTIVE_TOOL.test(name));
+		const hasUntrustedRead = normalized.some((name) => UNTRUSTED_READ.test(name));
+		if (hasDestructive && hasUntrustedRead) return {
+			verdict: "high",
+			score: .85,
+			categories: ["untrusted_to_destructive_chain"],
+			reason: "mixed_untrusted_and_destructive_tools"
+		};
+		if (toolSequence.length >= 8) return {
+			verdict: "medium",
+			score: .55,
+			categories: ["long_tool_chain"],
+			reason: "long_tool_sequence"
+		};
+		return {
+			verdict: "low",
+			score: .1
+		};
+	};
+}
+
+//#endregion
+export { canonicalizeForHash as C, createAgentAuditMetadata as S, AGENT_AUDIT_SCHEMA_VERSION as T, recordPolicyDecision as _, withScopedTool as a, flattenAgentAttributes as b, resolvePrivacyProfile as c, withAgentSession as d, delegateToAgent as f, recordDecisionBasis as g, defineAgentToolCall as h, runAgentPlanClassifier as i, sanitizeAuditPayload as l, defineAgentAction as m, heuristicPlanRiskClassifier as n, createSignedEventEnvelope as o, recordAgentHandoff as p, recordPlanRiskAssessment as r, verifyEventEnvelopeHash as s, AGENT_PLAN_RISK_ATTR as t, createAgentIdentityRegistry as u, withAgentAction as v, hashPayload as w, setAgentAttributes as x, withAgentToolCall as y };
+//# sourceMappingURL=agent-yHB-GF6g.js.map