agents 0.23.0 → 0.25.0

package/dist/capability-B4WbF81e.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-B4WbF81e.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/** Startup state of a Lifecycle. */\nexport type LifecycleStatus = \"zero\" | \"starting\" | \"started\";\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  /** The host's Durable Object name; see `Lifecycle.name`. */\n  readonly name: string;\n  /** The host class name, as exported from the Worker. */\n  readonly className: string;\n  readonly storage: DurableObjectStorage;\n  readonly sockets: LifecycleSockets;\n  /**\n   * Resolve once Lifecycle startup has finished, starting it if needed, and\n   * reject if that startup fails. Calls made from inside startup resolve\n   * immediately.\n   */\n  readonly ready: () => Promise<void>;\n  /**\n   * Startup state: `\"zero\"` before startup, `\"starting\"` while capability\n   * and host startup hooks run, `\"started\"` once `ready()` resolves without\n   * waiting.\n   */\n  readonly status: () => LifecycleStatus;\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  /** How this capability claims traffic; see {@link DurableObjectCapability.claims}. */\n  readonly claims: \"selective\" | \"catch-all\" = \"selective\";\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":";AAwHA,MAAM,oCAAoB,IAAI,QAAmC;;;;;;AAOjE,IAAsB,sBAAtB,MAAyE;CAMvE,YAAsB,cAAsB;EAF5C,KAAS,SAAoC;EAG3C,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/{capability-runner-Be_-PLR1.d.ts → capability-runner-DBAnGr6L.d.ts}

@@ -1,4 +1,4 @@
-import { t as RetryOptions } from "./retries-D9Ds-1lz.js";
+import { t as RetryOptions } from "./retries-CV6AkXmQ.js";
 
 //#region src/lifecycle/types.d.ts
 type ImmutablePrimitive = undefined | null | boolean | string | number;
@@ -174,6 +174,8 @@ type LifecycleRouteContext = {
     | undefined /** Capability-owned message payload. */;
   readonly payload: unknown;
 };
+/** Startup state of a Lifecycle. */
+type LifecycleStatus = "zero" | "starting" | "started";
 /** Best-effort telemetry available to every Lifecycle capability. */
 type LifecycleEvents = {
   /** Publish an event under this capability's stable identity. */ readonly emit: (
@@ -221,10 +223,22 @@ type LifecycleSockets = {
  * @experimental The API surface may change before stabilizing.
  */
 type LifecycleServices = {
+  /** The host's Durable Object name; see `Lifecycle.name`. */ readonly name: string /** The host class name, as exported from the Worker. */;
+  readonly className: string;
   readonly storage: DurableObjectStorage;
   readonly sockets: LifecycleSockets;
-  readonly ready: () => Promise<void> /** True while capability and host startup hooks are still running. */;
-  readonly starting: () => boolean;
+  /**
+   * Resolve once Lifecycle startup has finished, starting it if needed, and
+   * reject if that startup fails. Calls made from inside startup resolve
+   * immediately.
+   */
+  readonly ready: () => Promise<void>;
+  /**
+   * Startup state: `"zero"` before startup, `"starting"` while capability
+   * and host startup hooks run, `"started"` once `ready()` resolves without
+   * waiting.
+   */
+  readonly status: () => LifecycleStatus;
   /**
    * This capability's scoped access to the Lifecycle-owned work queue.
    * Pushed items are dispatched to `onJob` when due; every queue mutation
@@ -258,6 +272,8 @@ type LifecycleServices = {
  */
 declare abstract class LifecycleCapability<Props extends object = object> {
   readonly capabilityId: string;
+  /** How this capability claims traffic; see {@link DurableObjectCapability.claims}. */
+  readonly claims: "selective" | "catch-all";
   protected constructor(capabilityId: string);
   /** Default startup hook; capabilities override when they own startup work. */
   onStart(_context: CapabilityStartContext<Props>): void;
@@ -334,7 +350,7 @@ type MemoryLimitContext = {
  *
  * Dispatch contract, hook by hook:
  * - `onRequest` and `onWebSocketUpgrade` are offered in declaration
- *   order, fallbacks last; the first capability to return a `Response`
+ *   order, the catch-all last; the first capability to return a `Response`
  *   claims the request, and a claimed upgrade's socket belongs to that
  *   capability for its whole lifetime.
  * - `onWebSocketMessage`/`onWebSocketClose`/`onWebSocketError` are
@@ -349,6 +365,19 @@ type MemoryLimitContext = {
  * @experimental The API surface may change before stabilizing.
  */
 interface DurableObjectCapability<Props extends object = object> {
+  /**
+   * How this capability claims traffic. Default: `"selective"`.
+   *
+   * A `"selective"` capability answers only requests and upgrades it
+   * recognizes and declines the rest. A `"catch-all"` claims everything
+   * offered to the hooks it implements, so Lifecycle always places it
+   * last, whenever it was installed, and refuses a second catch-all for
+   * the same hook. Catch-alls for disjoint hooks coexist: `WebSockets`
+   * claims every upgrade and implements no `onRequest`, so an HTTP
+   * catch-all installs beside it. Selective HTTP capabilities target
+   * their own routes and run before either.
+   */
+  readonly claims?: "selective" | "catch-all";
   /** Initialize or recover the capability before the host handles work. */
   onStart?(context: CapabilityStartContext<Props>): MaybePromise<void>;
   /**
@@ -431,16 +460,17 @@ interface DurableObjectCapability<Props extends object = object> {
 }
 //#endregion
 export {
-  ConnectionState as C,
-  ConnectionSetStateFn as S,
-  LifecycleJobOutcome as _,
+  ConnectionSetStateFn as C,
+  ConnectionContext as S,
+  WSMessage as T,
+  LifecycleJobContext as _,
   LifecycleEvent as a,
-  Connection as b,
+  LifecycleJobs as b,
   LifecycleEvents as c,
   LifecycleRouteContext as d,
   LifecycleRoutes as f,
-  LifecycleJobContext as g,
-  LifecycleJob as h,
+  LifecycleJob as g,
+  LifecycleStatus as h,
   DurableObjectCapability as i,
   LifecycleHostContextScope as l,
   LifecycleSockets as m,
@@ -451,9 +481,9 @@ export {
   LifecycleCapability as s,
   CapabilityRequestContext as t,
   LifecycleRouteAddress as u,
-  LifecycleJobPushOptions as v,
-  WSMessage as w,
-  ConnectionContext as x,
-  LifecycleJobs as y
+  LifecycleJobOutcome as v,
+  ConnectionState as w,
+  Connection as x,
+  LifecycleJobPushOptions as y
 };
-//# sourceMappingURL=capability-runner-Be_-PLR1.d.ts.map
+//# sourceMappingURL=capability-runner-DBAnGr6L.d.ts.map