agents 0.7.1 → 0.7.3

package/dist/experimental/forever.d.ts

@@ -92,10 +92,11 @@ declare function withFibers<TBase extends AgentLike>(Base: TBase, options?: {
     _checkInterruptedFibers(): Promise<void>; /** @internal */
     _cleanupOrphanedHeartbeats(): void; /** @internal */
     _maybeCleanupFibers(): void;
-    readonly alarm: () => Promise<void>;
+    alarm: () => Promise<void>;
     sql: <T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]) => T[];
     scheduleEvery: <T = string>(intervalSeconds: number, callback: keyof Agent<Cloudflare.Env, unknown, Record<string, unknown>>, payload?: T | undefined, options?: {
       retry?: RetryOptions;
+      _idempotent?: boolean;
     }) => Promise<Schedule<T>>;
     cancelSchedule: (id: string) => Promise<boolean>;
     keepAlive: () => Promise<() => void>;

package/dist/experimental/sub-agent.d.ts

@@ -0,0 +1,205 @@
+import { Server } from "partyserver";
+
+//#region src/experimental/sub-agent.d.ts
+/** @internal */
+interface FacetCapableCtx {
+  facets: {
+    get(name: string, getStartupOptions: () => {
+      id?: DurableObjectId | string;
+      class: DurableObjectClass;
+    } | Promise<{
+      id?: DurableObjectId | string;
+      class: DurableObjectClass;
+    }>): Fetcher;
+    abort(name: string, reason: unknown): void;
+    delete(name: string): void;
+  };
+  exports: Record<string, DurableObjectClass>;
+}
+/**
+ * Constructor type for a SubAgent subclass.
+ * Used by {@link SubAgent.subAgent} to reference the child class
+ * via `ctx.exports`.
+ *
+ * The class name (`cls.name`) must match the export name in the
+ * worker entry point — re-exports under a different name
+ * (e.g. `export { Foo as Bar }`) are not supported.
+ */
+type SubAgentClass<T extends SubAgent = SubAgent> = {
+  new (ctx: DurableObjectState, env: never): T;
+};
+/**
+ * Wraps `T` in a `Promise` unless it already is one.
+ */
+type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+/**
+ * Server / DurableObject internals excluded from the RPC stub.
+ * This is a blocklist — if `Server` or `SubAgent` gains new methods
+ * they must be added here to stay hidden from the stub type.
+ */
+type SubAgentInternals = "fetch" | "alarm" | "webSocketMessage" | "webSocketClose" | "webSocketError" | "sql" | "broadcast" | "getConnection" | "getConnections" | "getConnectionTags" | "setName" | "onStart" | "onConnect" | "onMessage" | "onClose" | "onError" | "onRequest" | "onException" | "onAlarm" | "subAgent" | "abortSubAgent" | "deleteSubAgent";
+/**
+ * A typed RPC stub for a SubAgent. Exposes all public instance methods
+ * as callable RPC methods with Promise-wrapped return types.
+ *
+ * Methods inherited from `Server` / `DurableObject` internals are
+ * excluded — only user-defined methods on the SubAgent subclass are
+ * exposed.
+ */
+type SubAgentStub<T extends SubAgent> = { [K in keyof T as K extends SubAgentInternals ? never : T[K] extends ((...args: never[]) => unknown) ? K : never]: T[K] extends ((...args: infer A) => infer R) ? (...args: A) => Promisify<R> : never };
+/**
+ * Base class for sub-agents — child Durable Objects that run as facets
+ * of a parent Agent (or another SubAgent) on the same machine, each
+ * with their own isolated SQLite storage.
+ *
+ * Extends partyserver's `Server`, so inherits:
+ * - `this.sql` tagged-template SQL helper
+ * - `this.name` identity
+ * - WebSocket hibernation + `onConnect`/`onMessage`/`onClose`
+ * - `broadcast()`, `getConnection()`, `getConnections()`
+ *
+ * SubAgents do **not** need wrangler.jsonc entries — they are
+ * referenced via `ctx.exports` and instantiated through the
+ * experimental facets API.
+ *
+ * @experimental Requires the `"experimental"` compatibility flag.
+ *
+ * @example
+ * ```typescript
+ * import { SubAgent } from "agents/experimental/subagent";
+ *
+ * export class SearchAgent extends SubAgent {
+ *   async search(query: string): Promise<Result[]> {
+ *     const cached = this.sql`SELECT * FROM cache WHERE q = ${query}`;
+ *     if (cached.length) return cached;
+ *     // ... fetch, cache, return
+ *   }
+ * }
+ * ```
+ */
+declare class SubAgent<Env extends Cloudflare.Env = Cloudflare.Env> extends Server<Env> {
+  /**
+   * Get or create a named child sub-agent — a facet with its own
+   * isolated SQLite storage running on the same machine.
+   *
+   * The first call for a given name triggers the child's `onStart()`.
+   * Subsequent calls with the same name return the existing instance
+   * (the set-name fetch is a no-op if already initialized).
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param cls The SubAgent subclass (must be exported from the worker)
+   * @param name Unique name for this child instance
+   * @returns A typed RPC stub for calling methods on the child
+   *
+   * @example
+   * ```typescript
+   * const searcher = await this.subAgent(SearchAgent, "main-search");
+   * const results = await searcher.search("cloudflare agents");
+   * ```
+   */
+  subAgent<T extends SubAgent>(cls: SubAgentClass<T>, name: string): Promise<SubAgentStub<T>>;
+  /**
+   * Forcefully abort a running child sub-agent. The child stops
+   * executing immediately and will be restarted on next
+   * {@link subAgent} call. Pending RPC calls receive the reason
+   * as an error. Transitively aborts the child's own children.
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param name Name of the child to abort
+   * @param reason Error thrown to pending/future RPC callers
+   */
+  abortSubAgent(name: string, reason?: unknown): void;
+  /**
+   * Delete a child sub-agent: abort it if running, then permanently
+   * wipe its storage. Transitively deletes the child's own children.
+   *
+   * @experimental Requires the `"experimental"` compatibility flag.
+   *
+   * @param name Name of the child to delete
+   */
+  deleteSubAgent(name: string): void;
+}
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * Mixin that adds sub-agent management methods to an Agent (or
+ * AIChatAgent, McpAgent, etc.) without shipping them in the base
+ * `Agent` class.
+ *
+ * @experimental Requires the `"experimental"` compatibility flag.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from "agents";
+ * import { withSubAgents, SubAgent } from "agents/experimental/subagent";
+ *
+ * export class SearchAgent extends SubAgent {
+ *   async search(query: string) { ... }
+ * }
+ *
+ * const SubAgentParent = withSubAgents(Agent);
+ *
+ * export class MyAgent extends SubAgentParent<Env> {
+ *   async doStuff() {
+ *     const searcher = await this.subAgent(SearchAgent, "main");
+ *     await searcher.search("hello");
+ *   }
+ * }
+ * ```
+ */
+declare function withSubAgents<TBase extends Constructor>(Base: TBase): {
+  new (...args: any[]): {
+    /**
+     * Get or create a named sub-agent — a child Durable Object with its
+     * own isolated SQLite storage, running alongside this Agent on the
+     * same machine. The child class must extend `SubAgent` and be exported
+     * from the worker entry point.
+     *
+     * @experimental Requires the `"experimental"` compatibility flag.
+     *
+     * @param cls The SubAgent subclass (must be exported from the worker)
+     * @param name Unique name for this child instance
+     * @returns A typed RPC stub for calling methods on the child
+     */
+    subAgent<T extends SubAgent>(cls: SubAgentClass<T>, name: string): Promise<SubAgentStub<T>>;
+    /**
+     * Forcefully abort a running sub-agent. The child stops executing
+     * immediately and will be restarted on next {@link subAgent} call.
+     * Pending RPC calls receive the reason as an error.
+     * Transitively aborts the child's own children.
+     *
+     * @experimental Requires the `"experimental"` compatibility flag.
+     *
+     * @param name Name of the child to abort
+     * @param reason Error thrown to pending/future RPC callers
+     */
+    abortSubAgent(name: string, reason?: unknown): void;
+    /**
+     * Delete a sub-agent: abort it if running, then permanently wipe its
+     * storage. Transitively deletes the child's own children.
+     *
+     * @experimental Requires the `"experimental"` compatibility flag.
+     *
+     * @param name Name of the child to delete
+     */
+    deleteSubAgent(name: string): void;
+  };
+} & TBase;
+/**
+ * Synchronous validation that the SubAgent class exists in worker exports.
+ * Call this before `_getSubAgent` so the error is thrown synchronously
+ * in the caller’s scope (not as a rejected promise from an async function).
+ * This avoids unhandled-rejection noise in the workerd runtime.
+ * @internal
+ */
+declare function _validateSubAgentExport(ctx: DurableObjectState, cls: SubAgentClass): void;
+/** @internal */
+declare function _getSubAgent<T extends SubAgent>(ctx: DurableObjectState, cls: SubAgentClass<T>, name: string): Promise<SubAgentStub<T>>;
+/** @internal */
+declare function _abortSubAgent(ctx: DurableObjectState, name: string, reason?: unknown): void;
+/** @internal */
+declare function _deleteSubAgent(ctx: DurableObjectState, name: string): void;
+//#endregion
+export { FacetCapableCtx, SubAgent, SubAgentClass, SubAgentStub, _abortSubAgent, _deleteSubAgent, _getSubAgent, _validateSubAgentExport, withSubAgents };
+//# sourceMappingURL=sub-agent.d.ts.map

package/dist/experimental/sub-agent.js

@@ -0,0 +1,191 @@
+import { Server } from "partyserver";
+
+//#region src/experimental/sub-agent.ts
+/**
+* Base class for sub-agents — child Durable Objects that run as facets
+* of a parent Agent (or another SubAgent) on the same machine, each
+* with their own isolated SQLite storage.
+*
+* Extends partyserver's `Server`, so inherits:
+* - `this.sql` tagged-template SQL helper
+* - `this.name` identity
+* - WebSocket hibernation + `onConnect`/`onMessage`/`onClose`
+* - `broadcast()`, `getConnection()`, `getConnections()`
+*
+* SubAgents do **not** need wrangler.jsonc entries — they are
+* referenced via `ctx.exports` and instantiated through the
+* experimental facets API.
+*
+* @experimental Requires the `"experimental"` compatibility flag.
+*
+* @example
+* ```typescript
+* import { SubAgent } from "agents/experimental/subagent";
+*
+* export class SearchAgent extends SubAgent {
+*   async search(query: string): Promise<Result[]> {
+*     const cached = this.sql`SELECT * FROM cache WHERE q = ${query}`;
+*     if (cached.length) return cached;
+*     // ... fetch, cache, return
+*   }
+* }
+* ```
+*/
+var SubAgent = class extends Server {
+	/**
+	* Get or create a named child sub-agent — a facet with its own
+	* isolated SQLite storage running on the same machine.
+	*
+	* The first call for a given name triggers the child's `onStart()`.
+	* Subsequent calls with the same name return the existing instance
+	* (the set-name fetch is a no-op if already initialized).
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param cls The SubAgent subclass (must be exported from the worker)
+	* @param name Unique name for this child instance
+	* @returns A typed RPC stub for calling methods on the child
+	*
+	* @example
+	* ```typescript
+	* const searcher = await this.subAgent(SearchAgent, "main-search");
+	* const results = await searcher.search("cloudflare agents");
+	* ```
+	*/
+	async subAgent(cls, name) {
+		_validateSubAgentExport(this.ctx, cls);
+		return _getSubAgent(this.ctx, cls, name);
+	}
+	/**
+	* Forcefully abort a running child sub-agent. The child stops
+	* executing immediately and will be restarted on next
+	* {@link subAgent} call. Pending RPC calls receive the reason
+	* as an error. Transitively aborts the child's own children.
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param name Name of the child to abort
+	* @param reason Error thrown to pending/future RPC callers
+	*/
+	abortSubAgent(name, reason) {
+		_abortSubAgent(this.ctx, name, reason);
+	}
+	/**
+	* Delete a child sub-agent: abort it if running, then permanently
+	* wipe its storage. Transitively deletes the child's own children.
+	*
+	* @experimental Requires the `"experimental"` compatibility flag.
+	*
+	* @param name Name of the child to delete
+	*/
+	deleteSubAgent(name) {
+		_deleteSubAgent(this.ctx, name);
+	}
+};
+/**
+* Mixin that adds sub-agent management methods to an Agent (or
+* AIChatAgent, McpAgent, etc.) without shipping them in the base
+* `Agent` class.
+*
+* @experimental Requires the `"experimental"` compatibility flag.
+*
+* @example
+* ```typescript
+* import { Agent } from "agents";
+* import { withSubAgents, SubAgent } from "agents/experimental/subagent";
+*
+* export class SearchAgent extends SubAgent {
+*   async search(query: string) { ... }
+* }
+*
+* const SubAgentParent = withSubAgents(Agent);
+*
+* export class MyAgent extends SubAgentParent<Env> {
+*   async doStuff() {
+*     const searcher = await this.subAgent(SearchAgent, "main");
+*     await searcher.search("hello");
+*   }
+* }
+* ```
+*/
+function withSubAgents(Base) {
+	class WithSubAgents extends Base {
+		/**
+		* Get or create a named sub-agent — a child Durable Object with its
+		* own isolated SQLite storage, running alongside this Agent on the
+		* same machine. The child class must extend `SubAgent` and be exported
+		* from the worker entry point.
+		*
+		* @experimental Requires the `"experimental"` compatibility flag.
+		*
+		* @param cls The SubAgent subclass (must be exported from the worker)
+		* @param name Unique name for this child instance
+		* @returns A typed RPC stub for calling methods on the child
+		*/
+		async subAgent(cls, name) {
+			const { ctx } = this;
+			_validateSubAgentExport(ctx, cls);
+			return _getSubAgent(ctx, cls, name);
+		}
+		/**
+		* Forcefully abort a running sub-agent. The child stops executing
+		* immediately and will be restarted on next {@link subAgent} call.
+		* Pending RPC calls receive the reason as an error.
+		* Transitively aborts the child's own children.
+		*
+		* @experimental Requires the `"experimental"` compatibility flag.
+		*
+		* @param name Name of the child to abort
+		* @param reason Error thrown to pending/future RPC callers
+		*/
+		abortSubAgent(name, reason) {
+			const { ctx } = this;
+			_abortSubAgent(ctx, name, reason);
+		}
+		/**
+		* Delete a sub-agent: abort it if running, then permanently wipe its
+		* storage. Transitively deletes the child's own children.
+		*
+		* @experimental Requires the `"experimental"` compatibility flag.
+		*
+		* @param name Name of the child to delete
+		*/
+		deleteSubAgent(name) {
+			const { ctx } = this;
+			_deleteSubAgent(ctx, name);
+		}
+	}
+	return WithSubAgents;
+}
+/**
+* Synchronous validation that the SubAgent class exists in worker exports.
+* Call this before `_getSubAgent` so the error is thrown synchronously
+* in the caller’s scope (not as a rejected promise from an async function).
+* This avoids unhandled-rejection noise in the workerd runtime.
+* @internal
+*/
+function _validateSubAgentExport(ctx, cls) {
+	const { exports } = ctx;
+	if (!exports[cls.name]) throw new Error(`SubAgent class "${cls.name}" not found in worker exports. Make sure the class is exported from your worker entry point and that the export name matches the class name.`);
+}
+/** @internal */
+async function _getSubAgent(ctx, cls, name) {
+	const { facets, exports } = ctx;
+	const stub = facets.get(name, () => ({ class: exports[cls.name] }));
+	const req = new Request("http://dummy-example.cloudflare.com/cdn-cgi/partyserver/set-name/");
+	req.headers.set("x-partykit-room", name);
+	await stub.fetch(req).then((res) => res.text());
+	return stub;
+}
+/** @internal */
+function _abortSubAgent(ctx, name, reason) {
+	ctx.facets.abort(name, reason);
+}
+/** @internal */
+function _deleteSubAgent(ctx, name) {
+	ctx.facets.delete(name);
+}
+
+//#endregion
+export { SubAgent, _abortSubAgent, _deleteSubAgent, _getSubAgent, _validateSubAgentExport, withSubAgents };
+//# sourceMappingURL=sub-agent.js.map

package/dist/experimental/sub-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent.js","names":[],"sources":["../../src/experimental/sub-agent.ts"],"sourcesContent":["import { Server } from \"partyserver\";\n\n// ── Internal facet access types ─────────────────────────────────────\n// These mirror the experimental workerd `ctx.facets` API without\n// depending on the \"experimental\" compat flag at the type level.\n\n/** @internal */\nexport interface FacetCapableCtx {\n  facets: {\n    get(\n      name: string,\n      getStartupOptions: () =>\n        | { id?: DurableObjectId | string; class: DurableObjectClass }\n        | Promise<{\n            id?: DurableObjectId | string;\n            class: DurableObjectClass;\n          }>\n    ): Fetcher;\n    abort(name: string, reason: unknown): void;\n    delete(name: string): void;\n  };\n  exports: Record<string, DurableObjectClass>;\n}\n\n// ── Public types ────────────────────────────────────────────────────\n\n/**\n * Constructor type for a SubAgent subclass.\n * Used by {@link SubAgent.subAgent} to reference the child class\n * via `ctx.exports`.\n *\n * The class name (`cls.name`) must match the export name in the\n * worker entry point — re-exports under a different name\n * (e.g. `export { Foo as Bar }`) are not supported.\n */\nexport type SubAgentClass<T extends SubAgent = SubAgent> = {\n  new (ctx: DurableObjectState, env: never): T;\n};\n\n/**\n * Wraps `T` in a `Promise` unless it already is one.\n */\ntype Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;\n\n/**\n * Server / DurableObject internals excluded from the RPC stub.\n * This is a blocklist — if `Server` or `SubAgent` gains new methods\n * they must be added here to stay hidden from the stub type.\n */\ntype SubAgentInternals =\n  | \"fetch\"\n  | \"alarm\"\n  | \"webSocketMessage\"\n  | \"webSocketClose\"\n  | \"webSocketError\"\n  | \"sql\"\n  | \"broadcast\"\n  | \"getConnection\"\n  | \"getConnections\"\n  | \"getConnectionTags\"\n  | \"setName\"\n  | \"onStart\"\n  | \"onConnect\"\n  | \"onMessage\"\n  | \"onClose\"\n  | \"onError\"\n  | \"onRequest\"\n  | \"onException\"\n  | \"onAlarm\"\n  | \"subAgent\"\n  | \"abortSubAgent\"\n  | \"deleteSubAgent\";\n\n/**\n * A typed RPC stub for a SubAgent. Exposes all public instance methods\n * as callable RPC methods with Promise-wrapped return types.\n *\n * Methods inherited from `Server` / `DurableObject` internals are\n * excluded — only user-defined methods on the SubAgent subclass are\n * exposed.\n */\nexport type SubAgentStub<T extends SubAgent> = {\n  [K in keyof T as K extends SubAgentInternals\n    ? never\n    : T[K] extends (...args: never[]) => unknown\n      ? K\n      : never]: T[K] extends (...args: infer A) => infer R\n    ? (...args: A) => Promisify<R>\n    : never;\n};\n\n// ── SubAgent class ──────────────────────────────────────────────────\n\n/**\n * Base class for sub-agents — child Durable Objects that run as facets\n * of a parent Agent (or another SubAgent) on the same machine, each\n * with their own isolated SQLite storage.\n *\n * Extends partyserver's `Server`, so inherits:\n * - `this.sql` tagged-template SQL helper\n * - `this.name` identity\n * - WebSocket hibernation + `onConnect`/`onMessage`/`onClose`\n * - `broadcast()`, `getConnection()`, `getConnections()`\n *\n * SubAgents do **not** need wrangler.jsonc entries — they are\n * referenced via `ctx.exports` and instantiated through the\n * experimental facets API.\n *\n * @experimental Requires the `\"experimental\"` compatibility flag.\n *\n * @example\n * ```typescript\n * import { SubAgent } from \"agents/experimental/subagent\";\n *\n * export class SearchAgent extends SubAgent {\n *   async search(query: string): Promise<Result[]> {\n *     const cached = this.sql`SELECT * FROM cache WHERE q = ${query}`;\n *     if (cached.length) return cached;\n *     // ... fetch, cache, return\n *   }\n * }\n * ```\n */\nexport class SubAgent<\n  Env extends Cloudflare.Env = Cloudflare.Env\n> extends Server<Env> {\n  /**\n   * Get or create a named child sub-agent — a facet with its own\n   * isolated SQLite storage running on the same machine.\n   *\n   * The first call for a given name triggers the child's `onStart()`.\n   * Subsequent calls with the same name return the existing instance\n   * (the set-name fetch is a no-op if already initialized).\n   *\n   * @experimental Requires the `\"experimental\"` compatibility flag.\n   *\n   * @param cls The SubAgent subclass (must be exported from the worker)\n   * @param name Unique name for this child instance\n   * @returns A typed RPC stub for calling methods on the child\n   *\n   * @example\n   * ```typescript\n   * const searcher = await this.subAgent(SearchAgent, \"main-search\");\n   * const results = await searcher.search(\"cloudflare agents\");\n   * ```\n   */\n  async subAgent<T extends SubAgent>(\n    cls: SubAgentClass<T>,\n    name: string\n  ): Promise<SubAgentStub<T>> {\n    _validateSubAgentExport(this.ctx, cls);\n    return _getSubAgent(this.ctx, cls, name);\n  }\n\n  /**\n   * Forcefully abort a running child sub-agent. The child stops\n   * executing immediately and will be restarted on next\n   * {@link subAgent} call. Pending RPC calls receive the reason\n   * as an error. Transitively aborts the child's own children.\n   *\n   * @experimental Requires the `\"experimental\"` compatibility flag.\n   *\n   * @param name Name of the child to abort\n   * @param reason Error thrown to pending/future RPC callers\n   */\n  abortSubAgent(name: string, reason?: unknown): void {\n    _abortSubAgent(this.ctx, name, reason);\n  }\n\n  /**\n   * Delete a child sub-agent: abort it if running, then permanently\n   * wipe its storage. Transitively deletes the child's own children.\n   *\n   * @experimental Requires the `\"experimental\"` compatibility flag.\n   *\n   * @param name Name of the child to delete\n   */\n  deleteSubAgent(name: string): void {\n    _deleteSubAgent(this.ctx, name);\n  }\n}\n\n// ── withSubAgents mixin ─────────────────────────────────────────────\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- mixin constructor constraint\ntype Constructor<T = object> = new (...args: any[]) => T;\n\n/**\n * Mixin that adds sub-agent management methods to an Agent (or\n * AIChatAgent, McpAgent, etc.) without shipping them in the base\n * `Agent` class.\n *\n * @experimental Requires the `\"experimental\"` compatibility flag.\n *\n * @example\n * ```typescript\n * import { Agent } from \"agents\";\n * import { withSubAgents, SubAgent } from \"agents/experimental/subagent\";\n *\n * export class SearchAgent extends SubAgent {\n *   async search(query: string) { ... }\n * }\n *\n * const SubAgentParent = withSubAgents(Agent);\n *\n * export class MyAgent extends SubAgentParent<Env> {\n *   async doStuff() {\n *     const searcher = await this.subAgent(SearchAgent, \"main\");\n *     await searcher.search(\"hello\");\n *   }\n * }\n * ```\n */\nexport function withSubAgents<TBase extends Constructor>(Base: TBase) {\n  class WithSubAgents extends Base {\n    /**\n     * Get or create a named sub-agent — a child Durable Object with its\n     * own isolated SQLite storage, running alongside this Agent on the\n     * same machine. The child class must extend `SubAgent` and be exported\n     * from the worker entry point.\n     *\n     * @experimental Requires the `\"experimental\"` compatibility flag.\n     *\n     * @param cls The SubAgent subclass (must be exported from the worker)\n     * @param name Unique name for this child instance\n     * @returns A typed RPC stub for calling methods on the child\n     */\n    async subAgent<T extends SubAgent>(\n      cls: SubAgentClass<T>,\n      name: string\n    ): Promise<SubAgentStub<T>> {\n      const { ctx } = this as unknown as { ctx: DurableObjectState };\n      _validateSubAgentExport(ctx, cls);\n      return _getSubAgent(ctx, cls, name);\n    }\n\n    /**\n     * Forcefully abort a running sub-agent. The child stops executing\n     * immediately and will be restarted on next {@link subAgent} call.\n     * Pending RPC calls receive the reason as an error.\n     * Transitively aborts the child's own children.\n     *\n     * @experimental Requires the `\"experimental\"` compatibility flag.\n     *\n     * @param name Name of the child to abort\n     * @param reason Error thrown to pending/future RPC callers\n     */\n    abortSubAgent(name: string, reason?: unknown): void {\n      const { ctx } = this as unknown as { ctx: DurableObjectState };\n      _abortSubAgent(ctx, name, reason);\n    }\n\n    /**\n     * Delete a sub-agent: abort it if running, then permanently wipe its\n     * storage. Transitively deletes the child's own children.\n     *\n     * @experimental Requires the `\"experimental\"` compatibility flag.\n     *\n     * @param name Name of the child to delete\n     */\n    deleteSubAgent(name: string): void {\n      const { ctx } = this as unknown as { ctx: DurableObjectState };\n      _deleteSubAgent(ctx, name);\n    }\n  }\n  return WithSubAgents;\n}\n\n// ── Shared helpers (used by both SubAgent and withSubAgents mixin) ───\n\n/**\n * Synchronous validation that the SubAgent class exists in worker exports.\n * Call this before `_getSubAgent` so the error is thrown synchronously\n * in the caller’s scope (not as a rejected promise from an async function).\n * This avoids unhandled-rejection noise in the workerd runtime.\n * @internal\n */\nexport function _validateSubAgentExport(\n  ctx: DurableObjectState,\n  cls: SubAgentClass\n): void {\n  const { exports } = ctx as unknown as FacetCapableCtx;\n  if (!exports[cls.name]) {\n    throw new Error(\n      `SubAgent class \"${cls.name}\" not found in worker exports. ` +\n        `Make sure the class is exported from your worker entry point ` +\n        `and that the export name matches the class name.`\n    );\n  }\n}\n\n/** @internal */\nexport async function _getSubAgent<T extends SubAgent>(\n  ctx: DurableObjectState,\n  cls: SubAgentClass<T>,\n  name: string\n): Promise<SubAgentStub<T>> {\n  const { facets, exports } = ctx as unknown as FacetCapableCtx;\n  const stub = facets.get(name, () => ({\n    class: exports[cls.name] as DurableObjectClass\n  }));\n\n  // Trigger Server initialization (setName → onStart) via fetch,\n  // same pattern as getAgentByName / getServerByName.\n  const req = new Request(\n    \"http://dummy-example.cloudflare.com/cdn-cgi/partyserver/set-name/\"\n  );\n  req.headers.set(\"x-partykit-room\", name);\n  await stub.fetch(req).then((res) => res.text());\n\n  return stub as unknown as SubAgentStub<T>;\n}\n\n/** @internal */\nexport function _abortSubAgent(\n  ctx: DurableObjectState,\n  name: string,\n  reason?: unknown\n): void {\n  (ctx as unknown as FacetCapableCtx).facets.abort(name, reason);\n}\n\n/** @internal */\nexport function _deleteSubAgent(ctx: DurableObjectState, name: string): void {\n  (ctx as unknown as FacetCapableCtx).facets.delete(name);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2HA,IAAa,WAAb,cAEU,OAAY;;;;;;;;;;;;;;;;;;;;;CAqBpB,MAAM,SACJ,KACA,MAC0B;AAC1B,0BAAwB,KAAK,KAAK,IAAI;AACtC,SAAO,aAAa,KAAK,KAAK,KAAK,KAAK;;;;;;;;;;;;;CAc1C,cAAc,MAAc,QAAwB;AAClD,iBAAe,KAAK,KAAK,MAAM,OAAO;;;;;;;;;;CAWxC,eAAe,MAAoB;AACjC,kBAAgB,KAAK,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCnC,SAAgB,cAAyC,MAAa;CACpE,MAAM,sBAAsB,KAAK;;;;;;;;;;;;;EAa/B,MAAM,SACJ,KACA,MAC0B;GAC1B,MAAM,EAAE,QAAQ;AAChB,2BAAwB,KAAK,IAAI;AACjC,UAAO,aAAa,KAAK,KAAK,KAAK;;;;;;;;;;;;;EAcrC,cAAc,MAAc,QAAwB;GAClD,MAAM,EAAE,QAAQ;AAChB,kBAAe,KAAK,MAAM,OAAO;;;;;;;;;;EAWnC,eAAe,MAAoB;GACjC,MAAM,EAAE,QAAQ;AAChB,mBAAgB,KAAK,KAAK;;;AAG9B,QAAO;;;;;;;;;AAYT,SAAgB,wBACd,KACA,KACM;CACN,MAAM,EAAE,YAAY;AACpB,KAAI,CAAC,QAAQ,IAAI,MACf,OAAM,IAAI,MACR,mBAAmB,IAAI,KAAK,8IAG7B;;;AAKL,eAAsB,aACpB,KACA,KACA,MAC0B;CAC1B,MAAM,EAAE,QAAQ,YAAY;CAC5B,MAAM,OAAO,OAAO,IAAI,aAAa,EACnC,OAAO,QAAQ,IAAI,OACpB,EAAE;CAIH,MAAM,MAAM,IAAI,QACd,oEACD;AACD,KAAI,QAAQ,IAAI,mBAAmB,KAAK;AACxC,OAAM,KAAK,MAAM,IAAI,CAAC,MAAM,QAAQ,IAAI,MAAM,CAAC;AAE/C,QAAO;;;AAIT,SAAgB,eACd,KACA,MACA,QACM;AACN,CAAC,IAAmC,OAAO,MAAM,MAAM,OAAO;;;AAIhE,SAAgB,gBAAgB,KAAyB,MAAoB;AAC3E,CAAC,IAAmC,OAAO,OAAO,KAAK"}

