@economic/agents 2.15.0 → 3.0.0-alpha.38232858664.1.0

package/README.md

@@ -223,10 +223,10 @@ What `ChatAgent` adds over `Agent`:
 - **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?)` | `rating` is `1` (up), `-1` (down) or `0` (clear). Upserts on the message. Only for the chat's assistant messages; comments up to 2,000 characters. |
+  | `getMessageFeedback()`                               | All feedback for the chat, keyed by message id.                                                                                                    |
 
   Surfaced by the client as `chat.submitMessageFeedback` / `chat.getMessageFeedback`.
 
@@ -270,14 +270,16 @@ The `Assistant` keeps the chat list in its own SQLite (a `chats` table, created
 
 ## Bindings
 
-Checked in `Agent.onStart` when a connection opens:
+`AGENTS_DB` is checked in `Agent.onStart` when a connection opens; the rest are needed only for what
+they're noted for:
 
-| 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_AUDIT_LOGS` | R2                           | With `AuditLogHandler`            | Where the [audit log](#observability) handler writes one log per turn. Any name; you pass it in.                                                                 |
+| `AGENTS_ANALYTICS`  | Analytics Engine             | With `AnalyticsHandler`           | Where the [analytics](#observability) handler writes per-turn and per-tool events. Any name; you pass it in.                                                     |
+| `SKILLS_BUCKET`     | R2                           | No                                | Source for [remote skills](#remote-skills).                                                                                                                      |
+| `LOADER`            | Worker Loader                | No                                | Enables [native skill scripts](#skill-scripts) when bound.                                                                                                       |
+| `AGENTS_USERS`      | Durable Object (`UserStore`) | With `toolCallLimits` or `memory` | Keeps each user's state across their chats: their tool call counts and their memory. Export `UserStore` from your worker and bind it as a SQLite Durable Object. |
 
 ## Tools
 
@@ -314,27 +316,24 @@ const export_report = tool({
 
 ### Tool context
 
-The tool context is the second argument to `execute` — `experimental_context`:
+The tool context is `context` in the second argument to `execute`, typed by the tool's first type parameter:
 
 ```typescript
 import { tool, type ToolContext } from "@economic/agents";
 import { z } from "zod";
 
-interface RequestBody {
-  tokens: Record<string, string>;
-}
-
-const call_api = tool({
+const call_api = tool<ToolContext>({
   description: "Call the API for the user",
   inputSchema: z.object({ path: z.string() }),
-  execute: async ({ path }, { experimental_context }) => {
-    const ctx = experimental_context as ToolContext<RequestBody>;
-    return fetchWithAuth(ctx.tokens, path);
+  execute: async ({ path }, { context }) => {
+    const token = await context._auth?.credential("api");
+
+    return fetchWithToken(token, path);
   },
 });
 ```
 
-`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>` is `RequestContext & { _userContext?: UserContext; _auth?: Auth }`. Request context comes from the client (`toolContext` in the hooks). `_userContext` and `_auth` come from the agent's [authenticator](#authentication): `_auth.credential(name)` gives a token for another service, such as an exchanged one.
 
 ## Actions
 
@@ -352,7 +351,7 @@ interface RequestContext extends Record<string, unknown> {
 
 const deleteInput = z.object({ invoiceId: z.string() });
 
-const deleteInvoice = action<ToolContext<RequestContext>, typeof deleteInput>({
+const deleteInvoice = action<ToolContext<RequestContext>, z.infer<typeof deleteInput>>({
   description: "Delete a draft invoice",
   inputSchema: deleteInput,
 
@@ -367,7 +366,7 @@ const deleteInvoice = action<ToolContext<RequestContext>, typeof deleteInput>({
     const response = await fetch(`/api/invoices/${input.invoiceId}`, {
       method: "DELETE",
       headers: {
-        Authorization: ctx.experimental_context.tokens.Authorization ?? "",
+        Authorization: ctx.context.tokens.Authorization ?? "",
         // Think uses this key for its ledger. Forward it when the downstream
         // API also supports idempotency.
         "Idempotency-Key": ctx.idempotencyKey,
@@ -391,7 +390,7 @@ export const invoiceSkill = skill({
 
 An action receives the same tool execution data plus Cloudflare's native action fields:
 
-- `experimental_context` — the typed `ToolContext` supplied to ordinary tools.
+- `context` — the typed `ToolContext` supplied to ordinary tools.
 - `toolCallId`, `messages`, and `abortSignal` — the ordinary tool execution fields.
 - `idempotencyKey` — the resolved domain key, or the tool-call fallback when none was declared.
 - `requestId`, `signal`, `agent`, `env`, and `attachReply` — native Think action fields.
@@ -451,9 +450,15 @@ Set `command` to make a code-defined skill directly invocable from chat. For exa
 first model step; the model still interprets `in Copenhagen` and chooses the appropriate
 tool. Commands use lower-case letters, numbers, and hyphens, without the leading `/`.
 
-`ChatAgent` also exposes an authenticated `GET getInvocableSkills` action for command
-pickers. It returns the commands available to the current user as
-`{ command, name, description }[]`. The existing skill `description` is used for both the
+`activation` sets when a skill is active. Every skill is still returned from `getSkills()`.
+
+- `"auto"` (the default): once the model starts it, when it's relevant, or the user runs its `command`.
+- `"always"`: on every turn, without being started. Its instructions are a block of the system prompt, named after the skill, after the agent's own prompt, and its tools are always available.
+- `"manual"`: only once the user runs its `command`. It's hidden from the model's catalog, and the model can't start it itself. It needs a `command`, which the type requires.
+
+`ChatAgent` also has a `getInvocableSkills()` callable for command pickers. It returns the
+commands available to the caller as `{ command, name, description }[]`; `useChat` from
+`@economic/agents-react` exposes it as `getInvocableSkills()`. The existing skill `description` is used for both the
 model catalog and the human-facing picker.
 
 ### Native Agent Skills
@@ -572,118 +577,115 @@ Source order matters: if two sources define the same skill name, the first sourc
 
 ## Authentication
 
-### JWT
-
-Override the static `getJwtAuthConfig(env)` to verify a JWT on connect (static so an `Assistant` can check before routing). Return `undefined` to skip.
+Define `static getAuthenticator(env)` on the agent class to check callers on every WebSocket connect and HTTP request. An `Assistant` checks callers for its chats with its chat agent's authenticator, so it's defined once. Without one, the agent is open.
 
 ```typescript
-export class SupportAgent extends Agent {
-  static getJwtAuthConfig(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,
-      }),
-      getActorId: (claims) => `${claims.agreementNumber}_${claims.userGuid}`,
-    };
-  }
+import { Agent, jwtAuthenticator, TokenExchange } from "@economic/agents";
+
+const tokenExchange = new TokenExchange({
+  tokenUrl: `${env.IDENTITY_ENDPOINT}/connect/token`,
+  clientId: env.OAUTH_CLIENT_ID,
+  clientSecret: env.OAUTH_CLIENT_SECRET, // a string, or a Secrets Store binding
+  scopes: ["api.read", "api.write"],
+  actor: { scopes: ["agent.read"] }, // optional: the agent's own token as the actor
+});
 
-  // ...
+const authenticator = jwtAuthenticator<UserContext>({
+  issuers: [env.IDENTITY_ENDPOINT], // strings or RegExp
+  audience: "my-api",
+  scopes: ["support.read"],
+  actorId: (claims) => `${claims.agreement_number}_${claims.user_guid}`,
+  credentials: {
+    api: ({ token }) => tokenExchange.exchange(token),
+  },
+  userContext: async (auth) => fetchProfile(await auth.credential("api")),
+});
+
+export class SupportAgent extends Agent<RequestContext, UserContext> {
+  static getAuthenticator() {
+    return authenticator;
+  }
 }
 ```
 
-`getActorId` derives the authenticated actor from verified claims. It must exactly match the
-actor that owns the requested Durable Object: the Assistant name, the root parent of a chat
-facet, or the prefix in a standalone `${actorId}:${chatId}` name. A valid token belonging to
-another actor is rejected with `4003` before the connection is established.
-
-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.
-
-### User context
+- **The token** is read from `Authorization: Bearer …`, then from the `Sec-WebSocket-Protocol: bearer, <token>` header. Its signature, issuer, audience, expiry and scopes are checked, with the issuer's keys found through its OpenID configuration. `allow(claims)` can refuse a verified token, such as for its tenant.
+- **The owner:** `actorId` turns the claims into the actor the token is for. It must match the actor that owns the requested Durable Object: the Assistant's name, the root parent of a chat facet, or the prefix in a standalone `${actorId}:${chatId}` name. Another actor's token is refused with `4003`.
+- **Credentials** are fetched by name the first time a tool or the user context asks for one, with `auth.credential(name)`, and stored until they expire.
+- **The user context** is loaded once per token, when the caller is authenticated, and stored. Tools see it as `_userContext`.
+- **Refusals:** the socket closes with `4001` (no token, or an expired or refused one) or `4003` (forbidden), with status `"unauthorized"`. Throw an `AuthenticationError` from a credential provider or `userContext` to refuse a caller the same way. Any other error closes it with `1011`.
+- **Expiry:** a turn still runs after the caller's token has expired, such as a scheduled one. Tools then get no `_auth` or `_userContext`.
+- **What's kept:** a WebSocket handshake keeps the caller's identity, user context and credentials in the agent until the token expires, so turns after hibernation or eviction, and scheduled turns, fetch nothing again. Other requests are only checked.
+- **Requests without the caller's token,** such as an OAuth callback or a signed webhook, are refused unless `acceptsWithoutToken(request)` returns `true` for them. Check them another way.
+- **Any authenticator works:** `getAuthenticator(env)` can return your own `Authenticator`, such as one for a different identity provider.
 
-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.
+## Memory
 
-```typescript
-protected async getUserContext(jwtToken: string) {
-  const profile = await fetchProfile(jwtToken);
-  return { role: profile.role, tokens: profile.tokens };
-}
-```
+Return `memory: true` from `getAgentConfig()` to give each user a private memory with the agent, kept across all their chats in their `UserStore` (`AGENTS_USERS`). It's a writable block of the system prompt, which the model updates itself with `set_context`.
 
-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:
+It only works once the user opts in. Until then there's no memory block, and the model can't write to it. `ChatAgent` has callables for the client: `getMemory()` returns `{ optedIn, content }`, `setMemory(content)` replaces it, `deleteMemory()` empties it, and `setMemoryOptIn(optedIn)` turns it on or off. Turning it off keeps what's saved.
 
-```typescript
-const error = new Error("No Eva access");
-(error as Error & { closeCode: number }).closeCode = 4003;
-throw error;
-```
+## Observability
 
-### Token exchange
+An agent's tracing events go to the handlers it returns from `getTracingHandlers()`. It has none
+by default. The SDK provides two, each taking the binding it writes to:
 
-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`.
+- **`AuditLogHandler`** → one JSON object per turn in an R2 bucket (model, actor, IP, prompt,
+  response, tool calls). Each is kept in the agent's storage until the bucket has it, and one that
+  couldn't be written is sent again with the next turn's.
+- **`AnalyticsHandler`** → typed per-turn and per-tool events in an Analytics Engine dataset, using
+  the existing schema.
 
 ```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
-    };
-  }
+import { AnalyticsHandler, AuditLogHandler } from "@economic/agents";
+
+override getTracingHandlers() {
+  return [
+    new AuditLogHandler(this.env.AGENTS_AUDIT_LOGS, this.ctx.storage),
+    new AnalyticsHandler(this.env.AGENTS_ANALYTICS),
+  ];
 }
 ```
 
-When configured:
+`getTracingHandlers()` is called once, when the agent starts, so a handler can keep state across a
+turn's events, as both of these do. A handler that throws, as these do without their binding, stops
+the agent starting. Leave one out where it doesn't apply, such as analytics for
+test traffic.
 
-- 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.
-
-## Observability
+Each handler's `handle` receives every `TracingEvent`, told apart by `type`:
 
-AI telemetry is emitted per turn from the `ai` SDK's OpenTelemetry spans:
+- `span`: each OpenTelemetry span as soon as it ends, a model call, a tool call or the turn.
+- `turn.started`: the model messages the turn starts with.
+- `turn.ended`: its status and the assistant message.
+- `skill.invoked`: a skill run by its command.
+- `turn`: the completed turn. Who it was for, the request's origin (`clientIp`, `forwardedFor`), its
+  request `context` (as tools see it) and `spans`, the `ai` SDK's spans under the turn's
+  `ai.streamText` span. A turn continuing an earlier one, e.g. after a tool approval, sits under
+  that turn in the same trace.
+- `feedback`: a user's rating of an assistant message. `messageId`, `rating`, `comment` and
+  `spans`, the rating as a `gen_ai.evaluation.*` span under the turn that first answered the
+  message (none when the rating was removed).
 
-- **Audit logs** → one JSON object per turn in `AGENTS_AUDIT_LOGS` (model, actor, IP, prompt, response, tool calls).
-- **Analytics** → typed per-turn and per-tool events, written to `AGENTS_ANALYTICS` using the
-  existing Analytics Engine schema.
-- **Tracing** → completed turns and message feedback, handed to the handlers you return from
-  `getTracingHandlers()`.
-
-Override `getTracingHandlers()` to send turns and message feedback to a tracing or analytics
-service. Each handler's `handle` receives a `TracingEvent`, a `turn` or a `feedback` event told
-apart by `type`. Both carry their OpenTelemetry `spans`, so a handler that only forwards spans
-doesn't need to check:
+A handler ignores the types it doesn't need. One that forwards whole traces to a tracing service
+only needs `turn` and `feedback`:
 
 ```typescript
 import type { TracingHandler } from "@economic/agents";
 
 const tracing: TracingHandler = {
   name: "tracing-service",
-  handle: (event) => sendToTracingService(event.spans),
+  handle: (event) => {
+    if (event.type === "turn" || event.type === "feedback") {
+      return sendToTracingService(event.spans);
+    }
+  },
 };
-
-getTracingHandlers() {
-  return [tracing];
-}
 ```
 
-A `turn` event comes when a turn ends: who it was for, its request `context` (as tools see it) and
-`spans`, the `ai` SDK's OpenTelemetry spans under the turn's `ai.streamText` span. A turn
-continuing an earlier one, e.g. after a tool approval, sits under that turn in the same trace. A
-`feedback` event comes when a user rates an assistant message: `messageId`, `rating`, `comment` and
-`spans`, the rating as a `gen_ai.evaluation.*` span under the turn that first answered the message
-(none when the rating was removed).
 Hand the spans to any OpenTelemetry exporter or span processor as they are; `examples/assistant`
 has a complete handler.
 
-Spans and `context` can hold prompts, tool results and credentials, so pick what you send. Handlers
+Spans, `context`, the turn's messages and the request's origin can hold prompts, tool results,
+credentials and IP addresses, so pick what you send. Handlers
 run in the background; a failure is logged as `agent.tracing.handler.failed` and never affects the
 chat.
 
@@ -697,11 +699,13 @@ Imported from `@economic/agents` unless noted.
 
 ### Classes
 
-| Export      | Description                                              |
-| ----------- | -------------------------------------------------------- |
-| `Agent`     | Core agent base. Implement `getModel`/`getSystemPrompt`. |
-| `ChatAgent` | `Agent` + model-only compaction and message feedback.    |
-| `Assistant` | Per-user manager of `ChatAgent` chats.                   |
+| Export             | Description                                                   |
+| ------------------ | ------------------------------------------------------------- |
+| `Agent`            | Core agent base. Implement `getModel`/`getSystemPrompt`.      |
+| `ChatAgent`        | `Agent` + model-only compaction and message feedback.         |
+| `Assistant`        | Per-user manager of `ChatAgent` chats.                        |
+| `AuditLogHandler`  | Tracing handler writing one audit log per turn to R2.         |
+| `AnalyticsHandler` | Tracing handler writing analytics events to Analytics Engine. |
 
 ### Helpers and types
 
@@ -718,20 +722,20 @@ Imported from `@economic/agents` unless noted.
 
 ### 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 `[]`).                                           |
-| `getTracingHandlers()`                         | `Agent`     | Destinations for completed turns and message feedback (default: `[]`). |
-| `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.                                              |
+| 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 `[]`).                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `configureContext()`                           | `Agent`     | Think's system prompt blocks. An override must include `...(await super.configureContext())`, or the agent's own prompt and rules are lost.                                                                                                                                                                                                                                                                                             |
+| `getTracingHandlers()`                         | `Agent`     | Destinations for completed turns and message feedback (default: `[]`).                                                                                                                                                                                                                                                                                                                                                                  |
+| `static getAuthenticator(env)`                 | `Agent`     | Optional caller authentication, credentials and user context.                                                                                                                                                                                                                                                                                                                                                                           |
+| `submitMessageFeedback` / `getMessageFeedback` | `ChatAgent` | Callable message feedback.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `getAgentConfig(ctx?)`                         | `Agent`     | Settings for a turn (default `{}`): `maxSteps`, `temperature`, `maxOutputTokens`, `topP`, `toolChoice`, `maxRetries`, `timeout`, `sendReasoning`, `providerOptions`; `toolCallLimits`, how often each user may call each tool by name, per day (`dailyCalls`) and per minute (`burst`), which needs `AGENTS_USERS`; for a chat, `memory`, a private memory per user, and `deleteMessagesAfterMs`, after which its messages are deleted. |
+| `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`)