@economic/agents 2.12.0 → 2.13.0

package/README.md

@@ -640,7 +640,30 @@ When configured:
 AI telemetry is emitted per turn from the `ai` SDK's OpenTelemetry spans:
 
 - **Audit logs** → one JSON object per turn in `AGENTS_AUDIT_LOGS` (model, actor, IP, prompt, response, tool calls).
-- **Analytics** → per-turn and per-tool data points in `AGENTS_ANALYTICS`.
+- **Analytics** → typed per-turn and per-tool events. By default these are written to
+  `AGENTS_ANALYTICS` using the existing Analytics Engine schema.
+
+Additional analytics destinations can receive the same events by overriding
+`getAnalyticsHandlers()`. Analytics Engine remains enabled whenever `AGENTS_ANALYTICS` is bound:
+
+```typescript
+import type { AnalyticsHandler } from "@economic/agents";
+
+const warehouse: AnalyticsHandler = {
+  name: "warehouse",
+  async handle(event) {
+    await sendToWarehouse(event);
+  },
+};
+
+getAnalyticsHandlers() {
+  return [warehouse];
+}
+```
+
+Handler failures are isolated and recorded as operational errors. Delivery runs through the
+agent's lifetime management without blocking the response. `prompt.received` includes the raw
+prompt for destinations such as conversation classification; handlers must treat it as sensitive.
 
 Separately, the SDK writes structured operational logs for completed/failed LLM and tool calls, turn duration, framework failures, and selected recovery warnings. Prompt, response, tool argument, and tool result content is excluded. These records use the stable fields `source`, `event`, `level`, `timestamp`, `agentName`, `agentClass`, `durableObjectName`, and `attributes`, while preserving Cloudflare's diagnostic events.
 
@@ -669,21 +692,25 @@ Imported from `@economic/agents` unless noted.
 | `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                                  |
 | `AgentEnv`                                                               | The bindings the runtime expects.                                                   |
 | `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                            |
+| `AnalyticsHandler` / `AnalyticsEvent`                                    | Typed, consumer-configured product-analytics destinations.                          |
+| `createAnalyticsEngineHandler(dataset)`                                  | Analytics Engine destination using the existing v2 positional schema.               |
 
 ### Members
 
-| Member                                         | On          | Description                                  |
-| ---------------------------------------------- | ----------- | -------------------------------------------- |
-| `getModel(ctx?)`                               | `Agent`     | Required. Model for inference.               |
-| `getSystemPrompt(ctx?)`                        | `Agent`     | Required. System prompt.                     |
-| `getTools()`                                   | `Agent`     | Always-on tools (default `{}`).              |
-| `getSkills()`                                  | `Agent`     | Local skills (default `[]`).                 |
-| `static getJwtAuthConfig(env)`                 | `Agent`     | Optional JWT verification and actor binding. |
-| `getUserContext(jwtToken)`                     | `Agent`     | Optional per-user context after auth.        |
-| `submitMessageFeedback` / `getMessageFeedback` | `ChatAgent` | Callable message feedback.                   |
-| `agent`                                        | `Assistant` | Required. Your `ChatAgent` subclass.         |
-| `fastModel`                                    | `Assistant` | Required. Cheap model for titles/summaries.  |
-| `createChat` / `getChats` / `deleteChat`       | `Assistant` | Callable chat management.                    |
+| Member                                         | On          | Description                                                            |
+| ---------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `getModel(ctx?)`                               | `Agent`     | Required. Model for inference.                                         |
+| `getSystemPrompt(ctx?)`                        | `Agent`     | Required. System prompt.                                               |
+| `getTools()`                                   | `Agent`     | Always-on tools (default `{}`).                                        |
+| `getSkills()`                                  | `Agent`     | Local skills (default `[]`).                                           |
+| `getAnalyticsHandlers()`                       | `Agent`     | Additional analytics destinations; Analytics Engine remains automatic. |
+| `getAnalyticsAttributes()`                     | `Agent`     | Additional dimensions included on every analytics event.               |
+| `static getJwtAuthConfig(env)`                 | `Agent`     | Optional JWT verification and actor binding.                           |
+| `getUserContext(jwtToken)`                     | `Agent`     | Optional per-user context after auth.                                  |
+| `submitMessageFeedback` / `getMessageFeedback` | `ChatAgent` | Callable message feedback.                                             |
+| `agent`                                        | `Assistant` | Required. Your `ChatAgent` subclass.                                   |
+| `fastModel`                                    | `Assistant` | Required. Cheap model for titles/summaries.                            |
+| `createChat` / `getChats` / `deleteChat`       | `Assistant` | Callable chat management.                                              |
 
 ### Package root (`@economic/agents`)
 

package/dist/index.d.mts

