@anthropic-ai/claude-agent-sdk 0.3.266 → 0.3.267

package/browser-sdk.d.ts

@@ -8,7 +8,7 @@
  * Compiled by scripts/build-ant-sdk-typings.sh; see build-agent-sdk.sh for the
  * path rewrite and copy into the package.
  */
-import type { CanUseTool, HookCallbackMatcher, HookEvent, McpServerConfig, OnElicitation, OnUserDialog, Query, SDKUserMessage } from './agentSdkTypes.js';
+import type { CanUseTool, HookCallbackMatcher, HookEvent, McpServerConfig, OnElicitation, OnUserDialog, Query, SDKMessage, SDKUserMessage } from './agentSdkTypes.js';
 export type { CanUseTool, ElicitationRequest, ElicitationResult, HookCallbackMatcher, HookEvent, McpSdkServerConfigWithInstance, McpServerConfig, OnElicitation, OnUserDialog, Query, SDKAssistantMessage, SDKMessage, SDKResultMessage, SDKSystemMessage, SDKUserMessage, UserDialogRequest, UserDialogResult, } from './agentSdkTypes.js';
 export { createSdkMcpServer, tool } from './agentSdkTypes.js';
 export type OAuthCredential = {
@@ -40,6 +40,40 @@ export type SSEOptions = {
      * surface (web / iOS / Android / desktop) itself.
      */
     headers?: Record<string, string>;
+    /**
+     * Resume cursor for the first connect: the stream delivers only events
+     * whose `sequence_num` is greater. For a consumer that seeded its
+     * transcript from the REST event list — pass the highest `sequence_num` it
+     * has already applied (for a query replacing an earlier one,
+     * `getSseLastSequenceNum()` of that query, which only ever covers messages
+     * it actually yielded). Omitted or 0 starts from the beginning of the
+     * retained stream.
+     */
+    fromSequenceNum?: number;
+    /**
+     * Called when the server reports (`catch_up_truncated`) that it could not
+     * replay every event after the resume cursor — the stream continues from a
+     * later point, so re-fetch the gap from the REST event list and reseed.
+     * Each occurrence is also counted in `getSseDropCounts()` under
+     * `catch_up_truncated`. Exceptions thrown by the handler are contained.
+     */
+    onCatchUpTruncated?: () => void;
+    /**
+     * Called for each `delivery_update` frame: the worker's acknowledgement of
+     * one event this session was sent (`event_id` — matches the `event_id` of
+     * that event's own durable echo, see `getCcrEvent()`), with the raw server
+     * status string — `"DELIVERY_STATUS_RECEIVED"`, `"DELIVERY_STATUS_PROCESSING"`
+     * (the worker began the turn) or `"DELIVERY_STATUS_PROCESSED"` (that turn
+     * ended); treat unknown values as informational — and the server
+     * `timestamp` when present. Not durable: a reconnect does not replay
+     * earlier updates. Malformed frames are counted in `getSseDropCounts()`
+     * under `malformed_delivery_update`; handler exceptions are contained.
+     */
+    onDeliveryUpdate?: (update: {
+        event_id: string;
+        status: string;
+        timestamp?: string;
+    }) => void;
 };
 type BrowserQueryOptionsBase = {
     prompt: AsyncIterable<SDKUserMessage>;
@@ -105,3 +139,46 @@ export declare const G4_TEXT_ENVELOPE_ARM_PORTED: boolean;
  * never frame contents). Returns undefined for WebSocket-transport queries.
  */
 export declare function getSseDropCounts(query: Query): Readonly<Record<string, number>> | undefined;
+/**
+ * Resume cursor of a query() created with the `sse` transport: the highest
+ * `sequence_num` of a durable message this query has yielded (or the
+ * `fromSequenceNum` seed before any was). It is advanced immediately before
+ * each message is yielded, so while the consumer handles message `m` it is
+ * already `>= getCcrEvent(query, m).sequence_num`, and it never covers a
+ * message the consumer was not handed — frames still buffered when the
+ * consumer stops iterating, and durable events the SDK dropped or consumed
+ * internally, do not advance it. So at any point — mid-stream, after a
+ * `break`, or once the iterator has finished — it is where a REST catch-up
+ * fetch or a replacement query()'s `fromSequenceNum` should resume (the
+ * transport's own transparent reconnects use a separate internal wire
+ * cursor). Per-message ordering still reads `getCcrEvent(query, message)`.
+ * Returns undefined for WebSocket-transport queries and before any sequence
+ * number is known.
+ */
+export declare function getSseLastSequenceNum(query: Query): number | undefined;
+/**
+ * The wire envelope of the durable CCR event (SSE `client_event` frame) that
+ * delivered `message` on the `sse` query `query`: `sequence_num` is the
+ * session-wide order the server assigned, `event_id` is unique per event,
+ * `created_at` (RFC 3339 store time) and `source` (server-assigned channel,
+ * e.g. `worker`) appear when the frame carries them. Provenance contract:
+ * the transport records the envelope from the delivering frame, keyed by the
+ * exact message object it yields, and never writes it onto the message; a
+ * `ccr_event` field arriving inside any payload is a sender-authored claim
+ * and is stripped, so this accessor is the only way to read an envelope.
+ * Looked up by object identity — pass the message exactly as the query
+ * yielded it. Returns undefined for anything that transport did not itself
+ * yield from a durable frame: streaming deltas (`stream_event`,
+ * `system:thinking_tokens` are not sequenced), messages of a
+ * WebSocket-transport query, copies, and caller-constructed objects,
+ * regardless of the fields they carry. `sequence_num` is dense over ALL of
+ * the session's events, including control frames the SDK consumes
+ * internally and frames it drops, so consecutive yielded messages need not
+ * carry consecutive numbers.
+ */
+export declare function getCcrEvent(query: Query, message: SDKMessage): {
+    event_id: string;
+    sequence_num: number;
+    created_at?: string;
+    source?: string;
+} | undefined;