agents 0.23.0 → 0.24.0

package/docs/queue.md

@@ -1,218 +1,157 @@
-# Queue System
+# Queue
 
-The Agents SDK provides a built-in queue system that allows you to schedule tasks for asynchronous execution. This is particularly useful for background processing, delayed operations, and managing workloads that don't need immediate execution.
+Durable background work for an Agent or any Lifecycle Object. A queued item
+persists a callback name and a payload, runs from the Durable Object's alarm
+loop one item at a time in push order, retries when the callback throws, and
+survives the object leaving memory.
 
-## Overview
+## Queue Lifecycle capability
 
-The queue system is built into the base `Agent` class. Tasks are stored in a SQLite table and processed automatically in FIFO (First In, First Out) order.
+> **Experimental.** The `Queue` capability and the `agents/lifecycle` surface
+> it builds on may change between releases. Agent's established queue methods
+> (`this.queue()` and friends) are stable.
 
-## QueueItem Type
+`Queue` is a reusable Lifecycle capability. A plain Lifecycle Object can
+install it without extending `Agent`:
 
 ```typescript
-export type QueueItem<T = string> = {
-  id: string; // Unique identifier for the queued task
-  payload: T; // Data to pass to the callback function
-  callback: keyof Agent<unknown>; // Name of the method to call
-  created_at: number; // Timestamp when the task was created
-  retry?: RetryOptions; // Retry options (if configured)
-};
-```
-
-## Core Methods
-
-### queue()
-
-Adds a task to the queue for future execution.
-
-```typescript
-async queue<T = unknown>(
-  callback: keyof this,
-  payload: T,
-  options?: { retry?: RetryOptions }
-): Promise<string>
-```
-
-**Parameters:**
-
-- `callback`: The name of the method to call when processing the task
-- `payload`: Data to pass to the callback method
-- `options.retry`: Optional retry configuration. See [Retries](./retries.md) for details.
-
-**Returns:** The unique ID of the queued task
-
-**Example:**
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { Queue, type QueueItem } from "agents/queue";
 
-```typescript
-class MyAgent extends Agent {
-  async processEmail(data: { email: string; subject: string }) {
-    // Process the email
-    console.log(`Processing email: ${data.subject}`);
-  }
+export class UploadObject extends DurableObject<Env> {
+  readonly queue = new Queue({
+    callbacks: {
+      processUpload: (
+        payload: { fileName: string },
+        item: QueueItem<{ fileName: string }>
+      ) => {
+        console.log(item.id, payload.fileName);
+      }
+    }
+  });
 
-  async onMessage(message: string) {
-    // Queue an email processing task
-    const taskId = await this.queue("processEmail", {
-      email: "user@example.com",
-      subject: "Welcome!"
-    });
+  readonly lifecycle = Lifecycle.install(this).use(this.queue);
 
-    console.log(`Queued task with ID: ${taskId}`);
+  async enqueueUpload(fileName: string): Promise<string> {
+    const item = await this.queue.push("processUpload", { fileName });
+    return item.id;
   }
 }
 ```
 