@@ -114,6 +114,102 @@ type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INP
 };
 declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(definition: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
 //#endregion
+//#region src/server/features/analytics/types.d.ts
+type AnalyticsAttribute = string | number | boolean;
+type AnalyticsAttributes = Readonly<Record<string, AnalyticsAttribute>>;
+interface AnalyticsUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cachedInputTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+}
+type AnalyticsEventPayload = {
+  type: "prompt.received"; /** Raw model messages. Handlers must treat this field as sensitive data. */
+  messages: readonly ModelMessage[];
+  continuation: boolean;
+} | {
+  type: "turn.completed";
+  requestId: string;
+  status: string;
+  continuation: boolean;
+  responseSize: number;
+} | {
+  type: "llm.completed";
+  model: string;
+  provider: string;
+  finishReason: string;
+  usage: AnalyticsUsage;
+  durationMs: number;
+  inputSize: number;
+  responseSize: number;
+} | {
+  type: "tool.completed";
+  toolCallId?: string;
+  toolName: string;
+  skillNames: readonly string[];
+  success: boolean;
+  durationMs: number;
+  inputSize: number;
+  outputSize: number;
+} | {
+  type: "feedback.submitted";
+  messageId: string;
+  rating: 1 | -1 | 0;
+};
+type AnalyticsEvent = AnalyticsEventPayload & {
+  schemaVersion: 1;
+  eventId: string;
+  timestamp: number;
+  agentName: string;
+  durableObjectName: string;
+  actorId: string;
+  attributes: AnalyticsAttributes;
+};
+/** Receives typed product-analytics events emitted by the SDK. */
+interface AnalyticsHandler {
+  readonly name?: string;
+  handle(event: AnalyticsEvent): void | Promise<void>;
+}
+interface AnalyticsEventContext {
+  agentName: string;
+  durableObjectName: string;
+  actorId: string;
+  attributes?: AnalyticsAttributes;
+}
+//#endregion
+//#region src/server/features/analytics/analytics-engine.d.ts
+/**
+ * Creates a Cloudflare Analytics Engine destination for SDK analytics events.
+ * It preserves the SDK v2 positional schema and never writes prompt content.
+ */
+declare function createAnalyticsEngineHandler(dataset: AnalyticsEngineDataset): AnalyticsHandler;
+//#endregion
+//#region src/server/features/analytics/dispatcher.d.ts
+declare function createAnalyticsEvent(context: AnalyticsEventContext, payload: AnalyticsEventPayload): AnalyticsEvent;
+declare function dispatchAnalyticsEvent(handlers: readonly AnalyticsHandler[], event: AnalyticsEvent): Promise<void>;
+//#endregion
+//#region src/server/features/analytics/emitter.d.ts
+interface AnalyticsOptions {
+  getContext(): AnalyticsEventContext;
+  getHandlers(): readonly AnalyticsHandler[];
+  keepAlive<T>(callback: () => Promise<T>): Promise<T>;
+}
+declare class Analytics {
+  private readonly options;
+  private handlers?;
+  constructor(options: AnalyticsOptions);
+  private getHandlers;
+  private emit;
+  get enabled(): boolean;
+  get context(): AnalyticsEventContext;
+  promptReceived(messages: readonly ModelMessage[], continuation: boolean): void;
+  turnCompleted(requestId: string, status: string, continuation: boolean, response: unknown): void;
+  feedbackSubmitted(messageId: string, rating: 1 | -1 | 0): void;
+  event(payload: AnalyticsEventPayload | (() => AnalyticsEventPayload)): void;
+}
+//#endregion
 //#region src/server/agents/Agent.d.ts
 /** What the model would see on its next step — returned by {@link Agent.inspectTurn}. */
 interface TurnSnapshot {
@@ -305,6 +401,14 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * Best-effort and non-blocking — never allowed to interfere with a turn.
    */
   protected registerInstanceActivity(): Promise<void>;
+  protected readonly analytics: Analytics;
+  /**
+   * Additional product-analytics destinations for this agent. Analytics Engine
+   * remains enabled whenever `AGENTS_ANALYTICS` is bound.
+   */
+  getAnalyticsHandlers(): readonly AnalyticsHandler[];
+  /** Business dimensions added to every analytics event. */
+  getAnalyticsAttributes(): AnalyticsAttributes;
   observability?: Observability;
   /**
    * Resolves the analytics/telemetry agent name to the entry-point agent: the
@@ -455,4 +559,4 @@ declare function routeAgentRequest<Env>(request: Request, env: Env, options?: Ag
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type AnalyticsAttribute, type AnalyticsAttributes, type AnalyticsEvent, type AnalyticsEventPayload, type AnalyticsHandler, type AnalyticsUsage, Assistant, ChatAgent, type ExchangedToken, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -510,94 +510,35 @@ async function handleAuditSpan(span, auditLogs, context) {
 //#endregion
 //#region src/server/features/telemetry/analytics.ts
 const emittedToolCallIds = /* @__PURE__ */ new Set();
-function safeJsonString(value) {
-	if (value === void 0) return void 0;
+function serializedSize$1(value) {
 	try {
-		return JSON.stringify(value);
+		return JSON.stringify(value)?.length ?? 0;
 	} catch {
-		return;
-	}
-}
-function writeAnalyticsDatapoint(analytics, dataPoint) {
-	if (!analytics) return;
-	try {
-		analytics.writeDataPoint(dataPoint);
-	} catch (error) {
-		console.error("[Agent] Failed to write analytics datapoint", error);
+		return 0;
 	}
 }
-/**
-* Writes a message-feedback rating to Analytics Engine so sentiment can be
-* aggregated across all chats without fanning out to every chat DO.
-*
-* Emitted on every rating change; the dashboard takes the latest rating per
-* `messageId` (blob4) so re-rates and clears are idempotent.
-*/
-function recordFeedbackAnalytics(analytics, context, messageId, rating) {
-	writeAnalyticsDatapoint(analytics, {
-		indexes: [context.actorId],
-		blobs: [
-			"feedback",
-			context.agentName,
-			context.durableObjectName,
-			messageId
-		],
-		doubles: [rating]
-	});
-}
-function recordPromptReceivedAnalytics(analytics, context, messages, continuation) {
-	if (!analytics) return;
-	writeAnalyticsDatapoint(analytics, {
-		indexes: [context.actorId],
-		blobs: [
-			"prompt_received",
-			context.agentName,
-			context.durableObjectName,
-			String(continuation)
-		],
-		doubles: [safeJsonString(messages)?.length ?? 0]
-	});
-}
-function recordTurnCompletedAnalytics(analytics, context, requestId, status, continuation, response) {
-	if (!analytics) return;
-	writeAnalyticsDatapoint(analytics, {
-		indexes: [context.actorId],
-		blobs: [
-			"turn_completed",
-			context.agentName,
-			context.durableObjectName,
-			requestId,
-			status,
-			String(continuation)
-		],
-		doubles: [safeJsonString(response)?.length ?? 0]
-	});
-}
-function handleAnalyticsSpan(span, analytics, context) {
+function handleAnalyticsSpan(span, analytics) {
+	if (!analytics.enabled) return;
 	if (span.name === "ai.streamText.doStream") {
 		const promptMessages = parseJson(stringAttribute(span, "ai.prompt.messages"));
 		const responseText = stringAttribute(span, "ai.response.text") ?? "";
 		const responseToolCalls = parseJson(stringAttribute(span, "ai.response.toolCalls"));
-		writeAnalyticsDatapoint(analytics, {
-			indexes: [context.actorId],
-			blobs: [
-				"llm_call",
-				context.agentName,
-				context.durableObjectName,
-				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
-			]
+		analytics.event({
+			type: "llm.completed",
+			model: stringAttribute(span, "ai.model.id") ?? "",
+			provider: stringAttribute(span, "ai.model.provider") ?? "",
+			finishReason: stringAttribute(span, "ai.response.finishReason") ?? "",
+			usage: {
+				inputTokens: numberAttribute(span, "ai.usage.inputTokens") ?? 0,
+				outputTokens: numberAttribute(span, "ai.usage.outputTokens") ?? 0,
+				totalTokens: numberAttribute(span, "ai.usage.totalTokens") ?? 0,
+				cachedInputTokens: numberAttribute(span, "ai.usage.inputTokenDetails.cacheReadTokens") ?? void 0,
+				cacheWriteTokens: numberAttribute(span, "ai.usage.inputTokenDetails.cacheWriteTokens") ?? void 0,
+				reasoningTokens: numberAttribute(span, "ai.usage.reasoningTokens") ?? void 0
+			},
+			durationMs: durationMs(span.duration),
+			inputSize: promptCharCount(promptMessages ?? []),
+			responseSize: responseText.length
 		});
 		if (Array.isArray(responseToolCalls)) for (const value of responseToolCalls) {
 			if (!value || typeof value !== "object") continue;
@@ -607,70 +548,39 @@ function handleAnalyticsSpan(span, analytics, context) {
 			const toolName = typeof toolCall.toolName === "string" ? toolCall.toolName : void 0;
 			if (!toolName) continue;
 			const input = toolCall.input;
-			const argsRaw = safeJsonString(input);
-			const success = span.status.code === 0;
 			const activatedSkills = extractSkillNames(toolName, input);
-			const skillNames = activatedSkills.length ? activatedSkills : [currentSkillByChat.get(context.durableObjectName) ?? ""];
+			const skillNames = activatedSkills.length ? activatedSkills : [currentSkillByChat.get(analytics.context.durableObjectName) ?? ""];
 			if (toolCallId) emittedToolCallIds.add(toolCallId);
-			for (const skillName of skillNames) writeAnalyticsDatapoint(analytics, {
-				indexes: [context.actorId],
-				blobs: [
-					"tool_call",
-					context.agentName,
-					context.durableObjectName,
-					toolName,
-					skillName,
-					success ? "success" : "error"
-				],
-				doubles: [
-					0,
-					success ? 1 : 0,
-					argsRaw?.length ?? 0,
-					0,
-					0,
-					0,
-					0,
-					0
-				]
+			analytics.event({
+				type: "tool.completed",
+				toolCallId,
+				toolName,
+				skillNames,
+				success: span.status.code === 0,
+				durationMs: 0,
+				inputSize: serializedSize$1(input),
+				outputSize: 0
 			});
 		}
 		return;
 	}
-	if (span.name === "ai.toolCall") {
-		const toolName = stringAttribute(span, "ai.toolCall.name");
-		const toolCallId = stringAttribute(span, "ai.toolCall.id");
-		if (toolCallId && emittedToolCallIds.has(toolCallId)) return;
-		if (toolCallId) emittedToolCallIds.add(toolCallId);
-		const argsRaw = stringAttribute(span, "ai.toolCall.args");
-		const toolInput = parseJson(argsRaw);
-		const success = span.status.code === 0;
-		const duration = durationMs(span.duration);
-		const argsSize = argsRaw?.length ?? 0;
-		const resultSize = stringAttribute(span, "ai.toolCall.result")?.length ?? 0;
-		const activatedSkills = extractSkillNames(toolName, toolInput);
-		const skillNames = activatedSkills.length ? activatedSkills : [currentSkillByChat.get(context.durableObjectName) ?? ""];
-		for (const skillName of skillNames) writeAnalyticsDatapoint(analytics, {
-			indexes: [context.actorId],
-			blobs: [
-				"tool_call",
-				context.agentName,
-				context.durableObjectName,
-				toolName ?? "",
-				skillName,
-				success ? "success" : "error"
-			],
-			doubles: [
-				duration,
-				success ? 1 : 0,
-				argsSize,
-				resultSize,
-				0,
-				0,
-				0,
-				0
-			]
-		});
-	}
+	if (span.name !== "ai.toolCall") return;
+	const toolCallId = stringAttribute(span, "ai.toolCall.id");
+	if (toolCallId && emittedToolCallIds.has(toolCallId)) return;
+	if (toolCallId) emittedToolCallIds.add(toolCallId);
+	const toolName = stringAttribute(span, "ai.toolCall.name") ?? "";
+	const argsRaw = stringAttribute(span, "ai.toolCall.args");
+	const activatedSkills = extractSkillNames(toolName, parseJson(argsRaw));
+	analytics.event({
+		type: "tool.completed",
+		toolCallId,
+		toolName,
+		skillNames: activatedSkills.length ? activatedSkills : [currentSkillByChat.get(analytics.context.durableObjectName) ?? ""],
+		success: span.status.code === 0,
+		durationMs: durationMs(span.duration),
+		inputSize: argsRaw?.length ?? 0,
+		outputSize: stringAttribute(span, "ai.toolCall.result")?.length ?? 0
+	});
 }
 //#endregion
 //#region src/server/features/observability/index.ts
@@ -692,6 +602,36 @@ function writeOperationalLog(record, logger = console) {
 		else logger.log(message);
 	} catch {}
 }
+function errorAttributes(error) {
+	if (!(error instanceof Error)) return { error: String(error) };
+	const causes = [];
+	let cause = error.cause;
+	while (cause !== void 0 && causes.length < 5) {
+		causes.push(cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause));
+		cause = cause instanceof Error ? cause.cause : void 0;
+	}
+	return {
+		error: error.message,
+		errorType: error.name,
+		stack: error.stack,
+		...causes.length ? { causes } : {}
+	};
+}
+function logOperationalError(event, error, context = {}) {
+	writeOperationalLog({
+		source: "@economic/agents",
+		event,
+		level: "error",
+		timestamp: Date.now(),
+		agentName: context.agentName,
+		agentClass: context.agentClass,
+		durableObjectName: context.durableObjectName,
+		attributes: {
+			...context.attributes,
+			...errorAttributes(error)
+		}
+	});
+}
 function isFailure(event) {
 	return event.type.endsWith("error") || event.type.endsWith("failed") || event.type.endsWith("exhausted") || "error" in event.payload && Boolean(event.payload.error);
 }
@@ -793,11 +733,11 @@ var AgentSpanExporter = class {
 					if (span.name === "ai.streamText.doStream") {
 						rememberDoStream(span, this.context.durableObjectName);
 						attachToolCallsToChat(span, this.context.durableObjectName);
-						handleAnalyticsSpan(span, this.analytics, this.context);
+						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, this.context);
+						handleAnalyticsSpan(span, this.analytics);
 					}
 				}
 				resultCallback({ code: 0 });
@@ -815,6 +755,254 @@ function createAgentTracer(auditLogs, analytics, context) {
 	return new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new AgentSpanExporter(auditLogs, analytics, context))] }).getTracer("@economic/agents");
 }
 //#endregion
+//#region src/server/features/analytics/utils.ts
+function serializedSize(value) {
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}
+//#endregion
+//#region src/server/features/analytics/analytics-engine.ts
+const MAX_INDEX_BYTES = 96;
+const MAX_BLOB_BYTES = 16 * 1024;
+const encoder = new TextEncoder();
+/**
+* Creates a Cloudflare Analytics Engine destination for SDK analytics events.
+* It preserves the SDK v2 positional schema and never writes prompt content.
+*/
+function createAnalyticsEngineHandler(dataset) {
+	return {
+		name: "Cloudflare Analytics Engine",
+		async handle(event) {
+			for (const point of toAnalyticsEnginePoints(event)) dataset.writeDataPoint(await boundAnalyticsPoint(point));
+		}
+	};
+}
+async function boundAnalyticsPoint(point) {
+	return {
+		...point,
+		indexes: await Promise.all(point.indexes.map(boundIndex)),
+		blobs: boundBlobs(point.blobs)
+	};
+}
+async function boundIndex(value) {
+	if (byteLength(value) <= MAX_INDEX_BYTES) return value;
+	const digest = await crypto.subtle.digest("SHA-256", encoder.encode(value));
+	const suffix = `:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+	return `${truncateUtf8(value, MAX_INDEX_BYTES - byteLength(suffix))}${suffix}`;
+}
+function boundBlobs(values) {
+	const blobs = [...values];
+	let sizes = blobs.map(byteLength);
+	let total = sizes.reduce((sum, size) => sum + size, 0);
+	if (total <= MAX_BLOB_BYTES) return blobs;
+	const attributesIndex = blobs.length - 2;
+	blobs[attributesIndex] = "{}";
+	sizes = blobs.map(byteLength);
+	total = sizes.reduce((sum, size) => sum + size, 0);
+	while (total > MAX_BLOB_BYTES) {
+		const largestSize = Math.max(...sizes);
+		const largestIndex = sizes.indexOf(largestSize);
+		const value = truncateUtf8(blobs[largestIndex] ?? "", largestSize - (total - MAX_BLOB_BYTES));
+		const nextSize = byteLength(value);
+		blobs[largestIndex] = value;
+		sizes[largestIndex] = nextSize;
+		total -= largestSize - nextSize;
+	}
+	return blobs;
+}
+function truncateUtf8(value, maxBytes) {
+	let bytes = 0;
+	let end = 0;
+	for (const character of value) {
+		const characterBytes = byteLength(character);
+		if (bytes + characterBytes > maxBytes) break;
+		bytes += characterBytes;
+		end += character.length;
+	}
+	return value.slice(0, end);
+}
+function byteLength(value) {
+	return encoder.encode(value).byteLength;
+}
+function toAnalyticsEnginePoints(event) {
+	const common = [
+		event.eventId,
+		JSON.stringify(event.attributes),
+		String(event.schemaVersion)
+	];
+	const indexes = [event.actorId];
+	switch (event.type) {
+		case "prompt.received": return [{
+			indexes,
+			blobs: [
+				"prompt_received",
+				event.agentName,
+				event.durableObjectName,
+				String(event.continuation),
+				...common
+			],
+			doubles: [serializedSize(event.messages)]
+		}];
+		case "turn.completed": return [{
+			indexes,
+			blobs: [
+				"turn_completed",
+				event.agentName,
+				event.durableObjectName,
+				event.requestId,
+				event.status,
+				String(event.continuation),
+				...common
+			],
+			doubles: [event.responseSize]
+		}];
+		case "llm.completed": return [{
+			indexes,
+			blobs: [
+				"llm_call",
+				event.agentName,
+				event.durableObjectName,
+				event.model,
+				event.provider,
+				event.finishReason,
+				...common
+			],
+			doubles: [
+				event.usage.inputTokens,
+				event.usage.outputTokens,
+				event.usage.totalTokens,
+				event.usage.cachedInputTokens ?? 0,
+				event.usage.cacheWriteTokens ?? 0,
+				event.durationMs,
+				event.inputSize,
+				event.responseSize,
+				event.usage.reasoningTokens ?? 0
+			]
+		}];
+		case "tool.completed": return (event.skillNames.length ? event.skillNames : [""]).map((skillName) => ({
+			indexes,
+			blobs: [
+				"tool_call",
+				event.agentName,
+				event.durableObjectName,
+				event.toolName,
+				skillName,
+				event.success ? "success" : "error",
+				event.toolCallId ?? "",
+				...common
+			],
+			doubles: [
+				event.durationMs,
+				event.success ? 1 : 0,
+				event.inputSize,
+				event.outputSize,
+				0,
+				0,
+				0,
+				0
+			]
+		}));
+		case "feedback.submitted": return [{
+			indexes,
+			blobs: [
+				"feedback",
+				event.agentName,
+				event.durableObjectName,
+				event.messageId,
+				...common
+			],
+			doubles: [event.rating]
+		}];
+	}
+}
+//#endregion
+//#region src/server/features/analytics/dispatcher.ts
+function createAnalyticsEvent(context, payload) {
+	return {
+		...payload,
+		schemaVersion: 1,
+		eventId: crypto.randomUUID(),
+		timestamp: Date.now(),
+		agentName: context.agentName,
+		durableObjectName: context.durableObjectName,
+		actorId: context.actorId,
+		attributes: context.attributes ?? {}
+	};
+}
+async function dispatchAnalyticsEvent(handlers, event) {
+	await Promise.all(handlers.map(async (handler) => {
+		try {
+			await handler.handle(event);
+		} catch (error) {
+			writeOperationalLog({
+				source: "@economic/agents",
+				event: "agent.analytics.handler.failed",
+				level: "error",
+				timestamp: Date.now(),
+				agentName: event.agentName,
+				durableObjectName: event.durableObjectName,
+				attributes: {
+					handler: handler.name ?? "handler",
+					error: error instanceof Error ? error.message : String(error)
+				}
+			});
+		}
+	}));
+}
+//#endregion
+//#region src/server/features/analytics/emitter.ts
+var Analytics = class {
+	options;
+	handlers;
+	constructor(options) {
+		this.options = options;
+	}
+	getHandlers() {
+		return this.handlers ??= this.options.getHandlers();
+	}
+	emit(payload) {
+		const handlers = this.getHandlers();
+		if (handlers.length === 0) return;
+		const eventPayload = typeof payload === "function" ? payload() : payload;
+		this.options.keepAlive(() => dispatchAnalyticsEvent(handlers, createAnalyticsEvent(this.context, eventPayload)));
+	}
+	get enabled() {
+		return this.getHandlers().length > 0;
+	}
+	get context() {
+		return this.options.getContext();
+	}
+	promptReceived(messages, continuation) {
+		this.emit({
+			type: "prompt.received",
+			messages,
+			continuation
+		});
+	}
+	turnCompleted(requestId, status, continuation, response) {
+		this.emit(() => ({
+			type: "turn.completed",
+			requestId,
+			status,
+			continuation,
+			responseSize: serializedSize(response)
+		}));
+	}
+	feedbackSubmitted(messageId, rating) {
+		this.emit({
+			type: "feedback.submitted",
+			messageId,
+			rating
+		});
+	}
+	event(payload) {
+		this.emit(payload);
+	}
+};
+//#endregion
 //#region src/server/features/registry.ts
 /**
 * Registers a top-level DO in the global registry.
@@ -964,11 +1152,7 @@ var Agent = class extends Think {
 	* `returned.tools` into your own `TurnConfig.tools` if you return tools.
 	*/
 	async beforeTurn(ctx) {
-		recordPromptReceivedAnalytics(this.env.AGENTS_ANALYTICS, {
-			agentName: this.getTelemetryAgentName(),
-			durableObjectName: this.name,
-			actorId: this.getTelemetryActorId()
-		}, ctx.messages, ctx.continuation);
+		this.analytics.promptReceived(ctx.messages, ctx.continuation);
 		this.registerInstanceActivity();
 		const body = await this._applyTokenExchange(ctx.body);
 		this._turn.context = this.getToolContextForCurrentTurn(body);
@@ -987,7 +1171,7 @@ var Agent = class extends Think {
 			experimental_transform: buildSourcesTransform(),
 			experimental_telemetry: {
 				isEnabled: true,
-				tracer: createAgentTracer(this.env.AGENTS_AUDIT_LOGS, this.env.AGENTS_ANALYTICS, {
+				tracer: createAgentTracer(this.env.AGENTS_AUDIT_LOGS, this.analytics, {
 					agentName: this.getTelemetryAgentName(),
 					agentClass: this.constructor.name,
 					durableObjectName: this.name,
@@ -1346,7 +1530,12 @@ var Agent = class extends Think {
 		try {
 			result = await verifyJwt(request, config);
 		} catch (error) {
-			console.error(`[Agent] JWT verification error - ${error}`);
+			logOperationalError("agent.authentication.failed", error, {
+				agentName: this.getTelemetryAgentName(),
+				agentClass: this.constructor.name,
+				durableObjectName: this.name,
+				attributes: { stage: "jwt-verification" }
+			});
 			return {
 				success: false,
 				status: 401,
@@ -1369,7 +1558,12 @@ var Agent = class extends Think {
 			try {
 				exchanged = await exchangeToken(token, exchangeConfig);
 			} catch (error) {
-				console.error(`[Agent] Token exchange error - ${error}`);
+				logOperationalError("agent.authentication.failed", error, {
+					agentName: this.getTelemetryAgentName(),
+					agentClass: this.constructor.name,
+					durableObjectName: this.name,
+					attributes: { stage: "token-exchange" }
+				});
 				return {
 					success: false,
 					status: 500,
@@ -1377,7 +1571,12 @@ var Agent = class extends Think {
 				};
 			}
 			if (!exchanged.success) {
-				console.error(`[Agent] Token exchange failed - ${exchanged.message}`);
+				logOperationalError("agent.authentication.failed", new Error(exchanged.message), {
+					agentName: this.getTelemetryAgentName(),
+					agentClass: this.constructor.name,
+					durableObjectName: this.name,
+					attributes: { stage: "token-exchange" }
+				});
 				return {
 					success: false,
 					status: exchanged.subjectTokenRejected ? 401 : 500,
@@ -1395,7 +1594,12 @@ var Agent = class extends Think {
 				userContext: this.userContext
 			};
 		} catch (error) {
-			console.error(`[Agent] getUserContext error - ${error}`);
+			logOperationalError("agent.authentication.failed", error, {
+				agentName: this.getTelemetryAgentName(),
+				agentClass: this.constructor.name,
+				durableObjectName: this.name,
+				attributes: { stage: "user-context" }
+			});
 			const closeCode = getConnectCloseCode(error);
 			return {
 				success: false,
@@ -1459,7 +1663,11 @@ var Agent = class extends Think {
 				createdAt: Date.now()
 			});
 		} catch (error) {
-			console.error("[Agent] Failed to register in agent_registry", error);
+			logOperationalError("agent.registry.registration.failed", error, {
+				agentName: this.getTelemetryAgentName(),
+				agentClass: this.constructor.name,
+				durableObjectName: this.name
+			});
 		}
 	}
 	/**
@@ -1485,9 +1693,34 @@ var Agent = class extends Think {
 				updatedAt: Date.now()
 			});
 		} catch (error) {
-			console.error("[Agent] Failed to update agent_registry activity", error);
+			logOperationalError("agent.registry.activity.failed", error, {
+				agentName: this.getTelemetryAgentName(),
+				agentClass: this.constructor.name,
+				durableObjectName: this.name
+			});
 		}
 	}
+	analytics = new Analytics({
+		getContext: () => ({
+			agentName: this.getTelemetryAgentName(),
+			durableObjectName: this.name,
+			actorId: this.getTelemetryActorId(),
+			attributes: this.getAnalyticsAttributes()
+		}),
+		getHandlers: () => [...this.env.AGENTS_ANALYTICS ? [createAnalyticsEngineHandler(this.env.AGENTS_ANALYTICS)] : [], ...this.getAnalyticsHandlers()],
+		keepAlive: (callback) => this.keepAliveWhile(callback)
+	});
+	/**
+	* Additional product-analytics destinations for this agent. Analytics Engine
+	* remains enabled whenever `AGENTS_ANALYTICS` is bound.
+	*/
+	getAnalyticsHandlers() {
+		return [];
+	}
+	/** Business dimensions added to every analytics event. */
+	getAnalyticsAttributes() {
+		return {};
+	}
 	observability = createWorkerObservability({ getIdentity: () => ({
 		agentName: this.getTelemetryAgentName(),
 		agentClass: this.constructor.name
@@ -1884,7 +2117,12 @@ var Assistant = class extends Agent$1 {
 		try {
 			result = await verifyJwt(request, config);
 		} catch (error) {
-			console.error(`[Assistant] JWT verification error - ${error}`);
+			logOperationalError("agent.authentication.failed", error, {
+				agentName: this.constructor.name,
+				agentClass: this.constructor.name,
+				durableObjectName: this.name,
+				attributes: { stage: "jwt-verification" }
+			});
 			return {
 				success: false,
 				status: 401,
@@ -1896,13 +2134,18 @@ var Assistant = class extends Agent$1 {
 			durableObjectName: this.name,
 			parentPath: this.parentPath
 		})) {
-			console.error("[Assistant] Authenticated actor does not own the requested assistant", {
-				authenticatedActorId: config.getActorId(result.claims),
-				requiredActorId: getTargetActorId({
-					durableObjectName: this.name,
-					parentPath: this.parentPath
-				}),
-				durableObjectName: this.name
+			logOperationalError("agent.authentication.failed", /* @__PURE__ */ new Error("Authenticated actor does not own the requested assistant"), {
+				agentName: this.constructor.name,
+				agentClass: this.constructor.name,
+				durableObjectName: this.name,
+				attributes: {
+					stage: "actor-authorization",
+					authenticatedActorId: config.getActorId(result.claims),
+					requiredActorId: getTargetActorId({
+						durableObjectName: this.name,
+						parentPath: this.parentPath
+					})
+				}
 			});
 			return {
 				success: false,
@@ -1940,9 +2183,11 @@ var Assistant = class extends Agent$1 {
 			try {
 				await this.deleteSubAgent(this.agent, id);
 			} catch (cleanupError) {
-				console.error("[Assistant] Failed to clean up an unscheduled chat facet", {
-					durableObjectName: id,
-					error: cleanupError
+				logOperationalError("assistant.chat.cleanup.failed", cleanupError, {
+					agentName: this.constructor.name,
+					agentClass: this.constructor.name,
+					durableObjectName: this.name,
+					attributes: { chatName: id }
 				});
 			}
 			throw error;
@@ -1973,16 +2218,20 @@ var Assistant = class extends Agent$1 {
 		touchChat(this.sql.bind(this), durableObjectName);
 		this.keepAliveWhile(async () => {
 			await Promise.all([summariseChatWithAI(this.sql.bind(this), durableObjectName, messages, this.fastModel), this.scheduleChatForAutoDeletion(durableObjectName).catch((error) => {
-				console.error("[Assistant] Failed to reschedule chat deletion", {
-					durableObjectName,
-					error
+				logOperationalError("assistant.chat.reschedule.failed", error, {
+					agentName: this.constructor.name,
+					agentClass: this.constructor.name,
+					durableObjectName: this.name,
+					attributes: { chatName: durableObjectName }
 				});
 			})]);
 			await this.syncChatToGlobalList(durableObjectName);
 		}).catch((error) => {
-			console.error("[Assistant] Failed to record chat metadata", {
-				durableObjectName,
-				error
+			logOperationalError("assistant.chat.metadata.failed", error, {
+				agentName: this.constructor.name,
+				agentClass: this.constructor.name,
+				durableObjectName: this.name,
+				attributes: { chatName: durableObjectName }
 			});
 		});
 	}
@@ -2024,7 +2273,11 @@ var Assistant = class extends Agent$1 {
 				createdAt: Date.now()
 			});
 		} catch (error) {
-			console.error("[Assistant] Failed to register in agent_registry", error);
+			logOperationalError("agent.registry.registration.failed", error, {
+				agentName: this.constructor.name,
+				agentClass: this.constructor.name,
+				durableObjectName: this.name
+			});
 		}
 	}
 	/**
@@ -2041,7 +2294,11 @@ var Assistant = class extends Agent$1 {
 				updatedAt
 			});
 		} catch (error) {
-			console.error("[Assistant] Failed to update agent_registry activity", error);
+			logOperationalError("agent.registry.activity.failed", error, {
+				agentName: this.constructor.name,
+				agentClass: this.constructor.name,
+				durableObjectName: this.name
+			});
 		}
 	}
 	async syncChatToGlobalList(durableObjectName) {
@@ -2443,11 +2700,7 @@ var ChatAgent = class extends Agent {
 		return config;
 	}
 	async onChatResponse(result) {
-		recordTurnCompletedAnalytics(this.env.AGENTS_ANALYTICS, {
-			agentName: this.getTelemetryAgentName(),
-			durableObjectName: this.name,
-			actorId: this.getTelemetryActorId()
-		}, result.requestId, result.status, result.continuation, result.message.parts);
+		this.analytics.turnCompleted(result.requestId, result.status, result.continuation, result.message.parts);
 		const parent = await this.getParentAgent();
 		if (parent?.recordChatTurn) await parent.recordChatTurn(this.name, this.messages);
 	}
@@ -2519,18 +2772,15 @@ var ChatAgent = class extends Agent {
 	async submitMessageFeedback(messageId, rating, comment) {
 		const result = submitMessageFeedback(this.sql.bind(this), messageId, rating, comment);
 		const parent = await this.getParentAgent();
-		recordFeedbackAnalytics(this.env.AGENTS_ANALYTICS, {
-			agentName: this.getTelemetryAgentName(),
-			durableObjectName: this.name,
-			actorId: this.getTelemetryActorId()
-		}, messageId, rating);
+		if (rating === 1 || rating === -1 || rating === 0) this.analytics.feedbackSubmitted(messageId, rating);
 		if (parent?.recordChatFeedback) try {
 			await parent.recordChatFeedback(this.name, messageId, rating);
 		} catch (error) {
-			console.error("[ChatAgent] Failed to update parent chat feedback summary", {
+			logOperationalError("agent.feedback.summary.failed", error, {
+				agentName: this.getTelemetryAgentName(),
+				agentClass: this.constructor.name,
 				durableObjectName: this.name,
-				messageId,
-				error
+				attributes: { messageId }
 			});
 		}
 		return result;
@@ -2620,4 +2870,4 @@ function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { Agent, Assistant, ChatAgent, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [