@economic/agents 2.7.1 → 3.0.0-alpha.32271766282.1.0

package/README.md

@@ -1,21 +1,21 @@
 # @economic/agents
 
-Our agents SDK for building AI agents on Cloudflare Workers. Each agent is a Durable Object running an LLM loop — model, system prompt, tools, skills, auth, telemetry — on [`@cloudflare/think`](https://www.npmjs.com/package/@cloudflare/think) and the [`ai`](https://www.npmjs.com/package/ai) SDK.
+Our agents SDK for building AI agents on Cloudflare Workers. Each agent is a Durable Object running an LLM loop — model, system prompt, tools, skills, auth, analytics, and audit logging — on [`@cloudflare/think`](https://www.npmjs.com/package/@cloudflare/think) and the [`ai`](https://www.npmjs.com/package/ai) SDK.
 
 React client: [`@economic/agents-react`](../react/README.md).
 
-> The v1 (`@economic/agents/v1`) API (`ChatAgentHarness`, `buildLLMParams`) is deprecated and will be removed in v3.
+Upgrading from version 2: see the [v3 migration guide](./MIGRATION.md).
 
 ## The three classes
 
-- **`Agent`** — the core. Runs the agent loop and keeps message history. Drive it over a WebSocket or programmatically (schedule, alarm, RPC). Most agents stop here.
-- **`ChatAgent`** — `Agent` plus chat features: compaction and message feedback.
-- **`Assistant`** — per-user shell over `ChatAgent`: create/list/delete chats, titles, summaries, retention.
+- **`ChatAgent`** — persistent conversational agent built on `Think`, with tools, skills, authentication, compaction, and message feedback. Drive it over a WebSocket or programmatically.
+- **`TaskAgent`** — one bounded, at-most-once input-to-output run without chat history.
+- **`Assistant`** — per-user shell over `ChatAgent`: create/list/delete chats, titles, summaries, and retention.
 
 ```
-Agent            ← LLM + tools + skills (most agents stop here)
- └─ ChatAgent     ← one persistent chat
-     └─ Assistant ← one user, many chats
+ChatAgent                 ← one persistent conversation
+Assistant → ChatAgent     ← one user, many conversations
+TaskAgent                 ← one bounded run, no conversation
 ```
 
 ## Install
@@ -36,9 +36,9 @@ npm install -D wrangler vite @cloudflare/vite-plugin @cloudflare/worker-bundler
 Routes Claude models through Cloudflare AI Gateway → Google Vertex AI.
 
 ```typescript
-import { createAnthropicVertexProvider } from "@economic/agents/providers";
+import { createAnthropicProvider } from "@economic/agents/providers";
 
-const anthropic = createAnthropicVertexProvider({
+const anthropic = createAnthropicProvider({
   cloudflareAccountId: env.CLOUDFLARE_ACCOUNT_ID,
   cloudflareAiGatewayId: env.AI_GATEWAY_ID,
   cloudflareApiToken: env.CLOUDFLARE_API_TOKEN,
@@ -83,26 +83,26 @@ const { anthropic, gemini } = createAiGatewayVertexProviders({
   cloudflareAiGatewayId: env.AI_GATEWAY_ID,
   cloudflareApiToken: env.CLOUDFLARE_API_TOKEN,
   googleCloudProjectId: env.GOOGLE_CLOUD_PROJECT_ID,
-  // Included in cf-aig-metadata on every request, including background calls.
-  metadata: { agentId: "support" },
 });
 ```
 
-Set a stable `agentId` when multiple agents may use the same gateway. AI Gateway
-stores this custom metadata with each request, allowing cost queries to filter
-by agent without copying cost data into another store.
+When these providers are used inside an SDK agent, the SDK automatically adds
+the agent's explicit `agentName` as `agentId` in `cf-aig-metadata`. This allows
+usage from a shared gateway and shared Worker to be grouped by logical agent.
 
-## Quick start: an agent
+## Quick start: a chat agent
 
-Subclass `Agent` and implement `getModel` and `getSystemPrompt`. Add tools with `getTools`, skills with `getSkills`. Expose a `@callable` method to run a turn — `saveMessages` injects a message, runs the turn, and persists the result:
+Subclass `ChatAgent`, set `agentName` to the stable logical agent name, and implement `getModel` and `getSystemPrompt`. `agentName` identifies the configured agent across audit logs, analytics, observability, and AI Gateway metadata; it is deliberately not inferred from the implementation class or Durable Object name. A config-driven harness can implement it as a getter. Add tools with `getTools`, skills with `getSkills`. Expose a `@callable` method to run a turn — `saveMessages` injects a message, runs the turn, and persists the result:
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
 import { callable } from "agents";
-import { Agent, tool, type ToolSet } from "@economic/agents";
+import { ChatAgent, tool, type ToolSet } from "@economic/agents";
 import { z } from "zod";
 
-export class SupportAgent extends Agent {
+export class SupportAgent extends ChatAgent {
+  agentName = "customer-support";
+
   getModel() {
     return openai("gpt-4o");
   }
@@ -171,6 +171,16 @@ export default {
 }
 ```
 
+Analytics is opt-in. To send the SDK's typed product events to that binding:
+
+```typescript
+import { createAnalyticsEngineHandler } from "@economic/agents";
+
+protected getAnalyticsHandlers() {
+  return [createAnalyticsEngineHandler(this.env.AGENTS_ANALYTICS)];
+}
+```
+
 Run `wrangler types` for a typed `Env`.
 
 ### Calling it from the client
@@ -189,9 +199,9 @@ await agent.call("checkOrder", ["1234"]);
 
 You can also drive turns server-side — call `saveMessages` from a schedule or alarm.
 
-## A chat agent
+## Using a chat UI
 
-For a chat UI, extend `ChatAgent` instead of `Agent`. It adds compaction and message feedback, and connects to a browser with [`useChat`](../react/README.md#usechat) — no `Assistant` required. The DO name is the chat; address one per user, ticket, or whatever fits.
+`ChatAgent` connects to a browser with [`useChat`](../react/README.md#usechat) — no `Assistant` required. The DO name is the chat; address one per user, ticket, or whatever fits.
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
@@ -199,6 +209,8 @@ import { ChatAgent } from "@economic/agents";
 import { weatherSkill } from "./skills/weather";
 
 export class MyChatAgent extends ChatAgent {
+  agentName = "weather-assistant";
+
   getModel() {
     return openai("gpt-4o");
   }
@@ -221,15 +233,15 @@ const { chat } = useChat({
 });
 ```
 
-What `ChatAgent` adds over `Agent`:
+Built-in chat features:
 
 - **Compaction** — past 100,000 tokens, older messages are summarised (with `getModel()`) while recent ones are kept verbatim. Storage keeps the full history.
 - **Message feedback** — thumbs up/down with an optional comment, in the chat's SQLite (`assistant_messages_feedback`, created automatically):
 
-  | Method                                               | Description                                                  |
-  | ---------------------------------------------------- | ------------------------------------------------------------ |
-  | `submitMessageFeedback(messageId, rating, comment?)` | `rating` is `1` (up) or `-1` (down). Upserts on the message. |
-  | `getMessageFeedback()`                               | All feedback for the chat, keyed by message id.              |
+  | Method                                               | Description                                                |
+  | ---------------------------------------------------- | ---------------------------------------------------------- |
+  | `submitMessageFeedback(messageId, rating, comment?)` | `1` is up, `-1` is down, and `0` clears existing feedback. |
+  | `getMessageFeedback()`                               | All feedback for the chat, keyed by message id.            |
 
   Surfaced by the client as `chat.submitMessageFeedback` / `chat.getMessageFeedback`.
 
@@ -243,6 +255,7 @@ import { Assistant } from "@economic/agents";
 import { MyChatAgent } from "./chat-agent";
 
 export class MyAssistant extends Assistant {
+  agentName = "weather-assistant";
   protected agent = MyChatAgent;
   protected fastModel = openai("gpt-4o-mini"); // titles and summaries
 }
@@ -260,27 +273,117 @@ const { status, chats, assistant, chat } = useAssistant({
 
 The `Assistant` keeps the chat list in its own SQLite (a `chats` table, created automatically) and exposes four callable methods. A newly created chat facet is added to this table when its first turn starts.
 
-| Method           | Returns  | Description                                 |
-| ---------------- | -------- | ------------------------------------------- |
-| `createChat()`   | `string` | Creates a chat facet and returns its id.    |
-| `getChats()`     | `Chat[]` | Started chats, most recently updated first. |
-| `deleteChat(id)` | `void`   | Deletes a chat facet and its record.        |
-| `renameChat(id)` | `void`   | Renames a registered chat.                  |
+| Method                  | Returns  | Description                                 |
+| ----------------------- | -------- | ------------------------------------------- |
+| `createChat()`          | `string` | Creates a chat facet and returns its id.    |
+| `getChats()`            | `Chat[]` | Started chats, most recently updated first. |
+| `deleteChat(id)`        | `void`   | Deletes a chat facet and its record.        |
+| `renameChat(id, title)` | `void`   | Renames a registered chat.                  |
 
 - **Titles and summaries** — generated with `fastModel` after each turn (on the first turn, then refreshed as the chat grows).
 - **Empty chat cleanup** — a newly created facet is scheduled for deletion after one day. Its first completed turn replaces that schedule with the normal sliding retention period.
 - **Retention** — inactive chats are deleted after 90 days, via a Durable Object alarm.
 
+## TaskAgent
+
+Use `TaskAgent` for one input-to-output run without conversation history. Implement the model,
+system prompt, and an HTTP transport that calls `runTask`:
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { TaskAgent } from "@economic/agents";
+
+type SummariseContext = {
+  tenantId: string;
+};
+
+type SummariseRequest = {
+  input: string;
+  context: SummariseContext;
+};
+
+export class SummariseTask extends TaskAgent<SummariseContext> {
+  agentName = "summarise-task";
+
+  getModel() {
+    return openai("gpt-4o-mini");
+  }
+
+  getSystemPrompt() {
+    return "Summarise the supplied text concisely.";
+  }
+
+  override async onRequest(request: Request): Promise<Response> {
+    const authentication = await this.authenticateRequest(request);
+    if (authentication instanceof Response) return authentication;
+
+    const { input, context } = (await request.json()) as SummariseRequest;
+    return Response.json(await this.runTask(input, context, authentication));
+  }
+}
+```
+
+Export and bind the class as a normal SQLite-backed Cloudflare Durable Object, then route requests
+with `routeAgentRequest` as shown in the [chat-agent quick start](#quick-start-a-chat-agent).
+`TaskAgent` requires the `AGENTS_AUDIT_LOGS` binding and refuses to start without it.
+`TaskAgent.onRequest` returns `501` until the subclass defines its transport.
+`runTask` trusts the authentication value passed by that transport; do not expose
+an RPC endpoint that lets callers construct the `authentication` argument themselves.
+
+The Durable Object name is the run id. The first call to `runTask` claims it before inference
+starts, so another call using the same name returns `{ status: "duplicate" }` rather than running
+and billing twice. `retentionDays` controls how long that claim is retained and defaults to one day.
+Use a fresh, stable id for each intended run.
+
+`runTask(input, context?, authentication?)` accepts either a string or `UIMessage[]` and returns:
+
+| Status      | Meaning                                                                 |
+| ----------- | ----------------------------------------------------------------------- |
+| `completed` | Contains `output` and an `outputType` of `"text"` or `"json"`.          |
+| `error`     | The run failed and contains a combined error description.               |
+| `duplicate` | That Durable Object name has already been claimed within its retention. |
+
+The task may use tools and skills through `getTools()` and `getSkills()` just like `ChatAgent`.
+Tool and skill authorization receives the request context plus `_token` and `_userContext` from
+request-scoped authentication. `maxSteps` limits the model/tool loop and defaults to 10.
+
+For structured output, return a JSON Schema from `getOutputSchema`. The completed `output` remains
+a JSON string and `outputType` is `"json"`. `validateOutput` can reject values that pass the schema
+but fail application-specific checks:
+
+```typescript
+protected getOutputSchema() {
+  return {
+    type: "object",
+    properties: {
+      summary: { type: "string" },
+      confidence: { type: "number", minimum: 0, maximum: 1 },
+    },
+    required: ["summary", "confidence"],
+    additionalProperties: false,
+  };
+}
+
+protected validateOutput(value: unknown) {
+  const result = value as { summary?: string };
+  return result.summary?.trim() ? null : "Summary must not be empty";
+}
+```
+
+When a structured task also has tools or skills, the SDK adds a terminal `submit_result` tool and
+instructs the model to call it with the final value. Without tools, it uses the model's native JSON
+output mode.
+
 ## Bindings
 
-Checked in `Agent.onStart` when a connection opens:
+Validated when the relevant agent starts:
 
-| Binding             | Type             | Required | Notes                                                                     |
-| ------------------- | ---------------- | -------- | ------------------------------------------------------------------------- |
-| `AGENTS_AUDIT_LOGS` | R2               | Yes      | Connection rejected if missing. One [audit log](#observability) per turn. |
-| `AGENTS_ANALYTICS`  | Analytics Engine | No       | Per-turn/per-tool [analytics](#observability). Warns if missing.          |
-| `SKILLS_BUCKET`     | R2               | No       | Source for [remote skills](#remote-skills).                               |
-| `LOADER`            | Worker Loader    | No       | Enables [native skill scripts](#skill-scripts) when bound.                |
+| Binding             | Type             | Required  | Notes                                                              |
+| ------------------- | ---------------- | --------- | ------------------------------------------------------------------ |
+| `AGENTS_DB`         | D1               | Chat      | Global registry for top-level agent instances.                     |
+| `AGENTS_AUDIT_LOGS` | R2               | Chat/task | Startup fails if missing. One [audit log](#audit-logging) per run. |
+| `AGENTS_ANALYTICS`  | Analytics Engine | No        | Optional destination for [product analytics](#analytics).          |
+| `LOADER`            | Worker Loader    | No        | Enables [native skill scripts](#skill-scripts) when bound.         |
 
 ## Tools
 
@@ -302,7 +405,9 @@ getTools(): ToolSet {
 }
 ```
 
-`authorize` returning `false` hides the tool for that request.
+`authorize` returning `false` keeps the tool visible to the model but replaces its execution
+with an explicit permission refusal. This lets the model explain the missing access instead of
+silently trying another tool. Unauthorized skills cannot be activated.
 
 ### Tool context
 
@@ -326,7 +431,7 @@ const call_api = tool({
 });
 ```
 
-`ToolContext<RequestContext, UserContext>` is `RequestContext & { _userContext?: UserContext }`. Request context comes from the client (`toolContext` in the hooks); `_userContext` comes from [`getUserContext`](#user-context) when using JWT Authentication (via `getJwtAuthConfig`).
+`ToolContext<RequestContext, UserContext>` adds `_token` and `_userContext` to the request context. Request context comes from the client (`toolContext` in the hooks); authenticated values come from the agent's configured `Authenticator`.
 
 ## Skills
 
@@ -425,7 +530,7 @@ Skill scripts are enabled when a Worker Loader binding named `LOADER` is present
 }
 ```
 
-`Agent` automatically creates a script runner when `env.LOADER` is bound. Without the binding, script execution is unavailable.
+`ChatAgent` automatically creates a script runner when `env.LOADER` is bound. Without the binding, script execution is unavailable.
 
 TypeScript scripts use the function-style contract:
 
@@ -467,7 +572,7 @@ import { skills } from "@cloudflare/think";
 
 getSkills() {
   return [
-    skills.r2(this.env.SKILLS_BUCKET, {
+    skills.r2(this.env.REMOTE_SKILLS, {
       skills: ["top-customers-by-revenue", "vat-code-review"],
     }),
   ];
@@ -485,82 +590,318 @@ skills/top-customers-by-revenue/
 
 Source order matters: if two sources define the same skill name, the first source wins.
 
+Remote skill storage is owned by the application. `REMOTE_SKILLS` above is an example
+consumer binding, not a binding reserved by this SDK or included in `AgentEnv`.
+
 ## Authentication
 
-### JWT
+Authentication is generic. An agent can implement `getAuthenticator(env)` to return an `Authenticator`. The SDK does not know what kind of credentials the authenticator accepts. If the method is absent, the agent remains accessible without SDK-level authentication.
+
+Each `ChatAgent`, `Assistant`, or `TaskAgent` class owns its authentication hook. An `Assistant` does not inherit authentication from its child `ChatAgent`; configure the two boundaries independently. For example, an assistant can verify access to the chat list while each chat separately verifies and exchanges its token for tool calls.
+
+For `ChatAgent` and `Assistant`, an authenticator runs once when a WebSocket connects. `TaskAgent` runs it once per request. In either case it returns a denial or the authenticated values the agent needs:
+
+```typescript
+return {
+  authenticated: true,
+  token,
+  userContext: { userId, role },
+};
+```
+
+- `token` is an optional downstream credential. When returned, it is available as `ctx._token`.
+- `userContext` becomes `ctx._userContext` in prompts, models, tool authorization, and skill authorization.
+- A denial uses `{ authenticated: false, status: 401 | 403, message }`.
+- Unexpected operational failures should throw. They produce an `"error"` status and close code `1011` rather than being reported as bad user credentials.
 
-Override the static `getJwtAuthConfig(env)` to verify a JWT on connect (static so an `Assistant` can check before routing). Return `undefined` to skip.
+### JWT verification and token exchange
+
+`createJwtAuthenticator` supplies the normal bearer-JWT implementation. It reads the token from `Authorization: Bearer …` or `Sec-WebSocket-Protocol: bearer, <token>`, verifies it once, and optionally calls the consumer's `getExchangedToken` once.
 
 ```typescript
-export class SupportAgent extends Agent {
-  static getJwtAuthConfig(env: Cloudflare.Env) {
+import { ChatAgent, createJwtAuthenticator } from "@economic/agents";
+
+export class SupportAgent extends ChatAgent {
+  agentName = "customer-support";
+
+  protected getAuthenticator(env: Cloudflare.Env) {
+    return createJwtAuthenticator({
+      verificationConfig: {
+        allowedIssuers: [env.IDENTITY_ENDPOINT],
+        audience: "eva",
+        requiredScopes: ["eva.read"],
+        getClaims: (payload) => ({
+          userGuid: payload.user_guid as string,
+          agreementNumber: payload.agreement_number as number,
+        }),
+      },
+
+      async getExchangedToken({ token, claims }) {
+        // The consumer owns the exchange protocol and HTTP request.
+        return exchangeForBackendToken({
+          token,
+          userGuid: claims.userGuid,
+          env,
+        });
+      },
+
+      async getUserContext({ token, claims }) {
+        // `token` is now the value returned by getExchangedToken.
+        const profile = await fetchProfile(token);
+        return { ...profile, agreementNumber: claims.agreementNumber };
+      },
+    });
+  }
+}
+```
+
+The resulting flow is:
+
+```text
+bearer token → verify once → getExchangedToken once → authenticated result
+                                                    ├─ token / ctx._token
+                                                    └─ userContext
+```
+
+`verificationConfig` is consumed by the SDK's built-in JWT verification. `getExchangedToken` is entirely consumer-defined: it receives `{ token, claims }` and returns the exchanged token string. The SDK does not prescribe an identity provider, HTTP endpoint, grant type, or exchange protocol.
+
+The final token is exposed as `ToolContext._token`. Without `getExchangedToken`, it is the verified source JWT. Tools decide how that value maps to an HTTP header or another downstream transport; the authentication API contains no header names.
+
+Errors thrown by `getExchangedToken` are operational failures and close the socket with `1011`. A consumer can deliberately reject credentials by throwing an error with `closeCode: 4001` or `4003`.
+
+### Custom authentication
+
+Any authenticator can validate arbitrary credentials. This example validates an app-secret/agreement-grant pair:
+
+```typescript
+export class IntegrationAgent extends ChatAgent {
+  agentName = "accounting-integration";
+
+  protected getAuthenticator(env: Cloudflare.Env) {
     return {
-      allowedIssuers: [env.IDENTITY_ENDPOINT], // strings or RegExp
-      audience: "my-api",
-      requiredScopes: ["support.read"],
-      getClaims: (payload) => ({
-        userGuid: payload.user_guid as string,
-        agreementNumber: payload.agreement_number as number,
-      }),
+      async authenticate(request: Request) {
+        const appSecret = request.headers.get("X-AppSecretToken");
+        const agreementGrant = request.headers.get("X-AgreementGrantToken");
+
+        if (!appSecret || !agreementGrant) {
+          return {
+            authenticated: false as const,
+            status: 401 as const,
+            message: "Unauthorized",
+          };
+        }
+
+        const identity = await validateCredentials({ appSecret, agreementGrant }, env);
+
+        if (!identity) {
+          return {
+            authenticated: false as const,
+            status: 401 as const,
+            message: "Unauthorized",
+          };
+        }
+
+        return {
+          authenticated: true as const,
+          userContext: identity,
+        };
+      },
     };
   }
+}
+```
+
+The agent does not distinguish this from JWT authentication. Tool credentials supplied in the request context remain a consumer concern and pass through unchanged.
+
+A custom authenticator may omit `token`, as the example above does. In that case
+`ctx._token` is `undefined`; tools that require a downstream credential must check
+for it and fail safely. The built-in JWT authenticator always returns the verified
+source JWT, or the exchanged token when `getExchangedToken` is configured.
+
+### Tool context and credential lifetime
 
-  // ...
+After authentication succeeds, the result is stored in the server-side state attached to that WebSocket connection. Connection state survives Durable Object hibernation and is discarded when the connection closes. Authentication is not written to Durable Object KV, SQLite, or the agent's persisted `state`.
+
+Before every turn, the SDK builds the tool context as follows:
+
+```typescript
+toolContext._token = authentication.token; // string | undefined
+toolContext._userContext = authentication.userContext;
+```
+
+When present, `_token` is the normalized verified or exchanged token. It is `undefined` when a custom authenticator does not provide a downstream credential. Ordinary request-context fields, including any consumer-defined `tokens`, pass through unchanged. The completed context is used by `getModel`, `getSystemPrompt`, tool `authorize`, skill `authorize`, normal tool execution, and approved-tool continuations through `beforeTurn`, `beforeStep`, and `beforeToolCall`.
+
+`beforeTurn` does not authenticate, check expiry, or manage connections. It only reads the authenticated result and copies it into the tool context. JWT expiry is validated by `verifyJwt` when the connection is established. Updating `authToken` in the React hooks replaces the WebSocket, so the new token is verified and exchanged on the new connection.
+
+Authentication is scoped to the individual WebSocket connection. Turns use the state belonging to the connection that initiated them, including after the Durable Object hibernates and wakes again. Think's automatic chat recovery runs without a current connection, so the SDK restores authentication from the most recently authenticated live WebSocket for that recovery only. Other connectionless calls, including RPC calls, do not inherit WebSocket authentication and must provide and validate their own credentials.
+
+### TaskAgent authentication
+
+`TaskAgent` uses the same `getAuthenticator` contract, but authentication is request-scoped rather than connection-scoped. A custom `onRequest` transport calls `authenticateRequest(request)`, rejects a returned `Response`, and passes a successful result to `runTask`:
+
+```typescript
+override async onRequest(request: Request) {
+  const authentication = await this.authenticateRequest(request);
+  if (authentication instanceof Response) return authentication;
+
+  const { input, context } = await request.json();
+  return Response.json(await this.runTask(input, context, authentication));
 }
 ```
 
-On failure the socket closes (`4001` unauthorized, `4003` forbidden) and status becomes `"unauthorized"`. The token is read from `Authorization: Bearer …`, then the `Sec-WebSocket-Protocol: bearer, <token>` header.
+## Analytics
 
-### User context
+The SDK emits typed product facts from the lifecycle that produces them:
 
-Implement `getUserContext(jwtToken)` to load per-user data after auth. It's exposed as `ctx._userContext` in `getModel`, `getSystemPrompt`, tools, and skill `authorize`. Runs only when JWT auth is configured.
+- `prompt.received`
+- `turn.completed`
+- `llm.completed` (model, finish reason, and token usage from the model response)
+- `tool.completed` (tool, active skill, duration, success, and payload sizes)
+- `feedback.submitted`
+
+These events are inputs for analytics questions such as which tools or skills are used most. The SDK does not encode particular reports or business questions. Override `getAnalyticsAttributes()` to attach query dimensions that only the consumer knows, such as a tenant or user category:
 
 ```typescript
-protected async getUserContext(jwtToken: string) {
-  const profile = await fetchProfile(jwtToken);
-  return { role: profile.role, tokens: profile.tokens };
+protected getAnalyticsAttributes() {
+  return {
+    tenantId: this.userContext?.tenantId ?? "unknown",
+    userCategory: this.userContext?.category ?? "unknown",
+  };
 }
 ```
 
-If `getUserContext` throws, the socket closes with `1011` — or, when the thrown `Error` carries a numeric `closeCode` in the `4000`–`4999` range, with that code and an `"unauthorized"` status frame:
+Nothing is sent anywhere unless the consumer configures a handler. Multiple handlers can receive the same event, and a failing handler cannot fail or delay the agent turn:
 
 ```typescript
-const error = new Error("No Eva access");
-(error as Error & { closeCode: number }).closeCode = 4003;
-throw error;
+import {
+  createAnalyticsEngineHandler,
+  type AnalyticsHandler,
+} from "@economic/agents";
+
+protected getAnalyticsHandlers() {
+  const classificationHandler: AnalyticsHandler = {
+    name: "conversation classifier",
+    handle: (event) => {
+      if (event.type !== "prompt.received") return;
+
+      // Forward to an application-owned Queue or classifier agent. That service
+      // owns the semantic buckets and sends its result to Snowplow or Analytics Engine.
+      return this.env.CLASSIFICATION_QUEUE.send({
+        eventId: event.eventId,
+        messages: event.messages,
+        attributes: event.attributes,
+      });
+    },
+  };
+
+  return [
+    createAnalyticsEngineHandler(this.env.AGENTS_ANALYTICS),
+    classificationHandler,
+  ];
+}
 ```
 
-### Token exchange
+The built-in Analytics Engine handler stores metrics and dimensions, but never prompt content. A custom handler receives the typed event, including prompt content on `prompt.received`, so sending that content requires an explicit consumer decision. For reliable asynchronous processing, a handler should enqueue or forward the event to a Durable Object; handlers themselves are intentionally non-blocking.
 
-For agents whose clients connect with a _down-scoped_ token — one only valid for the client ↔ agent hop — override the static `getTokenExchangeConfig(env)` to exchange it (RFC 8693) at the identity server for a token issued to the agent's own OAuth client. Requires `getJwtAuthConfig`.
+The SDK emits these events from `beforeTurn`, `onStepFinish`, `afterToolCall`, and `onChatResponse`. Handlers run in the background under `keepAliveWhile`, so their work is protected from idle eviction without delaying the turn response. If an agent overrides one of those lifecycle hooks, it must call the corresponding `super` method to retain SDK analytics (the same rule already applies to the SDK's turn setup in `beforeTurn`).
 
-```typescript
-export class SupportAgent extends Agent {
-  static getTokenExchangeConfig(env: Cloudflare.Env) {
-    return {
-      tokenUrl: `${env.IDENTITY_ENDPOINT}/connect/token`,
-      clientId: env.OAUTH_CLIENT_ID,
-      clientSecret: env.OAUTH_CLIENT_SECRET, // string or Secrets Store binding
-      scopes: "api.read api.write", // always sent explicitly
-      tokenHeader: "X-EconomicToken", // default
-    };
+## Operational observability
+
+`ChatAgent` and `TaskAgent` preserve Cloudflare Agents' diagnostics-channel events and mirror failures and degraded conditions into structured Worker logs. Successful internal lifecycle events are not logged. The exception is a completed chat turn, whose duration and status are needed for latency distributions and error-rate denominators.
+
+The existing AI SDK telemetry stream also produces one operational record for each model call and executed tool:
+
+- `agent.llm.completed` / `agent.llm.failed`: provider, model, finish reason, duration, time to first chunk, and token usage.
+- `agent.tool.completed` / `agent.tool.failed`: tool name, duration, and error details when applicable.
+
+Prompts, responses, tool arguments, and tool results are deliberately excluded. The same underlying model and tool facts may also be sent through product-analytics handlers, but observability records contain no analytics attributes or prompt content and are intended for service-level metrics and alerts.
+
+Each record is a single JSON log with a stable source, event name, severity, agent identity, and the event-specific attributes. This lets a Workers Trace Events Logpush job create Datadog log-based counts, error rates, latency distributions, and alerts without a Datadog client in the agent:
+
+```json
+{
+  "source": "@economic/agents",
+  "event": "chat:turn:finish",
+  "level": "info",
+  "timestamp": 1787086800000,
+  "agentName": "customer-support",
+  "agentClass": "ChatHarness",
+  "durableObjectName": "user-123:support",
+  "attributes": {
+    "status": "completed",
+    "durationMs": 825
   }
 }
 ```
 
-When configured:
+The account-level Logpush destination is configured outside the SDK. Opt the deployed Worker into an existing job in `wrangler.jsonc`:
+
+```jsonc
+{
+  "logpush": true,
+}
+```
+
+Cloudflare runtime signals such as invocation outcome, CPU time, wall time, uncaught exceptions, and resource-limit failures are added by the platform rather than the SDK.
+
+## Audit logging
 
-- The verified connect token is exchanged on every connect; the exchanged token is what `getUserContext` receives and what tools see as `ctx.tokens[tokenHeader]` each turn. **Client-sent request-body tokens for that key are ignored** — tool credentials always derive from the verified connection identity, so clients should stop sending them.
-- Renewal is connection-based. The client token rides in the WebSocket protocols, so presenting a renewed token always means a reconnect, which re-verifies and re-exchanges. Keep the `authToken` passed to the hooks current (refresh it before expiry) and the socket rotates silently — the `unauthorized` close (`4001`) then only happens when the session is genuinely dead (logout, revocation).
-- The exchanged token expires on the identity server's clock (with a 30s margin). A turn arriving after expiry closes the connection `4001` to force a reconnect; a client that refreshes its token on time never hits this.
-- Exchange failures at connect: `invalid_grant` (dead session token) → status `"unauthorized"` + close `4001`; anything else (identity server down, misconfigured client) → status `"error"` + close `1011`. Partial configuration is the app's concern — throw from `getTokenExchangeConfig` if you consider it a deployment fault, or return `undefined` to disable the exchange.
+The SDK writes one versioned audit-log object per chat turn to `AGENTS_AUDIT_LOGS`. Each object contains the logical agent and harness identity, model, actor and IP, the rendered system prompt, the user message that initiated that turn, the final response, and the tool calls made during that turn. Turn content and tool activity carry their actual span timestamps.
 
-## Observability
+Tool inputs are retained so the attempted action can be established. Tool outputs are deliberately excluded because they may contain credentials, large API responses, or unrelated sensitive data. A tool failure retains its timestamp, error type, and message.
 
-Emitted per turn from the `ai` SDK's OpenTelemetry spans, no setup beyond bindings:
+Completed records are written directly to R2 inside the Agent SDK's `keepAliveWhile`, which prevents the Durable Object from being evicted while the write is pending. Tool-span collection is scoped to the individual turn tracer, so simultaneous agents cannot share pending tool calls.
+
+```json
+{
+  "schemaVersion": 2,
+  "id": "accounts-payable/user-123_chat-456/2026-08-18T20-14-30.000Z-ab12cd34.json",
+  "startedAt": "2026-08-18T20:14:25.000Z",
+  "completedAt": "2026-08-18T20:14:30.000Z",
+  "durableObjectName": "user-123:chat-456",
+  "agent": {
+    "name": "accounts-payable",
+    "class": "ChatHarness",
+    "llm": {
+      "model": "claude-sonnet-4-6",
+      "provider": "anthropic"
+    }
+  },
+  "actor": {
+    "id": "user-123",
+    "ip": {
+      "client": "192.0.2.1",
+      "forwardedFor": ["192.0.2.1"]
+    }
+  },
+  "systemPrompt": {
+    "timestamp": "2026-08-18T20:14:25.000Z",
+    "content": "You are the accounts payable assistant."
+  },
+  "prompt": {
+    "timestamp": "2026-08-18T20:14:25.000Z",
+    "content": "Email the first overdue invoice."
+  },
+  "response": {
+    "timestamp": "2026-08-18T20:14:30.000Z",
+    "content": "Email drafted.",
+    "finishReason": "stop"
+  },
+  "status": "success",
+  "tools": [
+    {
+      "id": "call-789",
+      "name": "create_email",
+      "input": { "invoiceId": "invoice-123" },
+      "status": "success",
+      "startedAt": "2026-08-18T20:14:27.000Z",
+      "completedAt": "2026-08-18T20:14:28.000Z"
+    }
+  ]
+}
+```
 
-- **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`.
+Operational observability is separate from both audit logging and product analytics. Cloudflare diagnostics, logs, traces, and any future Datadog export are not analytics handlers.
 
 ## API reference
 
@@ -568,36 +909,44 @@ Imported from `@economic/agents` unless noted.
 
 ### Classes
 
-| Export      | Description                                              |
-| ----------- | -------------------------------------------------------- |
-| `Agent`     | Core agent base. Implement `getModel`/`getSystemPrompt`. |
-| `ChatAgent` | `Agent` + compaction and message feedback.               |
-| `Assistant` | Per-user manager of `ChatAgent` chats.                   |
+| Export      | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| `ChatAgent` | Persistent Think agent with tools, skills, compaction, and feedback. |
+| `TaskAgent` | Bounded, at-most-once task without conversational state.             |
+| `Assistant` | Per-user manager of `ChatAgent` chats.                               |
 
 ### Helpers and types
 
-| Export                                                                   | Description                                                                     |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| `tool(def)` / `Tool` / `ToolSet`                                         | Define a tool with an optional `authorize(ctx)` guard.                          |
-| `skill(def)` / `Skill`                                                   | Define a skill (`name`, `description`, `instructions`, `tools?`, `authorize?`). |
-| `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                              |
-| `AgentEnv`                                                               | The bindings the runtime expects.                                               |
-| `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                        |
+| Export                                                     | Description                                                                     |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `tool(def)` / `Tool` / `ToolSet`                           | Define a tool with an optional `authorize(ctx)` guard.                          |
+| `skill(def)` / `Skill`                                     | Define a skill (`name`, `description`, `instructions`, `tools?`, `authorize?`). |
+| `ToolContext`                                              | Request context plus `_token` and `_userContext`.                               |
+| `TaskRunInput` / `TaskRunResult` / `TaskAuthentication`    | Task input, result states, and request-scoped authenticated values.             |
+| `createJwtAuthenticator(config)`                           | JWT verification with an optional consumer-defined token exchange.              |
+| `Authenticator` / `AuthenticationResult` / `Authenticated` | Generic authentication contract and normalized results.                         |
+| `AnalyticsHandler` / `AnalyticsEvent`                      | Typed, consumer-configured product-analytics pipeline.                          |
+| `createAnalyticsEngineHandler(dataset)`                    | Optional Cloudflare Analytics Engine destination; excludes prompt content.      |
+| `AgentEnv`                                                 | The bindings the runtime expects.                                               |
+| `AgentConnectionStatus` / `AgentConnectionType`            | Chat/assistant connection status and type shared with the client.               |
 
 ### 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 config.           |
-| `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                                      |
+| ------------------------------------------------------- | ---------------- | ------------------------------------------------ |
+| `agentName`                                             | All agents       | Required stable identity for shared deployments. |
+| `getModel(ctx?)`                                        | Chat/task agents | Required. Model for inference.                   |
+| `getSystemPrompt(ctx?)`                                 | Chat/task agents | Required. System prompt.                         |
+| `getTools()`                                            | Chat/task agents | Always-on tools (default `{}`).                  |
+| `getSkills()`                                           | Chat/task agents | Skills (default `[]`).                           |
+| `getAuthenticator(env)`                                 | All agents       | Optional generic authenticator.                  |
+| `runTask(input, context?, authentication?)`             | `TaskAgent`      | Executes the instance's at-most-once task.       |
+| `getOutputSchema()` / `validateOutput(value)`           | `TaskAgent`      | Optional structured-output contract.             |
+| `maxSteps` / `retentionDays`                            | `TaskAgent`      | Task loop and run-id retention limits.           |
+| `submitMessageFeedback` / `getMessageFeedback`          | `ChatAgent`      | Callable message feedback.                       |
+| `agent`                                                 | `Assistant`      | Required. Your `ChatAgent` subclass.             |
+| `fastModel`                                             | `Assistant`      | Required. Cheap model for titles/summaries.      |
+| `createChat` / `getChats` / `deleteChat` / `renameChat` | `Assistant`      | Callable chat management.                        |
 
 ### Package root (`@economic/agents`)