agents 0.31.0 → 0.32.0

package/dist/workflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.js","names":[],"sources":["../src/workflows.ts"],"sourcesContent":["/**\n * AgentWorkflow - Base class for Workflows that integrate with Agents\n *\n * Extends Cloudflare's WorkflowEntrypoint to provide seamless access to\n * the Agent that started the workflow, enabling bidirectional communication.\n *\n * @example\n * ```typescript\n * import { AgentWorkflow } from 'agents/workflows';\n * import type { MyAgent } from './agent';\n *\n * type TaskParams = { taskId: string; data: string };\n *\n * export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {\n *   async run(event: AgentWorkflowEvent<TaskParams>, step: WorkflowStep) {\n *     // Access the originating Agent via typed RPC\n *     await this.agent.updateTaskStatus(event.payload.taskId, 'processing');\n *\n *     const result = await step.do('process', async () => {\n *       // ... processing logic\n *       return { processed: true };\n *     });\n *\n *     // Report progress to Agent (typed)\n *     await this.reportProgress({ step: 'process', status: 'complete', percent: 0.5 });\n *\n *     // Broadcast to connected clients\n *     await this.broadcastToClients({ type: 'progress', data: result });\n *\n *     return result;\n *   }\n * }\n * ```\n */\n\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\nimport type {\n  WorkflowEvent,\n  WorkflowStep,\n  WorkflowStepEvent\n} from \"cloudflare:workers\";\nimport { getAgentByName, type Agent } from \"./index\";\nimport type {\n  AgentWorkflowParams,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  DefaultProgress,\n  WaitForApprovalOptions\n} from \"./workflow-types\";\nimport { WorkflowRejectedError } from \"./workflow-types\";\nimport type {\n  AgentWorkflowOrigin,\n  AgentWorkflowPathStep\n} from \"./workflow-types\";\nimport { isInternalJsStubProp } from \"./utils\";\n\ntype AgentPathInvoker = {\n  _cf_invokeAgentPath(\n    path: ReadonlyArray<AgentWorkflowPathStep>,\n    method: string,\n    args: unknown[]\n  ): Promise<unknown>;\n};\n\n/**\n * WeakSet to track which prototypes have been wrapped.\n * This prevents re-wrapping on subsequent instantiations of the same class.\n */\nconst wrappedPrototypes = new WeakSet<object>();\n\n/**\n * Base class for Workflows that need access to their originating Agent.\n *\n * @template AgentType - The Agent class type (for typed RPC access)\n * @template Params - User-defined params passed to the workflow (optional)\n * @template ProgressType - Type for progress reporting (defaults to DefaultProgress)\n * @template Env - Environment type (defaults to Cloudflare.Env)\n */\nexport class AgentWorkflow<\n  AgentType extends Agent = Agent,\n  Params = unknown,\n  ProgressType = DefaultProgress,\n  Env extends Cloudflare.Env = Cloudflare.Env\n> extends WorkflowEntrypoint<Env, AgentWorkflowParams<Params>> {\n  /**\n   * The Agent stub - initialized before run() is called.\n   * Use this.agent to access the Agent's RPC methods.\n   */\n  private _agent?: DurableObjectStub<AgentType>;\n\n  /**\n   * Workflow instance ID\n   */\n  private _workflowId!: string;\n\n  /**\n   * Workflow binding name (for callbacks)\n   */\n  private _workflowName!: string;\n\n  /**\n   * Instance-level guard to prevent double initialization.\n   * Used when a subclass calls super.run() after its own run() was wrapped.\n   */\n  private __agentInitCalled = false;\n\n  /**\n   * Guard to prevent double error notification.\n   * Set to true when reportError() is called explicitly, so the automatic\n   * error catch in the run() wrapper doesn't send a duplicate notification.\n   */\n  private _errorReported = false;\n\n  constructor(ctx: ExecutionContext, env: Env) {\n    super(ctx, env);\n\n    const proto = Object.getPrototypeOf(this);\n\n    // Only wrap if:\n    // 1. This prototype defines its own run method (hasOwnProperty)\n    // 2. It hasn't been wrapped yet (WeakSet check)\n    // This prevents double-wrapping inherited methods and ensures each subclass\n    // that defines run() gets wrapped exactly once.\n    if (Object.hasOwn(proto, \"run\") && !wrappedPrototypes.has(proto)) {\n      const originalRun = proto.run as (\n        event: WorkflowEvent<Params>,\n        step: AgentWorkflowStep\n      ) => Promise<unknown>;\n\n      // Replace the prototype's run method with a wrapper that initializes\n      // the agent before calling the user's implementation\n      proto.run = async function (\n        this: AgentWorkflow<AgentType, Params, ProgressType, Env>,\n        event: WorkflowEvent<AgentWorkflowParams<Params>>,\n        step: WorkflowStep\n      ) {\n        // Instance-level guard: only init once per instance\n        // (prevents double init if super.run() is called from a subclass)\n        if (!this.__agentInitCalled) {\n          const {\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            ...userParams\n          } = event.payload;\n\n          // Initialize agent connection\n          await this._initAgent(\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            event.instanceId\n          );\n          this.__agentInitCalled = true;\n\n          try {\n            // Pass cleaned event and wrapped step to user's implementation\n            const cleanedEvent = {\n              ...event,\n              payload: userParams as Params\n            } as WorkflowEvent<Params>;\n\n            const wrappedStep = this.extendStep(\n              this._wrapStep(step),\n              cleanedEvent\n            );\n\n            return await this._runWithErrorReporting(\n              originalRun,\n              cleanedEvent,\n              wrappedStep\n            );\n          } finally {\n            this._disposeAgent();\n          }\n        }\n\n        // If already initialized (e.g., called via super.run()),\n        // just call the original with the event as-is.\n        return await this._runWithErrorReporting(\n          originalRun,\n          event as WorkflowEvent<Params>,\n          step as AgentWorkflowStep\n        );\n      };\n\n      wrappedPrototypes.add(proto);\n    }\n  }\n\n  /**\n   * Initialize the Agent stub from workflow params.\n   * Called automatically before run() executes.\n   */\n  private async _initAgent(\n    agentName: string | undefined,\n    agentBinding: string | undefined,\n    workflowName: string | undefined,\n    agentOrigin: AgentWorkflowOrigin | undefined,\n    instanceId: string\n  ): Promise<void> {\n    if (!workflowName || (!agentOrigin && (!agentName || !agentBinding))) {\n      throw new Error(\n        \"AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. \" +\n          \"Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    this._workflowId = instanceId;\n    this._workflowName = workflowName;\n    this._errorReported = false;\n\n    // The origin payload is durably persisted in workflow params, so a workflow\n    // started by an older SDK can resume against newer code (and vice versa).\n    // Reject origin versions this build does not understand rather than\n    // silently misreading a future shape.\n    if (agentOrigin && agentOrigin.version !== 1) {\n      throw new Error(\n        `AgentWorkflow received an unsupported origin version (${\n          (agentOrigin as { version?: unknown }).version\n        }). Upgrade the \"agents\" package running this Workflow to match the Agent that started it.`\n      );\n    }\n\n    if (agentOrigin?.kind === \"facet\") {\n      this._agent = await this._initFacetAgent(agentOrigin);\n      return;\n    }\n\n    const resolvedAgentName =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.name : agentName;\n    const resolvedAgentBinding =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.binding : agentBinding;\n\n    if (!resolvedAgentName || !resolvedAgentBinding) {\n      throw new Error(\n        \"AgentWorkflow requires a valid Agent origin. Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    // Get the Agent namespace from env\n    const namespace = (this.env as Record<string, unknown>)[\n      resolvedAgentBinding\n    ] as DurableObjectNamespace<AgentType>;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${resolvedAgentBinding}' not found in environment`\n      );\n    }\n\n    // Get the Agent stub by name\n    this._agent = await getAgentByName<Cloudflare.Env, AgentType>(\n      namespace,\n      resolvedAgentName\n    );\n  }\n\n  private async _initFacetAgent(\n    origin: Extract<AgentWorkflowOrigin, { kind: \"facet\" }>\n  ): Promise<DurableObjectStub<AgentType>> {\n    const root = origin.path[0];\n    if (!root) {\n      throw new Error(\"AgentWorkflow facet origin requires a non-empty path\");\n    }\n\n    const namespace = (this.env as Record<string, unknown>)[\n      origin.rootBinding\n    ] as DurableObjectNamespace<Agent> | undefined;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${origin.rootBinding}' not found in environment`\n      );\n    }\n\n    const rootAgent = (await getAgentByName<Cloudflare.Env, Agent>(\n      namespace,\n      root.name\n    )) as unknown as AgentPathInvoker;\n\n    return new Proxy(\n      {},\n      {\n        get(_target, prop) {\n          if (isInternalJsStubProp(prop)) return undefined;\n          if (typeof prop !== \"string\") return undefined;\n          if (prop === \"fetch\") {\n            return () => {\n              throw new Error(\n                \"AgentWorkflow.agent for sub-agent origins is an RPC-only stub — .fetch() is not supported. Use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL for external HTTP/WS routing.\"\n              );\n            };\n          }\n          return async (...args: unknown[]) =>\n            rootAgent._cf_invokeAgentPath(origin.path, prop, args);\n        }\n      }\n    ) as DurableObjectStub<AgentType>;\n  }\n\n  /**\n   * Call user workflow code and report unhandled errors to the Agent.\n   */\n  private async _runWithErrorReporting(\n    originalRun: (\n      event: WorkflowEvent<Params>,\n      step: AgentWorkflowStep\n    ) => Promise<unknown>,\n    event: WorkflowEvent<Params>,\n    step: AgentWorkflowStep\n  ): Promise<unknown> {\n    try {\n      return await originalRun.call(this, event, step);\n    } catch (err) {\n      await this._autoReportError(err);\n      throw err;\n    }\n  }\n\n  /**\n   * Dispose the Agent stub owned by this workflow run.\n   */\n  private _disposeAgent(): void {\n    const agent = this._agent;\n    this._agent = undefined;\n    this.__agentInitCalled = false;\n    disposeIfPresent(agent);\n  }\n\n  /**\n   * Wrap WorkflowStep with durable Agent communication methods.\n   * Methods added to the wrapped step are idempotent and won't repeat on retry.\n   *\n   * Note: We add methods directly to the step object to preserve instanceof checks\n   * that Cloudflare's runtime may perform on the WorkflowStep class.\n   */\n  private _wrapStep(step: WorkflowStep): AgentWorkflowStep {\n    let stepCounter = 0;\n\n    // Cast step to our extended type and add methods directly\n    // This preserves the original object identity and instanceof relationship\n    const wrappedStep = step as AgentWorkflowStep;\n\n    // Add durable Agent methods directly to the step object\n    wrappedStep.reportComplete = async <T>(result?: T): Promise<void> => {\n      await step.do(`__agent_reportComplete_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"complete\",\n          result,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.reportError = async (error: Error | string): Promise<void> => {\n      const errorMessage = error instanceof Error ? error.message : error;\n      this._errorReported = true;\n      await step.do(`__agent_reportError_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"error\",\n          error: errorMessage,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.sendEvent = async <T>(event: T): Promise<void> => {\n      await step.do(`__agent_sendEvent_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"event\",\n          event,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.updateAgentState = async (state: unknown): Promise<void> => {\n      await step.do(`__agent_updateState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"set\", state);\n      });\n    };\n\n    wrappedStep.mergeAgentState = async (\n      partialState: Record<string, unknown>\n    ): Promise<void> => {\n      await step.do(`__agent_mergeState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"merge\", partialState);\n      });\n    };\n\n    wrappedStep.resetAgentState = async (): Promise<void> => {\n      await step.do(`__agent_resetState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"reset\");\n      });\n    };\n\n    return wrappedStep;\n  }\n\n  /**\n   * Extend the Agent-aware workflow step before user code receives it.\n   *\n   * Subclasses can override this to add framework-specific step helpers while\n   * preserving the underlying WorkflowStep object identity.\n   */\n  protected extendStep(\n    step: AgentWorkflowStep,\n    _event: WorkflowEvent<Params>\n  ): AgentWorkflowStep {\n    return step;\n  }\n\n  /**\n   * Get the Agent stub for RPC calls.\n   * Provides typed access to the Agent's methods.\n   *\n   * @example\n   * ```typescript\n   * // Call any public method on the Agent\n   * await this.agent.updateStatus('processing');\n   * const data = await this.agent.getData();\n   * ```\n   */\n  get agent(): DurableObjectStub<AgentType> {\n    if (!this._agent) {\n      throw new Error(\n        \"Agent not initialized. Ensure you're accessing this.agent inside run().\"\n      );\n    }\n    return this._agent;\n  }\n\n  /**\n   * Get the workflow instance ID\n   */\n  get workflowId(): string {\n    return this._workflowId;\n  }\n\n  /**\n   * Get the workflow binding name\n   */\n  get workflowName(): string {\n    return this._workflowName;\n  }\n\n  /**\n   * Automatically report an unhandled error to the Agent.\n   * Skipped if reportError() was already called (prevents double notification).\n   * Best-effort: notification failures are swallowed so the original error propagates.\n   *\n   * @param err - The caught error\n   */\n  private async _autoReportError(err: unknown): Promise<void> {\n    if (this._errorReported) {\n      return;\n    }\n    this._errorReported = true;\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    try {\n      await this.notifyAgent({\n        workflowName: this._workflowName,\n        workflowId: this._workflowId,\n        type: \"error\",\n        error: errorMessage,\n        timestamp: Date.now()\n      });\n    } catch (_notifyErr) {\n      // Best-effort: don't mask the original error\n    }\n  }\n\n  /**\n   * Send a notification to the Agent via RPC.\n   *\n   * @param callback - Callback payload to send\n   */\n  protected async notifyAgent(callback: WorkflowCallback): Promise<void> {\n    await this.agent._workflow_handleCallback(callback);\n  }\n\n  /**\n   * Report progress to the Agent with typed progress data.\n   * Triggers onWorkflowProgress() on the Agent.\n   *\n   * @param progress - Typed progress data\n   *\n   * @example\n   * ```typescript\n   * // Using default progress type\n   * await this.reportProgress({ step: 'fetch', status: 'running' });\n   * await this.reportProgress({ step: 'fetch', status: 'complete', percent: 0.5 });\n   *\n   * // With custom progress type\n   * await this.reportProgress({ stage: 'extract', recordsProcessed: 100 });\n   * ```\n   */\n  protected async reportProgress(progress: ProgressType): Promise<void> {\n    await this.notifyAgent({\n      workflowName: this._workflowName,\n      workflowId: this._workflowId,\n      type: \"progress\",\n      progress: progress as DefaultProgress,\n      timestamp: Date.now()\n    });\n  }\n\n  /**\n   * Broadcast a message to all connected WebSocket clients via the Agent.\n   * This is non-durable and may repeat on workflow retry.\n   *\n   * @param message - Message to broadcast (will be JSON-stringified)\n   */\n  protected broadcastToClients(message: unknown): void {\n    this.agent._workflow_broadcast(message);\n  }\n\n  /**\n   * Wait for approval from the Agent.\n   * Handles rejection by reporting error (durably) and throwing WorkflowRejectedError.\n   *\n   * @param step - AgentWorkflowStep object\n   * @param options - Wait options (timeout, eventType, stepName)\n   * @returns Approval payload (throws WorkflowRejectedError if rejected)\n   *\n   * @example\n   * ```typescript\n   * const approval = await this.waitForApproval(step, { timeout: '7 days' });\n   * // approval contains the payload from approveWorkflow()\n   * ```\n   */\n  protected async waitForApproval<T = unknown>(\n    step: AgentWorkflowStep,\n    options?: WaitForApprovalOptions\n  ): Promise<T> {\n    const stepName = options?.stepName ?? \"wait-for-approval\";\n    const eventType = options?.eventType ?? \"approval\";\n    const timeout = options?.timeout;\n\n    // Wait for the approval event\n    // Note: Call reportProgress() before this method if you want to update progress\n    const event = (await step.waitForEvent(stepName, {\n      type: eventType,\n      timeout\n    })) as WorkflowStepEvent<{\n      approved: boolean;\n      reason?: string;\n      metadata?: T;\n    }>;\n\n    try {\n      const payload = event.payload;\n\n      // Check if rejected\n      if (!payload.approved) {\n        const reason = payload.reason;\n        await step.reportError(reason ?? \"Workflow rejected\");\n        throw new WorkflowRejectedError(reason, this._workflowId);\n      }\n\n      // Return the approval metadata as the result\n      return payload.metadata as T;\n    } finally {\n      disposeIfPresent(event);\n    }\n  }\n}\n\ntype DisposableResource = {\n  [Symbol.dispose](): void;\n};\n\nfunction isDisposableResource(value: unknown): value is DisposableResource {\n  return (\n    !!value &&\n    typeof value === \"object\" &&\n    Symbol.dispose in value &&\n    typeof value[Symbol.dispose] === \"function\"\n  );\n}\n\nfunction disposeIfPresent(value: unknown): void {\n  if (isDisposableResource(value)) {\n    value[Symbol.dispose]();\n  }\n}\n\n// Re-export types for convenience\nexport type {\n  AgentWorkflowEvent,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  WorkflowCallbackType,\n  WorkflowProgressCallback,\n  WorkflowCompleteCallback,\n  WorkflowErrorCallback,\n  WorkflowEventCallback,\n  DefaultProgress,\n  WaitForApprovalOptions,\n  ApprovalEventPayload,\n  WorkflowStatus,\n  WorkflowTrackingRow,\n  RunWorkflowOptions,\n  WorkflowEventPayload,\n  WorkflowInfo,\n  WorkflowQueryCriteria,\n  WorkflowPage\n} from \"./workflow-types\";\n\nexport { WorkflowRejectedError } from \"./workflow-types\";\n"],"mappings":"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"}
+{"version":3,"file":"workflows.js","names":[],"sources":["../src/workflows.ts"],"sourcesContent":["/**\n * AgentWorkflow - Base class for Workflows that integrate with Agents\n *\n * Extends Cloudflare's WorkflowEntrypoint to provide seamless access to\n * the Agent that started the workflow, enabling bidirectional communication.\n *\n * @example\n * ```typescript\n * import { AgentWorkflow } from 'agents/workflows';\n * import type { MyAgent } from './agent';\n *\n * type TaskParams = { taskId: string; data: string };\n *\n * export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {\n *   async run(event: AgentWorkflowEvent<TaskParams>, step: WorkflowStep) {\n *     // Access the originating Agent via typed RPC\n *     await this.agent.updateTaskStatus(event.payload.taskId, 'processing');\n *\n *     const result = await step.do('process', async () => {\n *       // ... processing logic\n *       return { processed: true };\n *     });\n *\n *     // Report progress to Agent (typed)\n *     await this.reportProgress({ step: 'process', status: 'complete', percent: 0.5 });\n *\n *     // Broadcast to connected clients\n *     await this.broadcastToClients({ type: 'progress', data: result });\n *\n *     return result;\n *   }\n * }\n * ```\n */\n\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\nimport type {\n  WorkflowEvent,\n  WorkflowStep,\n  WorkflowStepEvent\n} from \"cloudflare:workers\";\nimport { getAgentByName, type Agent } from \"./index\";\nimport type {\n  AgentWorkflowParams,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  DefaultProgress,\n  WaitForApprovalOptions\n} from \"./workflow-types\";\nimport { WorkflowRejectedError } from \"./workflow-types\";\nimport type {\n  AgentWorkflowOrigin,\n  AgentWorkflowPathStep\n} from \"./workflow-types\";\nimport { isInternalJsStubProp } from \"./utils\";\n\ntype AgentPathInvoker = {\n  _cf_invokeAgentPath(\n    path: ReadonlyArray<AgentWorkflowPathStep>,\n    method: string,\n    args: unknown[]\n  ): Promise<unknown>;\n};\n\n/**\n * WeakSet to track which prototypes have been wrapped.\n * This prevents re-wrapping on subsequent instantiations of the same class.\n */\nconst wrappedPrototypes = new WeakSet<object>();\n\n/**\n * Base class for Workflows that need access to their originating Agent.\n *\n * @template AgentType - The Agent class type (for typed RPC access)\n * @template Params - User-defined params passed to the workflow (optional)\n * @template ProgressType - Type for progress reporting (defaults to DefaultProgress)\n * @template Env - Environment type (defaults to Cloudflare.Env)\n */\nexport class AgentWorkflow<\n  AgentType extends Agent = Agent,\n  Params = unknown,\n  ProgressType = DefaultProgress,\n  Env extends Cloudflare.Env = Cloudflare.Env\n> extends WorkflowEntrypoint<Env, AgentWorkflowParams<Params>> {\n  /**\n   * The Agent stub - initialized before run() is called.\n   * Use this.agent to access the Agent's RPC methods.\n   */\n  private _agent?: DurableObjectStub<AgentType>;\n\n  /**\n   * Workflow instance ID\n   */\n  private _workflowId!: string;\n\n  /**\n   * Workflow binding name (for callbacks)\n   */\n  private _workflowName!: string;\n\n  /**\n   * Instance-level guard to prevent double initialization.\n   * Used when a subclass calls super.run() after its own run() was wrapped.\n   */\n  private __agentInitCalled = false;\n\n  /**\n   * Guard to prevent double error notification.\n   * Set to true when reportError() is called explicitly, so the automatic\n   * error catch in the run() wrapper doesn't send a duplicate notification.\n   */\n  private _errorReported = false;\n\n  constructor(ctx: ExecutionContext, env: Env) {\n    super(ctx, env);\n\n    const proto = Object.getPrototypeOf(this);\n\n    // Only wrap if:\n    // 1. This prototype defines its own run method (hasOwnProperty)\n    // 2. It hasn't been wrapped yet (WeakSet check)\n    // This prevents double-wrapping inherited methods and ensures each subclass\n    // that defines run() gets wrapped exactly once.\n    if (Object.hasOwn(proto, \"run\") && !wrappedPrototypes.has(proto)) {\n      const originalRun = proto.run as (\n        event: WorkflowEvent<Params>,\n        step: AgentWorkflowStep\n      ) => Promise<unknown>;\n\n      // Replace the prototype's run method with a wrapper that initializes\n      // the agent before calling the user's implementation\n      proto.run = async function (\n        this: AgentWorkflow<AgentType, Params, ProgressType, Env>,\n        event: WorkflowEvent<AgentWorkflowParams<Params>>,\n        step: WorkflowStep\n      ) {\n        // Instance-level guard: only init once per instance\n        // (prevents double init if super.run() is called from a subclass)\n        if (!this.__agentInitCalled) {\n          const {\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            ...userParams\n          } = event.payload;\n\n          // Initialize agent connection\n          await this._initAgent(\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            event.instanceId\n          );\n          this.__agentInitCalled = true;\n\n          try {\n            // Pass cleaned event and wrapped step to user's implementation\n            const cleanedEvent = {\n              ...event,\n              payload: userParams as Params\n            } as WorkflowEvent<Params>;\n\n            const wrappedStep = this.extendStep(\n              this._wrapStep(step),\n              cleanedEvent\n            );\n\n            return await this._runWithErrorReporting(\n              originalRun,\n              cleanedEvent,\n              wrappedStep\n            );\n          } finally {\n            this._disposeAgent();\n          }\n        }\n\n        // If already initialized (e.g., called via super.run()),\n        // just call the original with the event as-is.\n        return await this._runWithErrorReporting(\n          originalRun,\n          event as WorkflowEvent<Params>,\n          step as AgentWorkflowStep\n        );\n      };\n\n      wrappedPrototypes.add(proto);\n    }\n  }\n\n  /**\n   * Initialize the Agent stub from workflow params.\n   * Called automatically before run() executes.\n   */\n  private async _initAgent(\n    agentName: string | undefined,\n    agentBinding: string | undefined,\n    workflowName: string | undefined,\n    agentOrigin: AgentWorkflowOrigin | undefined,\n    instanceId: string\n  ): Promise<void> {\n    if (!workflowName || (!agentOrigin && (!agentName || !agentBinding))) {\n      throw new Error(\n        \"AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. \" +\n          \"Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    this._workflowId = instanceId;\n    this._workflowName = workflowName;\n    this._errorReported = false;\n\n    // The origin payload is durably persisted in workflow params, so a workflow\n    // started by an older SDK can resume against newer code (and vice versa).\n    // Reject origin versions this build does not understand rather than\n    // silently misreading a future shape.\n    if (agentOrigin && agentOrigin.version !== 1) {\n      throw new Error(\n        `AgentWorkflow received an unsupported origin version (${\n          (agentOrigin as { version?: unknown }).version\n        }). Upgrade the \"agents\" package running this Workflow to match the Agent that started it.`\n      );\n    }\n\n    if (agentOrigin?.kind === \"facet\") {\n      this._agent = await this._initFacetAgent(agentOrigin);\n      return;\n    }\n\n    const resolvedAgentName =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.name : agentName;\n    const resolvedAgentBinding =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.binding : agentBinding;\n\n    if (!resolvedAgentName || !resolvedAgentBinding) {\n      throw new Error(\n        \"AgentWorkflow requires a valid Agent origin. Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    // Get the Agent namespace from env\n    const namespace = (this.env as Record<string, unknown>)[\n      resolvedAgentBinding\n    ] as DurableObjectNamespace<AgentType>;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${resolvedAgentBinding}' not found in environment`\n      );\n    }\n\n    // Get the Agent stub by name\n    this._agent = await getAgentByName<Cloudflare.Env, AgentType>(\n      namespace,\n      resolvedAgentName\n    );\n  }\n\n  private async _initFacetAgent(\n    origin: Extract<AgentWorkflowOrigin, { kind: \"facet\" }>\n  ): Promise<DurableObjectStub<AgentType>> {\n    const root = origin.path[0];\n    if (!root) {\n      throw new Error(\"AgentWorkflow facet origin requires a non-empty path\");\n    }\n\n    const namespace = (this.env as Record<string, unknown>)[\n      origin.rootBinding\n    ] as DurableObjectNamespace<Agent> | undefined;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${origin.rootBinding}' not found in environment`\n      );\n    }\n\n    const rootAgent = (await getAgentByName<Cloudflare.Env, Agent>(\n      namespace,\n      root.name\n    )) as unknown as AgentPathInvoker;\n\n    return new Proxy(\n      {},\n      {\n        get(_target, prop) {\n          if (isInternalJsStubProp(prop)) return undefined;\n          if (typeof prop !== \"string\") return undefined;\n          if (prop === \"fetch\") {\n            return () => {\n              throw new Error(\n                \"AgentWorkflow.agent for sub-agent origins is an RPC-only stub — .fetch() is not supported. Use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL for external HTTP/WS routing.\"\n              );\n            };\n          }\n          return async (...args: unknown[]) =>\n            rootAgent._cf_invokeAgentPath(origin.path, prop, args);\n        }\n      }\n    ) as DurableObjectStub<AgentType>;\n  }\n\n  /**\n   * Call user workflow code and report unhandled errors to the Agent.\n   */\n  private async _runWithErrorReporting(\n    originalRun: (\n      event: WorkflowEvent<Params>,\n      step: AgentWorkflowStep\n    ) => Promise<unknown>,\n    event: WorkflowEvent<Params>,\n    step: AgentWorkflowStep\n  ): Promise<unknown> {\n    try {\n      return await originalRun.call(this, event, step);\n    } catch (err) {\n      await this._autoReportError(err);\n      throw err;\n    }\n  }\n\n  /**\n   * Dispose the Agent stub owned by this workflow run.\n   */\n  private _disposeAgent(): void {\n    const agent = this._agent;\n    this._agent = undefined;\n    this.__agentInitCalled = false;\n    disposeIfPresent(agent);\n  }\n\n  /**\n   * Wrap WorkflowStep with durable Agent communication methods.\n   * Methods added to the wrapped step are idempotent and won't repeat on retry.\n   *\n   * Note: We add methods directly to the step object to preserve instanceof checks\n   * that Cloudflare's runtime may perform on the WorkflowStep class.\n   */\n  private _wrapStep(step: WorkflowStep): AgentWorkflowStep {\n    let stepCounter = 0;\n\n    // Cast step to our extended type and add methods directly\n    // This preserves the original object identity and instanceof relationship\n    const wrappedStep = step as AgentWorkflowStep;\n\n    // Add durable Agent methods directly to the step object\n    wrappedStep.reportComplete = async <T>(result?: T): Promise<void> => {\n      await step.do(`__agent_reportComplete_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"complete\",\n          result,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.reportError = async (error: Error | string): Promise<void> => {\n      const errorMessage = error instanceof Error ? error.message : error;\n      this._errorReported = true;\n      await step.do(`__agent_reportError_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"error\",\n          error: errorMessage,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.sendEvent = async <T>(event: T): Promise<void> => {\n      await step.do(`__agent_sendEvent_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"event\",\n          event,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.updateAgentState = async (state: unknown): Promise<void> => {\n      await step.do(`__agent_updateState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"set\", state);\n      });\n    };\n\n    wrappedStep.mergeAgentState = async (\n      partialState: Record<string, unknown>\n    ): Promise<void> => {\n      await step.do(`__agent_mergeState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"merge\", partialState);\n      });\n    };\n\n    wrappedStep.resetAgentState = async (): Promise<void> => {\n      await step.do(`__agent_resetState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"reset\");\n      });\n    };\n\n    return wrappedStep;\n  }\n\n  /**\n   * Extend the Agent-aware workflow step before user code receives it.\n   *\n   * Subclasses can override this to add framework-specific step helpers while\n   * preserving the underlying WorkflowStep object identity.\n   */\n  protected extendStep(\n    step: AgentWorkflowStep,\n    _event: WorkflowEvent<Params>\n  ): AgentWorkflowStep {\n    return step;\n  }\n\n  /**\n   * Get the Agent stub for RPC calls.\n   * Provides typed access to the Agent's methods.\n   *\n   * @example\n   * ```typescript\n   * // Call any public method on the Agent\n   * await this.agent.updateStatus('processing');\n   * const data = await this.agent.getData();\n   * ```\n   */\n  get agent(): DurableObjectStub<AgentType> {\n    if (!this._agent) {\n      throw new Error(\n        \"Agent not initialized. Ensure you're accessing this.agent inside run().\"\n      );\n    }\n    return this._agent;\n  }\n\n  /**\n   * Get the workflow instance ID\n   */\n  get workflowId(): string {\n    return this._workflowId;\n  }\n\n  /**\n   * Get the workflow binding name\n   */\n  get workflowName(): string {\n    return this._workflowName;\n  }\n\n  /**\n   * Automatically report an unhandled error to the Agent.\n   * Skipped if reportError() was already called (prevents double notification).\n   * Best-effort: notification failures are swallowed so the original error propagates.\n   *\n   * @param err - The caught error\n   */\n  private async _autoReportError(err: unknown): Promise<void> {\n    if (this._errorReported) {\n      return;\n    }\n    this._errorReported = true;\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    try {\n      await this.notifyAgent({\n        workflowName: this._workflowName,\n        workflowId: this._workflowId,\n        type: \"error\",\n        error: errorMessage,\n        timestamp: Date.now()\n      });\n    } catch (_notifyErr) {\n      // Best-effort: don't mask the original error\n    }\n  }\n\n  /**\n   * Send a notification to the Agent via RPC.\n   *\n   * @param callback - Callback payload to send\n   */\n  protected async notifyAgent(callback: WorkflowCallback): Promise<void> {\n    await this.agent._workflow_handleCallback(callback);\n  }\n\n  /**\n   * Report progress to the Agent with typed progress data.\n   * Triggers onWorkflowProgress() on the Agent.\n   *\n   * @param progress - Typed progress data\n   *\n   * @example\n   * ```typescript\n   * // Using default progress type\n   * await this.reportProgress({ step: 'fetch', status: 'running' });\n   * await this.reportProgress({ step: 'fetch', status: 'complete', percent: 0.5 });\n   *\n   * // With custom progress type\n   * await this.reportProgress({ stage: 'extract', recordsProcessed: 100 });\n   * ```\n   */\n  protected async reportProgress(progress: ProgressType): Promise<void> {\n    await this.notifyAgent({\n      workflowName: this._workflowName,\n      workflowId: this._workflowId,\n      type: \"progress\",\n      progress: progress as DefaultProgress,\n      timestamp: Date.now()\n    });\n  }\n\n  /**\n   * Broadcast a message to all connected WebSocket clients via the Agent.\n   * This is non-durable and may repeat on workflow retry.\n   *\n   * @param message - Message to broadcast (will be JSON-stringified)\n   */\n  protected broadcastToClients(message: unknown): void {\n    this.agent._workflow_broadcast(message);\n  }\n\n  /**\n   * Wait for approval from the Agent.\n   * Handles rejection by reporting error (durably) and throwing WorkflowRejectedError.\n   *\n   * @param step - AgentWorkflowStep object\n   * @param options - Wait options (timeout, eventType, stepName)\n   * @returns Approval payload (throws WorkflowRejectedError if rejected)\n   *\n   * @example\n   * ```typescript\n   * const approval = await this.waitForApproval(step, { timeout: '7 days' });\n   * // approval contains the payload from approveWorkflow()\n   * ```\n   */\n  protected async waitForApproval<T = unknown>(\n    step: AgentWorkflowStep,\n    options?: WaitForApprovalOptions\n  ): Promise<T> {\n    const stepName = options?.stepName ?? \"wait-for-approval\";\n    const eventType = options?.eventType ?? \"approval\";\n    const timeout = options?.timeout;\n\n    // Wait for the approval event\n    // Note: Call reportProgress() before this method if you want to update progress\n    const event = (await step.waitForEvent(stepName, {\n      type: eventType,\n      timeout\n    })) as WorkflowStepEvent<{\n      approved: boolean;\n      reason?: string;\n      metadata?: T;\n    }>;\n\n    try {\n      const payload = event.payload;\n\n      // Check if rejected\n      if (!payload.approved) {\n        const reason = payload.reason;\n        await step.reportError(reason ?? \"Workflow rejected\");\n        throw new WorkflowRejectedError(reason, this._workflowId);\n      }\n\n      // Return the approval metadata as the result\n      return payload.metadata as T;\n    } finally {\n      disposeIfPresent(event);\n    }\n  }\n}\n\ntype DisposableResource = {\n  [Symbol.dispose](): void;\n};\n\nfunction isDisposableResource(value: unknown): value is DisposableResource {\n  return (\n    !!value &&\n    typeof value === \"object\" &&\n    Symbol.dispose in value &&\n    typeof value[Symbol.dispose] === \"function\"\n  );\n}\n\nfunction disposeIfPresent(value: unknown): void {\n  if (isDisposableResource(value)) {\n    value[Symbol.dispose]();\n  }\n}\n\n// Re-export types for convenience\nexport type {\n  AgentWorkflowEvent,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  WorkflowCallbackType,\n  WorkflowProgressCallback,\n  WorkflowCompleteCallback,\n  WorkflowErrorCallback,\n  WorkflowEventCallback,\n  DefaultProgress,\n  WaitForApprovalOptions,\n  ApprovalEventPayload,\n  WorkflowStatus,\n  WorkflowTrackingRow,\n  RunWorkflowOptions,\n  WorkflowEventPayload,\n  WorkflowInfo,\n  WorkflowQueryCriteria,\n  WorkflowPage\n} from \"./workflow-types\";\n\nexport { WorkflowRejectedError } from \"./workflow-types\";\n"],"mappings":"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"}

