@economic/agents 1.7.2 → 1.8.1

package/dist/index.d.mts

@@ -48,8 +48,7 @@ declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
 //#region src/server/v1/types.d.ts
 /**
  * The context object available throughout an agent's lifetime — passed via
- * `experimental_context` to tool `execute` functions. Contains the typed
- * request body merged with platform capabilities like `logEvent`.
+ * `experimental_context` to tool `execute` functions.
  *
  * Define your own body shape and compose:
  * ```typescript
@@ -57,12 +56,13 @@ declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
  * type MyContext = AgentToolContext<MyBody>;
  * ```
  */
-type AgentToolContext<TBody = Record<string, unknown>, TJwtIdentity = Record<string, unknown> | undefined> = TBody & {
-  _logEvent: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
-  _jwtIdentity?: TJwtIdentity;
+type AgentToolContext<TBody = Record<string, unknown>, TUserContext = Record<string, unknown> | undefined> = TBody & {
+  _userContext?: TUserContext;
 };
 interface AgentEnv {
   AGENT_DB: D1Database;
+  AGENTS_AUDIT_LOGS: R2Bucket;
+  AGENTS_ANALYTICS: AnalyticsEngineDataset;
 }
 interface ChatAgentEnv extends AgentEnv {}
 //#endregion
@@ -86,16 +86,17 @@ interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string,
 //#endregion
 //#region src/server/v1/agent/Agent.d.ts
 /**
- * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
- * audit logging, and `buildLLMParams` wiring.
+ * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading
+ * and `buildLLMParams` wiring.
  *
- * Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state
- * and writing audit events to D1.
+ * Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state.
  *
  * For chat agents with message history, compaction, and conversation recording,
  * extend {@link ChatAgent} instead.
  */
-declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env, TJwtIdentity extends Record<string, unknown> = Record<string, unknown>> extends Agent$1<Env & AgentEnv> {
+declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env, TUserContext extends Record<string, unknown> = Record<string, unknown>> extends Agent$1<Env & AgentEnv> {
+  protected clientIp?: string;
+  protected forwardedFor?: string;
   /**
    * Override to enable JWT authentication on WebSocket connections.
    * Return the auth config based on the incoming request, or undefined to skip auth.
@@ -105,35 +106,25 @@ declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env, TJwtId
    */
   protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
   /**
-   * The identity associated with the session.
-   * Define getIdentity to return the identity from the request.
+   * The user context for the session.
+   * Define getUserContext to set a user context.
    */
-  protected jwtIdentity: TJwtIdentity;
+  protected get userContext(): TUserContext;
   /**
    * Returns the identity following verification of the JWT token - getJwtAuthConfig is required.
-   * @returns The identity from the request.
-   * @param token - The token from the request.
+   * This method should not have side effects - return a single object from it.
+   * @returns The user context from the request.
+   * @param jwtToken - A valid JWT token following authentication.
    */
-  protected getJwtIdentity?(token: string): Promise<TJwtIdentity>;
+  protected getUserContext?(jwtToken: string): Promise<TUserContext>;
   /**
    * Returns the user ID from the durable object name.
    */
   protected getUserId(): string;
   onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
-  /**
-   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
-   * otherwise silently does nothing.
-   *
-   * Called automatically at the end of each LLM turn (from `onFinish` in
-   * `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
-   * `execute` functions.
-   */
-  protected logEvent(message: string, payload?: Record<string, unknown>): Promise<void>;
   /**
    * Builds the parameter object for a `streamText` or `generateText` call,
    * pre-filling `activeSkills` from this agent instance.
-   * Injects `logEvent` into `experimental_context` and wires `onFinish` for
-   * turn-completed audit events.
    */
   protected buildLLMParams<TBody = Record<string, unknown>>(config: Omit<BuildLLMParamsConfig, "messages"> & {
     options?: OnChatMessageOptions;
@@ -148,17 +139,17 @@ interface MessageRating {
 //#endregion
 //#region src/server/v1/agent-chat/ChatAgent.d.ts
 /**
- * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
- * message persistence, compaction, and conversation metadata in D1.
+ * Chat agent for Cloudflare Agents SDK: lazy skill loading, message persistence,
+ * compaction, and conversation metadata in D1.
  *
  * Handles CF infrastructure concerns: DO SQLite for loaded skill state,
- * stripping skill meta-tool messages before persistence, history replay to
- * newly connected clients, and audit events to D1.
+ * stripping skill meta-tool messages before persistence, and history replay to
+ * newly connected clients.
  *
  * Skill loading, compaction, and LLM calls use `buildLLMParams` from
  * `@economic/agents` inside `onChatMessage`.
  */
-declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TJwtIdentity extends Record<string, unknown> = Record<string, unknown>> extends AIChatAgent<Env & ChatAgentEnv> {
+declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TUserContext extends Record<string, unknown> = Record<string, unknown>> extends AIChatAgent<Env & ChatAgentEnv> {
   /**
    * The binding of the Durable Object instance for this agent.
    */
@@ -194,6 +185,8 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TJ
    * Default is 15.
    */
   protected maxMessagesBeforeCompaction?: number | undefined;
+  protected clientIp?: string;
+  protected forwardedFor?: string;
   /**
    * Override to enable JWT authentication on WebSocket connections.
    * Return the auth config based on the incoming request, or undefined to skip auth.
@@ -203,36 +196,26 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env, TJ
    */
   protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
   /**
-   * The identity associated with the session.
-   * Define getIdentity to return the identity from the request.
+   * The user context for the session.
+   * Define getUserContext to set a user context.
    */
-  protected get jwtIdentity(): TJwtIdentity;
+  protected get userContext(): TUserContext;
   /**
    * Returns the identity following verification of the JWT token - getJwtAuthConfig is required.
    * This method should not have side effects - return a single object from it.
-   * @returns The identity from the request.
-   * @param token - The token from the request.
+   * @returns The user context from the request.
+   * @param jwtToken - A valid JWT token following authentication.
    */
-  protected getJwtIdentity?(token: string): Promise<TJwtIdentity>;
+  protected getUserContext?(jwtToken: string): Promise<TUserContext>;
   /**
    * Returns the user ID from the durable object name.
    */
   protected getUserId(): string;
   onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
-  /**
-   * Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
-   * otherwise silently does nothing.
-   *
-   * Called automatically at the end of each LLM turn (from `onFinish` in
-   * `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
-   * `execute` functions.
-   */
-  protected logEvent(message: string, payload?: Record<string, unknown>): Promise<void>;
+  protected _pendingUserContextRequest?: Promise<void>;
   /**
    * Builds the parameter object for a `streamText` or `generateText` call,
    * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
-   * Injects `logEvent` into `experimental_context` and wires `onFinish` for
-   * turn-completed audit events and conversation recording.
    *
    * **Compaction** runs automatically when `fastModel` is set on the class, using
    * `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) as the threshold. Override the

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs,
 import { Agent as Agent$1, callable, getCurrentAgent, routeAgentRequest as routeAgentRequest$1 } from "agents";
 import { AIChatAgent } from "@cloudflare/ai-chat";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
+import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 //#region src/server/shared/features/skills/index.ts
 const TOOL_NAME_ACTIVATE_SKILL = "activate_skill";
 const TOOL_NAME_LIST_CAPABILITIES = "list_capabilities";
@@ -269,98 +270,6 @@ async function routeAgentRequest(request, env, options) {
 	return response;
 }
 //#endregion
-//#region src/server/shared/features/audit/audit.ts
-/**
-* Inserts a single audit event row into the shared `audit_events` D1 table.
-*
-* Called by `ChatAgentHarness.logEvent()` (and `AgentHarness.logEvent()`). Not intended for direct use.
-*/
-const SENSITIVE_KEYS = /^(password|token|secret|api_key|apikey|authorization|credentials)$/i;
-const REDACTED = "[REDACTED]";
-/** Deep-clone and redact values for keys that look like secrets (for audit logging). */
-function sanitizePayload(value) {
-	if (value === null || value === void 0) return value;
-	if (Array.isArray(value)) return value.map(sanitizePayload);
-	if (typeof value === "object") {
-		const result = {};
-		for (const [key, val] of Object.entries(value)) result[key] = SENSITIVE_KEYS.test(key) ? REDACTED : sanitizePayload(val);
-		return result;
-	}
-	return value;
-}
-async function insertAuditEvent(db, durableObjectName, message, payload) {
-	await db.prepare(`INSERT INTO audit_events (id, durable_object_name, message, payload, created_at)
-       VALUES (?, ?, ?, ?, ?)`).bind(crypto.randomUUID(), durableObjectName, message, payload ? JSON.stringify(sanitizePayload(payload)) : null, (/* @__PURE__ */ new Date()).toISOString()).run();
-}
-function stringifyForSkillScan(output) {
-	if (typeof output === "string") return output;
-	if (output === null || output === void 0) return "";
-	try {
-		return JSON.stringify(output);
-	} catch {
-		return "";
-	}
-}
-function forEachStep(event, fn) {
-	if (event.steps.length > 0) for (const step of event.steps) fn(step);
-	else fn(event);
-}
-/**
-* User text from provider request body (`contents` is e.g. Gemini format).
-*/
-function extractUserInputFromRequestBody(body) {
-	const firstContent = body?.contents?.[0];
-	if (firstContent?.role !== "user" || !firstContent.parts?.length) return "";
-	return firstContent.parts.map((p) => p.text).filter((t) => typeof t === "string").join(" ").trim();
-}
-/**
-* Builds the payload for a "Turn completed" audit event from the AI SDK
-* `OnFinishEvent`.
-*
-* Returns:
-* - `input`: user message text from `request.body.contents[0]` (Gemini-style)
-* - `output`: assistant response text (truncated to 200 chars)
-* - `toolCalls`: array of { toolName, toolInput, toolOutput }
-* - `loadedSkills`: skill names extracted from activate_skill results
-*/
-function buildTurnLogPayload(event) {
-	const toolCalls = [];
-	let latestSkills;
-	const toolOutputs = /* @__PURE__ */ new Map();
-	forEachStep(event, (step) => {
-		for (const tr of step.toolResults) toolOutputs.set(tr.toolCallId, tr.output);
-	});
-	forEachStep(event, (step) => {
-		for (const tc of step.toolCalls) toolCalls.push({
-			name: tc.toolName,
-			input: tc.input,
-			output: toolOutputs.get(tc.toolCallId)
-		});
-		const considerToolResultForSkills = (toolName, output) => {
-			if (toolName !== "activate_skill") return;
-			const s = stringifyForSkillScan(output);
-			const sentinelIdx = s.indexOf(SKILL_STATE_SENTINEL);
-			if (sentinelIdx === -1) return;
-			try {
-				const stateJson = s.slice(sentinelIdx + 18);
-				latestSkills = JSON.parse(stateJson);
-			} catch {}
-		};
-		for (const tr of step.toolResults) considerToolResultForSkills(tr.toolName, tr.output);
-	});
-	const input = extractUserInputFromRequestBody(event.request?.body);
-	return {
-		detail: {
-			model: event.model.modelId,
-			tokens: event.usage?.totalTokens
-		},
-		loadedSkills: latestSkills ?? [],
-		toolCalls,
-		input: input.slice(0, 200),
-		output: (event.text ?? "").slice(0, 200)
-	};
-}
-//#endregion
 //#region src/server/shared/features/auth/index.ts
 const jwksByIssuer = /* @__PURE__ */ new Map();
 function getJwksForIssuer(issuer) {
@@ -461,23 +370,290 @@ async function verifyJwt(request, config) {
 	};
 }
 //#endregion
+//#region src/server/shared/features/telemetry/index.ts
+function durationMs(duration) {
+	return duration[0] * 1e3 + duration[1] / 1e6;
+}
+function stringAttribute(span, key) {
+	const value = span.attributes[key];
+	return typeof value === "string" ? value : void 0;
+}
+function numberAttribute(span, key) {
+	const value = span.attributes[key];
+	return typeof value === "number" ? value : void 0;
+}
+function parseJson(value) {
+	if (!value) return;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+function safePathSegment(value, fallback) {
+	return (value || fallback).replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function createAuditLogKey(agentName, conversationId) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-");
+	const id = crypto.randomUUID().slice(0, 8);
+	return [
+		safePathSegment(agentName, "unknown-agent"),
+		safePathSegment(conversationId, "unknown-conversation"),
+		`${timestamp}-${id}.json`
+	].join("/");
+}
+function textFromContent(content) {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) return content.map((part) => {
+		if (!part || typeof part !== "object") return "";
+		const value = part.text;
+		return typeof value === "string" ? value : "";
+	}).filter(Boolean).join("\n");
+	return "";
+}
+function extractPrompt(messages) {
+	const firstUserMessage = messages.find((message) => message.role === "user");
+	return firstUserMessage ? textFromContent(firstUserMessage.content) : "";
+}
+function promptCharCount(messages) {
+	const firstUserMessage = messages.find((message) => message.role === "user");
+	return firstUserMessage ? textFromContent(firstUserMessage.content).length : 0;
+}
+function extractTools(messages) {
+	const tools = [];
+	for (const message of messages) {
+		if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+		for (const part of message.content) {
+			if (!part || typeof part !== "object") continue;
+			const record = part;
+			if (record.type !== "tool_use") continue;
+			tools.push({
+				name: typeof record.name === "string" ? record.name : void 0,
+				input: record.input,
+				status: "success"
+			});
+		}
+	}
+	return tools;
+}
+/**
+* Stores the last ai.streamText.doStream span per conversation.
+* Its ai.prompt.messages contains the full conversation history including all
+* intermediate tool_use + tool_result turns from the agentic loop.
+*/
+const lastDoStreamByConversation = /* @__PURE__ */ new Map();
+const toolCallsByParentSpan = /* @__PURE__ */ new Map();
+const toolCallsByConversation = /* @__PURE__ */ new Map();
+const pendingToolCalls = [];
+const currentSkillByConversation = /* @__PURE__ */ new Map();
+function userIndex(userId) {
+	return userId;
+}
+function extractSkillName(toolName, input) {
+	if (!input || typeof input !== "object") return;
+	const record = input;
+	if (toolName === "load_context") {
+		const key = record.key;
+		return typeof key === "string" ? key : void 0;
+	}
+	if (toolName === "activate_skill") {
+		const skill = record.skill ?? record.name ?? record.key;
+		return typeof skill === "string" ? skill : void 0;
+	}
+}
+function pushToolCall(map, key, toolCall) {
+	const existing = map.get(key);
+	if (existing) existing.push(toolCall);
+	else map.set(key, [toolCall]);
+}
+function rememberToolCall(span) {
+	const parentSpanId = span.parentSpanContext?.spanId;
+	const toolName = stringAttribute(span, "ai.toolCall.name");
+	const input = parseJson(stringAttribute(span, "ai.toolCall.args"));
+	const toolCall = {
+		name: toolName,
+		input,
+		status: span.status.code === 0 ? "success" : "error",
+		skillName: extractSkillName(toolName, input)
+	};
+	if (parentSpanId) pushToolCall(toolCallsByParentSpan, parentSpanId, toolCall);
+	pendingToolCalls.push(toolCall);
+}
+function attachToolCallsToConversation(span, conversationId) {
+	const spanId = span.spanContext().spanId;
+	const toolCalls = toolCallsByParentSpan.get(spanId) ?? pendingToolCalls.splice(0);
+	if (!toolCalls.length) return;
+	toolCallsByParentSpan.delete(spanId);
+	const currentSkill = currentSkillByConversation.get(conversationId);
+	const attributedToolCalls = toolCalls.map((toolCall) => {
+		const skillName = toolCall.skillName ?? currentSkill;
+		if (toolCall.skillName) currentSkillByConversation.set(conversationId, toolCall.skillName);
+		return {
+			...toolCall,
+			...skillName ? { skillName } : {}
+		};
+	});
+	toolCallsByConversation.set(conversationId, [...toolCallsByConversation.get(conversationId) ?? [], ...attributedToolCalls]);
+}
+function buildAuditLog(span, context) {
+	const lastDoStream = lastDoStreamByConversation.get(context.conversationId);
+	lastDoStreamByConversation.delete(context.conversationId);
+	const promptMessages = parseJson(stringAttribute(lastDoStream ?? span, "ai.prompt.messages"));
+	const fallbackPrompt = parseJson(stringAttribute(span, "ai.prompt"));
+	const inputMessages = promptMessages ?? fallbackPrompt?.messages ?? [];
+	const spanToolCalls = toolCallsByConversation.get(context.conversationId) ?? [];
+	toolCallsByConversation.delete(context.conversationId);
+	return {
+		id: createAuditLogKey(context.agentName, context.conversationId),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		conversationId: context.conversationId,
+		agent: {
+			name: context.agentName,
+			llm: {
+				model: stringAttribute(span, "ai.model.id"),
+				provider: stringAttribute(span, "ai.model.provider")
+			}
+		},
+		actor: {
+			userId: context.userId,
+			ip: {
+				client: context.clientIp ?? context.forwardedFor?.split(",").map((ip) => ip.trim()).filter(Boolean)[0],
+				forwardedFor: context.forwardedFor?.split(",").map((ip) => ip.trim()).filter(Boolean) ?? []
+			}
+		},
+		prompt: extractPrompt(inputMessages),
+		response: stringAttribute(span, "ai.response.text") ?? "",
+		status: span.status.code === 0 ? "success" : "error",
+		tools: [...extractTools(inputMessages), ...spanToolCalls]
+	};
+}
+async function handleAuditSpan(span, auditLogs, context) {
+	const auditLog = buildAuditLog(span, context);
+	if (!auditLogs) return;
+	await auditLogs.put(auditLog.id, JSON.stringify(auditLog, null, 2), { httpMetadata: { contentType: "application/json" } });
+	console.log("[AuditLog] Created", auditLog.id);
+}
+function writeAnalyticsDatapoint(analytics, dataPoint) {
+	if (!analytics) return;
+	try {
+		analytics.writeDataPoint(dataPoint);
+	} catch (error) {
+		console.error("[Agent] Failed to write analytics datapoint", error);
+	}
+}
+function handleAnalyticsSpan(span, analytics) {
+	if (span.name === "ai.streamText.doStream") {
+		const promptMessages = parseJson(stringAttribute(span, "ai.prompt.messages"));
+		const responseText = stringAttribute(span, "ai.response.text") ?? "";
+		writeAnalyticsDatapoint(analytics, {
+			indexes: [userIndex(stringAttribute(span, "ai.telemetry.metadata.userId") ?? "")],
+			blobs: [
+				"llm_call",
+				stringAttribute(span, "ai.telemetry.metadata.agentName") ?? "",
+				stringAttribute(span, "ai.telemetry.metadata.conversationId") ?? "",
+				stringAttribute(span, "ai.model.id") ?? "",
+				stringAttribute(span, "ai.model.provider") ?? "",
+				stringAttribute(span, "ai.response.finishReason") ?? ""
+			],
+			doubles: [
+				numberAttribute(span, "ai.usage.inputTokens") ?? 0,
+				numberAttribute(span, "ai.usage.outputTokens") ?? 0,
+				numberAttribute(span, "ai.usage.totalTokens") ?? 0,
+				numberAttribute(span, "ai.usage.inputTokenDetails.cacheReadTokens") ?? 0,
+				numberAttribute(span, "ai.usage.inputTokenDetails.cacheWriteTokens") ?? 0,
+				durationMs(span.duration),
+				promptCharCount(promptMessages ?? []),
+				responseText.length
+			]
+		});
+		return;
+	}
+	if (span.name === "ai.toolCall") {
+		const toolName = stringAttribute(span, "ai.toolCall.name");
+		const toolInput = parseJson(stringAttribute(span, "ai.toolCall.args"));
+		const conversationId = stringAttribute(span, "ai.telemetry.metadata.conversationId") ?? "";
+		const skillName = extractSkillName(toolName, toolInput) ?? currentSkillByConversation.get(conversationId) ?? "";
+		const success = span.status.code === 0;
+		writeAnalyticsDatapoint(analytics, {
+			indexes: [userIndex(stringAttribute(span, "ai.telemetry.metadata.userId") ?? "")],
+			blobs: [
+				"tool_call",
+				stringAttribute(span, "ai.telemetry.metadata.agentName") ?? "",
+				conversationId,
+				toolName ?? "",
+				skillName,
+				success ? "success" : "error"
+			],
+			doubles: [
+				durationMs(span.duration),
+				success ? 1 : 0,
+				0,
+				0,
+				0,
+				0,
+				0,
+				0
+			]
+		});
+	}
+}
+var AgentSpanExporter = class {
+	auditLogs;
+	analytics;
+	context;
+	constructor(auditLogs, analytics, context) {
+		this.auditLogs = auditLogs;
+		this.analytics = analytics;
+		this.context = context;
+	}
+	export(spans, resultCallback) {
+		(async () => {
+			try {
+				for (const span of spans) if (span.name === "ai.streamText.doStream") {
+					lastDoStreamByConversation.set(this.context.conversationId, span);
+					attachToolCallsToConversation(span, this.context.conversationId);
+					handleAnalyticsSpan(span, this.analytics);
+				} else if (span.name === "ai.streamText") await handleAuditSpan(span, this.auditLogs, this.context);
+				else if (span.name === "ai.toolCall") {
+					rememberToolCall(span);
+					handleAnalyticsSpan(span, this.analytics);
+				}
+				resultCallback({ code: 0 });
+			} catch (error) {
+				resultCallback({
+					code: 1,
+					error: error instanceof Error ? error : new Error(String(error))
+				});
+			}
+		})();
+	}
+	async shutdown() {}
+};
+function createAgentTracer(auditLogs, analytics, context) {
+	return new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new AgentSpanExporter(auditLogs, analytics, context))] }).getTracer("@economic/agents");
+}
+//#endregion
 //#region src/server/v1/agent/Agent.ts
 /**
-* Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
-* audit logging, and `buildLLMParams` wiring.
+* Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading
+* and `buildLLMParams` wiring.
 *
-* Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state
-* and writing audit events to D1.
+* Handles CF infrastructure concerns: DO SQLite persistence for loaded skill state.
 *
 * For chat agents with message history, compaction, and conversation recording,
 * extend {@link ChatAgent} instead.
 */
 var Agent = class extends Agent$1 {
+	clientIp;
+	forwardedFor;
 	/**
-	* The identity associated with the session.
-	* Define getIdentity to return the identity from the request.
+	* The user context for the session.
+	* Define getUserContext to set a user context.
 	*/
-	jwtIdentity = {};
+	get userContext() {
+		const { connection } = getCurrentAgent();
+		return (connection?.state)?.userContext ?? {};
+	}
 	/**
 	* Returns the user ID from the durable object name.
 	*/
@@ -485,14 +661,22 @@ var Agent = class extends Agent$1 {
 		return this.name.split(":")[0];
 	}
 	async onConnect(connection, ctx) {
+		this.clientIp = ctx.request.headers.get("CF-Connecting-IP") ?? ctx.request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim();
+		this.forwardedFor = ctx.request.headers.get("X-Forwarded-For") ?? void 0;
 		if (!this.env.AGENT_DB) {
-			console.error("[ChatAgent] Connection rejected: no AGENT_DB bound");
-			connection.close(3e3, "Could not connect to agent, database not found");
+			console.error("[Agent] Connection rejected: no AGENT_DB bound");
+			connection.close(3e3, "Could not connect to agent");
+			return;
+		}
+		if (!this.env.AGENTS_AUDIT_LOGS) {
+			console.error("[Agent] Connection rejected: no AGENTS_AUDIT_LOGS bound. Audit logs are required.");
+			connection.close(3e3, "Could not connect to agent");
 			return;
 		}
+		if (!this.env.AGENTS_ANALYTICS) console.warn("[Agent] No AGENTS_ANALYTICS bound. Analytics will not be collected.");
 		if (!this.getUserId()) {
-			console.error("[ChatAgent] Connection rejected: name must be in the format userId:uniqueChatId");
-			connection.close(3e3, "Could not connect to agent, name is not in correct format");
+			console.error("[Agent] Connection rejected: name must be in the format userId:uniqueChatId");
+			connection.close(3e3, "Could not connect to agent");
 			return;
 		}
 		if (this.getJwtAuthConfig) {
@@ -502,7 +686,7 @@ var Agent = class extends Agent$1 {
 				try {
 					result = await verifyJwt(ctx.request, config);
 				} catch (error) {
-					console.error("[ChatAgent] JWT verification error", error);
+					console.error("[Agent] JWT verification error", error);
 					connection.close(4001, "Unauthorized");
 					return;
 				}
@@ -511,49 +695,49 @@ var Agent = class extends Agent$1 {
 					return;
 				}
 				const token = extractTokenFromConnectRequest(ctx.request);
-				if (token) this.jwtIdentity = await this.getJwtIdentity?.(token) ?? {};
+				if (token) {
+					const userContext = await this.getUserContext?.(token);
+					if (userContext) connection.setState({ userContext });
+				}
 			}
 		}
 		return super.onConnect(connection, ctx);
 	}
 	/**
-	* Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
-	* otherwise silently does nothing.
-	*
-	* Called automatically at the end of each LLM turn (from `onFinish` in
-	* `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
-	* `execute` functions.
-	*/
-	async logEvent(message, payload) {
-		try {
-			await insertAuditEvent(this.env.AGENT_DB, this.name, message, payload);
-		} catch (error) {
-			console.error("[Agent] Failed to write audit event", error);
-		}
-	}
-	/**
 	* Builds the parameter object for a `streamText` or `generateText` call,
 	* pre-filling `activeSkills` from this agent instance.
-	* Injects `logEvent` into `experimental_context` and wires `onFinish` for
-	* turn-completed audit events.
 	*/
 	async buildLLMParams(config) {
 		const activeSkills = await getStoredSkills(this.sql.bind(this));
 		const experimental_context = {
 			...config.experimental_context,
 			...config.options?.body,
-			_jwtIdentity: this.jwtIdentity,
-			_logEvent: this.logEvent.bind(this)
-		};
-		const onFinish = async (event) => {
-			this.logEvent("Turn completed", buildTurnLogPayload(event));
-			await config.onFinish?.(event);
+			_userContext: this.userContext
 		};
 		return buildLLMParams({
 			...config,
 			activeSkills,
 			experimental_context,
-			onFinish
+			experimental_telemetry: {
+				...config.experimental_telemetry,
+				isEnabled: true,
+				tracer: createAgentTracer(this.env.AGENTS_AUDIT_LOGS, this.env.AGENTS_ANALYTICS, {
+					agentName: this.constructor.name,
+					conversationId: this.name,
+					userId: this.getUserId(),
+					...this.clientIp ? { clientIp: this.clientIp } : {},
+					...this.forwardedFor ? { forwardedFor: this.forwardedFor } : {}
+				}),
+				metadata: {
+					agentName: this.constructor.name,
+					version: "v1",
+					conversationId: this.name,
+					userId: this.getUserId(),
+					...this.clientIp ? { clientIp: this.clientIp } : {},
+					...this.forwardedFor ? { forwardedFor: this.forwardedFor } : {},
+					...config.experimental_telemetry?.metadata
+				}
+			}
 		});
 	}
 };
@@ -836,12 +1020,12 @@ async function getMessageRatings(db, durableObjectName) {
 //#endregion
 //#region src/server/v1/agent-chat/ChatAgent.ts
 /**
-* Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,
-* message persistence, compaction, and conversation metadata in D1.
+* Chat agent for Cloudflare Agents SDK: lazy skill loading, message persistence,
+* compaction, and conversation metadata in D1.
 *
 * Handles CF infrastructure concerns: DO SQLite for loaded skill state,
-* stripping skill meta-tool messages before persistence, history replay to
-* newly connected clients, and audit events to D1.
+* stripping skill meta-tool messages before persistence, and history replay to
+* newly connected clients.
 *
 * Skill loading, compaction, and LLM calls use `buildLLMParams` from
 * `@economic/agents` inside `onChatMessage`.
@@ -861,13 +1045,15 @@ var ChatAgent = class extends AIChatAgent {
 	* Default is 15.
 	*/
 	maxMessagesBeforeCompaction = 15;
+	clientIp;
+	forwardedFor;
 	/**
-	* The identity associated with the session.
-	* Define getIdentity to return the identity from the request.
+	* The user context for the session.
+	* Define getUserContext to set a user context.
 	*/
-	get jwtIdentity() {
+	get userContext() {
 		const { connection } = getCurrentAgent();
-		return (connection?.state)?.jwtIdentity ?? {};
+		return (connection?.state)?.userContext ?? {};
 	}
 	/**
 	* Returns the user ID from the durable object name.
@@ -876,14 +1062,22 @@ var ChatAgent = class extends AIChatAgent {
 		return this.name.split(":")[0];
 	}
 	async onConnect(connection, ctx) {
+		this.clientIp = ctx.request.headers.get("CF-Connecting-IP") ?? ctx.request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim();
+		this.forwardedFor = ctx.request.headers.get("X-Forwarded-For") ?? void 0;
 		if (!this.env.AGENT_DB) {
-			console.error("[ChatAgent] Connection rejected: no AGENT_DB bound");
-			connection.close(3e3, "Could not connect to agent, database not found");
+			console.error("[Agent] Connection rejected: no AGENT_DB bound");
+			connection.close(3e3, "Could not connect to agent");
 			return;
 		}
+		if (!this.env.AGENTS_AUDIT_LOGS) {
+			console.error("[Agent] Connection rejected: no AGENTS_AUDIT_LOGS bound. Audit logs are required.");
+			connection.close(3e3, "Could not connect to agent");
+			return;
+		}
+		if (!this.env.AGENTS_ANALYTICS) console.warn("[Agent] No AGENTS_ANALYTICS bound. Analytics will not be collected.");
 		if (!this.getUserId()) {
-			console.error("[ChatAgent] Connection rejected: name must be in the format userId:uniqueChatId");
-			connection.close(3e3, "Could not connect to agent, name is not in correct format");
+			console.error("[Agent] Connection rejected: name must be in the format userId:uniqueChatId");
+			connection.close(3e3, "Could not connect to agent");
 			return;
 		}
 		if (this.getJwtAuthConfig) {
@@ -893,7 +1087,7 @@ var ChatAgent = class extends AIChatAgent {
 				try {
 					result = await verifyJwt(ctx.request, config);
 				} catch (error) {
-					console.error("[ChatAgent] JWT verification error", error);
+					console.error("[Agent] JWT verification error", error);
 					connection.close(4001, "Unauthorized");
 					return;
 				}
@@ -903,33 +1097,16 @@ var ChatAgent = class extends AIChatAgent {
 				}
 			}
 			const token = extractTokenFromConnectRequest(ctx.request);
-			if (token) {
-				const jwtIdentity = await this.getJwtIdentity?.(token);
-				if (jwtIdentity) connection.setState({ jwtIdentity });
-			}
+			if (token) this._pendingUserContextRequest = this.getUserContext?.(token).then((userContext) => {
+				if (userContext) connection.setState({ userContext });
+			});
 		}
 		return super.onConnect(connection, ctx);
 	}
-	/**
-	* Writes an audit event to D1 if `AGENT_DB` is bound on the environment,
-	* otherwise silently does nothing.
-	*
-	* Called automatically at the end of each LLM turn (from `onFinish` in
-	* `buildLLMParams`). Also available via `experimental_context.logEvent` in tool
-	* `execute` functions.
-	*/
-	async logEvent(message, payload) {
-		try {
-			await insertAuditEvent(this.env.AGENT_DB, this.name, message, payload);
-		} catch (error) {
-			console.error("[ChatAgent] Failed to write audit event", error);
-		}
-	}
+	_pendingUserContextRequest;
 	/**
 	* Builds the parameter object for a `streamText` or `generateText` call,
 	* pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
-	* Injects `logEvent` into `experimental_context` and wires `onFinish` for
-	* turn-completed audit events and conversation recording.
 	*
 	* **Compaction** runs automatically when `fastModel` is set on the class, using
 	* `DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION` (30) as the threshold. Override the
@@ -941,22 +1118,36 @@ var ChatAgent = class extends AIChatAgent {
 		const experimental_context = {
 			...config.experimental_context,
 			...config.options?.body,
-			_jwtIdentity: this.jwtIdentity,
-			_logEvent: this.logEvent.bind(this)
+			_userContext: this.userContext
 		};
 		const messages = await convertToModelMessages(this.messages);
 		const fastModel = this.getFastModel();
 		const processedMessages = fastModel && this.maxMessagesBeforeCompaction !== void 0 ? await compactIfNeeded(messages, fastModel, this.maxMessagesBeforeCompaction) : messages;
-		const onFinish = async (event) => {
-			this.logEvent("Turn completed", buildTurnLogPayload(event));
-			await config.onFinish?.(event);
-		};
 		return buildLLMParams({
 			...config,
 			activeSkills,
 			messages: processedMessages,
 			experimental_context,
-			onFinish
+			experimental_telemetry: {
+				...config.experimental_telemetry,
+				isEnabled: true,
+				tracer: createAgentTracer(this.env.AGENTS_AUDIT_LOGS, this.env.AGENTS_ANALYTICS, {
+					agentName: this.constructor.name,
+					conversationId: this.name,
+					userId: this.getUserId(),
+					...this.clientIp ? { clientIp: this.clientIp } : {},
+					...this.forwardedFor ? { forwardedFor: this.forwardedFor } : {}
+				}),
+				metadata: {
+					agentName: this.constructor.name,
+					version: "v1",
+					conversationId: this.name,
+					userId: this.getUserId(),
+					...this.clientIp ? { clientIp: this.clientIp } : {},
+					...this.forwardedFor ? { forwardedFor: this.forwardedFor } : {},
+					...config.experimental_telemetry?.metadata
+				}
+			}
 		});
 	}
 	async persistMessages(messages, excludeBroadcastIds = [], options) {
@@ -967,7 +1158,7 @@ var ChatAgent = class extends AIChatAgent {
 	}
 	async onChatResponse(result) {
 		if (result.error) {
-			console.error("[ChatAgent] Chat response error", result.error);
+			console.error("[Agent] Chat response error", result.error);
 			return;
 		}
 		recordConversationSummary(this.env.AGENT_DB, this.name, this.messages, this.getFastModel());
@@ -984,11 +1175,7 @@ var ChatAgent = class extends AIChatAgent {
 	}
 	@callable({ description: "Delete a conversation by its id" }) async deleteConversation(id) {
 		if (!id.startsWith(`${this.getUserId()}:`)) {
-			console.error("[ChatAgent] Failed to delete conversation: Not owned by current user", {
-				conversationName: id,
-				userId: this.getUserId()
-			});
-			this.logEvent("Failed to delete conversation: Not owned by current user", {
+			console.error("[Agent] Failed to delete conversation: Not owned by current user", {
 				conversationName: id,
 				userId: this.getUserId()
 			});
@@ -997,7 +1184,7 @@ var ChatAgent = class extends AIChatAgent {
 		try {
 			await deleteConversationRow(this.env.AGENT_DB, id);
 		} catch (error) {
-			console.error("[ChatAgent] Failed to delete conversation row", {
+			console.error("[Agent] Failed to delete conversation row", {
 				conversationName: id,
 				error
 			});
@@ -1010,12 +1197,12 @@ var ChatAgent = class extends AIChatAgent {
 		for (const connection of this.getConnections()) try {
 			connection.close(CONVERSATION_EXPIRED_CLOSE_CODE, CONVERSATION_EXPIRED_CLOSE_REASON);
 		} catch (error) {
-			console.error("[ChatAgent] Failed to close expired conversation connection", error);
+			console.error("[Agent] Failed to close expired conversation connection", error);
 		}
 		return super.destroy();
 	}
 	async deleteConversationCallback() {
-		if (await this.deleteConversation(this.name)) this.logEvent("Conversation deleted due to inactivity", {
+		if (await this.deleteConversation(this.name)) console.log("[Agent] Conversation deleted due to inactivity", {
 			conversationName: this.name,
 			retentionDays: this.conversationRetentionDays ?? null
 		});
@@ -1053,6 +1240,7 @@ var ChatAgentHarness = class extends ChatAgent {
 		return [];
 	}
 	async onChatMessage(onFinish, options) {
+		if (this._pendingUserContextRequest) await this._pendingUserContextRequest;
 		const ctx = options?.body;
 		return streamText(await this.buildLLMParams({
 			options,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {
@@ -25,7 +25,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@clack/prompts": "^1.2.0"
+    "@clack/prompts": "^1.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1"
   },
   "devDependencies": {
     "@cloudflare/ai-chat": "^0.6.2",

package/schema/chat/0003_drop_events.sql

@@ -0,0 +1,5 @@
+-- ─── Audit logging ────────────────────────────────────────────────────────────
+
+DROP INDEX IF EXISTS audit_events_do;
+DROP INDEX IF EXISTS audit_events_ts;
+DROP TABLE IF EXISTS audit_events;