package/dist/index.d.ts

@@ -596,7 +596,23 @@ declare class Agent<
     }
   ): Promise<Schedule<T>>;
   /**
-   * Schedule a task to run repeatedly at a fixed interval
+   * Schedule a task to run repeatedly at a fixed interval.
+   *
+   * This method is **idempotent** — calling it multiple times with the same
+   * `callback`, `intervalSeconds`, and `payload` returns the existing schedule
+   * instead of creating a duplicate. A different interval or payload is
+   * treated as a distinct schedule and creates a new row.
+   *
+   * This makes it safe to call in `onStart()`, which runs on every Durable
+   * Object wake:
+   *
+   * ```ts
+   * async onStart() {
+   *   // Only one schedule is created, no matter how many times the DO wakes
+   *   await this.scheduleEvery(30, "tick");
+   * }
+   * ```
+   *
    * @template T Type of the payload data
    * @param intervalSeconds Number of seconds between executions
    * @param callback Name of the method to call
@@ -611,6 +627,7 @@ declare class Agent<
     payload?: T,
     options?: {
       retry?: RetryOptions;
+      _idempotent?: boolean;
     }
   ): Promise<Schedule<T>>;
   /**
@@ -688,15 +705,25 @@ declare class Agent<
    */
   _cf_keepAliveHeartbeat(): Promise<void>;
   private _scheduleNextAlarm;