-### dequeue()
-
-Removes a specific task from the queue by ID.
-
-```typescript
-dequeue(id: string): void
-```
-
-**Parameters:**
-
-- `id`: The ID of the task to remove
-
-**Example:**
-
-```typescript
-// Remove a specific task
-agent.dequeue("abc123def");
-```
-
-### dequeueAll()
-
-Removes all tasks from the queue.
-
-```typescript
-dequeueAll(): void
-```
-
-**Example:**
-
-```typescript
-// Clear the entire queue
-agent.dequeueAll();
-```
-
-### dequeueAllByCallback()
-
-Removes all tasks that match a specific callback method.
-
-```typescript
-dequeueAllByCallback(callback: string): void
-```
-
-**Parameters:**
-
-- `callback`: Name of the callback method
-
-**Example:**
-
-```typescript
-// Remove all email processing tasks
-agent.dequeueAllByCallback("processEmail");
-```
-
-### getQueue()
-
-Retrieves a specific queued task by ID.
-
-```typescript
-getQueue(id: string): QueueItem<string> | undefined
-```
-
-**Parameters:**
+Queue owns no storage of its own. Each item is one job in the Lifecycle job
+queue, due immediately; Lifecycle owns the physical Durable Object alarm, the
+alarm event loop, retry policy, the deadman pre-arm, and the memory-limit
+circuit breaker. See [Durable Object lifecycle](./lifecycle.md#the-job-queue).
 
-- `id`: The ID of the task to retrieve
+Queue's API is small: callbacks are registered by name in the constructor,
+`push()` creates items typed against that registration, and `get()`,
+`list()`, `cancel()`, and `cancelAll()` manage them. All of these are
+asynchronous and work inside routed sub-agents.
 
-**Returns:** The QueueItem with parsed payload or undefined if not found
+Queue Lifecycle hooks run without ambient host context. Registered callbacks
+are user code, so they run inside the host invocation context with the
+Lifecycle Object available through `getCurrentAgent()`.
 
-**Note:** The payload is automatically parsed from JSON before being returned
-
-**Example:**
-
-```typescript
-const task = agent.getQueue("abc123def");
-if (task) {
-  console.log(`Task callback: ${task.callback}`);
-  console.log(`Task payload:`, task.payload);
-}
-```
+### `new Queue(options?)`
 
-### getQueues()
+| Option      | Description                                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `callbacks` | Named callbacks `(payload, item) => unknown`. Register in a field initializer so names re-bind on every wake. |
+| `retry`     | Default retry policy: `{ maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 3000 }`. See [Retries](./retries.md).  |
+| `onError`   | Observes an item's terminal failure after its attempts are exhausted. Runs without host context.              |
 
-Retrieves all queued tasks that match a specific key-value pair in their payload.
+### `push(callback, payload?, options?)`
 
-```typescript
-getQueues(key: string, value: string): QueueItem<string>[]
-```
+Queues one item and returns the `QueueItem`. The item is durable before the
+returned promise resolves, and it runs from the next alarm, so the caller
+never waits for the callback.
 
-**Parameters:**
+- `options.retry` overrides the Queue's retry policy for this item.
+- `options.id` sets a stable id. A push with an existing id replaces that
+  item in place, keeping its position in the queue (and superseding a
+  dispatch of it still in flight); use it for idempotent enqueues keyed by
+  your own identifier.
 
-- `key`: The key to filter by in the payload
-- `value`: The value to match
+Once the Lifecycle has started, the item row is written synchronously before
+`push()` returns its promise, so a push made in the same synchronous block as
+your own SQL writes commits atomically with them.
 
-**Returns:** Array of matching QueueItem objects
+### `get(id)`, `list(criteria?)`, `cancel(id)`, `cancelAll(callback?)`
 
-**Note:** This method fetches all queue items and filters them in memory by parsing each payload and checking if the specified key matches the value
+`list()` returns pending items in push order; `{ callback }` filters by
+callback name. `cancel()` returns whether an item was removed; `cancelAll()`
+returns how many were.
 
-**Example:**
+### QueueItem
 
 ```typescript
-// Find all tasks for a specific user
-const userTasks = await agent.getQueues("userId", "12345");
+type QueueItem<T = unknown> = {
+  id: string; // Unique identifier
+  callback: string; // Callback name
+  payload: T; // Data passed to the callback
+  createdAt: number; // Unix timestamp in seconds
+  retry?: RetryOptions; // Resolved retry policy
+};
 ```
 
-## How Queue Processing Works
-
-1. **Validation**: When calling `queue()`, the method validates that the callback exists as a function on the agent
-2. **Automatic Processing**: After queuing, the system automatically attempts to flush the queue
-3. **FIFO Order**: Tasks are processed in the order they were created (`created_at` timestamp)
-4. **Context Preservation**: Each queued task runs with the same agent context (connection, request, email)
-5. **Automatic Retries**: If a callback fails, it is retried with exponential backoff (configurable per task)
-6. **Automatic Dequeue**: Tasks are removed from the queue after successful execution or after all retry attempts are exhausted
-7. **Error Handling**: If a callback method does not exist at execution time, an error is logged and the task is skipped
-8. **Persistence**: Tasks are stored in the `cf_agents_queues` table and survive agent restarts
+## Using the queue through Agent
 
-## Queue Callback Methods
-
-When defining callback methods for queued tasks, they must follow this signature:
-
-```typescript
-async callbackMethod(payload: unknown, queueItem: QueueItem<string>): Promise<void>
-```
-
-**Example:**
+`Agent` installs a `Queue` and resolves callback names to its own methods, so
+`this.queue("methodName", payload)` keeps working with no registration:
 
 ```typescript
 class MyAgent extends Agent {
-  async sendNotification(
-    payload: { userId: string; message: string },
-    queueItem: QueueItem<string>
+  async processEmail(
+    payload: { email: string; subject: string },
+    item: QueueItem<{ email: string; subject: string }>
   ) {
-    console.log(`Processing task ${queueItem.id}`);
-    console.log(
-      `Sending notification to user ${payload.userId}: ${payload.message}`
-    );
-
-    // Your notification logic here
-    await this.notificationService.send(payload.userId, payload.message);
+    console.log(`Processing ${item.id}: ${payload.subject}`);
   }
 
-  async onUserSignup(userData: any) {
-    // Queue a welcome notification
-    await this.queue("sendNotification", {
-      userId: userData.id,
-      message: "Welcome to our platform!"
+  async onMessage(message: string) {
+    const id = await this.queue("processEmail", {
+      email: "user@example.com",
+      subject: "Welcome!"
     });
+    console.log(`Queued task ${id}`);
   }
 }
 ```
 
-## Use Cases
-
-### Background Processing
+| Method                               | Description                                                         |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `queue(callback, payload, options?)` | Queue a method by name. Returns the item id. Accepts `retry`, `id`. |
+| `dequeue(id)`                        | Remove a pending item. Resolves to whether one was removed.         |
+| `dequeueAll()`                       | Remove every pending item. Resolves to the count.                   |
+| `dequeueAllByCallback(callback)`     | Remove every pending item for one callback. Resolves to the count.  |
+| `getQueue(id)`                       | Read a pending item.                                                |
+| `getQueues(key, value)`              | Pending items whose payload has `key` equal to `value`.             |
+
+## How queue processing works
+
+1. **Validation**: `queue()` checks the callback exists and validates any
+   retry options. Invalid input throws immediately.
+2. **Durable first**: the item is a row in the `cf_agents_jobs` job queue
+   before `queue()` resolves. Items created before this capability existed
+   are migrated out of the old `cf_agents_queues` table on the next start.
+3. **Alarm-driven**: every push re-arms the Durable Object alarm. The
+   Lifecycle event loop runs due items in push order, awaiting each callback
+   before starting the next, in a fresh invocation rather than the request
+   that queued them.
+4. **Retries**: a throwing callback is retried with exponential backoff per
+   its retry policy, emitting `queue:retry` on each extra attempt.
+5. **Terminal failure**: after the last attempt the item is dropped, a
+   `queue:error` event is emitted, and Agent's `onError` (or the Queue's
+   `onError` option) observes the error.
+6. **Recovery**: an isolate that dies mid-callback wakes again on the
+   Lifecycle deadman alarm and resumes the queue, so callbacks should be
+   idempotent.
+
+## Use cases
+
+Queue work that must not block the current request or WebSocket message:
 
 ```typescript
 class DataProcessor extends Agent {
@@ -221,52 +160,31 @@ class DataProcessor extends Agent {
     await this.notifyUser(data.userId, results);
   }
 
-  async onDataUpload(uploadData: any) {
-    // Queue the processing instead of doing it synchronously
+  async onDataUpload(uploadData: { id: string; userId: string }) {
     await this.queue("processLargeDataset", {
       datasetId: uploadData.id,
       userId: uploadData.userId
     });
-
     return { message: "Data upload received, processing started" };
   }
 }
 ```
 
