agents 0.26.0 → 0.27.0

package/dist/channel-Bak_6zDP.d.ts

@@ -0,0 +1,333 @@
+import {
+  b as ChannelMessageSurface,
+  m as ResponseChunk,
+  p as Participant,
+  x as ChannelMessageSurfaceInput
+} from "./protocol-CukuI73M.js";
+
+//#region src/experimental/channels/identity.d.ts
+type ChannelIdentity = Readonly<{
+  /** Configured Channel that observed this identity. */ channelKey: string /** Stable Channel namespace in which `subject` is unique. @default "default" */;
+  scope?: string /** Stable Channel subject within `scope`. */;
+  subject: string;
+}>;
+/** A Channel-produced identity before its Host stamps the configured key. */
+type ChannelIdentityInput = Readonly<{
+  scope?: string;
+  subject: string;
+}>;
+/** Build a stable key for comparing or indexing a Channel identity. */
+declare function identityKey(identity: ChannelIdentity): string;
+//#endregion
+//#region src/experimental/channels/ingress.d.ts
+/** Serializable provider attachment facts available after ingress returns. */
+type ChannelAttachment = {
+  id?: string;
+  mediaType?: string;
+  name?: string;
+  size?: number;
+  text?: string;
+  url?: string;
+};
+type ChannelActor = {
+  readonly id: string /** Stable Channel identity suitable for explicit application linking. */;
+  readonly identity?: ChannelIdentity;
+  readonly username?: string;
+  readonly fullName?: string;
+  readonly isBot?: boolean | "unknown";
+  readonly isSelf?: boolean;
+};
+/** An actor before the Host stamps its configured Channel key. */
+type ChannelActorInput = Omit<ChannelActor, "identity"> & {
+  readonly identity?: ChannelIdentityInput;
+};
+type ChannelEventContext = {
+  /** Immutable Channel-scoped identity, independent of application routing. */ readonly eventId: string;
+  readonly thread: {
+    readonly id: string;
+    readonly isDirectMessage: boolean | "unknown";
+  } /** Exact provider destination for responding to this inbound event. */;
+  readonly replySurface?: ChannelMessageSurface;
+  readonly actor?: ChannelActor;
+};
+/** A normalized inbound message from a Channel. */
+type ChannelInboundMessage = ChannelEventContext & {
+  readonly type: "message";
+  readonly message: {
+    readonly id: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly markdown?: string;
+    readonly attachments?: readonly ChannelAttachment[];
+    readonly isMention?: boolean;
+    readonly reply?: {
+      readonly id: string;
+      readonly text?: string;
+    };
+    readonly metadata?: {
+      /** ISO 8601 timestamp supplied by the provider. */ readonly sentAt?: string;
+      readonly edited?: boolean /** ISO 8601 timestamp supplied by the provider. */;
+      readonly editedAt?: string;
+      readonly autoReply?: boolean;
+    };
+  };
+};
+/** A provider-normalized response to an external approval request. */
+type ChannelApprovalResponse = ChannelEventContext & {
+  readonly type: "approval-response";
+  readonly approvalId: string;
+  readonly decision:
+    | "approve"
+    | "reject" /** Provider reference for this inbound response. */;
+  readonly reference: string;
+};
+type ChannelIngressEvent = ChannelInboundMessage | ChannelApprovalResponse;
+/** A normalized message before the Host stamps its configured Channel key. */
+type ChannelEventContextInput = Omit<
+  ChannelEventContext,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+type ChannelInboundMessageInput = Omit<
+  ChannelInboundMessage,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+/** A normalized approval before the Host stamps its configured Channel key. */
+type ChannelApprovalResponseInput = Omit<
+  ChannelApprovalResponse,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+/** Authenticated event produced by a Channel before Host dispatch. */
+type ChannelIngressEventInput =
+  | ChannelInboundMessageInput
+  | ChannelApprovalResponseInput;
+/** Authenticated Channel output retained only until Host routing completes. */
+type ChannelIngressEnvelope<TRaw = unknown> = {
+  event: ChannelIngressEventInput;
+  raw: TRaw;
+};
+/** The normalized envelopes and provider acknowledgement produced by ingress. */
+type ChannelIngressResult<TRaw = unknown> = {
+  events: readonly ChannelIngressEnvelope<TRaw>[];
+  response: Response;
+};
+/** Match an HTTP request to one exact URL pathname. */
+declare function matchesPath(request: Request, path: string): boolean;
+/** Webhook-shaped inbound support owned by a Channel. */
+interface ChannelIngress<TRaw = unknown> {
+  /** Return null when this Channel does not own the request. */
+  receive(request: Request): Promise<ChannelIngressResult<TRaw> | null>;
+}
+/** Structural input supported by Workers Email and Agent email handlers. */
+type ChannelEmailInput = {
+  from: string;
+  to: string;
+  headers: Headers;
+  raw?: ReadableStream<Uint8Array>;
+  getRaw?: () => Promise<Uint8Array>;
+};
+type ChannelEmailIngressResult<TRaw = unknown> = {
+  events: readonly ChannelIngressEnvelope<TRaw>[];
+};
+/** Non-HTTP ingress for a Workers Email event. */
+interface ChannelEmailIngress<TRaw = unknown> {
+  /** Return null when this Channel does not own the email. */
+  receive(
+    email: ChannelEmailInput
+  ): Promise<ChannelEmailIngressResult<TRaw> | null>;
+}
+//#endregion
+//#region src/experimental/channels/channel.d.ts
+type Awaitable<T> = T | Promise<T>;
+/** A transport-neutral outbound message whose canonical content is Markdown. */
+type ChannelMessage = {
+  /** Optional topic. Each transport decides how to represent it. */ title?: string /** Canonical Markdown content. */;
+  markdown: string;
+};
+/** A transport failure safe to expose to an AI model. */
+type DeliveryFailure = {
+  code: string;
+  message: string;
+};
+/**
+ * The result of a direct delivery attempt, defined by what reached the reader.
+ *
+ * `delivered` means the whole message reached the reader, not that a person
+ * read it. `failed` means none of it did; its `retryable` field says whether
+ * the same route can be attempted again. `uncertain` means an unknown amount
+ * of the message reached the reader, so another attempt or route could
+ * duplicate content. A stream that ends before its answer is complete is
+ * `uncertain`, and carries a `reference` when the Channel created something
+ * the caller can point at.
+ */
+type DeliveryResult =
+  | {
+      status: "delivered";
+      reference?: string;
+    }
+  | {
+      status: "failed";
+      retryable: boolean;
+      error: DeliveryFailure;
+    }
+  | {
+      status: "uncertain";
+      reference?: string;
+      error: DeliveryFailure;
+    };
+/** A response's chunks, as `ChannelGateway.stream` takes them. */
+type ChannelChunkSource = ReadableStream<ResponseChunk>;
+/** Caller options for one finished delivery. */
+type ChannelDeliveryOptions = {
+  /** Caller-owned correlation an Adapter may use where the provider supports it. */ delivery?: ChannelDeliveryContext;
+};
+/** Caller options for one streamed answer. */
+type ChannelStreamOptions = {
+  /**
+   * Optional topic. It is an option rather than a chunk because it is known
+   * before the first token, and a Channel usually needs it in its opening
+   * provider call.
+   */
+  title?: string /** Caller-owned correlation an Adapter may use where the provider supports it. */;
+  delivery?: ChannelDeliveryContext;
+};
+/**
+ * Caller-owned correlation supplied to one provider delivery attempt.
+ *
+ * This is not an idempotency guarantee. An Adapter may map it to a provider
+ * idempotency primitive when one exists, or otherwise use it for observability.
+ */
+type ChannelDeliveryContext = {
+  deliveryId: string;
+};
+/**
+ * Who a sender is, as the application decides it. A string is shorthand
+ * for `{ id }`; `null` refuses the sender. Participants that share an id
+ * are the same participant.
+ */
+type ParticipantResult = Participant | string | null;
+/**
+ * Resolve who sent an authenticated event. Channels has no opinion on
+ * identity: this is the only place a webhook sender becomes a participant.
+ */
+type ChannelParticipant<TRaw = unknown> = (
+  event: ChannelIngressEvent,
+  raw: TRaw
+) => Awaitable<ParticipantResult>;
+/**
+ * Pick the agent object an event reaches, or return null to ignore it.
+ *
+ * The agent object is the authorization boundary: anyone who reaches one
+ * may use every conversation in it. Default: an agent object of the
+ * participant's own (`routes.perParticipant`).
+ */
+type ChannelRoute<TRaw = unknown> = (
+  event: ChannelIngressEvent,
+  raw: TRaw,
+  participant: Participant
+) => Awaitable<string | null>;
+/** A WebSocket upgrade's conversation, once it is known to be for Channels. */
+type ChannelUpgradeMatch = {
+  /** The conversation to follow. Default: the agent's default conversation. */ conversationId?: string;
+};
+/** How a Channel takes WebSocket upgrades in the gateway. */
+interface ChannelUpgrade {
+  /** Return undefined for an upgrade that is not for this Channel. */
+  match(request: Request): ChannelUpgradeMatch | undefined;
+  /** Who is connecting. Return null to refuse the upgrade. */
+  participant(request: Request): Awaitable<ParticipantResult>;
+  /** The agent object the upgrade reaches, or null to refuse it. */
+  route(request: Request, participant: Participant): Awaitable<string | null>;
+}
+/** A configured delivery route with optional ingress support. */
+interface Channel<TRaw = unknown> {
+  /**
+   * Who sent an ingress event. Required when the Channel has `ingress` or
+   * `emailIngress`; the gateway refuses to start without it.
+   */
+  participant?(
+    event: ChannelIngressEvent,
+    raw: TRaw
+  ): Awaitable<ParticipantResult>;
+  /** Pick the agent object an event reaches. See `ChannelRoute`. */
+  route?(
+    event: ChannelIngressEvent,
+    raw: TRaw,
+    participant: Participant
+  ): Awaitable<string | null>;
+  /** Derive a direct destination from this configured Channel's identity. */
+  contactSurface?(identity: ChannelIdentity): ChannelMessageSurfaceInput | null;
+  /**
+   * Deliver one finished message. Only for Channels that cannot stream:
+   * the gateway delivers to a Channel that can by streaming the message.
+   */
+  deliver?(
+    surface: ChannelMessageSurface,
+    message: ChannelMessage,
+    options?: ChannelDeliveryOptions
+  ): Promise<DeliveryResult>;
+  /**
+   * Deliver one progressively generated answer. Absent for Channels that
+   * cannot stream, which the Host serves by collecting and calling `deliver`.
+   *
+   * The Channel owns the consumption loop. It must finalize whether the
+   * stream closed or errored, because a model can fail mid-generation, and it
+   * must not abandon a terminal provider call on error.
+   */
+  stream?(
+    surface: ChannelMessageSurface,
+    chunks: ChannelChunkSource,
+    options: ChannelStreamOptions
+  ): Promise<DeliveryResult>;
+  readonly ingress?: ChannelIngress<TRaw>;
+  readonly emailIngress?: ChannelEmailIngress<TRaw>;
+  /** WebSocket upgrades this Channel takes, such as the Web Channel's. */
+  readonly upgrade?: ChannelUpgrade;
+}
+//#endregion
+export {
+  ChannelIngressEventInput as A,
+  ChannelEventContext as C,
+  ChannelIngress as D,
+  ChannelInboundMessageInput as E,
+  identityKey as F,
+  matchesPath as M,
+  ChannelIdentity as N,
+  ChannelIngressEnvelope as O,
+  ChannelIdentityInput as P,
+  ChannelEmailInput as S,
+  ChannelInboundMessage as T,
+  ChannelApprovalResponse as _,
+  ChannelDeliveryOptions as a,
+  ChannelEmailIngress as b,
+  ChannelRoute as c,
+  ChannelUpgradeMatch as d,
+  DeliveryFailure as f,
+  ChannelActorInput as g,
+  ChannelActor as h,
+  ChannelDeliveryContext as i,
+  ChannelIngressResult as j,
+  ChannelIngressEvent as k,
+  ChannelStreamOptions as l,
+  ParticipantResult as m,
+  Channel as n,
+  ChannelMessage as o,
+  DeliveryResult as p,
+  ChannelChunkSource as r,
+  ChannelParticipant as s,
+  Awaitable as t,
+  ChannelUpgrade as u,
+  ChannelApprovalResponseInput as v,
+  ChannelEventContextInput as w,
+  ChannelEmailIngressResult as x,
+  ChannelAttachment as y
+};
+//# sourceMappingURL=channel-Bak_6zDP.d.ts.map

package/dist/chat/index.d.ts

@@ -9,21 +9,23 @@ import {
   _ as FiberRecoveryContext$1,
   at as isPositionlessAgentToolChunk,
   z as AgentToolEventState
-} from "../agent-routing-0DR0Tk2v.js";
-import { _ as TaskStep, m as TaskRunOptions } from "../tasks-9YxYtByh.js";
+} from "../agent-routing-Bhdbvf7s.js";
+import { _ as TaskStep, m as TaskRunOptions } from "../tasks-PtlB4Uyn.js";
+import {
+  n as ClientToolSchema,
+  r as createToolsFromClientSchemas,
+  t as ClientToolExecutor
+} from "../client-tools-aIBO0Fk7.js";
+import { n as Streams } from "../streams-fbG61qM8.js";
 import {
   a as CHAT_MESSAGE_TYPES,
-  c as ClientToolExecutor,
   i as OutgoingMessage,
-  l as ClientToolSchema,
   n as IncomingMessage,
   o as STREAM_RESUME_NONE_REASONS,
   r as MessageType,
   s as StreamResumeNoneReason,
-  t as ChatTurnOutcome,
-  u as createToolsFromClientSchemas
-} from "../wire-types-CrjKvDyi.js";
-import { n as Streams } from "../streams-Cmkj9QfW.js";
+  t as ChatTurnOutcome
+} from "../wire-types-Cv0iwjk5.js";
 import {
   a as applyAgentToolEvent,
   i as AgentToolProgressEmitter,
@@ -32,7 +34,7 @@ import {
   r as AgentToolProgressEmitResult,
   s as interceptAgentToolBroadcast,
   t as AgentToolBroadcastHooks
-} from "../agent-tools-YrATZJu2.js";
+} from "../agent-tools-bJZwBMfq.js";
 import { l as SessionMessage } from "../types-B7LojTe4.js";
 import { ModelMessage, UIMessage } from "ai";
 import { Connection, FiberRecoveryContext } from "agents";

