agents 0.26.0 → 0.28.0

package/dist/conversations-FjHDRZyD.d.ts

@@ -0,0 +1,192 @@
+import { s as LifecycleCapability } from "./capability-runner-BiVUtjqC.js";
+import { n as Streams } from "./streams-vrCtbUIn.js";
+import {
+  _ as TranscriptMessage,
+  a as DispatchResult,
+  b as ChannelMessageSurface,
+  c as InboundEvent,
+  i as ConversationSnapshot,
+  m as ResponseChunk,
+  n as ConversationInfo,
+  o as EventOrigin,
+  r as ConversationOperation,
+  s as GatewayOrigin,
+  y as TurnStatus
+} from "./protocol-CukuI73M.js";
+import { i as WebSockets } from "./index-CBt8oRJt.js";
+import { t as AgentHarness } from "./harness-B6B9S3rb.js";
+
+//#region src/experimental/channels/conversations.d.ts
+/**
+ * An inbound event as the gateway sends it. An approval response from a
+ * webhook names no turn; Channels finds it from the conversation snapshot.
+ */
+type GatewayEvent =
+  | InboundEvent
+  | Omit<
+      Extract<
+        InboundEvent,
+        {
+          type: "approval-response";
+        }
+      >,
+      "turnId"
+    >;
+/** How a response finished, as a reader sees it. */
+type ResponseEnding = "ended" | "interrupted" | "not-found";
+/** A change Channels pushes to every channel showing a conversation. */
+type ConversationUpdate =
+  | {
+      type: "turn";
+      turn: TurnStatus;
+    }
+  | {
+      type: "messages";
+      messages: TranscriptMessage[] /** Set when the messages arrived as an inbound event. */;
+      origin?: EventOrigin /** The inbound event's id, set with `origin`. */;
+      eventId?: string;
+    }
+  | {
+      type: "reset";
+    }
+  | {
+      type: "response-end";
+      responseId: string;
+      ending: ResponseEnding;
+    };
+type ResponseReadOptions = {
+  from?: number;
+  signal?: AbortSignal;
+  onChunks(
+    from: number,
+    chunks: ResponseChunk[]
+  ): void /** Everything recorded so far has been read; what follows is live. */;
+  onCaughtUp(cursor: number): void;
+};
+/** Durable state a channel keeps in the agent, private to that channel. */
+type ChannelState = {
+  get<T>(key: string): T | undefined;
+  put(key: string, value: unknown): void;
+  delete(key: string): void;
+};
+/** What Channels gives a mounted channel. */
+type ChannelsHost = {
+  readonly channelKey: string;
+  /**
+   * The WebSockets this Channels' channels share: the instance Channels was
+   * given, or else the one the first channel to ask creates. Install it with
+   * `Lifecycle.use(channels.websockets)`.
+   */
+  websockets(
+    create: () => WebSockets
+  ): WebSockets /** This channel's surfaces that have joined the conversation. */;
+  surfaces(conversationId: string): Promise<ChannelMessageSurface[]>;
+  readonly state: ChannelState;
+  snapshot(
+    conversationId: string
+  ): Promise<ConversationSnapshot> /** The conversation a surface joins when it names none. */;
+  defaultConversation(): string /** The conversation operations the agent supports. */;
+  readonly operations: readonly ConversationOperation[] /** The agent's conversations. */;
+  listConversations(): Promise<ConversationInfo[]>;
+  /**
+   * Deliver an event to the agent. Resolves once the agent accepted it and
+   * rejects if the agent threw.
+   */
+  dispatch(event: InboundEvent, origin: EventOrigin): Promise<DispatchResult>;
+  readResponse(
+    conversationId: string,
+    responseId: string,
+    options: ResponseReadOptions
+  ): Promise<ResponseEnding>;
+};
+/** An interface that shows conversations, such as the Web Channel. */
+interface ConversationChannel {
+  /** Called once, when Channels is constructed. Take shared dependencies here. */
+  mount(host: ChannelsHost): void;
+  publish(
+    conversationId: string,
+    update: ConversationUpdate
+  ): void | Promise<void>;
+}
+type ChannelsOptions = {
+  /**
+   * The agent: its sessions are served as conversations, a conversation's
+   * id being its session's id.
+   */
+  harness: AgentHarness /** Install it before Channels. */;
+  streams: Streams /** Shared with channels that serve WebSockets, such as the Web Channel. */;
+  websockets?: WebSockets;
+  channels: Record<string, ConversationChannel>;
+};
+type ForHarnessOptions = {
+  channels: Record<
+    string,
+    ConversationChannel
+  > /** Default: a new Streams, exposed as `channels.streams`. */;
+  streams?: Streams /** Default: one the Web Channel creates, exposed as `channels.websockets`. */;
+  websockets?: WebSockets;
+};
+/**
+ * Serves an agent harness's sessions as conversations: carries inbound
+ * events to the harness, and responses, turn statuses and transcript
+ * updates back to every channel showing the conversation.
+ */
+declare class Channels extends LifecycleCapability {
+  #private;
+  /**
+   * Channels for any shared-interface harness, with their own Streams and
+   * (when a channel needs them) WebSockets. Lifecycle does not install one
+   * capability from another yet, so install them alongside:
+   *
+   * ```ts
+   * readonly channels = Channels.forHarness(harness, {
+   *   channels: { web: new WebChannel() }
+   * });
+   * readonly lifecycle = Lifecycle.install(this)
+   *   .use(this.harness)
+   *   .use(this.channels.streams)
+   *   .use(this.channels)
+   *   .use(this.channels.websockets);
+   *
+   * receive(event: GatewayEvent, origin: GatewayOrigin) {
+   *   return this.channels.receive(event, origin);
+   * }
+   * ```
+   */
+  static forHarness(
+    harness: AgentHarness,
+    options: ForHarnessOptions
+  ): Channels;
+  /** The responses' Streams. Install it before Channels. */
+  readonly streams: Streams;
+  constructor(options: ChannelsOptions);
+  /**
+   * The WebSockets the channels share. Install it with Lifecycle. Throws
+   * when no channel uses WebSockets.
+   */
+  get websockets(): WebSockets;
+  /** Mark responses left streaming by an earlier instance as interrupted. */
+  onStart(): Promise<void>;
+  /**
+   * Deliver an inbound event from the gateway, through the same path as
+   * the agent's own channels. The agent calls this from its RPC method.
+   */
+  receive(
+    event: GatewayEvent,
+    from: GatewayOrigin | EventOrigin
+  ): Promise<void>;
+}
+//#endregion
+export {
+  ConversationChannel as a,
+  GatewayEvent as c,
+  ChannelsOptions as i,
+  ResponseEnding as l,
+  Channels as n,
+  ConversationUpdate as o,
+  ChannelsHost as r,
+  ForHarnessOptions as s,
+  ChannelState as t,
+  ResponseReadOptions as u
+};
+//# sourceMappingURL=conversations-FjHDRZyD.d.ts.map

package/dist/{current-agent-vAk_5JMt.d.ts → current-agent-CKgT5d1O.d.ts}

@@ -3,8 +3,8 @@ import {
   o as MemoryLimitContext,
   v as LifecycleJobOutcome,
   x as Connection
-} from "./capability-runner-DBAnGr6L.js";
-import { t as Lifecycle } from "./durable-object-lifecycle-HhgOMWq9.js";
+} from "./capability-runner-BiVUtjqC.js";
+import { t as Lifecycle } from "./durable-object-lifecycle-DOI_bzCH.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { DurableObject } from "cloudflare:workers";
 
@@ -14,8 +14,6 @@ import { DurableObject } from "cloudflare:workers";
  *
  * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when
  * shared host code needs APIs implemented by a particular object.
- *
- * @experimental The API surface may change before stabilizing.
  */
 interface LifecycleObject<
   Env extends object = Cloudflare.Env,
@@ -90,4 +88,4 @@ export {
   LifecycleObject as r,
   AgentContextStore as t
 };
-//# sourceMappingURL=current-agent-vAk_5JMt.d.ts.map
+//# sourceMappingURL=current-agent-CKgT5d1O.d.ts.map

package/dist/current-agent-DhoDkSnH.js.map

@@ -1 +1 @@
-{"version":3,"file":"current-agent-DhoDkSnH.js","names":[],"sources":["../src/lifecycle/current-agent.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { DurableObject } from \"cloudflare:workers\";\n\nimport type { MemoryLimitContext } from \"./capability-runner\";\nimport type { Lifecycle } from \"./durable-object-lifecycle\";\nimport type { Connection } from \"./types\";\nimport type { LifecycleJobContext, LifecycleJobOutcome } from \"./job-queue\";\n\n/**\n * A Durable Object that has installed the Agents SDK Lifecycle.\n *\n * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when\n * shared host code needs APIs implemented by a particular object.\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport interface LifecycleObject<\n  Env extends object = Cloudflare.Env,\n  Props extends object = object\n> extends DurableObject<Env> {\n  readonly lifecycle: Lifecycle<Env, Props>;\n  onStart?(props?: Props): void | Promise<void>;\n  onRequest?(request: Request): Response | Promise<Response>;\n  onAlarm?(): void | Promise<void>;\n  onJob?(\n    context: LifecycleJobContext\n  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;\n  /**\n   * Host domain policy applied when the alarm memory-limit circuit breaker\n   * records a strike (#1825), after every capability's `onMemoryLimit` hook.\n   *\n   * Lifecycle dispatches host hooks structurally through its internal host\n   * cast, so TS visibility is the host's to choose: a framework host whose\n   * implementation is internal machinery declares the hook `protected` (the\n   * pattern — see `AIChatAgent`/`Think`) and keeps the real work in a\n   * `private _cf_`-prefixed method, without falling out of this contract at\n   * runtime.\n   */\n  onAlarmMemoryLimit?(context: MemoryLimitContext): void | Promise<void>;\n}\n\n/** Values associated with the currently executing Lifecycle host. */\nexport type AgentContextStore = {\n  /** Lifecycle host selected for this invocation. */\n  agent: unknown;\n  /** WebSocket connection selected for this invocation, when applicable. */\n  connection: Connection | undefined;\n  /** HTTP request selected for this invocation, when applicable. */\n  request: Request | undefined;\n  /** Extension-owned value selected for this invocation, when applicable. */\n  email: unknown;\n};\n\n/** Values returned by {@link getCurrentAgent}. */\nexport type CurrentAgentContext<\n  Host extends DurableObject = LifecycleObject,\n  Email = unknown\n> = {\n  agent: Host | undefined;\n  connection: Connection | undefined;\n  request: Request | undefined;\n  email: Email | undefined;\n};\n\n/**\n * Shared invocation context for Lifecycle, Agent, AIChatAgent, and Think.\n *\n * @internal Importing or relying on this symbol will break your code in a\n * future release. Use {@link getCurrentAgent} to read the public context.\n */\nexport const __DO_NOT_USE_WILL_BREAK__agentContext =\n  new AsyncLocalStorage<AgentContextStore>();\n\n/**\n * Return the current Agent or Lifecycle Object and invocation-specific values.\n *\n * Lifecycle host startup and alarm hooks receive the current object with no\n * request. Request hooks additionally receive the request being handled.\n * Lifecycle-managed WebSocket hooks receive their connection and, during\n * connect, its upgrade request. Agent extensions may also establish context\n * for email, chat turns, callable methods, and detached work. Capability hooks\n * do not run in this ambient context.\n */\nexport function getCurrentAgent<\n  Host extends DurableObject = LifecycleObject\n>(): CurrentAgentContext<Host> {\n  const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();\n  if (!store) {\n    return {\n      agent: undefined,\n      connection: undefined,\n      request: undefined,\n      email: undefined\n    };\n  }\n\n  return {\n    agent: store.agent as Host,\n    connection: store.connection,\n    request: store.request,\n    email: store.email\n  };\n}\n\ntype LifecycleHostContext<Env extends object, Props extends object> = {\n  readonly host: LifecycleObject<Env, Props>;\n  readonly connection?: Connection;\n  readonly request?: Request;\n};\n\n/** Run one host hook in the context of its Lifecycle Object. */\nexport function runInLifecycleHostContext<\n  Env extends object,\n  Props extends object,\n  T\n>(context: LifecycleHostContext<Env, Props>, operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.run(\n    {\n      agent: context.host,\n      connection: context.connection,\n      request: context.request,\n      email: undefined\n    },\n    operation\n  );\n}\n\n/** Run a capability hook without inheriting a current Agent or host context. */\nexport function runWithoutCurrentAgent<T>(operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.exit(operation);\n}\n"],"mappings":";;;;;;;;AAsEA,MAAa,wCACX,IAAI,kBAAqC;;;;;;;;;;;AAY3C,SAAgB,kBAEe;CAC7B,MAAM,QAAQ,sCAAsC,SAAS;CAC7D,IAAI,CAAC,OACH,OAAO;EACL,OAAO,KAAA;EACP,YAAY,KAAA;EACZ,SAAS,KAAA;EACT,OAAO,KAAA;CACT;CAGF,OAAO;EACL,OAAO,MAAM;EACb,YAAY,MAAM;EAClB,SAAS,MAAM;EACf,OAAO,MAAM;CACf;AACF;;AASA,SAAgB,0BAId,SAA2C,WAAuB;CAClE,OAAO,sCAAsC,IAC3C;EACE,OAAO,QAAQ;EACf,YAAY,QAAQ;EACpB,SAAS,QAAQ;EACjB,OAAO,KAAA;CACT,GACA,SACF;AACF;;AAGA,SAAgB,uBAA0B,WAAuB;CAC/D,OAAO,sCAAsC,KAAK,SAAS;AAC7D"}
+{"version":3,"file":"current-agent-DhoDkSnH.js","names":[],"sources":["../src/lifecycle/current-agent.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { DurableObject } from \"cloudflare:workers\";\n\nimport type { MemoryLimitContext } from \"./capability-runner\";\nimport type { Lifecycle } from \"./durable-object-lifecycle\";\nimport type { Connection } from \"./types\";\nimport type { LifecycleJobContext, LifecycleJobOutcome } from \"./job-queue\";\n\n/**\n * A Durable Object that has installed the Agents SDK Lifecycle.\n *\n * Pass a more specific Lifecycle Object type to {@link getCurrentAgent} when\n * shared host code needs APIs implemented by a particular object.\n */\nexport interface LifecycleObject<\n  Env extends object = Cloudflare.Env,\n  Props extends object = object\n> extends DurableObject<Env> {\n  readonly lifecycle: Lifecycle<Env, Props>;\n  onStart?(props?: Props): void | Promise<void>;\n  onRequest?(request: Request): Response | Promise<Response>;\n  onAlarm?(): void | Promise<void>;\n  onJob?(\n    context: LifecycleJobContext\n  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;\n  /**\n   * Host domain policy applied when the alarm memory-limit circuit breaker\n   * records a strike (#1825), after every capability's `onMemoryLimit` hook.\n   *\n   * Lifecycle dispatches host hooks structurally through its internal host\n   * cast, so TS visibility is the host's to choose: a framework host whose\n   * implementation is internal machinery declares the hook `protected` (the\n   * pattern — see `AIChatAgent`/`Think`) and keeps the real work in a\n   * `private _cf_`-prefixed method, without falling out of this contract at\n   * runtime.\n   */\n  onAlarmMemoryLimit?(context: MemoryLimitContext): void | Promise<void>;\n}\n\n/** Values associated with the currently executing Lifecycle host. */\nexport type AgentContextStore = {\n  /** Lifecycle host selected for this invocation. */\n  agent: unknown;\n  /** WebSocket connection selected for this invocation, when applicable. */\n  connection: Connection | undefined;\n  /** HTTP request selected for this invocation, when applicable. */\n  request: Request | undefined;\n  /** Extension-owned value selected for this invocation, when applicable. */\n  email: unknown;\n};\n\n/** Values returned by {@link getCurrentAgent}. */\nexport type CurrentAgentContext<\n  Host extends DurableObject = LifecycleObject,\n  Email = unknown\n> = {\n  agent: Host | undefined;\n  connection: Connection | undefined;\n  request: Request | undefined;\n  email: Email | undefined;\n};\n\n/**\n * Shared invocation context for Lifecycle, Agent, AIChatAgent, and Think.\n *\n * @internal Importing or relying on this symbol will break your code in a\n * future release. Use {@link getCurrentAgent} to read the public context.\n */\nexport const __DO_NOT_USE_WILL_BREAK__agentContext =\n  new AsyncLocalStorage<AgentContextStore>();\n\n/**\n * Return the current Agent or Lifecycle Object and invocation-specific values.\n *\n * Lifecycle host startup and alarm hooks receive the current object with no\n * request. Request hooks additionally receive the request being handled.\n * Lifecycle-managed WebSocket hooks receive their connection and, during\n * connect, its upgrade request. Agent extensions may also establish context\n * for email, chat turns, callable methods, and detached work. Capability hooks\n * do not run in this ambient context.\n */\nexport function getCurrentAgent<\n  Host extends DurableObject = LifecycleObject\n>(): CurrentAgentContext<Host> {\n  const store = __DO_NOT_USE_WILL_BREAK__agentContext.getStore();\n  if (!store) {\n    return {\n      agent: undefined,\n      connection: undefined,\n      request: undefined,\n      email: undefined\n    };\n  }\n\n  return {\n    agent: store.agent as Host,\n    connection: store.connection,\n    request: store.request,\n    email: store.email\n  };\n}\n\ntype LifecycleHostContext<Env extends object, Props extends object> = {\n  readonly host: LifecycleObject<Env, Props>;\n  readonly connection?: Connection;\n  readonly request?: Request;\n};\n\n/** Run one host hook in the context of its Lifecycle Object. */\nexport function runInLifecycleHostContext<\n  Env extends object,\n  Props extends object,\n  T\n>(context: LifecycleHostContext<Env, Props>, operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.run(\n    {\n      agent: context.host,\n      connection: context.connection,\n      request: context.request,\n      email: undefined\n    },\n    operation\n  );\n}\n\n/** Run a capability hook without inheriting a current Agent or host context. */\nexport function runWithoutCurrentAgent<T>(operation: () => T): T {\n  return __DO_NOT_USE_WILL_BREAK__agentContext.exit(operation);\n}\n"],"mappings":";;;;;;;;AAoEA,MAAa,wCACX,IAAI,kBAAqC;;;;;;;;;;;AAY3C,SAAgB,kBAEe;CAC7B,MAAM,QAAQ,sCAAsC,SAAS;CAC7D,IAAI,CAAC,OACH,OAAO;EACL,OAAO,KAAA;EACP,YAAY,KAAA;EACZ,SAAS,KAAA;EACT,OAAO,KAAA;CACT;CAGF,OAAO;EACL,OAAO,MAAM;EACb,YAAY,MAAM;EAClB,SAAS,MAAM;EACf,OAAO,MAAM;CACf;AACF;;AASA,SAAgB,0BAId,SAA2C,WAAuB;CAClE,OAAO,sCAAsC,IAC3C;EACE,OAAO,QAAQ;EACf,YAAY,QAAQ;EACpB,SAAS,QAAQ;EACjB,OAAO,KAAA;CACT,GACA,SACF;AACF;;AAGA,SAAgB,uBAA0B,WAAuB;CAC/D,OAAO,sCAAsC,KAAK,SAAS;AAC7D"}