+  /**
+   * Override PartyServer's onAlarm hook as a no-op.
+   * Agent handles alarm logic directly in the alarm() method override,
+   * but super.alarm() calls onAlarm() after #ensureInitialized(),
+   * so we suppress the default "Implement onAlarm" warning.
+   */
+  onAlarm(): void;
   /**
    * Method called when an alarm fires.
    * Executes any scheduled tasks that are due.
    *
+   * Calls super.alarm() first to ensure PartyServer's #ensureInitialized()
+   * runs, which hydrates this.name from storage and calls onStart() if needed.
+   *
    * @remarks
    * To schedule a task, please use the `this.schedule` method instead.
    * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
-  readonly alarm: () => Promise<void>;
+  alarm(): Promise<void>;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */
@@ -1077,7 +1104,7 @@ declare class Agent<
    * Broadcast a message to all connected clients via RPC.
    * @internal - Called by AgentWorkflow, do not call directly
    */
-  _workflow_broadcast(message: unknown): void;
+  _workflow_broadcast(message: unknown): Promise<void>;
   /**
    * Update agent state via RPC.
    * @internal - Called by AgentWorkflow, do not call directly
@@ -1085,7 +1112,7 @@ declare class Agent<
   _workflow_updateState(
     action: "set" | "merge" | "reset",
     state?: unknown
-  ): void;
+  ): Promise<void>;
   /**
    * Connect to a new MCP Server via RPC (Durable Object binding)
    *