experimental-a2 0.6.0 → 0.7.0

package/dist/ai.d.ts

@@ -1,2 +1,334 @@
-import { A as MessageInterruptedPayload, B as UIMessage, C as GenerationUsage, D as LanguageModelUsage, E as JSONValue, F as SessionClosedPayload, G as deriveUIMessages, H as agent, I as SessionCreatedPayload, J as inputs, K as events, L as ToolActivity, M as PendingInput, N as RetryGenerationOptions, O as MessageCompletedPayload, P as RetryRequestedPayload, R as ToolCalledPayload, S as GenerationStartedPayload, T as InputRespondedPayload, U as createEvents, V as UIMessageChunk, W as createReducer, Y as reduceAIState, _ as GenerationCompletedPayload, a as ActiveGenerationProjection, b as GenerationReason, c as AgentStatus, d as ApprovalRequestedPayload, f as ApprovalRespondedPayload, g as FinishReason, h as CompactionState, i as ActiveGeneration, j as PendingApproval, k as MessageCreatedPayload, l as AgentToolContext, m as CompactionRequestedPayload, n as AIInputs, o as AgentDefinition, p as CompactionCompletedPayload, q as handlerContext, r as AIState, s as AgentOptions, t as AIEventDefs, u as AgentToolEventDefs, v as GenerationFailedPayload, w as InputRequestedPayload, x as GenerationRequestedPayload, y as GenerationProgressPayload, z as ToolResultPayload } from "./ai-D_PGS-JR.js";
-export { AIEventDefs, AIInputs, AIState, ActiveGeneration, ActiveGenerationProjection, AgentDefinition, AgentOptions, AgentStatus, AgentToolContext, AgentToolEventDefs, ApprovalRequestedPayload, ApprovalRespondedPayload, CompactionCompletedPayload, CompactionRequestedPayload, CompactionState, type FinishReason, GenerationCompletedPayload, GenerationFailedPayload, GenerationProgressPayload, GenerationReason, GenerationRequestedPayload, GenerationStartedPayload, GenerationUsage, InputRequestedPayload, InputRespondedPayload, type JSONValue, type LanguageModelUsage, MessageCompletedPayload, MessageCreatedPayload, MessageInterruptedPayload, PendingApproval, PendingInput, RetryGenerationOptions, RetryRequestedPayload, SessionClosedPayload, SessionCreatedPayload, ToolActivity, ToolCalledPayload, ToolResultPayload, type UIMessage, type UIMessageChunk, agent, createEvents, createReducer, deriveUIMessages, events, handlerContext, inputs, reduceAIState };
+import { a as EventDefs, h as StandardSchemaV1, n as Contract, p as Reducer, t as AppendInput } from "./contract-jIfaR085.js";
+import { s as HandlerContext } from "./server-DgXmORIq.js";
+import { FinishReason, JSONValue, LanguageModelUsage, UIMessage, UIMessageChunk } from "ai";
+//#region src/ai.d.ts
+type AgentStatus = "idle" | "generating" | "waiting" | "failed" | "closed";
+type GenerationReason = "message" | "tool" | "input" | "retry";
+type SessionCreatedPayload = {
+  metadata?: JSONValue;
+};
+type SessionClosedPayload = {
+  reason?: string;
+};
+type MessageCreatedPayload<M extends UIMessage> = {
+  message: M;
+  /** For user messages, false records passive context. Omission or true schedules. */
+  generate?: boolean;
+};
+type MessageCompletedPayload = {
+  messageId: string;
+};
+type MessageInterruption = {
+  messageId: string;
+  reason?: string;
+  /** Last confirmed event-log index visible to the interrupter. */
+  lastSeenIndex?: number;
+};
+type MessageInterruptedPayload = MessageInterruption & ({
+  generationId: string;
+  requestId?: never;
+} | {
+  requestId: string;
+  generationId?: never;
+});
+type GenerationRequestedPayload = {
+  messageId: string;
+  reason: GenerationReason;
+  responseMessageId?: string;
+};
+type RetryGenerationOptions = {
+  messageId: string;
+  responseMessageId: string;
+  retryId: string;
+};
+type RetryRequestedPayload = RetryGenerationOptions;
+type GenerationStartedPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  responseMessageId: string;
+  attempt: number;
+  model: string;
+};
+type GenerationProgressPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  responseMessageId: string;
+  sequence: number;
+  chunks: UIMessageChunk[];
+};
+type GenerationCompletedPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  responseMessageId: string;
+  finishReason?: FinishReason;
+  usage?: LanguageModelUsage;
+};
+type GenerationFailedPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  responseMessageId: string;
+  error: string;
+  /** True when a later attempt replaced an incomplete attempt. */
+  superseded?: boolean;
+  stepLimit?: boolean;
+};
+type ToolCalledPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  dynamic?: boolean;
+  providerExecuted?: boolean;
+  supportsDeferredResults?: boolean;
+  providerMetadata?: unknown;
+  toolMetadata?: unknown;
+  title?: string;
+};
+type ToolResultPayload = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  toolCallId: string;
+  toolName?: string;
+  input?: unknown;
+  rawInput?: unknown;
+  output?: unknown;
+  error?: string;
+  denied?: boolean;
+  preliminary?: boolean;
+  phase?: "input" | "execution";
+  dynamic?: boolean;
+  providerExecuted?: boolean;
+  providerMetadata?: unknown;
+  toolMetadata?: unknown;
+};
+type ApprovalRequestedPayload = {
+  messageId: string;
+  generationId: string;
+  approvalId: string;
+  toolCallId: string;
+  isAutomatic?: boolean;
+  signature?: string;
+};
+type ApprovalRespondedPayload = {
+  messageId: string;
+  generationId: string;
+  approvalId: string;
+  approved: boolean;
+  reason?: string;
+};
+type InputRequestedPayload = {
+  messageId: string;
+  generationId: string;
+  inputId: string;
+  name: string;
+  question?: JSONValue;
+};
+type InputRespondedPayload = {
+  messageId: string;
+  generationId: string;
+  inputId: string;
+  name: string;
+  value: JSONValue;
+};
+type CompactionRequestedPayload = {
+  generationId: string;
+  throughMessageId: string;
+};
+type CompactionCompletedPayload<M extends UIMessage> = {
+  generationId: string;
+  throughMessageId: string;
+  messages: M[];
+  retainedMessageIds?: string[];
+};
+type AIEventDefs<M extends UIMessage = UIMessage> = {
+  "ai.session.created": StandardSchemaV1<SessionCreatedPayload>;
+  "ai.session.closed": StandardSchemaV1<SessionClosedPayload>;
+  "ai.message.created": StandardSchemaV1<MessageCreatedPayload<M>>;
+  "ai.message.completed": StandardSchemaV1<MessageCompletedPayload>;
+  "ai.message.interrupted": StandardSchemaV1<MessageInterruptedPayload>;
+  "ai.generation.requested": StandardSchemaV1<GenerationRequestedPayload>;
+  "ai.retry.requested": StandardSchemaV1<RetryRequestedPayload>;
+  "ai.generation.started": StandardSchemaV1<GenerationStartedPayload>;
+  "ai.generation.progress": StandardSchemaV1<GenerationProgressPayload>;
+  "ai.generation.completed": StandardSchemaV1<GenerationCompletedPayload>;
+  "ai.generation.failed": StandardSchemaV1<GenerationFailedPayload>;
+  "ai.tool.called": StandardSchemaV1<ToolCalledPayload>;
+  "ai.tool.result": StandardSchemaV1<ToolResultPayload>;
+  "ai.approval.requested": StandardSchemaV1<ApprovalRequestedPayload>;
+  "ai.approval.responded": StandardSchemaV1<ApprovalRespondedPayload>;
+  "ai.input.requested": StandardSchemaV1<InputRequestedPayload>;
+  "ai.input.responded": StandardSchemaV1<InputRespondedPayload>;
+  "ai.compaction.requested": StandardSchemaV1<CompactionRequestedPayload>;
+  "ai.compaction.completed": StandardSchemaV1<CompactionCompletedPayload<M>>;
+};
+type ActiveGeneration = GenerationStartedPayload;
+type ActiveGenerationProjection<M extends UIMessage = UIMessage> = {
+  generationId: string;
+  responseMessageId: string;
+  /** Log index of the completed model step while its response remains interruptible. */
+  completionIndex?: number;
+  baseMessage?: M;
+  baseCompaction?: CompactionState<M> | null;
+  batches: Array<{
+    index: number;
+    chunks: UIMessageChunk[];
+  }>;
+  baseTools: ToolActivity[];
+  toolEvents: Array<{
+    index: number;
+    type: "ai.tool.called";
+    payload: ToolCalledPayload;
+  } | {
+    index: number;
+    type: "ai.tool.result";
+    payload: ToolResultPayload;
+  }>;
+  approvalEvents: Array<{
+    index: number;
+    type: "ai.approval.requested";
+    payload: ApprovalRequestedPayload;
+  } | {
+    index: number;
+    type: "ai.approval.responded";
+    payload: ApprovalRespondedPayload;
+  }>;
+};
+type PendingApproval = ApprovalRequestedPayload;
+type PendingInput = InputRequestedPayload;
+type ToolActivity = {
+  requestId: string;
+  messageId: string;
+  generationId: string;
+  toolCallId: string;
+  toolName?: string;
+  input?: unknown;
+  rawInput?: unknown;
+  output?: unknown;
+  error?: string;
+  preliminary?: boolean;
+  phase?: "input" | "execution";
+  dynamic?: boolean;
+  providerExecuted?: boolean;
+  callProviderMetadata?: unknown;
+  resultProviderMetadata?: unknown;
+  toolMetadata?: unknown;
+  title?: string;
+  status: "running" | "completed" | "failed" | "denied";
+};
+type CompactionState<M extends UIMessage> = {
+  status: "running" | "completed";
+  generationId: string;
+  throughMessageId: string;
+  messages?: M[];
+  retainedMessageIds?: string[];
+};
+type GenerationUsage = {
+  generationId: string;
+  usage: LanguageModelUsage;
+};
+type AIState<M extends UIMessage = UIMessage> = {
+  session: {
+    created: boolean;
+    metadata?: JSONValue;
+  };
+  messages: M[];
+  status: AgentStatus;
+  activeGeneration: ActiveGeneration | null;
+  activeRequestId: string | null;
+  activeResponseMessageId: string | null;
+  activeProjection: ActiveGenerationProjection<M> | null;
+  responseGenerationIds: Record<string, string>;
+  terminalRequestIds?: Record<string, true>;
+  terminalGenerations?: Record<string, "completed" | "failed" | "interrupted" | "superseded">;
+  pendingApprovals: PendingApproval[];
+  pendingInputs: PendingInput[];
+  tools: ToolActivity[];
+  compaction: CompactionState<M> | null;
+  usage: GenerationUsage[];
+  error: string | null;
+};
+type AgentDefinition<M extends UIMessage = UIMessage, D extends EventDefs = AIEventDefs<M>> = {
+  readonly contract: Contract<D>;
+  readonly reducer: Reducer<D, AIState<M>>;
+};
+type AgentToolEventDefs = EventDefs & Pick<AIEventDefs, "ai.tool.called" | "ai.approval.responded">;
+/** The durable handler context supplied when A2 executes a local AI tool. */
+type AgentToolContext<D extends AgentToolEventDefs> = HandlerContext<D, "ai.tool.called"> | HandlerContext<D, "ai.approval.responded">;
+type AgentOptions<M extends UIMessage, E extends EventDefs> = {
+  name: string;
+  events?: E;
+  /** Optional stricter schema for custom UIMessage metadata/data/tool types. */
+  messageSchema?: StandardSchemaV1<M>;
+  /** Snapshot identity. Bump when application-level projection semantics change. */
+  reducerName?: string;
+};
+type AIMessageFrom<D extends EventDefs> = D extends Record<"ai.message.created", infer S extends StandardSchemaV1> ? StandardSchemaV1.InferOutput<S> extends MessageCreatedPayload<infer M extends UIMessage> ? M : UIMessage : UIMessage;
+declare function createEvents<M extends UIMessage = UIMessage>(options?: {
+  messageSchema?: StandardSchemaV1<M>;
+}): AIEventDefs<M>;
+declare const events: AIEventDefs<UIMessage>;
+/** Pure projection of the built-in AI protocol. Unknown extension events are ignored. */
+declare function reduceAIState<M extends UIMessage>(state: AIState<M>, event: {
+  type: string;
+  payload: unknown;
+  index: number;
+  id?: string;
+}): AIState<M>;
+/** Derive AI SDK UI messages directly from an A2 event history. */
+declare function deriveUIMessages<M extends UIMessage = UIMessage>(history: readonly {
+  type: string;
+  payload: unknown;
+  index: number;
+}[]): M[];
+/** Build the standard AI state projection for any contract containing the protocol. */
+declare function createReducer<D extends EventDefs>(options: {
+  contract: Contract<D>;
+  name?: string;
+}): Reducer<D, AIState<AIMessageFrom<D>>>;
+type ProtocolInput<M extends UIMessage, K extends keyof AIEventDefs<M> & string> = AppendInput<Pick<AIEventDefs<M>, K>>;
+type AIInputs = {
+  /** Record a message. User messages schedule unless generate is false. */
+  message<M extends UIMessage>(message: M, options?: {
+    generate?: boolean;
+  }): ProtocolInput<M, "ai.message.created">[];
+  /** Record a message without requesting a generation. */
+  seed<M extends UIMessage>(message: M): ProtocolInput<M, "ai.message.created">[];
+  /** Answer an AI SDK tool approval. The tool barrier owns continuation. */
+  approval(response: ApprovalRespondedPayload): ProtocolInput<UIMessage, "ai.approval.responded">[];
+  /** Answer an application-defined input request. */
+  input(response: InputRespondedPayload): ProtocolInput<UIMessage, "ai.input.responded">[];
+  /** Record an application-defined request for input. */
+  requestInput(request: InputRequestedPayload): ProtocolInput<UIMessage, "ai.input.requested">[];
+  /** Request a fresh attempt for a failed response. */
+  retry(options: RetryGenerationOptions): ProtocolInput<UIMessage, "ai.retry.requested">[];
+  /** Interrupt the active response for a message. */
+  interrupt(interruption: MessageInterruptedPayload): ProtocolInput<UIMessage, "ai.message.interrupted">[];
+};
+/** Pure append inputs for the built-in AI protocol. */
+declare const inputs: AIInputs;
+/**
+ * Read the durable handler context ambient to the current AI tool
+ * execution. A2 runs each local tool's `execute` inside this scope, so
+ * plain AI SDK `tool()` definitions reach their `event`, `attempt`,
+ * `session`, and `signal` without an A2-specific wrapper. The agent (or
+ * contract) argument carries the event types and is verified against
+ * the executing server's contract.
+ */
+declare function handlerContext<D extends AgentToolEventDefs>(agentOrContract: Contract<D> | {
+  readonly contract: Contract<D>;
+}): AgentToolContext<D>;
+/**
+ * Define an agent: built-in AI protocol + application events and one state
+ * reducer. The result is isomorphic.
+ */
+declare function agent<M extends UIMessage = UIMessage, E extends EventDefs = Record<never, never>>(options: AgentOptions<M, E>): AgentDefinition<M, AIEventDefs<M> & E>;
+//#endregion
+export { AIEventDefs, AIInputs, AIState, ActiveGeneration, ActiveGenerationProjection, AgentDefinition, AgentOptions, AgentStatus, AgentToolContext, AgentToolEventDefs, ApprovalRequestedPayload, ApprovalRespondedPayload, CompactionCompletedPayload, CompactionRequestedPayload, CompactionState, type FinishReason, GenerationCompletedPayload, GenerationFailedPayload, GenerationProgressPayload, GenerationReason, GenerationRequestedPayload, GenerationStartedPayload, GenerationUsage, InputRequestedPayload, InputRespondedPayload, type JSONValue, type LanguageModelUsage, MessageCompletedPayload, MessageCreatedPayload, MessageInterruptedPayload, PendingApproval, PendingInput, RetryGenerationOptions, RetryRequestedPayload, SessionClosedPayload, SessionCreatedPayload, ToolActivity, ToolCalledPayload, ToolResultPayload, type UIMessage, type UIMessageChunk, agent, createEvents, createReducer, deriveUIMessages, events, handlerContext, inputs, reduceAIState };
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","names":[],"sources":["../src/ai.ts"],"mappings":"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"}