-### Delayed Operations
-
-```typescript
-class ReminderAgent extends Agent {
-  async sendReminder(data: { userId: string; message: string }) {
-    await this.emailService.send(data.userId, data.message);
-  }
-
-  async scheduleReminder(userId: string, message: string, delayMs: number) {
-    // Note: For true delayed execution, combine with the scheduling system
-    // This example shows queueing for later processing
-    await this.queue("sendReminder", { userId, message });
-  }
-}
-```
-
-### Batch Operations
+Split large requests into batches that run one after another:
 
 ```typescript
 class BatchProcessor extends Agent {
-  async processBatch(data: { items: any[]; batchId: string }) {
+  async processBatch(data: { items: unknown[]; batchId: string }) {
     for (const item of data.items) {
       await this.processItem(item);
     }
-    console.log(`Completed batch ${data.batchId}`);
   }
 
-  async onLargeRequest(items: any[]) {
-    // Split large requests into smaller batches
+  async onLargeRequest(items: unknown[]) {
     const batchSize = 10;
     for (let i = 0; i < items.length; i += batchSize) {
-      const batch = items.slice(i, i + batchSize);
       await this.queue("processBatch", {
-        items: batch,
+        items: items.slice(i, i + batchSize),
         batchId: `batch-${i / batchSize + 1}`
       });
     }
@@ -274,56 +192,32 @@ class BatchProcessor extends Agent {
 }
 ```
 
-## Best Practices
+For work that should run at a specific time or on a schedule, use
+[Scheduling](./scheduling.md) instead. Both ride the same Lifecycle job queue.
 
-1. **Keep Payloads Small**: Payloads are JSON-serialized and stored in the database
-2. **Idempotent Operations**: Design callback methods to be safe to retry
-3. **Error Handling**: Include proper error handling in callback methods
-4. **Monitoring**: Use logging to track queue processing
-5. **Cleanup**: Regularly clean up completed or failed tasks if needed
+## Best practices
 
-## Error Handling and Retries
+1. **Keep payloads small**: payloads are JSON-serialized into the job row.
+2. **Idempotent callbacks**: an item can run again after an isolate reset.
+3. **Bounded callbacks**: the event loop awaits each callback, so a long one
+   delays every other job on the object. Detach unbounded work and return.
+4. **Stable ids for dedupe**: pass `id` when the same logical task may be
+   queued more than once.
 
-Queued tasks are automatically retried on failure with exponential backoff. The default is 3 attempts. You can customize this per task:
+## Error handling and retries
 
 ```typescript
-// Retry up to 5 times with custom backoff
 await this.queue("reliableTask", payload, {
   retry: { maxAttempts: 5, baseDelayMs: 500 }
 });
 ```
 
-If you need custom error handling in the callback:
-
-```typescript
-class RobustAgent extends Agent {
-  async reliableTask(payload: { data: string }, queueItem: QueueItem<string>) {
-    try {
-      await this.doSomethingRisky(payload);
-    } catch (error) {
-      console.error(`Task ${queueItem.id} failed:`, error);
-      // The retry system will catch this error and retry automatically
-      throw error;
-    }
-  }
-}
-```
-
-See [Retries](./retries.md) for full documentation on retry options and patterns.
-
-## Integration with Other Features
-
-The queue system works seamlessly with other Agent SDK features:
-
-- **State Management**: Access agent state within queued callbacks
-- **Scheduling**: Combine with `schedule()` for time-based queue processing
-- **Retries**: Built-in retry with exponential backoff. See [Retries](./retries.md).
-- **Context**: Queued tasks maintain the original request context
-- **Database**: Uses the same database as other agent data
+See [Retries](./retries.md) for full documentation on retry options, and
+[Observability](./observability.md) for the `queue:create`, `queue:retry`,
+and `queue:error` events.
 
 ## Limitations
 
-- Tasks are processed sequentially, not in parallel
-- No priority system (FIFO only)
-- Queue processing happens during agent execution, not as separate background jobs
-- Failed tasks are dequeued after all retry attempts are exhausted (no dead-letter queue)
+- Items run sequentially, not in parallel.
+- No priority system (FIFO only).
+- Failed items are dropped after all retry attempts (no dead-letter queue).

package/docs/retries.md

@@ -188,7 +188,7 @@ await this.queue("processWebhook", webhookData, {
 });
 ```
 
-If the callback throws, it is retried before the task is dequeued. After all attempts are exhausted, the task is dequeued and the error is logged.
+If the callback throws, it is retried before the item is removed. After all attempts are exhausted, the item is dropped, a `queue:error` event is emitted, and the error is logged.
 
 ## Validation
 

package/docs/sub-agents.md

@@ -4,7 +4,7 @@ Dynamic agents are child Durable Objects **colocated under and supervised by** a
 
 Use dynamic agents for code whose **class or lifecycle the parent owns**: dynamically-loaded or AI-generated code that has no wrangler binding, per-run tool agents, sandboxed components that need isolated storage plus supervised abort/restart. That is what the runtime built facets for.
 
-Do **not** use dynamic agents to model an open-ended set of independent peers — many chats, documents, or sessions per user. Those want one top-level Durable Object each plus a per-user index; see [When to use dynamic agents](#when-to-use-dynamic-agents) and [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats).
+Do **not** use dynamic agents to model an open-ended set of independent peers — many chats, documents, or sessions per user. Those want one top-level Durable Object each plus a per-user index; see [When to use dynamic agents](#when-to-use-dynamic-agents) and [`examples/next/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing).
 
 If you want a parent chat agent to dispatch another chat-capable agent during a
 single turn and render that child's progress inline, use [Agent Tools](./agent-tools.md).
