agents 0.20.0 → 0.21.0

package/docs/webhooks.md

@@ -7,56 +7,54 @@ Receive webhook events from external services and route them to dedicated agent
 ```typescript
 import { Agent, getAgentByName, routeAgentRequest } from "agents";
 
-// Agent that handles webhooks for a specific entity
+type GitHubWebhookPayload = {
+  repository?: { full_name?: string };
+};
+
+async function verifyGitHubWebhook(
+  rawBody: string,
+  signature: string | null,
+  secret: string
+): Promise<boolean> {
+  if (!signature || !/^sha256=[0-9a-f]{64}$/i.test(signature)) return false;
+
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  const signatureBytes = Uint8Array.from(
+    signature.slice("sha256=".length).match(/.{2}/g) ?? [],
+    (byte) => Number.parseInt(byte, 16)
+  );
+
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    signatureBytes,
+    encoder.encode(rawBody)
+  );
+}
+
 export class WebhookAgent extends Agent<Env> {
   async onRequest(request: Request): Promise<Response> {
     if (request.method !== "POST") {
       return new Response("Method not allowed", { status: 405 });
     }
 
-    // Verify the webhook signature
+    const rawBody = await request.text();
     const signature = request.headers.get("X-Hub-Signature-256");
-    const body = await request.text();
-
     if (
-      !(await this.verifySignature(body, signature, this.env.WEBHOOK_SECRET))
+      !(await verifyGitHubWebhook(rawBody, signature, this.env.WEBHOOK_SECRET))
     ) {
       return new Response("Invalid signature", { status: 401 });
     }
 
-    // Process the webhook payload
-    const payload = JSON.parse(body);
-    await this.processEvent(payload);
-
-    return new Response("OK", { status: 200 });
-  }
-
-  private async verifySignature(
-    payload: string,
-    signature: string | null,
-    secret: string
-  ): Promise<boolean> {
-    if (!signature) return false;
-
-    const encoder = new TextEncoder();
-    const key = await crypto.subtle.importKey(
-      "raw",
-      encoder.encode(secret),
-      { name: "HMAC", hash: "SHA-256" },
-      false,
-      ["sign"]
-    );
-
-    const signatureBytes = await crypto.subtle.sign(
-      "HMAC",
-      key,
-      encoder.encode(payload)
-    );
-    const expected = `sha256=${Array.from(new Uint8Array(signatureBytes))
-      .map((b) => b.toString(16).padStart(2, "0"))
-      .join("")}`;
-
-    return signature === expected;
+    await this.processEvent(JSON.parse(rawBody));
+    return new Response("OK");
   }
 
   private async processEvent(payload: unknown) {
@@ -64,19 +62,30 @@ export class WebhookAgent extends Agent<Env> {
   }
 }
 
-// Route webhooks to the right agent instance
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     const url = new URL(request.url);
 
-    // Webhook endpoint: POST /webhooks/:entityId
-    if (url.pathname.startsWith("/webhooks/") && request.method === "POST") {
-      const entityId = url.pathname.split("/")[2];
-      const agent = await getAgentByName(env.WebhookAgent, entityId);
+    if (url.pathname === "/webhooks/github" && request.method === "POST") {
+      const rawBody = await request.clone().text();
+      const signature = request.headers.get("X-Hub-Signature-256");
+      if (
+        !(await verifyGitHubWebhook(rawBody, signature, env.WEBHOOK_SECRET))
+      ) {
+        return new Response("Invalid signature", { status: 401 });
+      }
+
+      const payload = JSON.parse(rawBody) as GitHubWebhookPayload;
+      const repository = payload.repository?.full_name;
+      if (!repository) {
+        return new Response("Missing repository", { status: 400 });
+      }
+
+      const agentName = repository.toLowerCase().replace(/\//g, "-");
+      const agent = await getAgentByName(env.WebhookAgent, agentName);
       return agent.fetch(request);
     }
 
-    // Default routing for WebSocket connections
     return (
       (await routeAgentRequest(request, env)) ||
       new Response("Not found", { status: 404 })
@@ -131,7 +140,7 @@ Webhooks combined with agents enable powerful patterns where each external entit
 
 ## Routing Webhooks to Agents
 
-The key pattern is extracting an entity identifier from the webhook and using `getAgentByName()` to route to a dedicated agent instance.
+The key pattern is verifying the raw request before parsing it, then deriving the Agent identity from authenticated payload data. A body signature does not authenticate an unrelated URL segment or arbitrary header.
 
 ### Extract Entity from Payload
 
@@ -140,19 +149,23 @@ Most webhooks include an identifier in the payload:
 ```typescript
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
     if (request.method === "POST" && url.pathname === "/webhooks/github") {
-      const payload = await request.clone().json();
+      const rawBody = await request.clone().text();
+      const signature = request.headers.get("X-Hub-Signature-256");
+      if (
+        !(await verifyGitHubWebhook(rawBody, signature, env.WEBHOOK_SECRET))
+      ) {
+        return new Response("Invalid signature", { status: 401 });
+      }
 
-      // Extract entity ID from payload
-      const repoFullName = payload.repository?.full_name;
-      if (!repoFullName) {
+      const payload = JSON.parse(rawBody) as GitHubWebhookPayload;
+      const repository = payload.repository?.full_name;
+      if (!repository) {
         return new Response("Missing repository", { status: 400 });
       }
 
-      // Sanitize for use as agent name
-      const agentName = repoFullName.toLowerCase().replace(/\//g, "-");
-
-      // Route to dedicated agent
+      const agentName = repository.toLowerCase().replace(/\//g, "-");
       const agent = await getAgentByName(env.RepoAgent, agentName);
       return agent.fetch(request);
     }
@@ -160,69 +173,21 @@ export default {
 };
 ```
 
-### Extract Entity from URL
-
-Alternatively, include the entity ID in the webhook URL:
-
-```typescript
-// Webhook URL: https://your-worker.dev/webhooks/stripe/cus_123456
-if (url.pathname.startsWith("/webhooks/stripe/")) {
-  const customerId = url.pathname.split("/")[3]; // "cus_123456"
-  const agent = await getAgentByName(env.StripeAgent, customerId);
-  return agent.fetch(request);
-}
-```
+### Validate Entity IDs in URLs
 
-### Extract Entity from Headers
+A provider's body signature does not authenticate the webhook URL. If the URL includes an entity ID, compare it with the corresponding identity from the verified provider payload and reject a mismatch before calling `getAgentByName()`.
 
-Some services include identifiers in headers:
+### Derive Slack Identity from the Verified Body
 
-```typescript
-// Slack sends workspace info in headers
-const teamId = request.headers.get("X-Slack-Team-Id");
-if (teamId) {
-  const agent = await getAgentByName(env.SlackAgent, teamId);
-  return agent.fetch(request);
-}
-```
+Slack does not send an authenticated `X-Slack-Team-Id` routing header. Validate Slack's timestamped signature and replay window against the raw body, then read `team_id` from the verified event or form body.
 
 ## Signature Verification
 
-Always verify webhook signatures to ensure requests are authentic. Most providers use HMAC-SHA256.
+Always verify webhook signatures before trusting or processing the payload.
 
-### HMAC-SHA256 Pattern
+### GitHub HMAC-SHA256 Pattern
 
-```typescript
-async function verifySignature(
-  payload: string,
-  signature: string | null,
-  secret: string
-): Promise<boolean> {
-  if (!signature) return false;
-
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-
-  const signatureBytes = await crypto.subtle.sign(
-    "HMAC",
-    key,
-    encoder.encode(payload)
-  );
-
-  const expected = `sha256=${Array.from(new Uint8Array(signatureBytes))
-    .map((b) => b.toString(16).padStart(2, "0"))
-    .join("")}`;
-
-  // Use timing-safe comparison in production
-  return signature === expected;
-}
-```
+The Quick Start's `verifyGitHubWebhook()` helper verifies GitHub's `sha256=<hex>` signature over the raw body with `crypto.subtle.verify()`. This format is GitHub-specific. Other providers use different signature encodings, signed inputs, timestamp checks, and replay protections; follow the provider documentation linked under [Common Webhook Providers](#common-webhook-providers).
 
 ### Provider-Specific Headers
 
@@ -238,7 +203,7 @@ async function verifySignature(
 
 ### The onRequest Handler
 
-Use `onRequest()` to handle incoming webhooks in your agent:
+Use `onRequest()` to handle incoming webhooks in your agent. If the Worker has not already verified the request, verify it before parsing the body. This example reuses the Quick Start's `verifyGitHubWebhook()` helper:
 
 ```typescript
 export class WebhookAgent extends Agent<Env, MyState> {
@@ -248,14 +213,16 @@ export class WebhookAgent extends Agent<Env, MyState> {
       return new Response("Method not allowed", { status: 405 });
     }
 
-    // 2. Get event type from headers
-    const eventType = request.headers.get("X-Event-Type");
+    // 2. Get the GitHub event type
+    const eventType = request.headers.get("X-GitHub-Event") ?? "unknown";
 
-    // 3. Verify signature
-    const signature = request.headers.get("X-Signature");
+    // 3. Verify the GitHub signature
+    const signature = request.headers.get("X-Hub-Signature-256");
     const body = await request.text();
 
-    if (!(await this.verifySignature(body, signature))) {
+    if (
+      !(await verifyGitHubWebhook(body, signature, this.env.WEBHOOK_SECRET))
+    ) {
       return new Response("Invalid signature", { status: 401 });
     }
 
@@ -462,35 +429,41 @@ fibers retain status, dedupe provider retries, and let `onFiberRecovered()` or
 
 ### Multi-Provider Routing
 
-Handle webhooks from multiple services in one worker:
+Keep provider-specific verification and parsing behind one typed seam. Its implementation must validate the raw request according to the provider documentation linked under [Common Webhook Providers](#common-webhook-providers), then derive `agentName` only from the verified body.
 
 ```typescript
+type VerifiedWebhook =
+  | { provider: "github"; agentName: string }
+  | { provider: "stripe"; agentName: string }
+  | { provider: "slack"; agentName: string };
+
+declare function verifyAndParseWebhook(
+  request: Request,
+  env: Env
+): Promise<VerifiedWebhook | null>;
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     const url = new URL(request.url);
-
-    if (request.method === "POST") {
-      // GitHub webhooks
-      if (url.pathname.startsWith("/webhooks/github/")) {
-        const payload = await request.clone().json();
-        const repoName = payload.repository?.full_name?.replace("/", "-");
-        const agent = await getAgentByName(env.GitHubAgent, repoName);
-        return agent.fetch(request);
-      }
-
-      // Stripe webhooks
-      if (url.pathname.startsWith("/webhooks/stripe/")) {
-        const payload = await request.clone().json();
-        const customerId = payload.data?.object?.customer;
-        const agent = await getAgentByName(env.StripeAgent, customerId);
-        return agent.fetch(request);
+    if (request.method === "POST" && url.pathname.startsWith("/webhooks/")) {
+      const verified = await verifyAndParseWebhook(request.clone(), env);
+      if (!verified) {
+        return new Response("Invalid signature", { status: 401 });
       }
 
-      // Slack webhooks
-      if (url.pathname === "/webhooks/slack") {
-        const teamId = request.headers.get("X-Slack-Team-Id");
-        const agent = await getAgentByName(env.SlackAgent, teamId);
-        return agent.fetch(request);
+      switch (verified.provider) {
+        case "github":
+          return (
+            await getAgentByName(env.GitHubAgent, verified.agentName)
+          ).fetch(request);
+        case "stripe":
+          return (
+            await getAgentByName(env.StripeAgent, verified.agentName)
+          ).fetch(request);
+        case "slack":
+          return (
+            await getAgentByName(env.SlackAgent, verified.agentName)
+          ).fetch(request);
       }
     }
 

package/docs/workflows.md

@@ -246,7 +246,11 @@ const instanceId = await this.runWorkflow(
   {
     id: "custom-id", // optional - auto-generated if not provided
     metadata: { userId: "user-456", priority: "high" }, // optional - for querying
-    agentBinding: "MyAgent" // optional - auto-detected from class name if not provided
+    agentBinding: "MyAgent", // optional - auto-detected from class name if not provided
+    retention: {
+      successRetention: "1 day",
+      errorRetention: "7 days"
+    }
   }
 );
 ```
@@ -258,6 +262,10 @@ const instanceId = await this.runWorkflow(
 - `options.id` - Custom workflow ID (auto-generated if not provided)
 - `options.metadata` - Optional metadata stored for querying (not passed to workflow)
 - `options.agentBinding` - Agent binding name (auto-detected from class name if not provided). When called from a sub-agent, this is the root Agent binding name.
+- [`options.retention`](https://developers.cloudflare.com/workflows/build/workers-api/#workflowinstancecreateoptions) - Workflow retention passed unchanged to
+  `Workflow.create()`.
+  Use `successRetention` for successful instances and `errorRetention` for
+  errored or terminated instances.
 
 **Returns:** Workflow instance ID
 

package/package.json

@@ -9,7 +9,7 @@
     "durable objects"
   ],
   "type": "module",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -31,22 +31,23 @@
     "esbuild": "^0.28.1",
     "mimetext": "^3.0.28",
     "nanoid": "^5.1.16",
-    "partyserver": "^0.5.8",
+    "partyserver": "^0.5.9",
     "partysocket": "1.3.0",
     "yaml": "^2.9.0",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
     "@ai-sdk/react": "^4.0.0",
+    "@ai-sdk/valibot": "3.0.6",
     "@cloudflare/codemode": "^0.5.1",
-    "@modelcontextprotocol/client": "2.0.0-beta.5",
+    "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/conformance-v2": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.10",
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "@modelcontextprotocol/server": "2.0.0-beta.5",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@tanstack/ai": "0.38.0",
     "@types/react": "^19.2.17",
     "@types/yargs": "^17.0.35",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@valibot/to-json-schema": "1.3.0",
     "@x402/core": "^2.17.0",
     "@x402/evm": "^2.17.0",
     "ai": "^7.0.0",
@@ -54,15 +55,15 @@
     "glob": "^13.0.6",
     "just-bash": "^3.0.2",
     "react": "^19.2.7",
-    "vitest-browser-react": "^2.2.0",
+    "valibot": "1.4.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@ai-sdk/react": "^3.0.0 || ^4.0.0",
     "@cloudflare/codemode": ">=0.5.0",
-    "@modelcontextprotocol/client": "2.0.0-beta.5",
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "@modelcontextprotocol/server": "2.0.0-beta.5",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@tanstack/ai": ">=0.10.2 <1.0.0",
     "@x402/core": "^2.0.0",
     "@x402/evm": "^2.0.0",
@@ -98,6 +99,9 @@
     "just-bash": {
       "optional": true
     },
+    "react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
@@ -199,6 +203,11 @@
       "import": "./dist/chat/index.js",
       "require": "./dist/chat/index.js"
     },
+    "./chat/transport": {
+      "types": "./dist/chat/transport.d.ts",
+      "import": "./dist/chat/transport.js",
+      "require": "./dist/chat/transport.js"
+    },
     "./chat/react": {
       "types": "./dist/chat/react.d.ts",
       "import": "./dist/chat/react.js",

package/dist/cloudflare-BldFV0Pa.js

@@ -1,117 +0,0 @@
-import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
-import * as cloudflareWorkers from "cloudflare:workers";
-//#region src/observability/tracing/tracer.ts
-/** Creates a tracer from a runtime span capability. */
-function createTracer(runtime) {
-	return new RuntimeTracer(runtime);
-}
-var RuntimeTracer = class {
-	constructor(runtime) {
-		this.runtime = runtime;
-	}
-	withSpan(name, attributes, run) {
-		return this.activate(name, attributes, (span) => {
-			const result = run(span);
-			if (isPromiseLike(result)) return Promise.resolve(result).catch((cause) => {
-				span.fail(cause);
-				throw cause;
-			}).finally(() => {
-				span.close();
-			});
-			span.close();
-			return result;
-		});
-	}
-	openSpan(name, attributes, activate) {
-		return this.activate(name, attributes, activate);
-	}
-	/**
-	* Shared scaffold: opens an active span, seeds its attributes, and fails the
-	* span on a thrown defect before rethrowing. The `body` decides the span's
-	* finishing policy (managed vs. caller-owned).
-	*/
-	activate(name, attributes, body) {
-		return this.runtime.startActiveSpan(name, (writer) => {
-			setAttributes(writer, attributes);
-			const span = new ManagedSpan(writer);
-			try {
-				return body(span);
-			} catch (cause) {
-				span.fail(cause);
-				throw cause;
-			}
-		});
-	}
-};
-var _closed = /* @__PURE__ */ new WeakMap();
-var ManagedSpan = class {
-	constructor(span) {
-		this.span = span;
-		_classPrivateFieldInitSpec(this, _closed, false);
-	}
-	get isTraced() {
-		return this.span.isTraced;
-	}
-	/** INTERNAL: see {@link writeSpanAttributes}. */
-	writeAttributes(attributes) {
-		if (_classPrivateFieldGet2(_closed, this)) return;
-		setAttributes(this.span, attributes);
-	}
-	finish(attributes = {}) {
-		if (_classPrivateFieldGet2(_closed, this)) return;
-		setAttributes(this.span, attributes);
-		this.close();
-	}
-	fail(cause) {
-		if (_classPrivateFieldGet2(_closed, this)) return;
-		if (isCancellation(cause)) setAttributes(this.span, { "cloudflare.agents.canceled": true });
-		else setAttributes(this.span, { "error.type": cause instanceof Error ? cause.name || "Error" : typeof cause });
-		this.close();
-	}
-	close() {
-		if (_classPrivateFieldGet2(_closed, this)) return;
-		_classPrivateFieldSet2(_closed, this, true);
-		this.span.end();
-	}
-};
-/**
-* INTERNAL: writes attributes onto an open managed span. Lets instrumentation
-* defer expensive attribute computation until after the isTraced check (span
-* names must exist at open time; attributes need not). Not part of the public
-* barrel surface.
-*/
-function writeSpanAttributes(span, attributes) {
-	if (span instanceof ManagedSpan) span.writeAttributes(attributes);
-}
-function setAttributes(span, attributes) {
-	if (!span.isTraced) return;
-	try {
-		for (const [key, value] of Object.entries(attributes)) if (value !== void 0) span.setAttribute(key, value);
-	} catch {}
-}
-function isPromiseLike(value) {
-	return value !== null && value !== void 0 && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
-}
-/**
-* Recognizes caller/runtime cancellation (an `AbortError`, e.g. from an aborted
-* `AbortSignal`) so it can be classified separately from genuine failures. A
-* `DOMException` named `AbortError` is not always an `Error` instance, so this
-* probes the `name` field structurally rather than via `instanceof`.
-*/
-function isCancellation(cause) {
-	return typeof cause === "object" && cause !== null && "name" in cause && cause.name === "AbortError";
-}
-//#endregion
-//#region src/observability/tracing/cloudflare.ts
-const noopSpan = {
-	isTraced: false,
-	setAttribute() {},
-	end() {}
-};
-const tracer = createTracer(cloudflareWorkers.tracing ?? { startActiveSpan(_name, run) {
-	return run(noopSpan);
-} });
-//#endregion
-export { writeSpanAttributes as n, tracer as t };
-
-//# sourceMappingURL=cloudflare-BldFV0Pa.js.map

package/dist/cloudflare-BldFV0Pa.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cloudflare-BldFV0Pa.js","names":[],"sources":["../src/observability/tracing/tracer.ts","../src/observability/tracing/cloudflare.ts"],"sourcesContent":["/** 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/** 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  ): 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  ): 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\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  ): T | Promise<T> {\n    return this.activate(name, attributes, (span) => {\n      const result = run(span);\n      if (isPromiseLike(result)) {\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      span.close();\n      return result;\n    });\n  }\n\n  openSpan<T>(\n    name: string,\n    attributes: TraceAttributes,\n    activate: (span: AgentSpan) => T\n  ): T {\n    return this.activate(name, attributes, activate);\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/**\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 so runtimes that predate the `tracing` export\n// degrade to a no-op tracer instead of failing at module-link time — this\n// module loads with the main `agents` entry, not just for tracing users.\nconst runtime: SpanRuntime =\n  (cloudflareWorkers as { tracing?: SpanRuntime }).tracing ?? noopRuntime;\n\nexport const tracer: AgentTracer = createTracer(runtime);\n"],"mappings":";;;;AAsEA,SAAgB,aAAa,SAAmC;CAC9D,OAAO,IAAI,cAAc,OAAO;AAClC;AAEA,IAAM,gBAAN,MAA2C;CACzC,YAAY,SAAuC;EAAtB,KAAA,UAAA;CAAuB;CAEpD,SACE,MACA,YACA,KACgB;EAChB,OAAO,KAAK,SAAS,MAAM,aAAa,SAAS;GAC/C,MAAM,SAAS,IAAI,IAAI;GACvB,IAAI,cAAc,MAAM,GACtB,OAAO,QAAQ,QAAQ,MAAM,CAAC,CAC3B,OAAO,UAAmB;IACzB,KAAK,KAAK,KAAK;IACf,MAAM;GACR,CAAC,CAAC,CACD,cAAc;IACb,KAAK,MAAM;GACb,CAAC;GAGL,KAAK,MAAM;GACX,OAAO;EACT,CAAC;CACH;CAEA,SACE,MACA,YACA,UACG;EACH,OAAO,KAAK,SAAS,MAAM,YAAY,QAAQ;CACjD;;;;;;CAOA,SACE,MACA,YACA,MACG;EACH,OAAO,KAAK,QAAQ,gBAAgB,OAAO,WAAW;GACpD,cAAc,QAAQ,UAAU;GAChC,MAAM,OAAO,IAAI,YAAY,MAAM;GAEnC,IAAI;IACF,OAAO,KAAK,IAAI;GAClB,SAAS,OAAgB;IACvB,KAAK,KAAK,KAAK;IACf,MAAM;GACR;EACF,CAAC;CACH;AACF;;AAEA,IAAM,cAAN,MAAuC;CAGrC,YAAY,MAAmC;EAAlB,KAAA,OAAA;4CAFnB,KAAA;CAEsC;CAEhD,IAAI,WAAoB;EACtB,OAAO,KAAK,KAAK;CACnB;;CAGA,gBAAgB,YAAmC;EACjD,IAAA,uBAAA,SAAI,IAAA,GACF;EAGF,cAAc,KAAK,MAAM,UAAU;CACrC;CAEA,OAAO,aAA8B,CAAC,GAAS;EAC7C,IAAA,uBAAA,SAAI,IAAA,GACF;EAGF,cAAc,KAAK,MAAM,UAAU;EACnC,KAAK,MAAM;CACb;CAEA,KAAK,OAAsB;EACzB,IAAA,uBAAA,SAAI,IAAA,GACF;EAGF,IAAI,eAAe,KAAK,GAItB,cAAc,KAAK,MAAM,EAAE,8BAA8B,KAAK,CAAC;OAK/D,cAAc,KAAK,MAAM,EACvB,cACE,iBAAiB,QAAQ,MAAM,QAAQ,UAAU,OAAO,MAC5D,CAAC;EAGH,KAAK,MAAM;CACb;CAEA,QAAc;EACZ,IAAA,uBAAA,SAAI,IAAA,GACF;EAGF,uBAAA,SAAA,MAAe,IAAA;EACf,KAAK,KAAK,IAAI;CAChB;AACF;;;;;;;AAQA,SAAgB,oBACd,MACA,YACM;CACN,IAAI,gBAAgB,aAClB,KAAK,gBAAgB,UAAU;AAEnC;AAEA,SAAS,cAAc,MAAkB,YAAmC;CAC1E,IAAI,CAAC,KAAK,UACR;CAKF,IAAI;EACF,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,UAAU,GAClD,IAAI,UAAU,KAAA,GACZ,KAAK,aAAa,KAAK,KAAK;CAGlC,QAAQ,CAER;AACF;AAEA,SAAS,cAAiB,OAAiD;CACzE,OACE,UAAU,QACV,UAAU,KAAA,MACT,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,UAAU,SACV,OAAO,MAAM,SAAS;AAE1B;;;;;;;AAQA,SAAS,eAAe,OAAyB;CAC/C,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,MAAM,SAAS;AAEnB;;;ACpPA,MAAM,WAAuB;CAC3B,UAAU;CACV,eAAe,CAAC;CAChB,MAAM,CAAC;AACT;AAcA,MAAa,SAAsB,aAFhC,kBAAgD,WAAW,EAT5D,gBAAgB,OAAO,KAAK;CAC1B,OAAO,IAAI,QAAQ;AACrB,EAOsE,CAEjB"}