package/dist/ai.js

@@ -1,6 +1,6 @@
 import { n as validateSync, t as assertSyncSchema } from "./validate-XKT4FSNn.js";
 import { t as contract } from "./contract-48bUMgcL.js";
-import { l as ambientToolScopeStorage } from "./internal-DstsI6Re.js";
+import { l as ambientToolScopeStorage } from "./internal-DRXJ56EI.js";
 //#region src/ai-projector.ts
 const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const cloneMessage = (messageId, base) => structuredClone(base ?? {

package/dist/client.d.ts

@@ -1,2 +1,202 @@
-import { a as Connection, c as HistoryState, d as SessionClient, f as SessionClientPresence, h as createClient, i as ClientWebSocketConstructor, l as LoadHistoryOptions, m as SessionSnapshot, n as ClientApi, o as ConnectionStatus, p as SessionOptions, r as ClientWebSocket, s as CreateClientOptions, t as A2Client, u as PushResult } from "./client-CdMqi7mC.js";
-export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, createClient };
+import { a as EventDefs, c as PresencePatch, d as WithPresence, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+//#region src/client.d.ts
+type ConnectionStatus = "idle" | "connecting" | "live" | "closed";
+/**
+ * The connection, as a discriminated union — impossible states are
+ * unrepresentable: an error only exists while disconnected,
+ * `reconnects` only once a connection has been attempted.
+ * "Reconnecting…" is `status === 'connecting' && reconnects > 0`.
+ */
+type Connection = {
+  status: "idle";
+} | {
+  status: "connecting";
+  /** Drops of an established stream so far. `0` = first connect. */
+  reconnects: number;
+  /** Why the last connection ended; `null` on the first connect. */
+  error: Error | null;
+} | {
+  status: "live";
+  reconnects: number;
+} | {
+  status: "closed";
+};
+/**
+ * What `push` returns: resolves at the server ack (exactly like a
+ * plain promise — `await push(...)` gives the acked events), and
+ * carries `confirmed` for the later moment when the live stream has
+ * delivered the whole batch back and the optimistic overlay entry
+ * retired — the view now shows server truth. `confirmed` is lazy:
+ * never accessed, never created. A rejected push rejects both.
+ */
+type PushResult<D extends EventDefs> = Promise<ContractEvent<D>[]> & {
+  readonly confirmed: Promise<ContractEvent<D>[]>;
+};
+type LoadHistoryOptions = {
+  /**
+   * Exclusive upper bound for the fetch. Defaults to the oldest
+   * already-loaded index — successive calls page backward — or one
+   * past the hydration frontier while nothing is loaded yet.
+   */
+  before?: number;
+  /** Page size; defaults to 50. */
+  limit?: number;
+};
+/** Backscroll progress, derived from the raw event feed. */
+type HistoryState = {
+  /** A `loadHistory` fetch is in flight. */
+  loading: boolean;
+  /** The feed reaches index 1 — nothing older remains to fetch. */
+  complete: boolean;
+  /** The oldest loaded index; `null` while nothing is loaded. */
+  oldestLoaded: number | null;
+};
+/** One immutable view of the session — stable identity between changes. */
+type SessionSnapshot<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>;
+}> & {
+  /** The live view: server events folded, optimistic pushes applied. */
+  state: S;
+  /** The raw event feed: server truth — observed, seeded, or
+   * backscrolled via `loadHistory` — plus pending optimistic events
+   * (provisional indexes past the frontier). `state` never folds
+   * backscrolled events; they are display data below the frontier. */
+  events: ContractEvent<D>[];
+  /** The stream frontier: the last server-confirmed index. This is the
+   * `lastSeenIndex` cancellation wants. */
+  index: number;
+  /** Backscroll progress — `loadHistory` moves it. */
+  history: HistoryState;
+  connection: Connection;
+};
+/**
+ * The presence member of a client session — intersected in via
+ * `WithPresence`, so it exists exactly when the contract declares
+ * presence fields.
+ */
+type SessionClientPresence<P extends PresenceDefs> = {
+  /**
+   * Fire-and-forget presence: validates locally against the reducer's
+   * presence schemas, merges into the local map immediately (the
+   * echo), and coalesces on the wire to a fixed cadence — a leading
+   * send immediately, then at most one merged send per interval,
+   * later values winning field-wise. `null` clears a field. No ack,
+   * no retry, no rollback: a lost patch is repainted by the next one.
+   * Requires the session's `participant`.
+   */
+  setPresence(values: PresencePatch<P>["values"]): void;
+};
+type SessionClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, SessionClientPresence<P>> & {
+  readonly sessionId: string;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): SessionSnapshot<D, S, P>;
+  /**
+   * Optimistic append: validates locally against the reducer's event
+   * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
+   * local fold, POSTs, swaps in the ack, rolls back on rejection.
+   * Auto-retries only `STORE_UNAVAILABLE`. Resolves with the appended
+   * events as the server recorded them. Overlapping calls on this
+   * handle enter the transport in invocation order without delaying
+   * their optimistic folds.
+   */
+  push(...events: AppendInput<D>[]): PushResult<D>;
+  /**
+   * Backscroll: fetch a bounded slice of events from below the
+   * frontier and merge it into `events` — deduped, ordered, shared by
+   * every handle of this session. Folded state and the optimistic
+   * overlay are never touched. Calls serialize per session and skip
+   * already-loaded ranges, so overlapping backscrolls never fetch the
+   * same range twice. Resolves with the events in the requested range.
+   * Requires an http api; the `ws` transport has no history lane and
+   * this throws a TypeError there.
+   */
+  loadHistory(options?: LoadHistoryOptions): Promise<ContractEvent<D>[]>;
+  /**
+   * Take a lease on the live stream and return its release. Leases
+   * refcount per handle — the first connects, releasing the last
+   * closes — so independent consumers of one identity-mapped handle
+   * (two hooks, a hook plus vanilla code) never fight over the
+   * stream. Releasing twice is a no-op. While any lease is held the
+   * stream reconnects with backoff and resumes from the frontier.
+   */
+  connect(): () => void;
+  /**
+   * The hard stop: drops every outstanding lease and closes the
+   * stream now. Not terminal — a later `connect()` starts fresh from
+   * the current frontier.
+   */
+  close(): void;
+};
+type SessionOptions<D extends EventDefs, S> = {
+  initialState?: S;
+  initialIndex?: number;
+  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
+  initialEvents?: ContractEvent<D>[];
+  /** Overrides the client's `participant` for this session handle.
+   * Bound once per handle. */
+  participant?: string;
+};
+type A2Client<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  session(sessionId: string, options?: SessionOptions<D, S>): SessionClient<D, S, P>;
+};
+/**
+ * The wire the client rides. The string form is one route serving GET
+ * (SSE stream) + POST (push). `http` splits the verbs across two
+ * routes, for when platform duration limits differ per verb. `ws`
+ * rides everything — every session of this client — over one
+ * multiplexed WebSocket, served by `sessionsSocket`.
+ */
+type ClientApi = string | {
+  type: "http";
+  push: string;
+  stream: string;
+} | {
+  type: "ws";
+  url: string;
+};
+/**
+ * The socket surface the `ws` transport drives — satisfied structurally
+ * by the DOM `WebSocket` and Node's alike, and small enough to fake in
+ * tests.
+ */
+type ClientWebSocket = {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: "open", listener: () => void): void;
+  addEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  addEventListener(type: "close", listener: (event: {
+    code: number;
+    reason: string;
+  }) => void): void;
+  addEventListener(type: "error", listener: () => void): void;
+};
+type ClientWebSocketConstructor = new (url: string) => ClientWebSocket;
+type CreateClientOptions<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  reducer: Reducer<D, S, P>;
+  /** The route (or routes) the client speaks — see `ClientApi`. */
+  api: ClientApi;
+  /** Injectable fetch — defaults to the global. */
+  fetch?: typeof globalThis.fetch;
+  /** Injectable WebSocket constructor for the `ws` api — defaults to
+   * the global. The http transports never touch it. */
+  webSocket?: ClientWebSocketConstructor;
+  /** How long an idle session keeps its in-memory identity, in
+   * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
+  gcTime?: number;
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story; the app states it once here. The
+   * default for every session handle this client creates;
+   * `session(id, { participant })` overrides it per handle.
+   */
+  participant?: string;
+};
+declare function createClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P>;
+//#endregion
+export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, createClient };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;KAoDY;;;;;;;KAQA;EACN;;EAEA;;EAEA;;EAEA,OAAO;;EAEP;EAAgB;;EAChB;;;;;;;;;;KAUM,WAAW,UAAU,aAAa,QAAQ,cAAc;WACzD,WAAW,QAAQ,cAAc;;KAGhC;;;;;;EAMV;;EAEA;;;KAIU;;EAEV;;EAEA;;EAEA;;;KAIU,gBACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aACF;;EAGE,UAAU,YAAY;;;EAIxB,OAAO;;;;;EAKP,QAAQ,cAAc;;;EAGtB;;EAEA,SAAS;EACT,YAAY;;;;;;;KAQF,sBAAsB,UAAU;;;;;;;;;;EAU1C,YAAY,QAAQ,cAAc;;KAGxB,cACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aAAa,GAAG,sBAAsB;WAC/B;EACT,UAAU;EACV,eAAe,gBAAgB,GAAG,GAAG;;;;;;;;;;EAUrC,QAAQ,QAAQ,YAAY,OAAO,WAAW;;;;;;;;;;;EAW9C,YAAY,UAAU,qBAAqB,QAAQ,cAAc;;;;;;;;;EASjE;;;;;;EAMA;;KAGU,eAAe,UAAU,WAAW;EAC9C,eAAe;EACf;;EAEA,gBAAgB,cAAc;;;EAG9B;;KAGU,SACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,QACE,mBACA,UAAU,eAAe,GAAG,KAC3B,cAAc,GAAG,GAAG;;;;;;;;;KAUb;EAEN;EAAc;EAAc;;EAC5B;EAAY;;;;;;;KAON;WACD;EACT,KAAK;EACL,MAAM,eAAe;EACrB,iBAAiB,cAAc;EAC/B,iBACE,iBACA,WAAW;IAAS;;EAEtB,iBACE,eACA,WAAW;IAAS;IAAc;;EAEpC,iBAAiB,eAAe;;KAGtB,kCAAkC,gBAAgB;KAElD,oBACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,SAAS,QAAQ,GAAG,GAAG;;EAEvB,KAAK;;EAEL,eAAe,WAAW;;;EAG1B,YAAY;;;EAGZ;;;;;;;;EAQA;;iBAirBc,aACd,UAAU,WACV,GACA,UAAU,eAAe,sBACzB,SAAS,oBAAoB,GAAG,GAAG,KAAK,SAAS,GAAG,GAAG"}