@@ -471,13 +471,13 @@ await user.recordChatActivity(chatId, { title, lastMessage, seq });
 
 `RoutedAgents` packages the hub side of this pattern: a durable ID-to-Agent catalog plus request and WebSocket forwarding under one route segment. See [Routing to independent Agents](./routing.md#routing-to-independent-agents).
 
-Each chat gets its own alarms, placement, and storage budget; deletion is one `chats.delete(id)` call; and "search across all my chats" reads only the index. The example treats that index as a best-effort derived projection: a failed push leaves it stale until the next message, and a push for a deleted chat is refused. See [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats) for the pattern built on `RoutedAgents`, with tests. Idempotency and repair belong to the production design in [`design/rfc-user-chat-durable-objects.md`](https://github.com/cloudflare/agents/blob/main/design/rfc-user-chat-durable-objects.md).
+Each chat gets its own alarms, placement, and storage budget; deletion is one `chats.delete(id)` call; and "search across all my chats" reads only the index. The example treats that index as a best-effort derived projection: a failed push leaves it stale until the next message, and a push for a deleted chat is refused. See [`examples/next/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing) for the pattern built on `RoutedAgents`, with tests. Idempotency and repair belong to the production design in [`design/rfc-user-chat-durable-objects.md`](https://github.com/cloudflare/agents/blob/main/design/rfc-user-chat-durable-objects.md).
 
 ## Examples
 
 - [`examples/next/dynamic-agents`](https://github.com/cloudflare/agents/tree/main/examples/next/dynamic-agents) — the headline use case: a supervisor stores user-submitted Durable Object code, loads it via Worker Loader, and runs it as facets with isolated storage, supervised abort, and code upgrades over stable state.
 - [`examples/agents-as-tools`](https://github.com/cloudflare/agents/tree/main/examples/agents-as-tools) — per-run child agents as tools with inline streaming.
-- [`examples/multi-ai-chat`](https://github.com/cloudflare/agents/tree/main/examples/multi-ai-chat) — a multi-session chat app built on facet children under one `Inbox`. It works and demonstrates the routing surface, but for many long-lived chats per user prefer the top-level-DO-per-chat pattern in [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats) — see [When to use dynamic agents](#when-to-use-dynamic-agents).
+- [`examples/multi-ai-chat`](https://github.com/cloudflare/agents/tree/main/examples/multi-ai-chat) — a multi-session chat app built on facet children under one `Inbox`. It works and demonstrates the routing surface, but for many long-lived chats per user prefer the top-level-DO-per-chat pattern in [`examples/next/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing) — see [When to use dynamic agents](#when-to-use-dynamic-agents).
 
 ## Related
 

package/package.json

@@ -9,7 +9,7 @@
     "durable objects"
   ],
   "type": "module",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -52,7 +52,7 @@
     "just-bash": "^3.0.2",
     "react": "^19.2.7",
     "teleproto": "^1.228.5",
-    "valibot": "1.4.1",
+    "valibot": "1.4.2",
     "zod": "^4.5.4"
   },
   "peerDependencies": {
@@ -200,11 +200,21 @@
       "import": "./dist/websockets/index.js",
       "require": "./dist/websockets/index.js"
     },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js",
+      "require": "./dist/state/index.js"
+    },
     "./schedule": {
       "types": "./dist/schedule.d.ts",
       "import": "./dist/schedule.js",
       "require": "./dist/schedule.js"
     },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "import": "./dist/queue/index.js",
