autotel-genai 0.1.0

package/dist/agent-CqXauTpC.js

@@ -0,0 +1,951 @@
+import { estimateLLMCost } from "./cost.js";
+import { i as genAiResponseAttributes, r as genAiRequestAttributes, s as genAiUsageAttributes } from "./attributes--Pdezjj6.js";
+import { createNoopRequestLogger, createStructuredError, getRequestLoggerSafe, getTraceContext, otelTrace } from "autotel";
+import { createHash } from "node:crypto";
+import { forceKeepAuditEvent, withAudit } from "autotel-audit";
+
+//#region src/agent/constants.ts
+const AGENT_AUDIT_SCHEMA_VERSION = "1.1.0";
+
+//#endregion
+//#region src/agent/hash.ts
+function canonicalize(value) {
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "bigint") return value.toString(10);
+	if (Array.isArray(value)) return value.map((entry) => canonicalize(entry));
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value);
+		entries.sort(([left], [right]) => left.localeCompare(right));
+		return Object.fromEntries(entries.map(([key, entryValue]) => [key, canonicalize(entryValue)]));
+	}
+	return value;
+}
+function canonicalizeForHash(value) {
+	return JSON.stringify(canonicalize(value));
+}
+function hashPayload(value, options = {}) {
+	const algorithm = options.algorithm ?? "sha256";
+	const canonical = canonicalizeForHash(value);
+	return `${algorithm}:${createHash(algorithm).update(canonical).digest("hex")}`;
+}
+
+//#endregion
+//#region src/agent/metadata.ts
+function defaultEventKind(metadata) {
+	if (metadata.eventKind) return metadata.eventKind;
+	if (metadata.tool) return "tool_call";
+	if (metadata.policy) return "policy_decision";
+	return "action";
+}
+function normalizeTool(tool) {
+	if (!tool) return void 0;
+	return {
+		name: tool.name,
+		...tool.callId !== void 0 && { callId: tool.callId },
+		inputHash: tool.input === void 0 ? tool.inputHash : tool.inputHash ?? hashPayload(tool.input),
+		outputHash: tool.output === void 0 ? tool.outputHash : tool.outputHash ?? hashPayload(tool.output),
+		...tool.status !== void 0 && { status: tool.status },
+		...tool.executionMs !== void 0 && { executionMs: tool.executionMs }
+	};
+}
+function sanitizeTool(tool) {
+	if (!tool) return void 0;
+	return {
+		name: tool.name,
+		...tool.callId !== void 0 && { callId: tool.callId },
+		...tool.inputHash !== void 0 && { inputHash: tool.inputHash },
+		...tool.outputHash !== void 0 && { outputHash: tool.outputHash },
+		...tool.status !== void 0 && { status: tool.status },
+		...tool.executionMs !== void 0 && { executionMs: tool.executionMs }
+	};
+}
+function sanitizeGovernance(governance) {
+	if (!governance) return void 0;
+	return {
+		...governance.reviewRequired !== void 0 && { reviewRequired: governance.reviewRequired },
+		...governance.reviewerId !== void 0 && { reviewerId: governance.reviewerId },
+		...governance.controlId !== void 0 && { controlId: governance.controlId },
+		...governance.documentationUrl !== void 0 && { documentationUrl: governance.documentationUrl },
+		...governance.lifecycleStage !== void 0 && { lifecycleStage: governance.lifecycleStage },
+		...governance.framework !== void 0 && { framework: governance.framework }
+	};
+}
+function normalizeDecision(decision, reasoningSummary) {
+	if (decision) return {
+		...decision,
+		summary: decision.summary ?? reasoningSummary ?? ""
+	};
+	if (reasoningSummary === void 0) return void 0;
+	return { summary: reasoningSummary };
+}
+function createAgentAuditMetadata(metadata) {
+	const eventKind = defaultEventKind(metadata);
+	if (eventKind === "tool_call" && !metadata.tool) throw new Error("[autotel-genai] eventKind \"tool_call\" requires metadata.tool.");
+	if (eventKind === "policy_decision" && !metadata.policy) throw new Error("[autotel-genai] eventKind \"policy_decision\" requires metadata.policy.");
+	if (eventKind === "handoff" && !metadata.delegation) throw new Error("[autotel-genai] eventKind \"handoff\" requires metadata.delegation.");
+	const delegation = metadata.delegation && (metadata.delegation.authorityLineageHash === void 0 || metadata.delegation.depth === void 0) ? {
+		...metadata.delegation,
+		...metadata.delegation.authorityLineage && {
+			authorityLineageHash: metadata.delegation.authorityLineageHash ?? hashPayload(metadata.delegation.authorityLineage),
+			depth: metadata.delegation.depth ?? Math.max(metadata.delegation.authorityLineage.length - 1, 0)
+		}
+	} : metadata.delegation;
+	return {
+		...metadata,
+		schemaVersion: metadata.schemaVersion ?? "1.1.0",
+		eventKind,
+		decision: normalizeDecision(metadata.decision, metadata.reasoningSummary),
+		...delegation !== void 0 && { delegation }
+	};
+}
+function normalizeMetadata(metadata) {
+	const normalized = createAgentAuditMetadata(metadata);
+	return {
+		...normalized,
+		tool: normalizeTool(normalized.tool)
+	};
+}
+function buildAuditMetadata(metadata) {
+	return {
+		action: metadata.action,
+		...metadata.resource !== void 0 && { resource: metadata.resource },
+		actorId: metadata.actorId ?? metadata.delegation?.parentIdentity ?? metadata.agent.id,
+		category: metadata.category ?? "agent",
+		...metadata.outcome !== void 0 && { outcome: metadata.outcome },
+		agentId: metadata.agent.id,
+		agentEventKind: metadata.eventKind,
+		agentAuditVersion: metadata.schemaVersion,
+		...metadata.agent.version !== void 0 && { agentVersion: metadata.agent.version },
+		...metadata.tool?.name !== void 0 && { toolName: metadata.tool.name },
+		...metadata.policy?.decision !== void 0 && { policyDecision: metadata.policy.decision },
+		...metadata.session?.status !== void 0 && { sessionStatus: metadata.session.status }
+	};
+}
+function buildLoggerContext(metadata) {
+	const tool = sanitizeTool(metadata.tool);
+	const governance = sanitizeGovernance(metadata.governance);
+	const context = {
+		agent: {
+			...metadata.agent,
+			...metadata.resource !== void 0 && { resource: metadata.resource },
+			...metadata.outcome !== void 0 && { outcome: metadata.outcome },
+			...metadata.reasoningSummary !== void 0 && { reasoningSummary: metadata.reasoningSummary },
+			schemaVersion: metadata.schemaVersion ?? "1.1.0",
+			eventKind: metadata.eventKind ?? defaultEventKind(metadata)
+		},
+		...metadata.delegation !== void 0 && { delegation: metadata.delegation },
+		...tool !== void 0 && { tool },
+		...metadata.policy !== void 0 && { policy: metadata.policy },
+		...governance !== void 0 && { governance },
+		...metadata.session !== void 0 && { session: metadata.session },
+		...metadata.decision !== void 0 && { decision: metadata.decision }
+	};
+	return structuredClone(context);
+}
+/**
+* Context for the *completion* `logger.set()` of a specialized lifecycle
+* wrapper. Carries only the domain state that finished mutating — tool or
+* session status. Outcome is owned by `withAgentAction`, which wraps every
+* variant and stamps it on both span and log. This deliberately omits the
+* request-level `delegation`/`decision` blocks: those were set once at the
+* start, and re-sending them would concatenate their array fields into the
+* wide event (see `buildLoggerContext`).
+*/
+function buildLifecycleUpdateContext(metadata) {
+	const tool = sanitizeTool(metadata.tool);
+	return {
+		...tool !== void 0 && { tool },
+		...metadata.session !== void 0 && { session: structuredClone(metadata.session) }
+	};
+}
+
+//#endregion
+//#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)`);
+}
+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/attributes.ts
+function setIfPresent(target, key, value) {
+	const attr = toAttributeValue(value);
+	if (attr !== void 0) target[key] = attr;
+}
+function appendIdentityAttributes(attrs, agent) {
+	setIfPresent(attrs, "agent.id", agent.id);
+	setIfPresent(attrs, "agent.version", agent.version);
+	setIfPresent(attrs, "agent.framework", agent.framework);
+	setIfPresent(attrs, "agent.model", agent.model);
+	setIfPresent(attrs, "agent.role", agent.role);
+	setIfPresent(attrs, "agent.session.id", agent.sessionId);
+	setIfPresent(attrs, "agent.conversation.id", agent.conversationId);
+}
+function appendDelegationAttributes(attrs, delegation) {
+	if (!delegation) return;
+	setIfPresent(attrs, "delegation.parent_identity", delegation.parentIdentity);
+	setIfPresent(attrs, "delegation.scope", delegation.scope);
+	setIfPresent(attrs, "delegation.token_id", delegation.tokenId);
+	setIfPresent(attrs, "delegation.id", delegation.delegationId);
+	setIfPresent(attrs, "delegation.authority_lineage", delegation.authorityLineage);
+	setIfPresent(attrs, "delegation.authority_lineage_hash", delegation.authorityLineageHash);
+	setIfPresent(attrs, "delegation.depth", delegation.depth);
+	setIfPresent(attrs, "delegation.issued_at", delegation.issuedAt);
+	setIfPresent(attrs, "delegation.expires_at", delegation.expiresAt);
+}
+function appendToolAttributes(attrs, tool) {
+	if (!tool) return;
+	setIfPresent(attrs, "tool.name", tool.name);
+	setIfPresent(attrs, "tool.call.id", tool.callId);
+	setIfPresent(attrs, "tool.input_hash", tool.inputHash);
+	setIfPresent(attrs, "tool.output_hash", tool.outputHash);
+	setIfPresent(attrs, "tool.status", tool.status);
+	setIfPresent(attrs, "tool.execution_ms", tool.executionMs);
+}
+function appendPolicyAttributes(attrs, policy) {
+	if (!policy) return;
+	setIfPresent(attrs, "policy.decision", policy.decision);
+	setIfPresent(attrs, "policy.id", policy.policyId);
+	setIfPresent(attrs, "policy.risk_score", policy.riskScore);
+	setIfPresent(attrs, "policy.reason", policy.reason);
+}
+function appendGovernanceAttributes(attrs, governance) {
+	if (!governance) return;
+	setIfPresent(attrs, "governance.review_required", governance.reviewRequired);
+	setIfPresent(attrs, "governance.reviewer_id", governance.reviewerId);
+	setIfPresent(attrs, "governance.control_id", governance.controlId);
+	setIfPresent(attrs, "governance.documentation_url", governance.documentationUrl);
+	setIfPresent(attrs, "governance.lifecycle_stage", governance.lifecycleStage);
+	setIfPresent(attrs, "governance.framework", governance.framework);
+}
+function appendSessionAttributes(attrs, session) {
+	if (!session) return;
+	setIfPresent(attrs, "agent.session.status", session.status);
+	setIfPresent(attrs, "agent.session.started_at", session.startedAt);
+	setIfPresent(attrs, "agent.session.ended_at", session.endedAt);
+	setIfPresent(attrs, "agent.session.delegated_by", session.delegatedBy);
+}
+function appendDecisionAttributes(attrs, decision) {
+	if (!decision) return;
+	setIfPresent(attrs, "decision.summary", decision.summary);
+	setIfPresent(attrs, "decision.input_hash", decision.inputHash);
+	setIfPresent(attrs, "decision.policy_ids", decision.policyIds);
+	setIfPresent(attrs, "decision.justification_codes", decision.justificationCodes);
+	setIfPresent(attrs, "decision.evidence_ids", decision.evidenceIds);
+	setIfPresent(attrs, "decision.review_required", decision.reviewRequired);
+	setIfPresent(attrs, "decision.confidence", decision.confidence);
+}
+function flattenAgentAttributes(metadata) {
+	const normalized = normalizeMetadata(metadata);
+	const attrs = {
+		"autotel.agent": true,
+		"agent.action": normalized.action,
+		"agent.audit.version": normalized.schemaVersion ?? "1.1.0",
+		"agent.event.kind": normalized.eventKind ?? defaultEventKind(normalized)
+	};
+	setIfPresent(attrs, "agent.resource", normalized.resource);
+	setIfPresent(attrs, "agent.outcome", normalized.outcome);
+	setIfPresent(attrs, "reasoning.summary", normalized.reasoningSummary);
+	appendIdentityAttributes(attrs, normalized.agent);
+	appendDelegationAttributes(attrs, normalized.delegation);
+	appendToolAttributes(attrs, normalized.tool);
+	appendPolicyAttributes(attrs, normalized.policy);
+	appendGovernanceAttributes(attrs, normalized.governance);
+	appendSessionAttributes(attrs, normalized.session);
+	appendDecisionAttributes(attrs, normalized.decision);
+	return attrs;
+}
+function setAgentAttributes(metadata, ctx) {
+	resolveContext(ctx).setAttributes(flattenAgentAttributes(metadata));
+}
+/**
+* Stamp only the terminal outcome on the active span. Used by lifecycle
+* wrappers on completion so they don't re-flatten (and clobber) richer state a
+* nested step already wrote — e.g. a tool call's `tool.status=complete`.
+*/
+function setAgentOutcome(outcome, ctx) {
+	resolveContext(ctx).setAttribute("agent.outcome", outcome);
+}
+
+//#endregion
+//#region src/agent/runtime.ts
+/**
+* Record canonical OpenTelemetry GenAI semantic attributes for an LLM-backed
+* agent action, reusing the local cost model. Best-effort: anything unknown is
+* simply omitted. `gen_ai.request.model` is always recorded; token counts and
+* the estimated `gen_ai.usage.cost.usd` are recorded when `usage` is available
+* (up front via metadata, or post-call via `options.extractUsage`).
+*
+* Emits canonical v1.42.0 keys only — no `gen_ai.usage.total_tokens` (not a
+* registry attribute) and no legacy `gen.ai.*` names.
+*/
+function recordAiTelemetry(ctx, ai, usage) {
+	const attrs = {
+		...genAiRequestAttributes({
+			operation: ai.operation,
+			provider: ai.provider,
+			model: ai.model
+		}),
+		...genAiResponseAttributes({
+			model: ai.responseModel,
+			id: ai.responseId,
+			finishReasons: ai.finishReasons
+		})
+	};
+	if (usage) {
+		const cost = estimateLLMCost(ai.model, usage, ai.pricing ? { pricing: ai.pricing } : void 0);
+		Object.assign(attrs, genAiUsageAttributes({
+			...usage,
+			costUsd: cost
+		}));
+	}
+	ctx.setAttributes(attrs);
+}
+async function withAgentAction(metadata, fn, options = {}) {
+	const normalized = normalizeMetadata(metadata);
+	return withAudit(buildAuditMetadata(normalized), async (ctx, logger) => {
+		setAgentAttributes(normalized, ctx);
+		logger.set(buildLoggerContext(normalized));
+		try {
+			const result = await fn(ctx, logger);
+			const outcome = normalized.outcome ?? "success";
+			setAgentOutcome(outcome, ctx);
+			logger.set({ agent: { outcome } });
+			if (normalized.ai) recordAiTelemetry(ctx, normalized.ai, options.extractUsage?.(result) ?? normalized.ai.usage);
+			return result;
+		} catch (error) {
+			setAgentOutcome("failure", ctx);
+			logger.set({ agent: { outcome: "failure" } });
+			if (normalized.ai) recordAiTelemetry(ctx, normalized.ai);
+			throw error;
+		}
+	}, options);
+}
+function recordPolicyDecision(metadata, options = {}) {
+	const normalized = normalizeMetadata(metadata);
+	const traceCtx = resolveContextSafe(options.ctx);
+	if (!traceCtx) {
+		const mode = options.onMissingContext ?? "warn";
+		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
+		if (mode === "warn") warnMissingContextOnce(normalized.action);
+		return;
+	}
+	const logger = options.logger ?? getRequestLoggerSafe() ?? createNoopRequestLogger();
+	if (options.forceKeep !== false) forceKeepAuditEvent(traceCtx);
+	setAgentAttributes(normalized, traceCtx);
+	logger.set(buildLoggerContext(normalized));
+	if (options.emitNow) logger.emitNow();
+}
+function recordDecisionBasis(metadata, options = {}) {
+	if (!metadata.decision && !metadata.reasoningSummary) throw new Error("[autotel-genai] recordDecisionBasis requires metadata.decision or metadata.reasoningSummary.");
+	recordPolicyDecision(metadata, options);
+}
+/**
+* Define a reusable, instrumented agent action — the `trace()`-style factory
+* companion to `withAgentAction`. Declare it once at module scope and call the
+* returned function many times; each call opens its own audit scope.
+*
+* `metadata` may be a static object or a function of the call arguments, so
+* call-specific fields can be derived per invocation.
+*
+* @example
+* ```ts
+* const planTrip = defineAgentAction(
+*   (req: TripRequest) => ({
+*     action: 'agent.trip.plan',
+*     agent: { id: 'planner' },
+*     delegation: { parentIdentity: req.userId, scope: ['trip:plan'] },
+*   }),
+*   (ctx) => async (req: TripRequest) => planItinerary(req),
+* );
+*
+* await planTrip({ userId: 'usr_1', destination: 'Lisbon' });
+* ```
+*/
+function defineAgentAction(metadata, factory, options = {}) {
+	return (...args) => {
+		return withAgentAction(typeof metadata === "function" ? metadata(...args) : metadata, (ctx, logger) => factory(ctx, logger)(...args), options);
+	};
+}
+/**
+* Define a reusable, instrumented agent tool call — the `trace()`-style factory
+* companion to `withAgentToolCall`. Declare it once and call it per invocation;
+* tool inputs/results are hashed (never attached raw) on every call.
+*
+* Pass `metadata` as a function of the arguments when `tool.input` (or any other
+* field) depends on the call, so each invocation hashes its own input.
+*
+* @example
+* ```ts
+* const handleRefund = defineAgentToolCall(
+*   (req: RefundRequest) => ({
+*     action: 'agent.refund.tool_call',
+*     resource: 'stripe_refund_v3',
+*     agent: { id: 'refunds-specialist' },
+*     tool: { name: 'stripe_refund_v3', input: { refundId: req.refundId } },
+*   }),
+*   (ctx) => async (req: RefundRequest) => stripe.refunds.create(req),
+* );
+*
+* await handleRefund({ refundId: 're_123' });
+* ```
+*/
+function defineAgentToolCall(metadata, factory, options = {}) {
+	return (...args) => {
+		return withAgentToolCall(typeof metadata === "function" ? metadata(...args) : metadata, (ctx, logger) => factory(ctx, logger)(...args), options);
+	};
+}
+async function withAgentToolCall(metadata, fn, options = {}) {
+	const start = Date.now();
+	const normalized = normalizeMetadata({
+		...metadata,
+		tool: {
+			...metadata.tool,
+			status: metadata.tool?.status ?? "planned"
+		}
+	});
+	return withAgentAction(normalized, async (ctx, logger) => {
+		try {
+			const result = await fn(ctx, logger);
+			const executionMs = Date.now() - start;
+			const completed = {
+				...normalized,
+				outcome: normalized.outcome ?? "success",
+				tool: {
+					...metadata.tool,
+					inputHash: normalized.tool?.inputHash,
+					outputHash: normalized.tool?.outputHash ?? (options.hashResult === false ? void 0 : hashPayload(result)),
+					status: "complete",
+					executionMs
+				}
+			};
+			setAgentAttributes(completed, ctx);
+			logger.set(buildLifecycleUpdateContext(normalizeMetadata(completed)));
+			return result;
+		} catch (error) {
+			const failed = {
+				...normalized,
+				outcome: "failure",
+				tool: {
+					...metadata.tool,
+					inputHash: normalized.tool?.inputHash,
+					status: "error",
+					executionMs: Date.now() - start
+				}
+			};
+			setAgentAttributes(failed, ctx);
+			logger.set(buildLifecycleUpdateContext(normalizeMetadata(failed)));
+			throw error;
+		}
+	}, options);
+}
+
+//#endregion
+//#region src/agent/delegation.ts
+function buildAuthorityLineage(parentIdentity, agentId, existingLineage) {
+	const lineage = existingLineage ? [...existingLineage] : [parentIdentity];
+	if (lineage.at(-1) !== agentId) lineage.push(agentId);
+	return lineage;
+}
+function delegateToAgent(input) {
+	const authorityLineage = buildAuthorityLineage(input.parentIdentity, input.targetAgentId, input.authorityLineage);
+	return {
+		parentIdentity: input.parentIdentity,
+		...input.scope !== void 0 && { scope: input.scope },
+		...input.tokenId !== void 0 && { tokenId: input.tokenId },
+		...input.delegationId !== void 0 && { delegationId: input.delegationId },
+		authorityLineage,
+		authorityLineageHash: hashPayload(authorityLineage),
+		depth: Math.max(authorityLineage.length - 1, 0),
+		issuedAt: input.issuedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		...input.expiresAt !== void 0 && { expiresAt: input.expiresAt }
+	};
+}
+function recordAgentHandoff(metadata, options = {}) {
+	const authorityLineage = metadata.authorityLineage ?? [metadata.parentIdentity, metadata.fromAgent.id];
+	const delegation = delegateToAgent({
+		parentIdentity: metadata.parentIdentity,
+		targetAgentId: metadata.toAgent.id,
+		scope: metadata.scope,
+		tokenId: metadata.tokenId,
+		delegationId: metadata.delegationId,
+		authorityLineage
+	});
+	recordPolicyDecision({
+		action: metadata.action,
+		resource: metadata.resource,
+		eventKind: "handoff",
+		agent: metadata.toAgent,
+		delegation,
+		governance: metadata.governance,
+		reasoningSummary: `Control passed from ${metadata.fromAgent.id} to ${metadata.toAgent.id}.`
+	}, options);
+}
+
+//#endregion
+//#region src/agent/session.ts
+function toIsoString$2(value) {
+	if (!value) return (/* @__PURE__ */ new Date()).toISOString();
+	return value instanceof Date ? value.toISOString() : value;
+}
+async function withAgentSession(metadata, fn, options = {}) {
+	const startedAt = toIsoString$2(metadata.session?.startedAt);
+	return withAgentAction({
+		...metadata,
+		category: metadata.category ?? "agent_session",
+		session: {
+			...metadata.session,
+			status: metadata.session?.status ?? "active",
+			startedAt
+		}
+	}, async (ctx, logger) => {
+		try {
+			const result = await fn(ctx, logger);
+			const completed = {
+				...metadata,
+				outcome: metadata.outcome ?? "success",
+				session: {
+					...metadata.session,
+					status: "completed",
+					startedAt,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			};
+			setAgentAttributes(completed, ctx);
+			logger.set(buildLifecycleUpdateContext(completed));
+			return result;
+		} catch (error) {
+			const failed = {
+				...metadata,
+				outcome: "failure",
+				session: {
+					...metadata.session,
+					status: "failed",
+					startedAt,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			};
+			setAgentAttributes(failed, ctx);
+			logger.set(buildLifecycleUpdateContext(failed));
+			throw error;
+		}
+	}, options);
+}
+
+//#endregion
+//#region src/agent/identity-registry.ts
+function toIsoString$1(value) {
+	if (!value) return void 0;
+	return value instanceof Date ? value.toISOString() : value;
+}
+function normalizeScopes$1(scope) {
+	if (!scope) return [];
+	return Array.isArray(scope) ? [...scope] : [scope];
+}
+function isExpired(record, at) {
+	return record.expiresAt !== void 0 && record.expiresAt < at;
+}
+function createAgentIdentityRegistry(initial = []) {
+	const records = /* @__PURE__ */ new Map();
+	const provisionIdentity = (input) => {
+		const now = toIsoString$1(input.provisionedAt) ?? (/* @__PURE__ */ new Date()).toISOString();
+		const record = {
+			agent: input.agent,
+			scopes: input.scopes ?? [],
+			status: "active",
+			tokenId: input.tokenId,
+			tokenHash: input.tokenId === void 0 ? void 0 : hashPayload(input.tokenId),
+			delegatedBy: input.delegatedBy,
+			provisionedAt: now,
+			expiresAt: toIsoString$1(input.expiresAt),
+			metadata: input.metadata
+		};
+		records.set(input.agent.id, record);
+		return record;
+	};
+	for (const item of initial) provisionIdentity(item);
+	return {
+		provisionIdentity,
+		rotateIdentity(agentId, input = {}) {
+			const existing = records.get(agentId);
+			if (!existing) throw new Error(`[autotel-genai] Cannot rotate unknown agent identity "${agentId}".`);
+			const rotatedAt = toIsoString$1(input.rotatedAt) ?? (/* @__PURE__ */ new Date()).toISOString();
+			const record = {
+				...existing,
+				scopes: input.scopes ?? existing.scopes,
+				status: "rotated",
+				tokenId: input.tokenId ?? existing.tokenId,
+				tokenHash: input.tokenId === void 0 ? existing.tokenHash : hashPayload(input.tokenId),
+				delegatedBy: input.delegatedBy ?? existing.delegatedBy,
+				rotatedAt,
+				expiresAt: toIsoString$1(input.expiresAt) ?? existing.expiresAt,
+				metadata: input.metadata ?? existing.metadata
+			};
+			records.set(agentId, record);
+			return record;
+		},
+		revokeIdentity(agentId, input) {
+			const existing = records.get(agentId);
+			if (!existing) throw new Error(`[autotel-genai] Cannot revoke unknown agent identity "${agentId}".`);
+			const revokedAt = toIsoString$1(input.revokedAt) ?? (/* @__PURE__ */ new Date()).toISOString();
+			const record = {
+				...existing,
+				status: "revoked",
+				revokedAt,
+				revocationReason: input.reason
+			};
+			records.set(agentId, record);
+			return record;
+		},
+		getIdentity(agentId) {
+			return records.get(agentId);
+		},
+		getIdentityStatus(agentId, at = (/* @__PURE__ */ new Date()).toISOString()) {
+			const record = records.get(agentId);
+			if (!record) return;
+			return isExpired(record, at) ? "expired" : record.status;
+		},
+		assertUsable(agentId, at = (/* @__PURE__ */ new Date()).toISOString()) {
+			const record = records.get(agentId);
+			if (!record) throw new Error(`[autotel-genai] Unknown agent identity "${agentId}". Provision it before use.`);
+			const status = isExpired(record, at) ? "expired" : record.status;
+			if (status !== "active" && status !== "rotated") throw new Error(`[autotel-genai] Agent identity "${agentId}" is ${status} and cannot execute delegated work.`);
+			return record;
+		},
+		assertScopes(agentId, requiredScopes) {
+			const record = this.assertUsable(agentId);
+			const missing = requiredScopes.filter((scope) => !record.scopes.includes(scope));
+			if (missing.length > 0) throw new Error(`[autotel-genai] Agent identity "${agentId}" is missing delegated scopes: ${missing.join(", ")}.`);
+			return record;
+		},
+		issueDelegation(agentId, input) {
+			const record = this.assertUsable(agentId);
+			const scope = normalizeScopes$1(input.scope);
+			if (scope.length > 0) this.assertScopes(agentId, scope);
+			return delegateToAgent({
+				parentIdentity: input.parentIdentity,
+				targetAgentId: record.agent.id,
+				scope: input.scope ?? record.scopes,
+				tokenId: input.tokenId ?? record.tokenId,
+				delegationId: input.delegationId,
+				authorityLineage: input.authorityLineage,
+				issuedAt: input.issuedAt,
+				expiresAt: input.expiresAt ?? record.expiresAt
+			});
+		},
+		list() {
+			return [...records.values()];
+		}
+	};
+}
+
+//#endregion
+//#region src/agent/privacy.ts
+const PRIVACY_PROFILES = {
+	strict: {
+		name: "strict",
+		hashKeys: [
+			/email/i,
+			/phone/i,
+			/user_?id/i,
+			/account/i,
+			/customer/i,
+			/card/i,
+			/iban/i,
+			/tax/i
+		],
+		dropKeys: [
+			/secret/i,
+			/token/i,
+			/api[_-]?key/i,
+			/authorization/i,
+			/cookie/i,
+			/password/i,
+			/bearer/i
+		],
+		maskKeys: [
+			/name/i,
+			/address/i,
+			/prompt/i,
+			/message/i,
+			/content/i
+		],
+		maxStringLength: 256
+	},
+	pci: {
+		name: "pci",
+		hashKeys: [
+			/card/i,
+			/pan/i,
+			/account/i,
+			/customer/i,
+			/email/i
+		],
+		dropKeys: [
+			/cvv/i,
+			/cvc/i,
+			/secret/i,
+			/token/i,
+			/api[_-]?key/i
+		],
+		maskKeys: [/name/i, /address/i],
+		maxStringLength: 128
+	},
+	healthcare: {
+		name: "healthcare",
+		hashKeys: [
+			/patient/i,
+			/mrn/i,
+			/member/i,
+			/email/i,
+			/phone/i
+		],
+		dropKeys: [
+			/diagnosis/i,
+			/notes/i,
+			/secret/i,
+			/token/i,
+			/password/i
+		],
+		maskKeys: [
+			/name/i,
+			/address/i,
+			/symptom/i
+		],
+		maxStringLength: 128
+	}
+};
+function maskValue(value) {
+	if (typeof value !== "string") return "<masked>";
+	if (value.length <= 6) return "***";
+	return `${value.slice(0, 3)}***${value.slice(-3)}`;
+}
+function matches(patterns, key) {
+	return patterns?.some((pattern) => pattern.test(key)) ?? false;
+}
+function truncateString(value, maxLength) {
+	if (maxLength === void 0 || value.length <= maxLength) return value;
+	return `${value.slice(0, maxLength)}…`;
+}
+function sanitizeNode(value, profile, keyPath) {
+	if (value instanceof Date) return value.toISOString();
+	const lowered = keyPath.toLowerCase();
+	if (matches(profile.dropKeys, lowered)) return "<redacted>";
+	if (matches(profile.hashKeys, lowered)) return hashPayload(value);
+	if (matches(profile.maskKeys, lowered)) return maskValue(value);
+	if (typeof value === "string") return truncateString(value, profile.maxStringLength);
+	if (Array.isArray(value)) return value.map((entry, index) => sanitizeNode(entry, profile, `${keyPath}[${index}]`));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeNode(entry, profile, keyPath ? `${keyPath}.${key}` : key)]));
+	if (typeof value === "bigint") return value.toString(10);
+	return value;
+}
+function resolvePrivacyProfile(profile = "strict") {
+	return typeof profile === "string" ? PRIVACY_PROFILES[profile] : profile;
+}
+function sanitizeAuditPayload(value, profile = "strict") {
+	return sanitizeNode(value, resolvePrivacyProfile(profile), "");
+}
+
+//#endregion
+//#region src/agent/non-repudiation.ts
+function toIsoString(value) {
+	if (!value) return (/* @__PURE__ */ new Date()).toISOString();
+	return value instanceof Date ? value.toISOString() : value;
+}
+async function createSignedEventEnvelope(metadata, options = {}) {
+	const normalized = normalizeMetadata(metadata);
+	const envelopeBase = {
+		schemaVersion: normalized.schemaVersion ?? "1.1.0",
+		emittedAt: toIsoString(options.emittedAt),
+		...options.previousEventHash !== void 0 && { previousEventHash: options.previousEventHash },
+		metadata: normalized,
+		...options.evidence !== void 0 && { evidence: sanitizeAuditPayload(options.evidence, options.privacyProfile ?? "strict") }
+	};
+	const eventHash = hashPayload(envelopeBase);
+	const signature = options.signer ? await options.signer(canonicalizeForHash(envelopeBase)) : void 0;
+	return {
+		...envelopeBase,
+		eventHash,
+		...signature !== void 0 && { signature }
+	};
+}
+function verifyEventEnvelopeHash(envelope) {
+	const expected = hashPayload({
+		schemaVersion: envelope.schemaVersion,
+		emittedAt: envelope.emittedAt,
+		...envelope.previousEventHash !== void 0 && { previousEventHash: envelope.previousEventHash },
+		metadata: envelope.metadata,
+		...envelope.evidence !== void 0 && { evidence: envelope.evidence }
+	});
+	return envelope.eventHash === expected;
+}
+
+//#endregion
+//#region src/agent/scoped-tool.ts
+function normalizeScopes(scope) {
+	if (!scope) return [];
+	return Array.isArray(scope) ? scope : [scope];
+}
+function missingScopes(delegated, required) {
+	return required.filter((scope) => !delegated.includes(scope));
+}
+/**
+* Decide whether a scoped tool call must be denied.
+*
+* When the identity is registry-backed, the registry is authoritative: a
+* delegation may only *narrow* the stored grant, never widen it. Scopes a
+* caller claims that the registry never granted are a forged escalation and are
+* denied before any missing-scope check — otherwise passing an explicit
+* `delegation.scope` could grant access the registry record does not allow.
+*/
+function resolveScopeDenial(claimedScopes, requiredScopes, registryScopes) {
+	const unauthorized = registryScopes ? claimedScopes.filter((scope) => !registryScopes.includes(scope)) : [];
+	if (unauthorized.length > 0) return {
+		scopes: unauthorized,
+		reason: `unauthorized_scope:${unauthorized.join(",")}`,
+		why: `Delegation claims scopes the identity was never granted: ${unauthorized.join(", ")}`
+	};
+	const missing = missingScopes(claimedScopes, requiredScopes);
+	if (missing.length > 0) return {
+		scopes: missing,
+		reason: `missing_scope:${missing.join(",")}`,
+		why: `Missing delegated scopes: ${missing.join(", ")}`
+	};
+}
+function resolveDelegation(definition) {
+	const registry = definition.identityRegistry;
+	if (registry) registry.assertUsable(definition.agent.id);
+	return definition.delegation;
+}
+function buildGovernance(governance, reviewRequired) {
+	if (!governance && reviewRequired === void 0) return governance;
+	return {
+		...governance,
+		...reviewRequired !== void 0 && { reviewRequired }
+	};
+}
+function buildDecision(input, decision, privacyProfile) {
+	if (!decision) return void 0;
+	const sanitizedInput = sanitizeAuditPayload(input, privacyProfile ?? "strict");
+	return {
+		...decision,
+		inputHash: decision.inputHash ?? hashPayload(sanitizedInput)
+	};
+}
+async function withScopedTool(definition, input, fn, options = {}) {
+	const requiredScopes = definition.requiredScopes ?? [];
+	const delegation = resolveDelegation(definition);
+	const registryScopes = definition.identityRegistry?.getIdentity(definition.agent.id)?.scopes;
+	const denial = resolveScopeDenial(normalizeScopes(delegation?.scope ?? registryScopes), requiredScopes, registryScopes);
+	const policy = definition.policyId || definition.riskScore !== void 0 || denial ? {
+		decision: denial ? "deny" : "permit",
+		...definition.policyId !== void 0 && { policyId: definition.policyId },
+		...definition.riskScore !== void 0 && { riskScore: definition.riskScore },
+		...denial && { reason: denial.reason }
+	} : void 0;
+	const governance = buildGovernance(definition.governance, definition.reviewRequired);
+	if (policy && policy.decision === "deny" && denial) {
+		recordPolicyDecision({
+			action: definition.action,
+			resource: definition.resource ?? definition.tool.name,
+			category: definition.category,
+			agent: definition.agent,
+			delegation,
+			policy,
+			governance,
+			decision: buildDecision(input, definition.decision, definition.privacyProfile)
+		}, options);
+		throw createStructuredError({
+			status: 403,
+			code: "AGENT_SCOPE_DENIED",
+			message: `Agent "${definition.agent.id}" cannot invoke ${definition.tool.name}.`,
+			why: denial.why,
+			fix: "Grant the missing scopes or route the task to an agent with the required delegation."
+		});
+	}
+	if (policy) recordPolicyDecision({
+		action: `${definition.action}.policy`,
+		resource: definition.resource ?? definition.tool.name,
+		category: definition.category,
+		agent: definition.agent,
+		delegation,
+		policy,
+		governance
+	}, options);
+	if (definition.decision) recordDecisionBasis({
+		action: `${definition.action}.decision`,
+		resource: definition.resource ?? definition.tool.name,
+		category: definition.category,
+		agent: definition.agent,
+		delegation,
+		governance,
+		decision: buildDecision(input, definition.decision, definition.privacyProfile)
+	}, options);
+	return withAgentToolCall({
+		action: definition.action,
+		resource: definition.resource ?? definition.tool.name,
+		category: definition.category,
+		agent: definition.agent,
+		delegation,
+		governance,
+		tool: {
+			...definition.tool,
+			input
+		}
+	}, fn, options);
+}
+
+//#endregion
+export { setAgentAttributes as _, sanitizeAuditPayload as a, hashPayload as b, delegateToAgent as c, defineAgentToolCall as d, recordDecisionBasis as f, flattenAgentAttributes as g, withAgentToolCall as h, resolvePrivacyProfile as i, recordAgentHandoff as l, withAgentAction as m, createSignedEventEnvelope as n, createAgentIdentityRegistry as o, recordPolicyDecision as p, verifyEventEnvelopeHash as r, withAgentSession as s, withScopedTool as t, defineAgentAction as u, createAgentAuditMetadata as v, AGENT_AUDIT_SCHEMA_VERSION as x, canonicalizeForHash as y };
+//# sourceMappingURL=agent-CqXauTpC.js.map