agents 0.21.0 → 0.23.0

package/dist/browser/tanstack-ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../src/browser/tanstack-ai.ts"],"sourcesContent":["import { toolDefinition } from \"@tanstack/ai\";\nimport type { ServerTool } from \"@tanstack/ai\";\nimport type { ProxyToolOutput } from \"@cloudflare/codemode\";\nimport { z } from \"zod\";\nimport { createBrowserRuntime, type CreateBrowserToolsOptions } from \"./ai\";\n\nexport type { CreateBrowserToolsOptions } from \"./ai\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array with a single durable `browser_execute` `ServerTool`\n * backed by the same codemode runtime as `agents/browser/ai` — the model\n * writes TypeScript against the `cdp` connector and browser sessions\n * survive pauses.\n *\n * The stateless Quick Action tools are not surfaced through this TanStack\n * wrapper (it exposes only `browser_execute`); use `createQuickActionTools`\n * from `agents/browser/ai` if you want them.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ServerTool[] {\n  // This wrapper only surfaces `browser_execute`, so don't build the default-on\n  // Quick Action tools just to discard them.\n  const { tools } = createBrowserRuntime({ ...options, quickActions: false });\n  const executeTool = tools.browser_execute;\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description:\n      typeof executeTool.description === \"function\"\n        ? \"\"\n        : (executeTool.description ?? \"\"),\n    inputSchema: z.object({\n      code: z.string().meta({\n        description:\n          \"TypeScript async arrow function that uses the cdp connector\"\n      })\n    })\n  }).server(async ({ code }) => {\n    if (!executeTool.execute) {\n      throw new Error(\"browser_execute tool is not executable\");\n    }\n    const result = (await executeTool.execute({ code }, {\n      toolCallId: crypto.randomUUID(),\n      messages: [],\n      context: {}\n    } as never)) as ProxyToolOutput;\n    // TanStack has a single return channel, so what the host sees is what the\n    // model sees: apply the AI SDK path's `toModelOutput` projection so a\n    // screenshot's base64 cannot reach the model. The execution envelope\n    // (status, executionId, calls) is preserved either way.\n    const modelOutput = await executeTool.toModelOutput?.({\n      toolCallId: crypto.randomUUID(),\n      input: { code },\n      output: result\n    });\n    if (modelOutput?.type === \"error-text\") {\n      throw new Error(modelOutput.value);\n    }\n    if (modelOutput?.type === \"text\") {\n      return { ...result, result: modelOutput.value };\n    }\n    if (modelOutput?.type === \"json\") {\n      return modelOutput.value;\n    }\n    return result;\n  });\n\n  return [execute];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,mBACd,SACc;CAGd,MAAM,EAAE,UAAU,qBAAqB;EAAE,GAAG;EAAS,cAAc;CAAM,CAAC;CAC1E,MAAM,cAAc,MAAM;CA4C1B,OAAO,CA1CS,eAAe;EAC7B,MAAM;EACN,aACE,OAAO,YAAY,gBAAgB,aAC/B,KACC,YAAY,eAAe;EAClC,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aACE,8DACJ,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,IAAI,CAAC,YAAY,SACf,MAAM,IAAI,MAAM,wCAAwC;EAE1D,MAAM,SAAU,MAAM,YAAY,QAAQ,EAAE,KAAK,GAAG;GAClD,YAAY,OAAO,WAAW;GAC9B,UAAU,CAAC;GACX,SAAS,CAAC;EACZ,CAAU;EAKV,MAAM,cAAc,MAAM,YAAY,gBAAgB;GACpD,YAAY,OAAO,WAAW;GAC9B,OAAO,EAAE,KAAK;GACd,QAAQ;EACV,CAAC;EACD,IAAI,aAAa,SAAS,cACxB,MAAM,IAAI,MAAM,YAAY,KAAK;EAEnC,IAAI,aAAa,SAAS,QACxB,OAAO;GAAE,GAAG;GAAQ,QAAQ,YAAY;EAAM;EAEhD,IAAI,aAAa,SAAS,QACxB,OAAO,YAAY;EAErB,OAAO;CACT,CAEc,CAAC;AACjB"}
+{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../src/browser/tanstack-ai.ts"],"sourcesContent":["import { toolDefinition } from \"@tanstack/ai\";\nimport type { ServerTool } from \"@tanstack/ai\";\nimport type { ProxyToolOutput } from \"@cloudflare/codemode\";\nimport { z } from \"zod\";\nimport { createBrowserRuntime, type CreateBrowserToolsOptions } from \"./ai\";\n\nexport type { CreateBrowserToolsOptions } from \"./ai\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array with a single durable `browser_execute` `ServerTool`\n * backed by the same codemode runtime as `agents/browser/ai` — the model\n * writes TypeScript against the `cdp` connector and browser sessions\n * survive pauses.\n *\n * The stateless Quick Action tools are not surfaced through this TanStack\n * wrapper (it exposes only `browser_execute`); use `createQuickActionTools`\n * from `agents/browser/ai` if you want them.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ServerTool[] {\n  // This wrapper only surfaces `browser_execute`, so don't build the default-on\n  // Quick Action tools just to discard them.\n  const { tools } = createBrowserRuntime({ ...options, quickActions: false });\n  const executeTool = tools.browser_execute;\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description:\n      typeof executeTool.description === \"function\"\n        ? \"\"\n        : (executeTool.description ?? \"\"),\n    inputSchema: z.object({\n      code: z.string().meta({\n        description:\n          \"TypeScript async arrow function that uses the cdp connector\"\n      })\n    })\n  }).server(async ({ code }) => {\n    if (!executeTool.execute) {\n      throw new Error(\"browser_execute tool is not executable\");\n    }\n    const result = (await executeTool.execute({ code }, {\n      toolCallId: crypto.randomUUID(),\n      messages: [],\n      context: {}\n    } as never)) as ProxyToolOutput;\n    // TanStack has a single return channel, so what the host sees is what the\n    // model sees: apply the AI SDK path's `toModelOutput` projection so a\n    // screenshot's base64 cannot reach the model and the durable `calls` log\n    // stays out of its context. The execution envelope (status, executionId)\n    // is preserved either way.\n    const modelOutput = await executeTool.toModelOutput?.({\n      toolCallId: crypto.randomUUID(),\n      input: { code },\n      output: result\n    });\n    if (modelOutput?.type === \"error-text\") {\n      throw new Error(modelOutput.value);\n    }\n    if (modelOutput?.type === \"text\") {\n      return { ...result, result: modelOutput.value };\n    }\n    if (modelOutput?.type === \"json\") {\n      return modelOutput.value;\n    }\n    return result;\n  });\n\n  return [execute];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,mBACd,SACc;CAGd,MAAM,EAAE,UAAU,qBAAqB;EAAE,GAAG;EAAS,cAAc;CAAM,CAAC;CAC1E,MAAM,cAAc,MAAM;CA6C1B,OAAO,CA3CS,eAAe;EAC7B,MAAM;EACN,aACE,OAAO,YAAY,gBAAgB,aAC/B,KACC,YAAY,eAAe;EAClC,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aACE,8DACJ,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,IAAI,CAAC,YAAY,SACf,MAAM,IAAI,MAAM,wCAAwC;EAE1D,MAAM,SAAU,MAAM,YAAY,QAAQ,EAAE,KAAK,GAAG;GAClD,YAAY,OAAO,WAAW;GAC9B,UAAU,CAAC;GACX,SAAS,CAAC;EACZ,CAAU;EAMV,MAAM,cAAc,MAAM,YAAY,gBAAgB;GACpD,YAAY,OAAO,WAAW;GAC9B,OAAO,EAAE,KAAK;GACd,QAAQ;EACV,CAAC;EACD,IAAI,aAAa,SAAS,cACxB,MAAM,IAAI,MAAM,YAAY,KAAK;EAEnC,IAAI,aAAa,SAAS,QACxB,OAAO;GAAE,GAAG;GAAQ,QAAQ,YAAY;EAAM;EAEhD,IAAI,aAAa,SAAS,QACxB,OAAO,YAAY;EAErB,OAAO;CACT,CAEc,CAAC;AACjB"}

package/dist/callable-decorator-DP__HhBA.d.ts

@@ -0,0 +1,72 @@
+//#region src/callable-decorator.d.ts
+/**
+ * The `@callable()` method decorator and its metadata registry.
+ *
+ * Consumed by Agent's legacy JSON RPC protocol and, as a fallback
+ * interface source, by the WebSockets capability's Cap'n Web callables
+ * endpoint. Kept dependency-free so both can import it without cycles.
+ */
+/**
+ * Metadata for a callable method
+ */
+type CallableMetadata = {
+  /** Optional description of what the method does */ description?: string /** Whether the method supports streaming responses */;
+  streaming?: boolean;
+};
+/**
+ * Decorator that marks a method as callable by clients
+ * @param metadata Optional metadata about the callable method
+ */
+declare function callable(
+  metadata?: CallableMetadata
+): <This, Args extends unknown[], Return>(
+  target: (this: This, ...args: Args) => Return,
+  _context: ClassMethodDecoratorContext
+) => (this: This, ...args: Args) => Return;
+/**
+ * Decorator that marks a method as callable by clients
+ * @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
+ * @param metadata Optional metadata about the callable method
+ */
+declare const unstable_callable: (
+  metadata?: CallableMetadata
+) => <This, Args extends unknown[], Return>(
+  target: (this: This, ...args: Args) => Return,
+  _context: ClassMethodDecoratorContext
+) => (this: This, ...args: Args) => Return;
+/** @internal Read the metadata registered for a decorated method. */
+declare function getCallableMetadata(
+  method: Function
+): CallableMetadata | undefined;
+/** @internal Whether a method was registered with `@callable()`. */
+declare function isCallableMethod(method: Function): boolean;
+/**
+ * @internal Preserve registration when a framework wraps a decorated
+ * method (e.g. Agent's context auto-wrapping).
+ */
+declare function copyCallableMetadata(source: Function, target: Function): void;
+/**
+ * Every `@callable()`-registered method reachable on a host's prototype
+ * chain, with its metadata. The nearest declaration wins when a
+ * subclass overrides a decorated parent method.
+ *
+ * The canonical decorator scan — Agent introspection and the WebSockets
+ * capability's decorator-fallback target both consume it.
+ *
+ * @param host - The object whose prototype chain is scanned.
+ * @returns Method names mapped to their registered metadata.
+ */
+declare function decoratedMethods(
+  host: object
+): ReadonlyMap<string, CallableMetadata>;
+//#endregion
+export {
+  getCallableMetadata as a,
+  decoratedMethods as i,
+  callable as n,
+  isCallableMethod as o,
+  copyCallableMetadata as r,
+  unstable_callable as s,
+  CallableMetadata as t
+};
+//# sourceMappingURL=callable-decorator-DP__HhBA.d.ts.map

package/dist/callable-decorator.d.ts

@@ -0,0 +1,18 @@
+import {
+  a as getCallableMetadata,
+  i as decoratedMethods,
+  n as callable,
+  o as isCallableMethod,
+  r as copyCallableMetadata,
+  s as unstable_callable,
+  t as CallableMetadata
+} from "./callable-decorator-DP__HhBA.js";
+export {
+  CallableMetadata,
+  callable,
+  copyCallableMetadata,
+  decoratedMethods,
+  getCallableMetadata,
+  isCallableMethod,
+  unstable_callable
+};

package/dist/callable-decorator.js

@@ -0,0 +1,71 @@
+//#region src/callable-decorator.ts
+const callableMetadata = /* @__PURE__ */ new WeakMap();
+/**
+* Decorator that marks a method as callable by clients
+* @param metadata Optional metadata about the callable method
+*/
+function callable(metadata = {}) {
+	return function callableDecorator(target, _context) {
+		if (!callableMetadata.has(target)) callableMetadata.set(target, metadata);
+		return target;
+	};
+}
+let didWarnAboutUnstableCallable = false;
+/**
+* Decorator that marks a method as callable by clients
+* @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
+* @param metadata Optional metadata about the callable method
+*/
+const unstable_callable = (metadata = {}) => {
+	if (!didWarnAboutUnstableCallable) {
+		didWarnAboutUnstableCallable = true;
+		console.warn("unstable_callable is deprecated, use callable instead. unstable_callable will be removed in the next major version.");
+	}
+	return callable(metadata);
+};
+/** @internal Read the metadata registered for a decorated method. */
+function getCallableMetadata(method) {
+	return callableMetadata.get(method);
+}
+/** @internal Whether a method was registered with `@callable()`. */
+function isCallableMethod(method) {
+	return callableMetadata.has(method);
+}
+/**
+* @internal Preserve registration when a framework wraps a decorated
+* method (e.g. Agent's context auto-wrapping).
+*/
+function copyCallableMetadata(source, target) {
+	const metadata = callableMetadata.get(source);
+	if (metadata) callableMetadata.set(target, metadata);
+}
+/**
+* Every `@callable()`-registered method reachable on a host's prototype
+* chain, with its metadata. The nearest declaration wins when a
+* subclass overrides a decorated parent method.
+*
+* The canonical decorator scan — Agent introspection and the WebSockets
+* capability's decorator-fallback target both consume it.
+*
+* @param host - The object whose prototype chain is scanned.
+* @returns Method names mapped to their registered metadata.
+*/
+function decoratedMethods(host) {
+	const result = /* @__PURE__ */ new Map();
+	let prototype = Object.getPrototypeOf(host);
+	while (prototype && prototype !== Object.prototype) {
+		for (const name of Object.getOwnPropertyNames(prototype)) {
+			if (name === "constructor" || result.has(name)) continue;
+			const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+			if (!descriptor || typeof descriptor.value !== "function") continue;
+			const metadata = getCallableMetadata(descriptor.value);
+			if (metadata) result.set(name, metadata);
+		}
+		prototype = Object.getPrototypeOf(prototype);
+	}
+	return result;
+}
+//#endregion
+export { callable, copyCallableMetadata, decoratedMethods, getCallableMetadata, isCallableMethod, unstable_callable };
+
+//# sourceMappingURL=callable-decorator.js.map

