@economic/agents 2.11.3 → 2.13.0

package/README.md

@@ -443,7 +443,7 @@ Use this skill whenever the user asks about current conditions or a forecast.
 });
 ```
 
-Return skills from `getSkills()`. Add `authorize(ctx)` to gate a skill (and its tools). `skill()` throws if `description` or `instructions` is missing.
+Return skills from `getSkills()`. Add `authorize(ctx)` to gate a skill (and its tools). Denied skills are hidden from the catalog and `activate_skill` by default. Set `onUnauthorized` to a reason string, or a function that returns one, to expose a denied skill with user-facing guidance. A function can return `undefined` to keep it hidden. `skill()` throws if `description` or `instructions` is missing.
 
 ### Native Agent Skills
 
@@ -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.
 
@@ -660,29 +683,34 @@ Imported from `@economic/agents` unless noted.
 
 ### Helpers and types
 
-| Export                                                                   | Description                                                                |
-| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `tool(def)` / `Tool` / `ToolSet`                                         | Define a tool with optional `approval`, `authorize`, and `onUnauthorized`. |
-| `action(def)` / `Action` / `RegisteredAction` / `ActionContext`          | Define a ledger-backed action with approval and idempotency support.       |
-| `skill(def)` / `Skill`                                                   | Define a skill with optional `tools`, `actions`, and authorization.        |
-| `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 optional `approval`, `authorize`, and `onUnauthorized`.          |
+| `action(def)` / `Action` / `RegisteredAction` / `ActionContext`          | Define a ledger-backed action with approval and idempotency support.                |
+| `skill(def)` / `Skill`                                                   | Define a skill with optional `tools`, `actions`, `authorize`, and `onUnauthorized`. |
+| `UnauthorizedPolicy`                                                     | Shared reason or context-dependent reason for denied tools, actions, and skills.    |
+| `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

@@ -24,6 +24,11 @@ interface AgentEnv {
 }
 type AgentConnectionStatus = "connecting" | "reconnecting" | "connected" | "disconnected" | "unauthorized" | "error";
 type AgentConnectionType = "agent" | "chat" | "assistant";
+/**
+ * Guidance for an unauthorized capability. A string exposes the capability
+ * with that guidance; `undefined` from a function keeps it hidden.
+ */
+type UnauthorizedPolicy<Context extends Record<string, unknown> = Record<string, unknown>> = string | ((ctx?: Context) => string | undefined);
 //#endregion
 //#region src/server/features/auth/index.d.ts
 interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string, unknown>> {
@@ -100,22 +105,111 @@ declare function exchangeToken(subjectToken: string, config: TokenExchangeConfig
 //#endregion
 //#region src/server/util/tools.d.ts
 type ToolSet = Record<string, Tool>;
-interface UnauthorizedToolPolicy<Context extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Keep the tool visible to the model when {@link Tool.authorize} returns
-   * `false`. A function can decide from the same context passed to `authorize`.
-   */
-  expose: boolean | ((ctx?: Context) => boolean);
-  /** Explanation shown to the model for this unavailable tool. */
-  reason: string | ((ctx?: Context) => string);
-}
+/** @deprecated Use {@link UnauthorizedPolicy}. */
+type UnauthorizedToolPolicy<Context extends Record<string, unknown> = Record<string, unknown>> = UnauthorizedPolicy<Context>;
 type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool$1<INPUT, OUTPUT> & {
   /** SDK-consistent alias for the AI SDK's `needsApproval` option. */approval?: Tool$1<INPUT, OUTPUT>["needsApproval"];
   authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedToolPolicy<Context>;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
 };
 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 {
@@ -193,14 +287,14 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
   }): Promise<TurnSnapshot>;
   workspaceBash: boolean;
   getSkillScriptRunner(): skills.SkillScriptRunner | null;
-  /**
-   * Returns the remote skills to be loaded from SKILLS_BUCKET.
-   * @returns The remote skills to be loaded from SKILLS_BUCKET.
-   */
-  protected getRemoteSkills(): string[];
   protected pruneTurnMessages(messages: ModelMessage[]): ModelMessage[];
-  private _getTurnSystemPrompt;
   private _prepareTools;
+  private _renderSkillsSystemBlock;
+  private _filterSkillHelperTools;
+  private _filterActivateSkillTool;
+  private _skillSources?;
+  private _getUnauthorizedReason;
+  private _getSkillSources;
   /**
    * Wrap each tool's `execute` so it falls back to the current turn's tool
    * context (request body + `_userContext`)
@@ -307,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
@@ -423,12 +525,12 @@ type Action<Context extends Record<string, unknown> = Record<string, unknown>, I
   idempotencyKey?: ActionIdempotencyKey<Input>;
   permissions?: ActionPermissionSpec<Input>;
   authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedToolPolicy<Context>;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
   execute(input: Input, ctx: ActionContext<Context>): Promise<Output> | Output;
 };
 type RegisteredAction<Context extends Record<string, unknown> = Record<string, unknown>, InputSchema extends FlexibleSchema = FlexibleSchema, Output = unknown> = Action$1<InputSchema, Output> & {
   authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedToolPolicy<Context>;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
 };
 /** A native Think action with the SDK's standard authorization policy. */
 declare function action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any>(definition: Action<Context, Input, Output>): RegisteredAction<Context, FlexibleSchema<Input>, Output>;
@@ -441,11 +543,13 @@ interface Skill<Context extends Record<string, unknown> = Record<string, unknown
   tools?: Record<string, Tool<Context>>;
   actions?: Record<string, RegisteredAction<Context, any, any>>;
   authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
 }
 interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
   tools?: Record<string, Tool<Context>>;
   actions?: Record<string, RegisteredAction<Context, any, any>>;
   authorize?: (ctx?: Context | undefined) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
 }
 declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
 //#endregion
@@ -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 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 };