package/dist/chat/index.js

@@ -2,12 +2,13 @@ import { isPositionlessAgentToolChunk } from "../agent-tool-types.js";
 import { isDurableObjectResetError, isPlatformFailure, tryN } from "../retries.js";
 import { a as isReplayChunk, i as isLateToolInputChunk, n as applyLateToolInput, o as lateToolInputForwardChunks, r as getPartialStreamText, s as normalizeToolInput, t as applyChunkToParts } from "../message-builder-DAl9AhHH.js";
 import { a as interceptAgentToolBroadcast, i as createAgentToolEventState, r as applyAgentToolEvent, s as storedChunkBytes, t as AgentToolProgressEmitter } from "../agent-tools-CdJC-8Dc.js";
-import { t as TextSegmentJoiner } from "../text-segment-joiner-BtAFQSA_.js";
 import { n as sanitizeMessage, t as byteLength } from "../sanitize-D9TujEK8.js";
-import { a as StreamAccumulator, i as transition, n as STREAM_RESUME_NONE_REASONS, t as CHAT_MESSAGE_TYPES } from "../protocol-kHsr-f0X.js";
-import { n as Streams } from "../streams-DW-UCOUc.js";
+import { n as STREAM_RESUME_NONE_REASONS, r as StreamAccumulator, t as CHAT_MESSAGE_TYPES } from "../protocol-eXeJxhgu.js";
+import { t as TextSegmentJoiner } from "../text-segment-joiner-BtAFQSA_.js";
+import { n as transition } from "../broadcast-state-CEyI4uAK.js";
+import { n as Streams } from "../streams-CITClVer.js";
+import { i as createToolsFromClientSchemas, n as iterateWithStallWatchdog, r as parseProtocolMessage, t as ChatStreamStalledError } from "../stall-watchdog-BpRF2uwG.js";
 import { t as MessageType } from "../wire-types-CnMt6_HR.js";
