@economic/agents 2.9.1 → 2.10.0

package/README.md

@@ -4,8 +4,6 @@ Our agents SDK for building AI agents on Cloudflare Workers. Each agent is a Dur
 
 React client: [`@economic/agents-react`](../react/README.md).
 
-> The v1 (`@economic/agents/v1`) API (`ChatAgentHarness`, `buildLLMParams`) is deprecated and will be removed in v3.
-
 ## 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.
@@ -562,11 +560,15 @@ When configured:
 
 ## Observability
 
-Emitted per turn from the `ai` SDK's OpenTelemetry spans, no setup beyond bindings:
+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`.
 
+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.
+
+To send Worker logs through an existing Logpush job, enable `"logpush": true` in the Worker configuration; this does not create the Logpush job. Worker CPU, memory, and resource-limit metrics come from Cloudflare's platform telemetry rather than these SDK logs.
+
 ## API reference
 
 Imported from `@economic/agents` unless noted.

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { n as JwtAuthConfig, r as createJwtAuthConfig, t as routeAgentRequest } from "./route-agent-request-9vqbi1bt.mjs";
-import { Agent as Agent$1, Connection, ConnectionContext, SubAgentClass } from "agents";
+import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext, SubAgentClass } from "agents";
 import { ChatResponseResult, PrepareStepContext, Session, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext, skills } from "@cloudflare/think";
 import { JSONValue, LanguageModel, ModelMessage, Tool as Tool$1, UIMessage } from "ai";
+import { Observability } from "agents/observability";
 import { createCompactFunction } from "agents/experimental/memory/utils";
 import { SkillSource as SkillSource$1 } from "agents/skills";
 
@@ -22,9 +22,27 @@ interface AgentEnv {
   SKILLS_BUCKET: R2Bucket;
   LOCAL_AGENT_DB?: D1Database;
 }
-type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized" | "error";
+type AgentConnectionStatus = "connecting" | "reconnecting" | "connected" | "disconnected" | "unauthorized" | "error";
 type AgentConnectionType = "agent" | "chat" | "assistant";
 //#endregion
+//#region src/server/features/auth/index.d.ts
+interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string, unknown>> {
+  /** Issuers whose tokens are accepted (exact string or RegExp). */
+  allowedIssuers: readonly (string | RegExp)[];
+  /** Expected `aud` claim. */
+  audience: string;
+  /** Required OAuth scopes; token `scope` must include all (empty = no scope check). */
+  requiredScopes?: readonly string[];
+  /**
+   * Extract the claims you need from the verified JWT payload.
+   * These will be stored and made available in the agent's tool context.
+   */
+  getClaims: (payload: Record<string, unknown>) => TClaims;
+  /** Derive the actor ID represented by the verified claims. */
+  getActorId(claims: TClaims): string;
+}
+declare function createJwtAuthConfig<TClaims extends Record<string, unknown>>(config: JwtAuthConfig<TClaims>): JwtAuthConfig<TClaims>;
+//#endregion
 //#region src/server/features/auth/tokenExchange.d.ts
 interface TokenExchangeConfig {
   /** Identity server token endpoint, e.g. `${identityOrigin}/connect/token`. */
@@ -275,6 +293,7 @@ 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>;
+  observability?: Observability;
   /**
    * Resolves the analytics/telemetry agent name to the entry-point agent: the
    * top-level DO registered in the `agent` catalog table.
@@ -303,11 +322,11 @@ declare abstract class ChatAgent<RequestContext extends Record<string, unknown>
   onStart(): Promise<void>;
   configureSession(session: Session): Session;
   beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
-  onChatResponse(_result: ChatResponseResult): Promise<void>;
+  onChatResponse(result: ChatResponseResult): Promise<void>;
   /**
    * Submit feedback for a message by its id.
    * @param messageId - The id of the message to give feedback on.
-   * @param rating - The rating to give the message. 1 = thumbs up, -1 = thumbs down.
+   * @param rating - The rating to give the message. 1 = thumbs up, -1 = thumbs down, 0 = clear.
    * @returns The message id and the rating.
    */
   submitMessageFeedback(messageId: string, rating: number, comment?: string): Promise<void>;
@@ -364,6 +383,7 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
    * Best-effort and non-blocking.
    */
   private touchInstance;
+  observability?: Observability;
 }
 //#endregion
 //#region src/server/util/skills.d.ts
@@ -380,6 +400,9 @@ interface SkillSource<Context extends Record<string, unknown> = Record<string, u
 }
 declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
 //#endregion
+//#region src/server/route-agent-request.d.ts
+declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
+//#endregion
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion