@economic/agents 3.0.0-alpha.39514403335.1.0 → 3.0.1

package/README.md

@@ -89,6 +89,21 @@ the entry-point agent class as `agentId` in `cf-aig-metadata`. This includes
 requests made by child chat/facet agents and allows a shared gateway's usage to
 be grouped by agent without application configuration or duplicated analytics.
 
+### Model and turn settings
+
+The providers return models without per-model defaults, and the SDK sets none. The agent sets what its models need, such as a lower `effort` for Sonnet 5, from `getAgentConfig()`:
+
+```typescript
+getAgentConfig() {
+  return {
+    providerOptions: { anthropic: { effort: "low" } },
+    timeout: { stepMs: 60_000 },
+  };
+}
+```
+
+Think's own timeouts are properties of the agent, such as `chatStreamStallTimeoutMs`, which aborts a model stream that stops sending; an action's is its `timeoutMs`.
+
 ## Quick start: an 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:
@@ -230,6 +245,30 @@ What `ChatAgent` adds over `Agent`:
 
   Surfaced by the client as `chat.submitMessageFeedback` / `chat.getMessageFeedback`.
 
+### Context blocks
+
+To give the model facts about the user, such as their company, add each fact as its own block of the system prompt with `configureContext()`. A block is read on every turn:
+
+```typescript
+override async configureContext() {
+  return [
+    ...(await super.configureContext()),
+    {
+      label: "company",
+      provider: {
+        get: async () => {
+          const agreement = this.identity.userContext()?.currentAgreement;
+
+          return agreement ? `Name: ${agreement.name}\nCVR: ${agreement.cvr}` : "";
+        },
+      },
+    },
+  ];
+}
+```
+
+Read the user context with `this.identity.userContext()`, and request values, such as the page the user is on, with `this.getToolContextForCurrentTurn()`.
+
 ## Many chats per user: Assistant
 
 When one user needs a list of chats — a sidebar, titles, summaries — add an `Assistant`. It owns the chat list and routes to a `ChatAgent` per chat.
@@ -364,6 +403,23 @@ const send_invoice = tool<ToolContext>({
 
 `step.runAgent(name, Agent, input, { inheritAuth })` runs another agent and returns its answer; see [migration](./MIGRATION.md#agents-you-run-can-act-as-your-caller) for `inheritAuth`.
 
+### MCP tools
+
+Think adds every connected MCP server's tools to every turn, with no `authorize` and no skill. To gate them, turn that off and add them from `getTools()` yourself:
+
+```typescript
+override includeMcpTools = false;
+
+getTools(): ToolSet {
+  return Object.fromEntries(
+    Object.entries(this.mcp.getAITools()).map(([name, mcpTool]) => [
+      name,
+      { ...mcpTool, authorize: (ctx) => ctx?._userContext?.canUseConnectors === true },
+    ]),
+  );
+}
+```
+
 ## Actions
 
 Use `action()` instead of `tool()` for operations with side effects. Actions use Cloudflare Think's durable action ledger for idempotent execution, settled-result replay, pending-action handling, recovery, timeouts, cancellation, and structured errors.
@@ -593,7 +649,7 @@ const tokenExchange = new TokenExchange({
 });
 
 const authenticator = jwtAuthenticator<UserContext>({
-  issuers: [env.IDENTITY_ENDPOINT], // strings or RegExp
+  issuers: [env.IDENTITY_ENDPOINT], // strings, or RegExps that must match the whole issuer
   audience: "my-api",
   scopes: ["support.read"],
   actorId: (claims) => `${claims.agreement_number}_${claims.user_guid}`,
@@ -695,6 +751,10 @@ Separately, the SDK writes structured operational logs for completed/failed LLM
 
 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.
 
+## Testing
+
+Test agents against the real runtime with [`@cloudflare/vitest-plugin`](https://developers.cloudflare.com/workers/testing/vitest-integration/), as the SDK's own tests do, rather than mocking the SDK, Think or `agents`: a mock drifts from the runtime it stands in for. Evals use [`@economic/evals`](../evals/README.md).
+
 ## API reference
 
 Imported from `@economic/agents` unless noted.

package/dist/index.d.mts

@@ -9,7 +9,6 @@ import { z } from "zod";
 import { DurableObject } from "cloudflare:workers";
 import { ContextConfig } from "agents/context";
 import { SkillSource as SkillSource$1 } from "agents/skills";
-//#region src/server/features/auth/errors.d.ts
 /** A request or connection refused because of who made it. */
 export declare class AuthenticationError extends Error {
   readonly status: 401 | 403;
@@ -21,8 +20,6 @@ export declare class AuthenticationError extends Error {
     reason?: string;
   });
 }
-//#endregion
-//#region src/server/features/auth/types.d.ts
 type Claims = JWTPayload;
 /** Who sent a request, as an authenticator checked them. */
 interface Identity {
@@ -91,8 +88,6 @@ interface Caller<UserContext> {
   auth: Auth;
   userContext: UserContext | undefined;
 }
-//#endregion
-//#region src/server/features/auth/identityStore.d.ts
 interface IdentityStoreOptions<UserContext> {
   /** Whose agent this is. Only an identity with this `actorId` is kept. */
   owner: () => string | undefined;
@@ -147,8 +142,6 @@ interface InheritedCaller<UserContext = unknown> {
   identity: Identity;
   userContext: UserContext | undefined;
 }
-//#endregion
-//#region src/server/features/auth/jwt.d.ts
 interface JwtOptions {
   /** Trusted issuers, matched exactly or by pattern. */
   issuers: readonly (string | RegExp)[];
@@ -183,8 +176,6 @@ export declare function bearerToken(request: Request): string | undefined;
  * without an expiry is refused.
  */
 export declare function verifyJwt(token: string, options: JwtOptions): Promise<JWTPayload>;
-//#endregion
-//#region src/server/features/auth/tokenExchange.d.ts
 type Stage = "client_credentials" | "token_exchange";
 interface TokenExchangeOptions {
   tokenUrl: string;
@@ -236,8 +227,6 @@ export declare class TokenExchange {
   private _exchange;
   private _request;
 }
-//#endregion
-//#region src/server/features/users/store.d.ts
 /** How often a user may call a tool: per UTC day, and per minute for bursts. Either can be left out. */
 interface ToolCallLimit {
   dailyCalls?: number;
@@ -259,8 +248,6 @@ export declare class UserStore extends DurableObject {
   /** Deletes everything kept for the user. The call ends with an error, as the object is shut down. */
   destroy(): Promise<void>;
 }
-//#endregion
-//#region src/server/types.d.ts
 /**
  * The context object available throughout an agent's lifetime — passed via
  * `context` to tool `execute` functions. Contains the typed
@@ -303,8 +290,6 @@ type AgentConnectionType = "agent" | "chat" | "assistant";
  * 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/tasks/runAgent.d.ts
 type AgentClass = DynamicAgentClass<Agent>;
 interface RunAgentOptions {
   /**
@@ -314,8 +299,6 @@ interface RunAgentOptions {
    */
   inheritAuth?: boolean;
 }
-//#endregion
-//#region src/server/features/tasks/step.d.ts
 interface ApprovalRequest {
   summary: string;
   risk?: "low" | "medium" | "high";
@@ -338,8 +321,6 @@ interface BranchStep extends ToolStep {
   /** Aborts the signal of the branch's running steps and refuses any more. */
   cancel(reason?: string): void;
 }
-//#endregion
-//#region src/server/util/tools.d.ts
 type ToolSet = Record<string, Tool>;
 /** What a durable tool's `executeTask` gets: its call ID, its context, and `step` for durable steps and approvals. */
 interface ExecuteTaskOptions<Context extends Record<string, unknown> = Record<string, unknown>> {
@@ -360,8 +341,61 @@ type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INP
   executeTask?: ExecuteTask<Context, INPUT, NoInfer<OUTPUT> & TaskValue>;
 };
 export 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<Context, INPUT, OUTPUT>;
-//#endregion
-//#region src/server/features/telemetry/exchange.d.ts
+/** Tool execution options plus the additional context supplied by native Think actions. */
+type ActionContext<Context extends Record<string, unknown> = Record<string, unknown>> = ToolExecutionOptions<Context> & ActionContext$1 & {
+  /** The action's resolved domain key, or its tool-call fallback when none was declared. */
+  idempotencyKey: string;
+};
+type Action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any> = Omit<ActionConfig<FlexibleSchema<Input>, Output>, "approval" | "execute" | "idempotencyKey" | "inputSchema" | "permissions"> & {
+  description: string;
+  inputSchema: FlexibleSchema<Input>;
+  approval?: ActionApprovalPolicy<Input>;
+  idempotencyKey?: ActionIdempotencyKey<Input>;
+  permissions?: ActionPermissionSpec<Input>;
+  authorize?: (ctx?: Context) => boolean;
+  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?: UnauthorizedPolicy<Context>;
+};
+/** A native Think action with the SDK's standard authorization policy. */
+export 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>;
+interface SkillDefinition<Context extends Record<string, unknown>> {
+  name: string;
+  description: string;
+  instructions: string;
+  tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, RegisteredAction<Context, any, any>>;
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+}
+/**
+ * When the skill is active:
+ * - `"auto"`: once the model starts it, when it's relevant. The default.
+ * - `"always"`: on every turn, without being started.
+ * - `"manual"`: once the user starts it with its `command`. It's hidden from
+ *   the model, which can't start it itself.
+ */
+type SkillActivation = "auto" | "always" | "manual";
+type Skill<Context extends Record<string, unknown> = Record<string, unknown>> = SkillDefinition<Context> & ({
+  activation?: "auto" | "always";
+  /** Lets the user start the skill from chat with `/command`. */
+  command?: string;
+} | {
+  activation: "manual";
+  command: string;
+});
+interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
+  command?: string;
+  activation?: SkillActivation;
+  tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, RegisteredAction<Context, any, any>>;
+  authorize?: (ctx?: Context | undefined) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+}
+export declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
 interface SpanIds {
   traceId: string;
   spanId: string;
@@ -376,8 +410,6 @@ interface TurnExchange extends SpanIds {
   /** An earlier turn already answered the user message, e.g. before a tool approval. */
   continues: boolean;
 }
-//#endregion
-//#region src/server/features/telemetry/utils.d.ts
 /** The agent, chat and actor a turn belongs to. */
 interface AgentIdentity {
   agentName: string;
@@ -390,8 +422,6 @@ interface RequestOrigin {
   clientIp?: string;
   forwardedFor?: string;
 }
-//#endregion
-//#region src/server/features/telemetry/tracing.d.ts
 /** A completed turn and the OpenTelemetry spans the `ai` SDK recorded for it. */
 interface TracedTurn extends AgentIdentity, RequestOrigin {
   type: "turn";
@@ -485,11 +515,10 @@ declare class Tracing {
    */
   private _keepAliveUntil;
 }
-//#endregion
-//#region src/server/agents/Agent.d.ts
 type MessagePart = UIMessage["parts"][number];
 interface TurnInspection<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>> {
   messages?: ModelMessage[];
+  continuation?: boolean;
   requestContext?: RequestContext;
   userContext?: UserContext;
 }
@@ -506,6 +535,8 @@ type CurrentTurnState<RequestContext extends Record<string, unknown>, UserContex
   context?: ToolContext<RequestContext, UserContext>;
   inputTools: ToolSet;
   preparedTools: ToolSet;
+  activeSkillNames: Set<string>;
+  skillSourcesByName?: Promise<Map<string, SkillSource>>;
   unavailableSkillIds: Set<string>;
   skillsSystemBlock: string;
   visibleSkillNames: string[];
@@ -682,7 +713,7 @@ export declare abstract class Agent<RequestContext extends Record<string, unknow
   workspaceTools: boolean;
   sendReasoning: boolean;
   getSkillScriptRunner(): skills.SkillScriptRunner | null;
-  protected pruneTurnMessages(messages: ModelMessage[]): ModelMessage[];
+  protected pruneTurnMessages(messages: ModelMessage[], continuation?: boolean): ModelMessage[];
   private _prepareTools;
   private _renderSkillsSystemBlock;
   /**
@@ -693,7 +724,6 @@ export declare abstract class Agent<RequestContext extends Record<string, unknow
   private _filterSkillHelperTools;
   private _filterActivateSkillTool;
   private _skillSources?;
-  private _skillSourcesByName?;
   private _getUnauthorizedReason;
   private _getSkillSources;
   /** Each skill's source, by the skill's name. A source can hold several skills. */
@@ -730,12 +760,10 @@ export declare abstract class Agent<RequestContext extends Record<string, unknow
   private _withTurnContextFallback;
   /** The current turn's tool context, for every tool prepared for the turn. */
   private _toolsContext;
-  /**
-   * The skill the last `activate_skill` call started. A manual skill counts
-   * only when its command started it, not a call the model made itself.
-   */
-  private _activeSkillName;
-  private _getLastActivatedSkillName;
+  private _skillTurnStart;
+  private _activeSkillNamesForTurn;
+  private _activatedSkillNames;
+  private _getActivatedSkillNames;
   /**
    * The caller's identity, user context and credentials, kept until the
    * token expires so turns after hibernation, and scheduled turns, can still
@@ -816,8 +844,6 @@ export declare abstract class Agent<RequestContext extends Record<string, unknow
   /** The owner authentication checks, when the agent has an authenticator. */
   protected getTelemetryActorId(): string;
 }
-//#endregion
-//#region src/server/features/messages.d.ts
 type MessageFeedback = {
   message_id: string;
   rating: number;
@@ -825,67 +851,6 @@ type MessageFeedback = {
   created_at: number;
   updated_at: number;
 };
-//#endregion
-//#region src/server/util/actions.d.ts
-/** Tool execution options plus the additional context supplied by native Think actions. */
-type ActionContext<Context extends Record<string, unknown> = Record<string, unknown>> = ToolExecutionOptions<Context> & ActionContext$1 & {
-  /** The action's resolved domain key, or its tool-call fallback when none was declared. */
-  idempotencyKey: string;
-};
-type Action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any> = Omit<ActionConfig<FlexibleSchema<Input>, Output>, "approval" | "execute" | "idempotencyKey" | "inputSchema" | "permissions"> & {
-  description: string;
-  inputSchema: FlexibleSchema<Input>;
-  approval?: ActionApprovalPolicy<Input>;
-  idempotencyKey?: ActionIdempotencyKey<Input>;
-  permissions?: ActionPermissionSpec<Input>;
-  authorize?: (ctx?: Context) => boolean;
-  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?: UnauthorizedPolicy<Context>;
-};
-/** A native Think action with the SDK's standard authorization policy. */
-export 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>;
-//#endregion
-//#region src/server/util/skills.d.ts
-interface SkillDefinition<Context extends Record<string, unknown>> {
-  name: string;
-  description: string;
-  instructions: string;
-  tools?: Record<string, Tool<Context>>;
-  actions?: Record<string, RegisteredAction<Context, any, any>>;
-  authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-}
-/**
- * When the skill is active:
- * - `"auto"`: once the model starts it, when it's relevant. The default.
- * - `"always"`: on every turn, without being started.
- * - `"manual"`: once the user starts it with its `command`. It's hidden from
- *   the model, which can't start it itself.
- */
-type SkillActivation = "auto" | "always" | "manual";
-type Skill<Context extends Record<string, unknown> = Record<string, unknown>> = SkillDefinition<Context> & ({
-  activation?: "auto" | "always";
-  /** Lets the user start the skill from chat with `/command`. */
-  command?: string;
-} | {
-  activation: "manual";
-  command: string;
-});
-interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
-  command?: string;
-  activation?: SkillActivation;
-  tools?: Record<string, Tool<Context>>;
-  actions?: Record<string, RegisteredAction<Context, any, any>>;
-  authorize?: (ctx?: Context | undefined) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-}
-export declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
-//#endregion
-//#region src/server/util/skillCommands.d.ts
 interface InvocableSkill {
   /** Slash command without the leading `/`. */
   command: string;
@@ -894,8 +859,6 @@ interface InvocableSkill {
   /** Human- and model-readable summary from the skill definition. */
   description: string;
 }
-//#endregion
-//#region src/server/agents/ChatAgent.d.ts
 declare const DELETE_MESSAGES_CALLBACK = "deleteMessagesCallback";
 /** How a `run` ended: with its answer, waiting for an approval, or without one. */
 type RunResult = {
@@ -962,8 +925,6 @@ export declare abstract class ChatAgent<RequestContext extends Record<string, un
   private _scheduleMessageDeletion;
   private [DELETE_MESSAGES_CALLBACK];
 }
-//#endregion
-//#region src/server/features/chats.d.ts
 type Chat = {
   durable_object_name: string;
   title?: string;
@@ -979,8 +940,6 @@ interface ChatSummaryInput {
   recentMessages: UIMessage[];
 }
 declare const DELETE_CHAT_CALLBACK: "deleteChatCallback";
-//#endregion
-//#region src/server/agents/Assistant.d.ts
 export declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env & AgentEnv, State> {
   private _fix;
   protected abstract fastModel: LanguageModel;
@@ -1035,8 +994,6 @@ export declare abstract class Assistant<State = unknown> extends Agent$1<Cloudfl
   private deleteChatFromGlobalList;
   observability?: Observability;
 }
-//#endregion
-//#region src/server/features/turn-schemas.d.ts
 /**
  * A file input, sent inline as a data URL, of one of `mediaTypes`. A type
  * such as "image/*" takes any image.
@@ -1047,11 +1004,7 @@ export declare function file(mediaTypes: readonly string[]): z.ZodObject<{
   url: z.ZodString;
   filename: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-//#endregion
-//#region src/server/route-agent-request.d.ts
 export declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
-//#endregion
-//#region src/server/features/telemetry/audit-log/handler.d.ts
 /**
  * Writes one audit log per turn to `bucket`. Each is kept in the agent's
  * `storage` until the bucket has it, and an undelivered one is sent again with
@@ -1070,8 +1023,6 @@ export declare class AuditLogHandler implements TracingHandler {
   /** The turn's last model call, and its tool calls with the skill each ran in. */
   private _modelAndToolCalls;
 }
-//#endregion
-//#region src/server/features/telemetry/analytics/handler.d.ts
 /** Writes per-turn and per-tool analytics events to an Analytics Engine `dataset`. */
 export declare class AnalyticsHandler implements TracingHandler {
   readonly name = "analytics";
@@ -1081,5 +1032,4 @@ export declare class AnalyticsHandler implements TracingHandler {
   handle(event: TracingEvent): Promise<void>;
   private _events;
 }
-//#endregion
 export { type Action, type ActionContext, type AgentConfig, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type Auth, type Authenticator, type Claims, type Credential, type CredentialProvider, type Identity, type InvocableSkill, type JwtAuthenticatorOptions, type JwtOptions, type RegisteredAction, type RunResult, type Skill, type SkillActivation, type SkillInvoked, type SkillSource, type TokenExchangeOptions, type Tool, type ToolContext, type ToolSet, type TracedFeedback, type TracedSpan, type TracedTurn, type TracingEvent, type TracingHandler, type TurnEnded, type TurnInspection, type TurnSnapshot, type TurnStarted, type UnauthorizedPolicy, getCurrentAgent };