-import { jsonSchema, tool } from "ai";
 import { nanoid } from "nanoid";
 //#region src/chat/tool-output-truncation.ts
 const DEFAULT_MAX_DEPTH = 8;
@@ -1495,42 +1496,6 @@ function buildInClauseStrings(prefix, count) {
 	return asTemplateStringsArray(parts);
 }
 //#endregion
-//#region src/chat/client-tools.ts
-/**
-* Converts client tool schemas to AI SDK tool format.
-*
-* By default these tools have no `execute` function — when the AI model calls
-* them, the tool call is sent back to the client for execution.
-*
-* When `options.execute` is provided, each tool is built WITH an `execute` that
-* delegates to it. This is used by the RPC path (e.g. a parent agent driving a
-* Think sub-agent) so the model's client-tool call is resolved inline within
-* the same turn.
-*
-* @param clientTools - Array of tool schemas from the client
-* @param options - Optional `execute` delegate to run the tools inline
-* @returns Record of AI SDK tools that can be spread into your tools object
-*/
-function createToolsFromClientSchemas(clientTools, options) {
-	if (!clientTools || clientTools.length === 0) return {};
-	const seenNames = /* @__PURE__ */ new Set();
-	for (const t of clientTools) {
-		if (seenNames.has(t.name)) console.warn(`[createToolsFromClientSchemas] Duplicate tool name "${t.name}" found. Later definitions will override earlier ones.`);
-		seenNames.add(t.name);
-	}
-	const execute = options?.execute;
-	const createTool = tool;
-	return Object.fromEntries(clientTools.map((t) => [t.name, createTool({
-		description: typeof t.description === "function" ? "" : t.description ?? "",
-		inputSchema: jsonSchema(t.parameters ?? { type: "object" }),
-		...execute ? { execute: (input, executeOptions) => execute({
-			toolName: t.name,
-			input,
-			toolCallId: executeOptions?.toolCallId ?? ""
-		}) } : {}
-	})]));
-}
-//#endregion
 //#region src/chat/continuation-state.ts
 /**
 * ContinuationState — shared state container for auto-continuation lifecycle.
@@ -2274,84 +2239,6 @@ function hasIncompleteToolBatch(messages) {
 	return false;
 }
 //#endregion
-//#region src/chat/parse-protocol.ts
-/**
-* Protocol Message Parser — typed parsing of cf_agent_chat_* WebSocket messages.
-*
-* Parses raw WebSocket messages into a discriminated union of protocol events.
-* Both AIChatAgent and Think can use this instead of manual JSON.parse + type checking.
-*/
-/**
-* Parse a raw WebSocket message string into a typed protocol event.
-*
-* Returns `null` if the message is not valid JSON or not a recognized
-* protocol message type. Callers should fall through to the user's
-* `onMessage` handler when `null` is returned.
-*
-* @example
-* ```typescript
-* const event = parseProtocolMessage(rawMessage);
-* if (!event) return userOnMessage(connection, rawMessage);
-*
-* switch (event.type) {
-*   case "chat-request": { ... }
-*   case "clear": { ... }
-*   case "tool-result": { ... }
-* }
-* ```
-*/
-function parseProtocolMessage(raw) {
-	let data;
-	try {
-		data = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	const wireType = data.type;
-	if (!wireType) return null;
-	switch (wireType) {
-		case CHAT_MESSAGE_TYPES.USE_CHAT_REQUEST: return {
-			type: "chat-request",
-			id: data.id,
-			init: data.init ?? {}
-		};
-		case CHAT_MESSAGE_TYPES.CHAT_CLEAR: return { type: "clear" };
-		case CHAT_MESSAGE_TYPES.CHAT_REQUEST_CANCEL: return {
-			type: "cancel",
-			id: data.id
-		};
-		case CHAT_MESSAGE_TYPES.TOOL_RESULT: return {
-			type: "tool-result",
-			toolCallId: data.toolCallId,
-			toolName: data.toolName ?? "",
-			output: data.output,
-			state: data.state,
-			errorText: data.errorText,
-			autoContinue: data.autoContinue,
-			clientTools: data.clientTools
-		};
-		case CHAT_MESSAGE_TYPES.TOOL_APPROVAL: return {
-			type: "tool-approval",
-			toolCallId: data.toolCallId,
-			approved: data.approved,
-			autoContinue: data.autoContinue
-		};
-		case CHAT_MESSAGE_TYPES.STREAM_RESUME_REQUEST: return {
-			type: "stream-resume-request",
-			...typeof data.probeId === "string" ? { probeId: data.probeId } : {}
-		};
-		case CHAT_MESSAGE_TYPES.STREAM_RESUME_ACK: return {
-			type: "stream-resume-ack",
-			id: data.id
-		};
-		case CHAT_MESSAGE_TYPES.CHAT_MESSAGES: return {
-			type: "messages",
-			messages: data.messages ?? []
-		};
-		default: return null;
-	}
-}
-//#endregion
 //#region src/chat/message-reconciler.ts
 /**
 * Reconcile incoming client messages against server state.
@@ -4057,82 +3944,6 @@ async function runChatRecoveryExhaustion(input, hooks) {
 	await hooks.terminalize(ctx);
 }
 //#endregion
-//#region src/chat/stall-watchdog.ts
-/**
-* Shared inactivity watchdog for UI-message streams.
-*
-* A model/transport stream can park indefinitely without ever throwing (a hung
-* provider, a wedged transport). Left unguarded, the consumer read-loop waits
-* forever. {@link iterateWithStallWatchdog} wraps such a stream so that a gap of
-* `timeoutMs` between chunks aborts the upstream and throws
-* {@link ChatStreamStalledError}, letting the consumer route the stall into
-* bounded recovery (#1626) — a transient hang is retried within the existing
-* recovery budget — while genuine in-band errors stay terminal.
-*
-* @internal Sibling-package support for `@cloudflare/ai-chat` and
-* `@cloudflare/think`, not a public API. See
-* `design/rfc-chat-recovery-foundation.md`.
-*/
-/**
-* Thrown by {@link iterateWithStallWatchdog} when the inactivity watchdog fires
-* (a model/transport stream that parks without ever throwing). Distinct from
-* in-band model/stream errors so the read-loop catch can route a stall into
-* bounded recovery (#1626) — a transient hang is retried within the existing
-* recovery budget — while genuine errors stay terminal.
-*/
-var ChatStreamStalledError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.isChatStreamStall = true;
-		this.name = "ChatStreamStalledError";
-	}
-};
-/**
-* Wrap a UI-message stream with an inactivity watchdog. If no chunk arrives
-* within `timeoutMs`, `onStall` runs (aborting the upstream model stream) and
-* the iterator throws, so the consumer loop exits with a terminal error
-* instead of parking forever on a hung provider/transport. `timeoutMs <= 0`
-* passes the source through untouched.
-*/
-async function* iterateWithStallWatchdog(source, timeoutMs, onStall) {
-	if (!(timeoutMs > 0)) {
-		yield* source;
-		return;
-	}
-	const iterator = source[Symbol.asyncIterator]();
-	let selfAborted = false;
-	try {
-		while (true) {
-			let timer;
-			let stalled = false;
-			const stall = new Promise((_, reject) => {
-				timer = setTimeout(() => {
-					stalled = true;
-					reject(new ChatStreamStalledError(`Chat stream stalled: no activity for ${timeoutMs}ms; the turn was aborted by the stall watchdog.`));
-				}, timeoutMs);
-			});
-			const nextPromise = iterator.next();
-			nextPromise.catch(() => {});
-			let next;
-			try {
-				next = await Promise.race([nextPromise, stall]);
-			} catch (err) {
-				if (stalled) {
-					selfAborted = true;
-					onStall();
-				}
-				throw err;
-			} finally {
-				if (timer !== void 0) clearTimeout(timer);
-			}
-			if (next.done) return;
-			yield next.value;
-		}
-	} finally {
-		if (!selfAborted) await iterator.return?.(void 0).catch(() => {});
-	}
-}
-//#endregion
 //#region src/chat/truncate-older-messages.ts
 /**
 * Truncate tool outputs and long text in older messages.