+      "require": "./dist/queue/index.js"
+    },
     "./schedules": {
       "types": "./dist/schedules/index.d.ts",
       "import": "./dist/schedules/index.js",

package/dist/capability-BjSKYpzg.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-BjSKYpzg.js","names":[],"sources":["../src/lifecycle/capability.ts"],"sourcesContent":["import type {\n  CapabilityStartContext,\n  DurableObjectCapability\n} from \"./capability-runner\";\nimport type { Connection } from \"./types\";\nimport type { LifecycleJobs } from \"./job-queue\";\n\n/** Opaque address understood by a Lifecycle routing transport. */\nexport type LifecycleRouteAddress = {\n  /** Stable equality and storage key. */\n  readonly key: string;\n  /** Transport-owned serialized address. */\n  readonly data: string;\n};\n\n/** Context supplied with a routed capability message. */\nexport type LifecycleRouteContext = {\n  /** Address of the sending Lifecycle, or undefined for an unrouted root. */\n  readonly source: LifecycleRouteAddress | undefined;\n  /** Capability-owned message payload. */\n  readonly payload: unknown;\n};\n\n/** Best-effort telemetry available to every Lifecycle capability. */\nexport type LifecycleEvents = {\n  /** Publish an event under this capability's stable identity. */\n  readonly emit: (type: string, payload: unknown) => void;\n};\n\n/** Routing available to every Lifecycle capability. */\nexport type LifecycleRoutes = {\n  /** This Lifecycle's transport address, or undefined at the route root. */\n  readonly source: LifecycleRouteAddress | undefined;\n  /** Route a capability-owned message to the root Lifecycle. */\n  readonly toRoot: (payload: unknown) => Promise<unknown>;\n  /** Route a capability-owned message to another Lifecycle. */\n  readonly to: (\n    target: LifecycleRouteAddress,\n    payload: unknown\n  ) => Promise<unknown>;\n};\n\n/**\n * Ambient scope a capability supplies when entering host context on\n * behalf of a live connection or request.\n */\nexport type LifecycleHostContextScope = {\n  /** The connection the callback runs on behalf of, when there is one. */\n  readonly connection?: Connection;\n  /** The request the callback runs on behalf of, when there is one. */\n  readonly request?: Request;\n};\n\n/**\n * The platform's hibernatable-socket surface, exposed narrowly so a\n * capability that owns connections (e.g. WebSockets) can accept and\n * enumerate them without holding the whole `DurableObjectState`.\n * These are workerd API names, not Lifecycle modeling sockets.\n */\nexport type LifecycleSockets = {\n  /** Accept a socket into hibernation under the given tags. */\n  readonly accept: (ws: WebSocket, tags: string[]) => void;\n  /** Every hibernated socket on the object, optionally by tag. */\n  readonly get: (tag?: string) => WebSocket[];\n};\n\n/**\n * Standard services granted to every installed Lifecycle capability.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport type LifecycleServices = {\n  readonly storage: DurableObjectStorage;\n  readonly sockets: LifecycleSockets;\n  readonly ready: () => Promise<void>;\n  /** True while capability and host startup hooks are still running. */\n  readonly starting: () => boolean;\n  /**\n   * This capability's scoped access to the Lifecycle-owned work queue.\n   * Pushed items are dispatched to `onJob` when due; every queue mutation\n   * re-arms the physical alarm automatically.\n   */\n  readonly jobs: LifecycleJobs;\n  /**\n   * Keep work this capability hands off at a bounded `onJob` return inside\n   * the current alarm's memory-limit breaker domain (#1825). Returns false,\n   * tracking nothing, outside an alarm invocation.\n   */\n  readonly trackAlarmWork: (work: Promise<unknown>) => boolean;\n  /**\n   * Run a capability-held user callback inside the host invocation context.\n   * Capability hooks run outside host context; this is the one boundary for\n   * entering it, and a host composition root may substitute its own wrapper\n   * (Agent adds tracing span scope). Pass `scope` to make a live\n   * connection or request ambient for the callback.\n   */\n  readonly runInHostContext: (\n    fn: () => unknown,\n    scope?: LifecycleHostContextScope\n  ) => Promise<unknown>;\n  readonly events: LifecycleEvents;\n  readonly routes: LifecycleRoutes;\n};\n\nconst installedServices = new WeakMap<object, LifecycleServices>();\n\n/**\n * Base class for capabilities that consume standard Lifecycle services.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport abstract class LifecycleCapability<Props extends object = object> {\n  readonly capabilityId: string;\n\n  protected constructor(capabilityId: string) {\n    if (capabilityId.trim() === \"\") {\n      throw new Error(\"Lifecycle capability IDs must be non-empty\");\n    }\n    this.capabilityId = capabilityId;\n  }\n\n  /** Default startup hook; capabilities override when they own startup work. */\n  onStart(_context: CapabilityStartContext<Props>): void {}\n\n  /** Standard services when installed, or undefined in isolated unit tests. */\n  protected get lifecycleServices(): LifecycleServices | undefined {\n    return installedServices.get(this);\n  }\n\n  /** Standard services supplied when Lifecycle installs this capability. */\n  protected get lifecycle(): LifecycleServices {\n    const services = this.lifecycleServices;\n    if (!services) {\n      throw new Error(\n        `${this.constructor.name} must be installed with Lifecycle.use() before use`\n      );\n    }\n    return services;\n  }\n}\n\n/**\n * @internal Bind the standard service surface to one capability instance.\n * `Lifecycle.use()` calls this during installation. Test a capability by\n * installing it on a minimal Durable Object with a real Lifecycle rather\n * than binding fake services.\n */\nexport function bindLifecycleCapability(\n  capability: LifecycleCapability,\n  services: LifecycleServices\n): void {\n  installedServices.set(capability, services);\n}\n\n/** @internal Read a capability ID without exposing installation internals. */\nexport function lifecycleCapabilityId(\n  capability: DurableObjectCapability\n): string | undefined {\n  return capability instanceof LifecycleCapability\n    ? capability.capabilityId\n    : undefined;\n}\n"],"mappings":";AAwGA,MAAM,oCAAoB,IAAI,QAAmC;;;;;;AAOjE,IAAsB,sBAAtB,MAAyE;CAGvE,YAAsB,cAAsB;EAC1C,IAAI,aAAa,KAAK,MAAM,IAC1B,MAAM,IAAI,MAAM,4CAA4C;EAE9D,KAAK,eAAe;CACtB;;CAGA,QAAQ,UAA+C,CAAC;;CAGxD,IAAc,oBAAmD;EAC/D,OAAO,kBAAkB,IAAI,IAAI;CACnC;;CAGA,IAAc,YAA+B;EAC3C,MAAM,WAAW,KAAK;EACtB,IAAI,CAAC,UACH,MAAM,IAAI,MACR,GAAG,KAAK,YAAY,KAAK,mDAC3B;EAEF,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,wBACd,YACA,UACM;CACN,kBAAkB,IAAI,YAAY,QAAQ;AAC5C;;AAGA,SAAgB,sBACd,YACoB;CACpB,OAAO,sBAAsB,sBACzB,WAAW,eACX,KAAA;AACN"}

package/dist/client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  type PartyFetchOptions,\n  PartySocket,\n  type PartySocketOptions\n} from \"partysocket\";\nimport type { Agent, RPCRequest, RPCResponse } from \"./\";\nimport type {\n  ClientParameters,\n  Method,\n  RPCMethod,\n  SerializableReturnValue,\n  SerializableValue\n} from \"./serializable\";\nimport { MessageType } from \"./types\";\nimport { camelCaseToKebabCase, isInternalJsStubProp } from \"./utils\";\n\nexport class AgentConnectionError extends Error {\n  code: number;\n  reason: string;\n  wasClean: boolean;\n\n  constructor(event: CloseEvent) {\n    const reason = event.reason || `WebSocket closed with code ${event.code}`;\n    super(`Agent connection closed: ${reason}`);\n    this.name = \"AgentConnectionError\";\n    this.code = event.code;\n    this.reason = event.reason;\n    this.wasClean = event.wasClean;\n  }\n}\n\nexport function isTerminalCloseEvent(event: CloseEvent): boolean {\n  return event.code === 1008 || (event.code >= 4000 && event.code <= 4999);\n}\n\ntype TerminalReconnectOptions = {\n  shouldReconnectOnClose?: (event: CloseEvent) => boolean;\n};\n\n/**\n * Options for creating an AgentClient\n */\nexport type AgentClientOptions<State = unknown> = Omit<\n  PartySocketOptions,\n  \"party\" | \"room\"\n> &\n  TerminalReconnectOptions & {\n    /** Name of the agent to connect to (ignored if basePath is set) */\n    agent: string;\n    /** Name of the specific Agent instance (ignored if basePath is set) */\n    name?: string;\n    /**\n     * Full URL path - bypasses agent/name URL construction.\n     * When set, the client connects to this path directly.\n     * Server must handle routing manually (e.g., with getAgentByName + fetch).\n     * @example\n     * // Client connects to /user, server routes based on session\n     * useAgent({ agent: \"UserAgent\", basePath: \"user\" })\n     */\n    basePath?: string;\n    /** Called when the Agent's state is updated */\n    onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n    /** Called when a state update fails (e.g., connection is readonly) */\n    onStateUpdateError?: (error: string) => void;\n    /**\n     * Called when the server sends the agent's identity on connect.\n     * Useful when using basePath, as the actual instance name is determined server-side.\n     * @param name The actual agent instance name\n     * @param agent The agent class name (kebab-case)\n     */\n    onIdentity?: (name: string, agent: string) => void;\n    /**\n     * Called when identity changes on reconnect (different instance than before).\n     * If not provided and identity changes, a warning will be logged.\n     * @param oldName Previous instance name\n     * @param newName New instance name\n     * @param oldAgent Previous agent class name\n     * @param newAgent New agent class name\n     */\n    onIdentityChange?: (\n      oldName: string,\n      newName: string,\n      oldAgent: string,\n      newAgent: string\n    ) => void;\n    /**\n     * Additional path to append to the URL.\n     * Works with both standard routing and basePath.\n     * @example\n     * // With basePath: /user/settings\n     * { basePath: \"user\", path: \"settings\" }\n     * // Standard: /agents/my-agent/room/settings\n     * { agent: \"MyAgent\", name: \"room\", path: \"settings\" }\n     */\n    path?: string;\n    /**\n     * Default timeout (in milliseconds) applied to non-streaming `call()`s\n     * that don't pass an explicit `timeout`. Defaults to 30 000 ms.\n     * Set to `0` to disable. Streaming calls never get a default timeout.\n     */\n    defaultCallTimeout?: number;\n    /** Called when the connection closes with a terminal code and will not reconnect. */\n    onConnectionError?: (error: AgentConnectionError) => void;\n  };\n\n/**\n * Default timeout (in milliseconds) applied to non-streaming RPC calls\n * that don't pass an explicit `timeout`. Acts as a backstop so calls\n * whose response is lost (e.g. the connection drops mid-flight) reject\n * instead of hanging forever. Override per client via\n * `defaultCallTimeout`, or per call via `timeout` (0 disables).\n */\nexport const DEFAULT_CALL_TIMEOUT_MS = 30_000;\n\n/**\n * Options for streaming RPC calls\n */\nexport type StreamOptions = {\n  /** Called when a chunk of data is received */\n  onChunk?: (chunk: unknown) => void;\n  /** Called when the stream ends */\n  onDone?: (finalChunk: unknown) => void;\n  /** Called when an error occurs */\n  onError?: (error: string) => void;\n};\n\n/**\n * Options for RPC calls\n */\nexport type CallOptions = {\n  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */\n  timeout?: number;\n  /** Streaming options for handling streaming responses */\n  stream?: StreamOptions;\n};\n\n/**\n * Options for the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the request is made to this path directly.\n   */\n  basePath?: string;\n};\n\n// ---- Shared RPC Type Utilities ----\n\ntype AllOptional<T> = T extends [infer A, ...infer R]\n  ? undefined extends A\n    ? AllOptional<R>\n    : false\n  : true;\n\nexport type RPCMethods<T> = {\n  [K in keyof T as T[K] extends RPCMethod<T[K]> ? K : never]: RPCMethod<T[K]>;\n};\n\ntype OptionalParametersMethod<T extends RPCMethod> =\n  AllOptional<ClientParameters<T>> extends true ? T : never;\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic agent type constraint\nexport type AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;\n\nexport type OptionalAgentMethods<T> = {\n  [K in keyof AgentMethods<T> as AgentMethods<T>[K] extends OptionalParametersMethod<\n    AgentMethods<T>[K]\n  >\n    ? K\n    : never]: OptionalParametersMethod<AgentMethods<T>[K]>;\n};\n\nexport type RequiredAgentMethods<T> = Omit<\n  AgentMethods<T>,\n  keyof OptionalAgentMethods<T>\n>;\n\nexport type AgentPromiseReturnType<T, K extends keyof AgentMethods<T>> =\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic promise return type\n  ReturnType<AgentMethods<T>[K]> extends Promise<any>\n    ? ReturnType<AgentMethods<T>[K]>\n    : Promise<ReturnType<AgentMethods<T>[K]>>;\n\nexport type AgentStub<T> = {\n  [K in keyof AgentMethods<T>]: (\n    ...args: ClientParameters<AgentMethods<T>[K]>\n  ) => AgentPromiseReturnType<AgentMethods<T>, K>;\n};\n\nexport type UntypedAgentStub = Record<string, Method>;\n\ntype AgentClientStub<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentStub\n  : AgentStub<AgentT>;\n\ntype OptionalArgsAgentClientCall<AgentT> = <\n  K extends keyof OptionalAgentMethods<AgentT>\n>(\n  method: K,\n  args?: ClientParameters<OptionalAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype RequiredArgsAgentClientCall<AgentT> = <\n  K extends keyof RequiredAgentMethods<AgentT>\n>(\n  method: K,\n  args: ClientParameters<RequiredAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype TypedAgentClientCall<AgentT> = OptionalArgsAgentClientCall<AgentT> &\n  RequiredArgsAgentClientCall<AgentT>;\n\ntype UntypedAgentClientCall = {\n  <T extends SerializableReturnValue>(\n    method: string,\n    args?: SerializableValue[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  <T = unknown>(\n    method: string,\n    args?: unknown[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n};\n\ntype AgentClientCall<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentClientCall\n  : TypedAgentClientCall<AgentT>;\n\n/**\n * Creates a proxy that wraps RPC method calls.\n * Internal JS methods (toJSON, then, etc.) return undefined to avoid\n * triggering RPC calls during serialization (e.g., console.log)\n */\nexport function createStubProxy<T = Record<string, Method>>(\n  call: (method: string, args: unknown[]) => unknown\n): T {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- proxy needs any for dynamic method access\n  return new Proxy<any>(\n    {},\n    {\n      get: (_target, method) => {\n        if (isInternalJsStubProp(method)) {\n          return undefined;\n        }\n        return (...args: unknown[]) => call(method as string, args);\n      }\n    }\n  );\n}\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<\n  AgentT = unknown,\n  State = AgentT extends { get state(): infer S } ? S : AgentT\n> extends PartySocket {\n  /**\n   * @deprecated Use agentFetch instead\n   */\n  static fetch(_opts: PartyFetchOptions): Promise<Response> {\n    throw new Error(\n      \"AgentClient.fetch is not implemented, use agentFetch instead\"\n    );\n  }\n  agent: string;\n  name: string;\n  call: AgentClientCall<AgentT>;\n  stub: AgentClientStub<AgentT>;\n\n  /**\n   * The current agent state, updated on server broadcasts and client setState calls.\n   * Starts as undefined until the first state message is received from the server.\n   */\n  state: State | undefined = undefined;\n\n  /**\n   * Whether the client has received identity from the server.\n   * Becomes true after the first identity message is received.\n   * Resets to false on connection close.\n   */\n  identified = false;\n\n  /**\n   * Terminal connection error, if the server closed the socket with a code\n   * that should not be retried automatically.\n   */\n  connectionError: AgentConnectionError | null = null;\n\n  /**\n   * Promise that resolves when identity has been received from the server.\n   * Useful for waiting before making calls that depend on knowing the instance.\n   * Resets on connection close so it can be awaited again after reconnect.\n   */\n  get ready(): Promise<void> {\n    return this._readyPromise;\n  }\n\n  private options: AgentClientOptions<State>;\n  private _pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n      /**\n       * Whether the request was actually transmitted to the server.\n       * Requests issued while disconnected sit in PartySocket's internal\n       * buffer (transmitted: false) and are flushed on the next open —\n       * they survive a transient close instead of being rejected, since\n       * the server never saw them and re-delivery can't double-execute.\n       */\n      transmitted: boolean;\n    }\n  >();\n  private _readyPromise!: Promise<void>;\n  private _resolveReady!: () => void;\n  private _previousName: string | null = null;\n  private _previousAgent: string | null = null;\n\n  private _resetReady() {\n    this._readyPromise = new Promise((resolve) => {\n      this._resolveReady = resolve;\n    });\n  }\n\n  constructor(options: AgentClientOptions<State>) {\n    const agentNamespace = camelCaseToKebabCase(options.agent);\n    const shouldReconnectOnClose = options.shouldReconnectOnClose;\n    const classifyReconnect = (event: CloseEvent) =>\n      (shouldReconnectOnClose?.(event) ?? true) && !isTerminalCloseEvent(event);\n\n    // If basePath is provided, use it directly; otherwise construct from agent/name\n    const socketOptions = options.basePath\n      ? {\n          basePath: options.basePath,\n          path: options.path,\n          ...options,\n          shouldReconnectOnClose: classifyReconnect\n        }\n      : {\n          party: agentNamespace,\n          prefix: \"agents\",\n          room: options.name || \"default\",\n          path: options.path,\n          ...options,\n          shouldReconnectOnClose: classifyReconnect\n        };\n\n    super(socketOptions);\n    this.agent = agentNamespace;\n    this.name = options.name || \"default\";\n    this.options = options;\n\n    // Initialize ready promise\n    this._resetReady();\n\n    this.addEventListener(\"message\", (event) => {\n      if (typeof event.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(event.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = this._previousName;\n          const oldAgent = this._previousAgent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Resolve ready/identified\n          this.identified = true;\n          this._resolveReady();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (this.options.onIdentityChange) {\n              this.options.onIdentityChange(\n                oldName,\n                newName,\n                oldAgent,\n                newAgent\n              );\n            } else {\n              const agentChanged = oldAgent !== newAgent;\n              const nameChanged = oldName !== newName;\n              let changeDescription = \"\";\n              if (agentChanged && nameChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\", instance \"${oldName}\" → \"${newName}\"`;\n              } else if (agentChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\"`;\n              } else {\n                changeDescription = `instance \"${oldName}\" → \"${newName}\"`;\n              }\n              console.warn(\n                `[agents] Identity changed on reconnect: ${changeDescription}. ` +\n                  \"This can happen with server-side routing (e.g., basePath with getAgentByName) \" +\n                  \"where the instance is determined by auth/session. \" +\n                  \"Provide onIdentityChange callback to handle this explicitly, \" +\n                  \"or ignore if this is expected for your routing pattern.\"\n              );\n            }\n          }\n\n          // Always update from server identity (server is authoritative)\n          this._previousName = newName;\n          this._previousAgent = newAgent;\n          this.name = newName;\n          this.agent = newAgent;\n\n          // Call onIdentity callback\n          this.options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          this.state = parsedMessage.state as State;\n          this.options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {\n          this.options.onStateUpdateError?.(parsedMessage.error as string);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = this._pendingCalls.get(response.id);\n          if (!pending) {\n            console.warn(\n              `[AgentClient] Discarded an RPC response with no matching pending call (id \"${response.id}\"). ` +\n                \"The call likely timed out or was rejected when its connection closed before the response arrived.\"\n            );\n            return;\n          }\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            this._pendingCalls.delete(response.id);\n            pending.stream?.onError?.(response.error);\n            return;\n          }\n\n          // Handle streaming responses\n          if (\"done\" in response) {\n            if (response.done) {\n              pending.resolve(response.result);\n              this._pendingCalls.delete(response.id);\n              pending.stream?.onDone?.(response.result);\n            } else {\n              pending.stream?.onChunk?.(response.result);\n            }\n          } else {\n            // Non-streaming response\n            pending.resolve(response.result);\n            this._pendingCalls.delete(response.id);\n          }\n        }\n      }\n    });\n\n    // PartySocket flushes its internal message buffer right before\n    // dispatching \"open\" — anything queued has now been transmitted.\n    this.addEventListener(\"open\", () => {\n      this.connectionError = null;\n      for (const pending of this._pendingCalls.values()) {\n        pending.transmitted = true;\n      }\n    });\n\n    // Clean up pending calls and reset ready state when connection closes\n    this.addEventListener(\"close\", (event) => {\n      const terminalClose = isTerminalCloseEvent(event);\n      // Reset ready state for next connection\n      this.identified = false;\n      this._resetReady();\n\n      if (this.shouldReconnect) {\n        // Transient disconnect: reject calls whose request was already\n        // transmitted — their response can never arrive. Buffered calls\n        // stay pending; PartySocket re-sends them on reconnect.\n        this._rejectPendingCalls(\"Connection closed\", {\n          onlyTransmitted: true\n        });\n      } else {\n        // Permanent close (close() called or retries exhausted): nothing\n        // will ever flush the buffer, so reject everything.\n        this._rejectPendingCalls(\"Connection closed\");\n        if (terminalClose) {\n          const error = new AgentConnectionError(event);\n          this.connectionError = error;\n          this.options.onConnectionError?.(error);\n        }\n      }\n    });\n\n    this.call = this._callImpl.bind(this) as AgentClientCall<AgentT>;\n    this.stub = createStubProxy((method, args) =>\n      this._callImpl(method, args)\n    ) as AgentClientStub<AgentT>;\n  }\n\n  /**\n   * Reject pending RPC calls with the given reason.\n   * With `onlyTransmitted`, calls still sitting in the send buffer are\n   * kept pending (they'll be flushed on reconnect).\n   */\n  private _rejectPendingCalls(\n    reason: string,\n    { onlyTransmitted = false }: { onlyTransmitted?: boolean } = {}\n  ) {\n    const error = new Error(reason);\n    for (const [id, pending] of this._pendingCalls) {\n      if (onlyTransmitted && !pending.transmitted) continue;\n      this._pendingCalls.delete(id);\n      pending.reject(error);\n      pending.stream?.onError?.(reason);\n    }\n  }\n\n  setState(state: State) {\n    this.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    this.state = state;\n    this.options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Close the connection and immediately reject all pending RPC calls.\n   * This provides immediate feedback on intentional close rather than\n   * waiting for the WebSocket close handshake to complete.\n   *\n   * Note: Any calls made after `close()` will be rejected when the\n   * underlying WebSocket close event fires.\n   */\n  close(code?: number, reason?: string) {\n    // Immediately reject all pending calls on intentional close\n    this._rejectPendingCalls(\"Connection closed\");\n\n    // Then close the underlying socket\n    super.close(code, reason);\n  }\n\n  /**\n   * Call a method on the Agent.\n   * When AgentT is provided, method names are inferred from the agent's methods.\n   * Falls back to untyped string-based calls when AgentT is not provided.\n   */\n  private async _callImpl(\n    method: string,\n    args: unknown[] = [],\n    options?: CallOptions | StreamOptions\n  ): Promise<unknown> {\n    if (this.connectionError && this.readyState === this.CLOSED) {\n      throw new Error(\"Connection closed\");\n    }\n\n    return new Promise((resolve, reject) => {\n      const id = crypto.randomUUID();\n      let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n      // Detect legacy format: { onChunk?, onDone?, onError? } vs new format: { timeout?, stream? }\n      const isLegacyFormat =\n        options &&\n        (\"onChunk\" in options || \"onDone\" in options || \"onError\" in options);\n      const streamOptions = isLegacyFormat\n        ? (options as StreamOptions)\n        : (options as CallOptions | undefined)?.stream;\n      const timeout = isLegacyFormat\n        ? undefined\n        : (options as CallOptions | undefined)?.timeout;\n\n      // Apply the default timeout as a backstop for non-streaming calls\n      // so a lost response rejects instead of hanging forever. An\n      // explicit `timeout` (including 0 = disabled) always wins.\n      const effectiveTimeout =\n        timeout !== undefined\n          ? timeout\n          : streamOptions\n            ? undefined\n            : (this.options.defaultCallTimeout ?? DEFAULT_CALL_TIMEOUT_MS);\n\n      if (effectiveTimeout) {\n        timeoutId = setTimeout(() => {\n          const pending = this._pendingCalls.get(id);\n          this._pendingCalls.delete(id);\n          const errorMessage = `RPC call to ${method} timed out after ${effectiveTimeout}ms`;\n          pending?.stream?.onError?.(errorMessage);\n          reject(new Error(errorMessage));\n        }, effectiveTimeout);\n      }\n\n      this._pendingCalls.set(id, {\n        reject: (e: Error) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          reject(e);\n        },\n        resolve: (value: unknown) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          resolve(value);\n        },\n        stream: streamOptions,\n        // If the socket is open, send() below transmits synchronously;\n        // otherwise the request is buffered until the next open event\n        // (the \"open\" listener then marks it transmitted).\n        transmitted: this.readyState === this.OPEN\n      });\n\n      const request: RPCRequest = {\n        args,\n        id,\n        method,\n        type: MessageType.RPC\n      };\n\n      this.send(JSON.stringify(request));\n    });\n  }\n}\n\n/**\n * Make an HTTP request to an Agent\n * @param opts Connection options\n * @param init Request initialization options\n * @returns Promise resolving to a Response\n */\nexport function agentFetch(opts: AgentClientFetchOptions, init?: RequestInit) {\n  const agentNamespace = camelCaseToKebabCase(opts.agent);\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  // When basePath is set, room/party aren't used by PartySocket (basePath replaces the URL)\n  if (opts.basePath) {\n    return PartySocket.fetch(\n      { basePath: opts.basePath, ...opts } as unknown as PartyFetchOptions,\n      init\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      party: agentNamespace,\n      prefix: \"agents\",\n      room: opts.name || \"default\",\n      ...opts\n    },\n    init\n  );\n}\n"],"mappings":"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"}