package/docs/harnesses/pi.md

@@ -118,13 +118,19 @@ Pi's extensions can do more: hooks on model requests and tool calls (`hook(ToolT
 
 ### Skills
 
-`skills(sources)` turns `agents/skills` sources (refer to [Agent Skills](../../think/index.md#agent-skills)) into a Pi extension named `agents.skills`. It has two tools, `activate_skill` and `read_skill_resource`, and a `skills` section that lists the skills. Install it in the factory, since it reads the sources:
+`skills(sources)` turns `agents/skills` sources (refer to [Agent Skills](../../think/index.md#agent-skills)) into a Pi extension named `agents.skills`. It has two tools, `activate_skill` and `read_skill_resource`, and a `skills` section that lists the skills. Sources can read skills from a Computer Workspace (`workspace()`), an R2 bucket (`r2()`), or code (`manifest()`). Install it in the factory, since it reads the sources:
 
 ```ts
 import { skills } from "agents/harness/pi";
+import * as agentSkills from "agents/skills";
 
 harness: async ({ storage, context, onWake }) => {
-  this.registry.install(await skills(sources));
+  this.registry.install(
+    await skills([
+      agentSkills.workspace(workspace), // /workspace/.agents/skills
+      agentSkills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" })
+    ])
+  );
   return Harness.open(
     storage,
     { models, registry: this.registry, onWake },
@@ -133,7 +139,7 @@ harness: async ({ storage, context, onWake }) => {
 };
 ```
 
-The existing `@cloudflare/think` skills work out-of-the-box.
+The sources are read once, when the factory builds the extension. The tools and their output match `@cloudflare/think`, so a skill behaves the same in both.
 
 ### Browser
 

package/docs/mcp-client.md

@@ -60,7 +60,7 @@ available.
 Install the exact MCP client peer used by this Agents release:
 
 ```sh
-pnpm add agents @modelcontextprotocol/client@2.3.1
+pnpm add agents @modelcontextprotocol/client@2.4.0
 ```
 
 The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Those packages are optional peers used only by the MCP server APIs.
@@ -367,6 +367,28 @@ class MyAgent extends Agent {
 }
 ```
 
+#### Client ID Metadata Documents
+
+Some authorization servers accept a [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#client-id-metadata-documents) instead of dynamic client registration. Pass `clientMetadataUrl` to use one. When a server advertises `client_id_metadata_document_supported`, the agent sends that URL as its `client_id`. Servers that don't advertise it still get dynamic client registration.
+
+```typescript
+import { Agent, DurableObjectOAuthClientProvider } from "agents";
+import type { AgentMcpOAuthProvider } from "agents";
+
+class MyAgent extends Agent {
+  createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
+    return new DurableObjectOAuthClientProvider(
+      this.ctx.storage,
+      this.name,
+      callbackUrl,
+      { clientMetadataUrl: "https://my-app.example.com/oauth/client.json" }
+    );
+  }
+}
+```
+
+Serve the document at that URL. `provider.clientMetadataDocument` returns its JSON: `client_id` is the URL and `redirect_uris` holds the callback URL. The authorization server checks every redirect URI against the document, so pass a fixed `callbackPath` to `addMcpServer` rather than relying on the per-instance default.
+
 ## Using MCP Capabilities
 
 Once connected, access the server's capabilities:

package/docs/mcp-servers.md

@@ -5,7 +5,7 @@ Build an MCP server on Workers with `createMcpHandler` from `agents/mcp/server`
 ## Install
 
 ```sh
-pnpm add agents @modelcontextprotocol/server@2.3.1 zod
+pnpm add agents @modelcontextprotocol/server@2.4.0 zod
 ```
 
 `@modelcontextprotocol/server` is an optional peer dependency of `agents`, so your package manager does not install it for you. Use the exact version required by your installed Agents release.
@@ -279,7 +279,7 @@ If the handler lifecycle does not fit, use the SDK's `WebStandardStreamableHTTPS
 `McpAgent` is deprecated, but existing servers keep working. It is built on MCP SDK v1, which is an optional peer dependency of `agents`, so your package manager no longer installs it for you. Add the exact version your Agents release expects before you upgrade:
 
 ```sh
-pnpm add agents @modelcontextprotocol/sdk@1.32.1 zod
+pnpm add agents @modelcontextprotocol/sdk@1.32.2 zod
 ```
 
 Keep importing `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` in an `McpAgent`. An SDK v2 server from `@modelcontextprotocol/server` cannot run inside `McpAgent`. The same applies to `WorkerTransport` and `createLegacyMcpHandler` from `agents/mcp`.

package/docs/observability.md

@@ -438,9 +438,11 @@ exists:
 `gen_ai.response.finish_reasons` and `gen_ai.request.stop_sequences` are arrays
 in OTel. Workers' custom `Span.setAttribute` currently accepts only a string,
 number, or boolean, so the wrapper omits those attributes rather than placing
-JSON text under an array-typed key. Similarly, span status is state rather than
-an attribute: failures emit `error.type`, but the wrapper does not invent an
-`otel.status_code` attribute when Workers exposes no custom-span status setter.
+JSON text under an array-typed key. Failures emit `error.type` and, on runtimes
+with `Span.setStatus()` (the 2026-10-26 release or later), set span status
+`error` without a description. Status is span state, exported to OpenTelemetry
+destinations, not an attribute; the raw error message is never recorded.
+Cancellations leave the status unset.
 
 ### Context and safety
 

package/package.json

@@ -12,7 +12,10 @@
   "bin": {
     "agents": "./dist/cli.js"
   },
-  "version": "0.31.0",
+  "version": "0.32.0",
+  "sideEffects": [
+    "./dist/cli.js"
+  ],
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -26,10 +29,10 @@
   "dependencies": {
     "@babel/plugin-proposal-decorators": "^8.0.2",
     "@cfworker/json-schema": "^4.1.1",
+    "@opentelemetry/api": "^1.9.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "capnweb": "^0.12.0",
     "cron-schedule": "^6.0.0",
-    "esbuild": "^0.28.1",
     "mimetext": "^3.0.28",
     "nanoid": "^5.1.16",
     "partysocket": "1.3.0",
@@ -42,15 +45,15 @@
     "@ai-sdk/provider": "^4.0.0",
     "@ai-sdk/react": "^4.0.0",
     "@ai-sdk/valibot": "3.0.6",
-    "@cloudflare/codemode": "^0.5.5",
+    "@cloudflare/codemode": "^0.5.6",
     "@earendil-works/chord": "~1.4.0",
     "@earendil-works/pi-ai": "~1.4.0",
     "@earendil-works/pi-durable": "~1.4.0",
     "@earendil-works/pi-tui": "1.4.0",
-    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/client": "2.4.0",
     "@modelcontextprotocol/conformance-v2": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.12",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@opencode/plugin": "2.0.24",
     "@opencode/sdk": "2.0.24",
     "@tanstack/ai": "0.38.0",
@@ -60,6 +63,7 @@
     "@x402/evm": "^2.17.0",
     "ai": "^7.0.0",
     "chat": "^4.31.0",
+    "esbuild": "^0.28.1",
     "glob": "^13.0.6",
     "highlight.js": "11.12.0",
     "just-bash": "^3.0.2",
@@ -74,12 +78,12 @@
     "@earendil-works/chord": "~1.4.0",
     "@earendil-works/pi-ai": "~1.4.0",
     "@earendil-works/pi-durable": "~1.4.0",
-    "@modelcontextprotocol/client": "2.3.1",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/client": "2.4.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@opencode/plugin": "^2.0.24",
     "@opencode/sdk": "^2.0.24",
-    "@tanstack/ai": ">=0.10.2 <1.0.0",
+    "@tanstack/ai": ">=0.10.2 <2.0.0",
     "@x402/core": "^2.0.0",
     "@x402/evm": "^2.0.0",
     "ai": "^6.0.0 || ^7.0.0",
@@ -533,10 +537,15 @@
       "import": "./dist/skills/index.js",
       "require": "./dist/skills/index.js"
     },
-    "./skills/compile": {
-      "types": "./dist/skills/compile.d.ts",
-      "import": "./dist/skills/compile.js",
-      "require": "./dist/skills/compile.js"
+    "./skills/tools/ai-sdk": {
+      "types": "./dist/skills/tools/ai-sdk.d.ts",
+      "import": "./dist/skills/tools/ai-sdk.js",
+      "require": "./dist/skills/tools/ai-sdk.js"
+    },
+    "./skills/runner": {
+      "types": "./dist/skills/runner.d.ts",
+      "import": "./dist/skills/runner.js",
+      "require": "./dist/skills/runner.js"
     }
   },
   "publishConfig": {
@@ -546,7 +555,6 @@
     "dist",
     "docs",
     "agents.tsconfig.json",
-    "skills-module.d.ts",
     "README.md"
   ],
   "nx": {
@@ -579,6 +587,7 @@
     "test:voice:react": "vitest --project voice-react",
     "test:channels": "vitest --project channels",
     "test:browser": "vitest run --config src/browser-tests/vitest.config.ts",
+    "test:otel-runtime": "vitest run --config src/otel-tests/vitest.config.ts",
     "test:workers": "vitest --project workers",
     "test:chat": "vitest --project chat",
     "test:harness:opencode": "vitest --project harness-opencode",

package/dist/ai-sdk-hW3vntnk.d.ts

@@ -1,72 +0,0 @@
-import {
-  n as BrowserToolOptions,
-  r as BrowserToolOutput,
-  t as BrowserToolInput
-} from "./browser-tool-BhjCcNVE.js";
-import { FlexibleSchema, JSONValue } from "ai";
-
-//#region src/browser/tool-helpers.d.ts
-/** What the model sees in place of a browser tool's output. */
-type BrowserModelOutput =
-  | {
-      type: "text";
-      value: string;
-    }
-  | {
-      type: "json";
-      value: JSONValue;
-    };
-//#endregion
-//#region src/browser/tools/ai-sdk.d.ts
-/**
- * The AI SDK tool {@link browserTool} returns. Assignable to the AI SDK's
- * `Tool`, and `execute` / `toModelOutput` are always present.
- */
-interface BrowserTool {
-  description: string;
-  inputSchema: FlexibleSchema<BrowserToolInput>;
-  execute(
-    input: BrowserToolInput,
-    options: unknown
-  ): Promise<BrowserToolOutput>;
-  toModelOutput(options: { output: BrowserToolOutput }): BrowserModelOutput;
-}
-/**
- * Create an AI SDK tool that lets the model drive a persistent browser with
- * JavaScript and the Chrome DevTools Protocol.
- *
- * The browser outlives each run: tabs, cookies, and logins carry over. The
- * model never starts, closes, or resets it, and `sessionId: "active"`
- * addresses the tab it last worked in. If the browser had to be replaced
- * (it expired or was closed), the code still runs in the new browser and the
- * result's `notice` says so.
- *
- * Browser Run only (Chromium). Guardrails, `keepAliveMs`, and recording are
- * set on the `Browser`'s provider.
- *
- * @example
- * ```ts
- * import { Browser, browserRun } from "agents/browser";
- * import { browserTool } from "agents/browser/ai-sdk";
- *
- * export class MyAgent extends Agent<Env> {
- *   browser = new Browser({ provider: browserRun(this.env.BROWSER) });
- *
- *   constructor(ctx: AgentContext, env: Env) {
- *     super(ctx, env);
- *     this.lifecycle.use(this.browser);
- *   }
- *
- *   async onChatMessage() {
- *     const tools = {
- *       browser: browserTool({ browser: this.browser, loader: this.env.LOADER })
- *     };
- *     // …pass `tools` to streamText / generateText
- *   }
- * }
- * ```
- */
-declare function browserTool(options: BrowserToolOptions): BrowserTool;
-//#endregion
-export { browserTool as n, BrowserTool as t };
-//# sourceMappingURL=ai-sdk-hW3vntnk.d.ts.map

package/dist/cloudflare-Dzvc7V2N.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cloudflare-Dzvc7V2N.js","names":[],"sources":["../src/observability/tracing/tracer.ts","../src/observability/tracing/cloudflare.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\n/** Attribute values accepted by custom spans. */\nexport type TraceAttributeValue = string | number | boolean | undefined;\n\n/** Initial or finish attributes attached to a span. */\nexport type TraceAttributes = Readonly<Record<string, TraceAttributeValue>>;\n\n/** A value that may complete synchronously or through a promise-like result. */\nexport type MaybePromise<T> = T | PromiseLike<T>;\n\n/** Minimal runtime span surface used by tracers. */\nexport type SpanWriter = {\n  readonly isTraced: boolean;\n  setAttribute(key: string, value: TraceAttributeValue): void;\n  end(): void;\n};\n\n/** Runtime capability for starting an active span in the current async context. */\nexport type SpanRuntime = {\n  startActiveSpan<T>(name: string, run: (span: SpanWriter) => T): T;\n};\n\n/** Optional automatic lifetime policy for invocation-bounded spans. */\nexport type SpanLifetime = {\n  /**\n   * Close the span no later than the end of the surrounding\n   * {@link withInvocationScope}, so it cannot outlive the native invocation\n   * that owns its tracing context. Ignored outside such a scope.\n   */\n  readonly boundToInvocation?: boolean;\n};\n\n/** AgentTracer seam used by integrations. */\nexport type AgentTracer = {\n  /**\n   * Runs `run` inside an active span whose lifetime the tracer owns: the span\n   * finishes when `run` returns (or its promise resolves) and fails when `run`\n   * throws or rejects. Callers do not call {@link AgentSpan.finish}/{@link AgentSpan.fail};\n   * doing so early is safe but the tracer guarantees closure.\n   *\n   * @template T The value produced by the instrumented work.\n   */\n  withSpan<T>(\n    name: string,\n    attributes: TraceAttributes,\n    run: (span: AgentSpan) => MaybePromise<T>,\n    lifetime?: SpanLifetime\n  ): T | Promise<T>;\n  /**\n   * Activates a span and returns whatever `activate` returns (typically the\n   * {@link AgentSpan} handle itself). The caller owns the span lifetime and MUST call\n   * {@link AgentSpan.finish} or {@link AgentSpan.fail}; an unfinished span leaks. Use this\n   * for work that outlives the callback, such as streams and event-driven\n   * telemetry. A throw from `activate` still fails the span before rethrowing.\n   *\n   * @template T The value returned to the caller, usually the span handle.\n   */\n  openSpan<T>(\n    name: string,\n    attributes: TraceAttributes,\n    activate: (span: AgentSpan) => T,\n    lifetime?: SpanLifetime\n  ): T;\n};\n\n/** Active span handle passed to instrumented work. */\nexport type AgentSpan = {\n  /**\n   * Whether this invocation is actually being traced. Instrumentation can use\n   * this to skip expensive capture work when nobody is listening.\n   */\n  readonly isTraced: boolean;\n  /** Records the optional finish attributes and ends the span. Idempotent. */\n  finish(attributes?: TraceAttributes): void;\n  /**\n   * Ends the span as not-successful. Genuine failures record `error.type`;\n   * recognized cancellations (an `AbortError`) record `canceled` instead so aborts\n   * are not counted as errors. The cause message is never recorded. Idempotent.\n   */\n  fail(cause: unknown): void;\n};\n\ntype InvocationScope = {\n  /** Bounded spans still open. Emptied when the invocation ends. */\n  readonly open: Set<ManagedSpan>;\n  /** Whether the invocation this scope represents has already ended. */\n  ended: boolean;\n};\n\nexport type InvocationScopeOptions = {\n  /**\n   * Open a scope even inside a live one, for work deliberately detached from\n   * the handler that started it — `ctx.waitUntil` bodies, queue drains — which\n   * runs on past that handler and must not be cut off with it.\n   */\n  readonly detached?: boolean;\n};\n\n/**\n * Spans that asked to be invocation-bounded while a scope was active. Closed\n * when that scope ends; see {@link withInvocationScope}.\n */\nconst invocationScope = new AsyncLocalStorage<InvocationScope>();\n\n/**\n * Runs `body` as one traced invocation.\n *\n * Work that escapes its native invocation cannot be traced from the context it\n * started in: the still-open span is force-closed against the invocation that\n * owned that context, which reports a negative duration or `span_not_ended`.\n * Spans opened with {@link SpanLifetime.boundToInvocation} inside this scope\n * are therefore closed before `body` settles — but not one moment earlier, so\n * everything that completes during the invocation (the normal case: a chat\n * turn is awaited by the handler that received it) still records its finish\n * attributes. A span truncated this way is marked\n * `cloudflare.agents.span.truncated` rather than passing as complete.\n */\nexport function withInvocationScope<T>(\n  body: () => T,\n  options?: InvocationScopeOptions\n): T {\n  // Nested scopes would truncate spans at an inner boundary that is not an\n  // invocation edge, so the outermost live scope owns the lifetime. A scope\n  // that has already ended is not an enclosing invocation at all — it is a\n  // leftover context on work that resumed later — so `body` starts a new one.\n  const current = invocationScope.getStore();\n  if (options?.detached !== true && current !== undefined && !current.ended) {\n    return body();\n  }\n\n  const scope: InvocationScope = { ended: false, open: new Set() };\n  const endInvocation = () => {\n    scope.ended = true;\n    for (const span of scope.open) {\n      // Fail open: this runs on the return path of every agent handler, so a\n      // span writer that throws must not take the handler's result with it,\n      // nor stop the remaining spans from closing.\n      try {\n        span.truncate();\n      } catch {\n        // Nothing useful to do with a broken span writer.\n      }\n    }\n    scope.open.clear();\n  };\n\n  return invocationScope.run(scope, () => {\n    let result: T;\n    try {\n      result = body();\n    } catch (cause: unknown) {\n      endInvocation();\n      throw cause;\n    }\n\n    if (isPromiseLike(result)) {\n      // SAFETY: T is promise-like here, so the settled promise is still a T.\n      return Promise.resolve(result).finally(endInvocation) as T;\n    }\n\n    endInvocation();\n    return result;\n  });\n}\n\n/** Creates a tracer from a runtime span capability. */\nexport function createTracer(runtime: SpanRuntime): AgentTracer {\n  return new RuntimeTracer(runtime);\n}\n\nclass RuntimeTracer implements AgentTracer {\n  constructor(private readonly runtime: SpanRuntime) {}\n\n  withSpan<T>(\n    name: string,\n    attributes: TraceAttributes,\n    run: (span: AgentSpan) => MaybePromise<T>,\n    lifetime?: SpanLifetime\n  ): T | Promise<T> {\n    return this.activate(name, attributes, (span) => {\n      // Ask before running: a span that opens and closes in one tick still\n      // needs to know whether that tick happened after its invocation ended.\n      const outOfBand =\n        lifetime?.boundToInvocation === true && bindToInvocation(span);\n      const result = run(span);\n      if (isPromiseLike(result)) {\n        if (outOfBand) {\n          span.truncate();\n        }\n        return Promise.resolve(result)\n          .catch((cause: unknown) => {\n            span.fail(cause);\n            throw cause;\n          })\n          .finally(() => {\n            span.close();\n          });\n      }\n\n      if (outOfBand) {\n        span.truncate();\n      }\n      span.close();\n      return result;\n    });\n  }\n\n  openSpan<T>(\n    name: string,\n    attributes: TraceAttributes,\n    activate: (span: AgentSpan) => T,\n    lifetime?: SpanLifetime\n  ): T {\n    if (!lifetime?.boundToInvocation) {\n      return this.activate(name, attributes, activate);\n    }\n\n    return this.activate(name, attributes, (span) => {\n      const invocationEnded = bindToInvocation(span);\n      try {\n        return activate(span);\n      } finally {\n        // Truncate only once `activate` has had its turn: callers that open\n        // with an empty attribute set and write the real one lazily (the AI\n        // operation span does, to stay cheap for untraced calls) would\n        // otherwise be closed before writing anything at all.\n        if (invocationEnded) {\n          span.truncate();\n        }\n      }\n    });\n  }\n\n  /**\n   * Shared scaffold: opens an active span, seeds its attributes, and fails the\n   * span on a thrown defect before rethrowing. The `body` decides the span's\n   * finishing policy (managed vs. caller-owned).\n   */\n  private activate<T>(\n    name: string,\n    attributes: TraceAttributes,\n    body: (span: ManagedSpan) => T\n  ): T {\n    return this.runtime.startActiveSpan(name, (writer) => {\n      setAttributes(writer, attributes);\n      const span = new ManagedSpan(writer);\n\n      try {\n        return body(span);\n      } catch (cause: unknown) {\n        span.fail(cause);\n        throw cause;\n      }\n    });\n  }\n}\n\nclass ManagedSpan implements AgentSpan {\n  #closed = false;\n\n  constructor(private readonly span: SpanWriter) {}\n\n  get isTraced(): boolean {\n    return this.span.isTraced;\n  }\n\n  /** INTERNAL: see {@link writeSpanAttributes}. */\n  writeAttributes(attributes: TraceAttributes): void {\n    if (this.#closed) {\n      return;\n    }\n\n    setAttributes(this.span, attributes);\n  }\n\n  finish(attributes: TraceAttributes = {}): void {\n    if (this.#closed) {\n      return;\n    }\n\n    setAttributes(this.span, attributes);\n    this.close();\n  }\n\n  fail(cause: unknown): void {\n    if (this.#closed) {\n      return;\n    }\n\n    if (isCancellation(cause)) {\n      // Cancellation is a control path, not a failure: OTel semconv leaves\n      // status Unset and records no error.type for cancellations, so aborted\n      // operations do not inflate error rates. The vendor marker is additive.\n      setAttributes(this.span, { \"cloudflare.agents.canceled\": true });\n    } else {\n      // Workers' custom Span API does not currently expose setStatus(). Do not\n      // invent an `otel.status_code` attribute: status is span state in OTel,\n      // not an attribute. error.type remains the standard queryable marker.\n      setAttributes(this.span, {\n        \"error.type\":\n          cause instanceof Error ? cause.name || \"Error\" : typeof cause\n      });\n    }\n\n    this.close();\n  }\n\n  close(): void {\n    if (this.#closed) {\n      return;\n    }\n\n    this.#closed = true;\n    this.span.end();\n  }\n\n  /**\n   * Closes a span whose work has not finished because its invocation is ending.\n   * The marker distinguishes \"this span has no tokens because the turn escaped\n   * its invocation\" from \"this span completed and reported none\".\n   */\n  truncate(): void {\n    if (this.#closed) {\n      return;\n    }\n\n    setAttributes(this.span, { \"cloudflare.agents.span.truncated\": true });\n    this.close();\n  }\n}\n\n/**\n * Registers a span for closure at the end of the current invocation, and\n * reports whether that invocation has already ended.\n *\n * Outside any scope the span keeps its natural lifetime: with no known\n * invocation boundary there is nothing to bound it to, and closing early would\n * discard finish attributes for no gain. Inside a scope that has already\n * ended — work resumed later while still carrying this context — the span\n * cannot outlive an invocation that is already gone, so the caller truncates\n * it as soon as it has written what it knows.\n */\nfunction bindToInvocation(span: ManagedSpan): boolean {\n  const scope = invocationScope.getStore();\n  if (scope === undefined) {\n    return false;\n  }\n\n  if (scope.ended) {\n    return true;\n  }\n\n  scope.open.add(span);\n  return false;\n}\n\n/**\n * INTERNAL: writes attributes onto an open managed span. Lets instrumentation\n * defer expensive attribute computation until after the isTraced check (span\n * names must exist at open time; attributes need not). Not part of the public\n * barrel surface.\n */\nexport function writeSpanAttributes(\n  span: AgentSpan,\n  attributes: TraceAttributes\n): void {\n  if (span instanceof ManagedSpan) {\n    span.writeAttributes(attributes);\n  }\n}\n\nfunction setAttributes(span: SpanWriter, attributes: TraceAttributes): void {\n  if (!span.isTraced) {\n    return;\n  }\n\n  // Fail-safe: a throwing writer must not leak the span or replace the\n  // application's original error with a telemetry one.\n  try {\n    for (const [key, value] of Object.entries(attributes)) {\n      if (value !== undefined) {\n        span.setAttribute(key, value);\n      }\n    }\n  } catch {\n    // Drop the attributes; the span still closes.\n  }\n}\n\nfunction isPromiseLike<T>(value: MaybePromise<T>): value is PromiseLike<T> {\n  return (\n    value !== null &&\n    value !== undefined &&\n    (typeof value === \"object\" || typeof value === \"function\") &&\n    \"then\" in value &&\n    typeof value.then === \"function\"\n  );\n}\n\n/**\n * Recognizes caller/runtime cancellation (an `AbortError`, e.g. from an aborted\n * `AbortSignal`) so it can be classified separately from genuine failures. A\n * `DOMException` named `AbortError` is not always an `Error` instance, so this\n * probes the `name` field structurally rather than via `instanceof`.\n */\nfunction isCancellation(cause: unknown): boolean {\n  return (\n    typeof cause === \"object\" &&\n    cause !== null &&\n    \"name\" in cause &&\n    cause.name === \"AbortError\"\n  );\n}\n","import * as cloudflareWorkers from \"cloudflare:workers\";\nimport { createTracer } from \"./tracer\";\nimport type { SpanRuntime, SpanWriter, AgentTracer } from \"./tracer\";\n\nconst noopSpan: SpanWriter = {\n  isTraced: false,\n  setAttribute() {},\n  end() {}\n};\n\nconst noopRuntime: SpanRuntime = {\n  startActiveSpan(_name, run) {\n    return run(noopSpan);\n  }\n};\n\n// Accessed via the namespace because this loads with the main `agents` entry.\n// Runtimes can omit `tracing` or expose it without `startActiveSpan`; both\n// degrade to no-op tracing instead of breaking Agent behavior.\nconst runtime = resolveCloudflareSpanRuntime(\n  (cloudflareWorkers as { tracing?: unknown }).tracing\n);\n\n/** Selects native Cloudflare tracing or a no-op for unsupported runtimes. */\nexport function resolveCloudflareSpanRuntime(runtime: unknown): SpanRuntime {\n  const candidate = runtime as Partial<SpanRuntime> | null | undefined;\n  return typeof candidate?.startActiveSpan === \"function\"\n    ? (candidate as SpanRuntime)\n    : noopRuntime;\n}\n\nexport const tracer: AgentTracer = createTracer(runtime);\n"],"mappings":"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"}