package/dist/callable-decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callable-decorator.js","names":[],"sources":["../src/callable-decorator.ts"],"sourcesContent":["/**\n * The `@callable()` method decorator and its metadata registry.\n *\n * Consumed by Agent's legacy JSON RPC protocol and, as a fallback\n * interface source, by the WebSockets capability's Cap'n Web callables\n * endpoint. Kept dependency-free so both can import it without cycles.\n */\n\n/**\n * Metadata for a callable method\n */\nexport type CallableMetadata = {\n  /** Optional description of what the method does */\n  description?: string;\n  /** Whether the method supports streaming responses */\n  streaming?: boolean;\n};\n\nconst callableMetadata = new WeakMap<Function, CallableMetadata>();\n\n/**\n * Decorator that marks a method as callable by clients\n * @param metadata Optional metadata about the callable method\n */\nexport function callable(metadata: CallableMetadata = {}) {\n  return function callableDecorator<This, Args extends unknown[], Return>(\n    target: (this: This, ...args: Args) => Return,\n    _context: ClassMethodDecoratorContext\n  ) {\n    if (!callableMetadata.has(target)) {\n      callableMetadata.set(target, metadata);\n    }\n\n    return target;\n  };\n}\n\nlet didWarnAboutUnstableCallable = false;\n\n/**\n * Decorator that marks a method as callable by clients\n * @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version\n * @param metadata Optional metadata about the callable method\n */\nexport const unstable_callable = (metadata: CallableMetadata = {}) => {\n  if (!didWarnAboutUnstableCallable) {\n    didWarnAboutUnstableCallable = true;\n    console.warn(\n      \"unstable_callable is deprecated, use callable instead. unstable_callable will be removed in the next major version.\"\n    );\n  }\n  return callable(metadata);\n};\n\n/** @internal Read the metadata registered for a decorated method. */\nexport function getCallableMetadata(\n  method: Function\n): CallableMetadata | undefined {\n  return callableMetadata.get(method);\n}\n\n/** @internal Whether a method was registered with `@callable()`. */\nexport function isCallableMethod(method: Function): boolean {\n  return callableMetadata.has(method);\n}\n\n/**\n * @internal Preserve registration when a framework wraps a decorated\n * method (e.g. Agent's context auto-wrapping).\n */\nexport function copyCallableMetadata(source: Function, target: Function): void {\n  const metadata = callableMetadata.get(source);\n  if (metadata) callableMetadata.set(target, metadata);\n}\n\n/**\n * Every `@callable()`-registered method reachable on a host's prototype\n * chain, with its metadata. The nearest declaration wins when a\n * subclass overrides a decorated parent method.\n *\n * The canonical decorator scan — Agent introspection and the WebSockets\n * capability's decorator-fallback target both consume it.\n *\n * @param host - The object whose prototype chain is scanned.\n * @returns Method names mapped to their registered metadata.\n */\nexport function decoratedMethods(\n  host: object\n): ReadonlyMap<string, CallableMetadata> {\n  const result = new Map<string, CallableMetadata>();\n  let prototype: object | null = Object.getPrototypeOf(host);\n  while (prototype && prototype !== Object.prototype) {\n    for (const name of Object.getOwnPropertyNames(prototype)) {\n      if (name === \"constructor\" || result.has(name)) continue;\n      const descriptor = Object.getOwnPropertyDescriptor(prototype, name);\n      if (!descriptor || typeof descriptor.value !== \"function\") continue;\n      const metadata = getCallableMetadata(descriptor.value);\n      if (metadata) result.set(name, metadata);\n    }\n    prototype = Object.getPrototypeOf(prototype);\n  }\n  return result;\n}\n"],"mappings":";AAkBA,MAAM,mCAAmB,IAAI,QAAoC;;;;;AAMjE,SAAgB,SAAS,WAA6B,CAAC,GAAG;CACxD,OAAO,SAAS,kBACd,QACA,UACA;EACA,IAAI,CAAC,iBAAiB,IAAI,MAAM,GAC9B,iBAAiB,IAAI,QAAQ,QAAQ;EAGvC,OAAO;CACT;AACF;AAEA,IAAI,+BAA+B;;;;;;AAOnC,MAAa,qBAAqB,WAA6B,CAAC,MAAM;CACpE,IAAI,CAAC,8BAA8B;EACjC,+BAA+B;EAC/B,QAAQ,KACN,qHACF;CACF;CACA,OAAO,SAAS,QAAQ;AAC1B;;AAGA,SAAgB,oBACd,QAC8B;CAC9B,OAAO,iBAAiB,IAAI,MAAM;AACpC;;AAGA,SAAgB,iBAAiB,QAA2B;CAC1D,OAAO,iBAAiB,IAAI,MAAM;AACpC;;;;;AAMA,SAAgB,qBAAqB,QAAkB,QAAwB;CAC7E,MAAM,WAAW,iBAAiB,IAAI,MAAM;CAC5C,IAAI,UAAU,iBAAiB,IAAI,QAAQ,QAAQ;AACrD;;;;;;;;;;;;AAaA,SAAgB,iBACd,MACuC;CACvC,MAAM,yBAAS,IAAI,IAA8B;CACjD,IAAI,YAA2B,OAAO,eAAe,IAAI;CACzD,OAAO,aAAa,cAAc,OAAO,WAAW;EAClD,KAAK,MAAM,QAAQ,OAAO,oBAAoB,SAAS,GAAG;GACxD,IAAI,SAAS,iBAAiB,OAAO,IAAI,IAAI,GAAG;GAChD,MAAM,aAAa,OAAO,yBAAyB,WAAW,IAAI;GAClE,IAAI,CAAC,cAAc,OAAO,WAAW,UAAU,YAAY;GAC3D,MAAM,WAAW,oBAAoB,WAAW,KAAK;GACrD,IAAI,UAAU,OAAO,IAAI,MAAM,QAAQ;EACzC;EACA,YAAY,OAAO,eAAe,SAAS;CAC7C;CACA,OAAO;AACT"}

package/dist/capability-BjSKYpzg.js

@@ -0,0 +1,42 @@
+//#region src/lifecycle/capability.ts
+const installedServices = /* @__PURE__ */ new WeakMap();
+/**
+* Base class for capabilities that consume standard Lifecycle services.
+*
+* @experimental The API surface may change before stabilizing.
+*/
+var LifecycleCapability = class {
+	constructor(capabilityId) {
+		if (capabilityId.trim() === "") throw new Error("Lifecycle capability IDs must be non-empty");
+		this.capabilityId = capabilityId;
+	}
+	/** Default startup hook; capabilities override when they own startup work. */
+	onStart(_context) {}
+	/** Standard services when installed, or undefined in isolated unit tests. */
+	get lifecycleServices() {
+		return installedServices.get(this);
+	}
+	/** Standard services supplied when Lifecycle installs this capability. */
+	get lifecycle() {
+		const services = this.lifecycleServices;
+		if (!services) throw new Error(`${this.constructor.name} must be installed with Lifecycle.use() before use`);
+		return services;
+	}
+};
+/**
+* @internal Bind the standard service surface to one capability instance.
+* `Lifecycle.use()` calls this during installation. Test a capability by
+* installing it on a minimal Durable Object with a real Lifecycle rather
+* than binding fake services.
+*/
+function bindLifecycleCapability(capability, services) {
+	installedServices.set(capability, services);
+}
+/** @internal Read a capability ID without exposing installation internals. */
+function lifecycleCapabilityId(capability) {
+	return capability instanceof LifecycleCapability ? capability.capabilityId : void 0;
+}
+//#endregion
+export { bindLifecycleCapability as n, lifecycleCapabilityId as r, LifecycleCapability as t };
+
+//# sourceMappingURL=capability-BjSKYpzg.js.map

package/dist/capability-BjSKYpzg.js.map

@@ -0,0 +1 @@
+{"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"}