experimental-a2 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,212 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 38de9de: Add `handle(server, options?)`, the one call that exposes a session over
+  HTTP: it returns a `{ GET, POST }` route pair where `GET` serves the live
+  stream, websocket upgrades, and bounded history slices, and `POST` appends.
+  The library parses every request into a typed intent (`'ws-upgrade' |
+'stream' | 'history' | 'push'`) before any policy runs; hooks are where
+  apps decide. `before` sees each parsed intent and refuses by returning a
+  Response, `after` decorates or replaces HTTP responses (`outcome.covered`
+  on a history read marks an immutable slice, safe to cache), `upgrade`
+  supplies the runtime's websocket upgrade, `presence: true` enables the
+  presence plane, and `deadline` caps request handling. Parse failures
+  answer `INVALID_PAYLOAD` before hooks run, on every lane.
+
+  The `experimental-a2/http` surface shrinks around it: `sseResponse`,
+  `parsePushBody`, `sessionsSocket`, `sessionSocket`, `historyResponse`,
+  and `createSessionRoutes` are removed as exports — `handle` composes
+  them internally. `schedulerHandler`, `errorResponse`, `deserializeError`,
+  `A2Socket`, and the new `A2Intent`, `A2Outcome`, `UpgradeFn`, and
+  `HandleOptions` types remain the whole module.
+
+- 38de9de: Add `loadHistory` backscroll to the client and React bindings. A client
+  session (and `useSession()`) exposes `loadHistory({ before?, limit? })`,
+  which fetches a bounded slice of the log below the stream frontier over
+  the same route (`gte`/`lte` query parameters) and merges it into
+  `events`: deduped, ordered, shared across every handle of the session,
+  never touching folded state or the optimistic overlay. Calls serialize
+  per session, and by default each walks backward 50 events from the
+  oldest one loaded. `useSession()` also gains `history`, the backscroll
+  progress: `{ loading, complete, oldestLoaded }`, where `complete` means
+  the feed reaches index 1 or the log is empty.
+- 38de9de: Coalesce same-tick state reads into one store round trip. Concurrent
+  `session.state()` calls that land in the same microtask window — a
+  `Promise.all` over sessions, a burst of parallel requests — are batched
+  into a single backend read, with no caching across ticks and no change
+  in results: every caller still gets its own independently folded state.
+  Custom store adapters can opt in by implementing the optional
+  `readStates(requests)` batch method (the built-in Postgres store does,
+  as one statement); without it, reads fall back to per-session
+  `readState` unchanged.
+- 38de9de: Multiplex every session of a client over one websocket. A `ws` client
+  now opens a single socket per `createClient` and subscribes sessions
+  onto it with tagged wire frames (subscribe/unsubscribe, per-session
+  acks), instead of one connection per session; the server side accepts
+  the multiplexed protocol on the same `handle` route. Push retries over
+  a live socket are also floored at the HTTP pacing clock: an error ack
+  arriving at wire speed no longer re-fires instantly, so a shedding
+  server is not re-hammered by its own healthy connections.
+
+## 0.4.0
+
+### Minor Changes
+
+- 0640425: Replace the A2 `tool()` wrapper with ambient handler context for plain AI SDK
+  tools. Tools are now ordinary `tool()` definitions from `ai`; inside a local
+  `execute`, `handlerContext(agent)` from `experimental-a2/ai` returns the
+  durable `AgentToolContext` (verified against the executing server's contract),
+  and `runWithHandlerContext(ctx, fn)` from `experimental-a2/ai/server` makes
+  tools directly testable. `tool()`, `AgentToolOptions`, and the agent-binding
+  construction checks are removed, and the model-phase option bans are lifted:
+  `contextSchema`, dynamic `description`, `needsApproval` predicates, input
+  lifecycle callbacks, and generation `toolsContext` now pass through to the AI
+  SDK untouched. Approval predicates are re-evaluated on recovery for the same
+  durable tool call, so they must be deterministic over the tool input.
+- d0c5323: Add a typed `messageMetadata` mapper to the default AI SDK generator so
+  assistant stream metadata, including final usage, can be durably projected.
+- 870dbd5: Add agent-bound `tool()` definitions whose local executors receive the current
+  durable A2 handler context. The playground agent now demonstrates the API by
+  scheduling reminders that return as new user messages.
+- 4c11535: Add indexed `gte` and `lte` history ranges and rename the exclusive stream
+  cursor from `startAt` to `startAfter`.
+- 0c3d861: Rename the configured storage and delivery primitives across the public API.
+  `log` is now `store`, `recovery` is now `scheduler`, built-in adapter entry
+  points move to `experimental-a2/store-*` and
+  `experimental-a2/scheduler-vercel`, and the corresponding public types and
+  error codes use `Store` and `Scheduler` names. This is a breaking rename with
+  no persisted storage or queue-message format change.
+- 2a1743a: Add versioned Devtools captures, the `a2 devtools` read-only CLI, offline reducer replay helpers, conservative authorization that opens without a callback only when `NODE_ENV` is exactly `development`, and fixed-frontier pagination that keeps Redis reads, reducer state, session summaries, detail, and exports complete beyond provider range limits.
+- 589c361: Fence the public AI projection against stale lifecycle events after generation
+  failure, interruption, and attempt supersession. Interrupted responses now keep
+  only the exact visible frontier across post-step tool, approval, and
+  application-input barriers and across failure races, preserve terminal tool
+  results, restore the committed message and compaction base for retries, and
+  clear failed pending inputs without allowing delayed events to corrupt a later
+  model step.
+  Clients identify a requested response with its active `requestId` and a
+  started response with its exact `generationId`. A request-owned interruption
+  remains valid if that same request starts before the interruption commits.
+  The response message and owner IDs must identify the same work.
+  `AIState` exposes optional terminal request and generation ownership maps. The
+  built-in public and coordinator reducers use new versioned names so stored
+  snapshots refold under these semantics.
+- 75bf51a: Fence handler appends by attempt currency and abort superseded runs. A
+  `ctx.session.append` from an attempt a recovery claim has replaced now
+  rejects with `SUPERSEDED_ATTEMPT` instead of landing stale events —
+  atomically, in the store's append operation — while exact retries of
+  already-committed batches still replay idempotently. `ctx.signal` is now
+  live for every handler and aborts with a `SUPERSEDED_ATTEMPT` reason when
+  the claim heartbeat learns a newer attempt owns the event; `abortOn`
+  remains the additional user-cancellation source. Custom store adapters:
+  `append` must implement the fence, and `renewClaims` now takes
+  `{ index, attempt }` pairs and returns `{ renewed, superseded }`.
+- 22534c2: Self-fence at local lease lapse and retry failed renewals promptly. A
+  handler whose claim lapses without renewal now gets its `ctx.signal`
+  aborted with a `CLAIM_EXPIRED` reason, decided by the local clock with
+  zero I/O — so it fires during store outages and in the first tick after
+  an event-loop stall, before any round trip could report back. A failed
+  heartbeat renewal retries after a short jittered delay while the lease
+  can still be saved instead of waiting out the next scheduled beat. A
+  lapsed-but-unsuperseded attempt that returns normally still completes;
+  proven supersession remains what releases the drain.
+- a7a3818: Add passive user messages with `inputs.message(message, { generate: false })`
+  and make `inputs.seed()` record context without scheduling a user turn.
+  Passive user messages join the prompt when a later generating message advances
+  the ordered conversation frontier.
+- f84cbe8: Presence: the ephemeral plane. Contracts grow an optional `presence`
+  field-schema map; sessions gain `setPresence(patch)`, `presence()`, and
+  `stream({ presence: true })` (one snapshot frame, then live patches
+  interleaved with events); `useSession` gains `presence`/`setPresence`,
+  typed from the contract with no type arguments and existing only on
+  presence-declaring contracts. Per-participant state replicates
+  last-writer-wins per field, stamped with the sender's stream frontier
+  (`seen`), and never touches the log: no index, no history, no folds, no
+  scheduler arm, no browser cache. Backed by an optional `A2Store.presence`
+  capability: push tier on `store-redis` (pub/sub beside the notify
+  channel) and `store-memory`; degraded poll-merge tier on `store-postgres`,
+  `store-sqlite`, and `store-redis-http`. `parsePushBody` accepts a branded
+  `presence` sibling (presence-only pushes valid); `sseResponse` rides it
+  as named SSE frames old clients skip. New error codes:
+  `UNKNOWN_PRESENCE_FIELD`, `PRESENCE_NOT_SUPPORTED`. Also fixes a latent
+  `store-redis` subscriber-handshake race (channel commands could beat the
+  ready check).
+- 817d636: Make `qstash()` zero-config in local Node.js development by inferring its
+  conventional localhost callback and enabling the QStash SDK development server.
+  Infer Vercel production and preview callbacks, and disable SDK development mode
+  in production. For inferred previews, opportunistically forward a fresh-enough
+  invocation identity for Vercel Trusted Sources and request redaction from the
+  QStash dashboard and API.
+  Allow static callback headers with automatic provider redaction, or a configured
+  QStash publishing client while A2 keeps the default signature receiver.
+  Require `@upstash/qstash` 2.11.0 or newer so both redaction and zero-config local
+  development are enforced by the peer range.
+- 1d0aa9c: Add first-party delayed events with `session.schedule()`. Configured scheduler
+  adapters now deliver both recovery watchdogs and named, typed timer events.
+  Scheduler routes use `schedulerHandler(...)`, which rejects mismatched adapter
+  wiring before accepting deliveries.
+- ac007ed: Drop the pre-versioning kindless drain envelope: scheduler routes now accept
+  only the versioned task union, and `dueAt` is required on `SchedulerDrainTask`.
+  The `DrainMessage` type exports and the `delaySeconds` fallback options are
+  removed from both scheduler adapters (`vercelQueues` keeps its documented
+  unsettled-redelivery backoff with a fixed base). In-flight kindless watchdogs
+  from earlier versions are rejected at delivery; affected sessions heal on
+  their next append or explicit drain.
+- d3b3f8d: Remove the default agent response step limit. Set `maxSteps` to a positive
+  integer when a response needs an explicit bound.
+- c446705: Add `experimental-a2/scheduler-qstash`, a QStash-backed scheduler adapter with
+  authenticated callback delivery, delayed watchdogs, and deterministic publish
+  deduplication.
+- 62018f1: Transports: the `ws` wire. `createClient`'s `api` becomes the
+  documented `ClientApi` union — a string (one route: GET SSE + POST
+  push), `{ type: 'http', push, stream }` (split routes for per-route
+  duration limits), or `{ type: 'ws', url }` (one WebSocket, both
+  directions: the stream down, pushes and presence up, each presence
+  send a socket frame instead of a route invocation). Everything above
+  the wire seam — optimistic pushes with ack and `confirmed`,
+  frontier-resumed reads, reconnect with backoff, the stall watchdog,
+  the presence throttle and re-send — is transport-agnostic and behaves
+  identically on every wire. `experimental-a2/http` gains
+  `sessionSocket(session, socket, { startAfter?, presence?, deadline? })`,
+  which speaks the frame protocol (event / presence / presence-snapshot
+  / ack / ping down; push / presence up) against any structurally
+  `ws`-shaped socket and validates pushes exactly as `parsePushBody`
+  does — same brands, same per-plane `validatePush` calls; the platform
+  upgrade API stays out of the library. `createClient` gains a
+  `webSocket` injectable mirroring `fetch`. In-flight pushes that lose
+  their socket reject retryably as `STORE_UNAVAILABLE`; client-generated
+  event ids make retries idempotent.
+
+### Patch Changes
+
+- 0664146: Harden the lease machinery against three adversarial-review findings. A
+  drain that re-claims its own lapsed event now fences the old attempt's
+  slot before the new one takes it, and continuations are
+  identity-guarded, so a settling zombie can no longer orphan the live
+  attempt from heartbeat coverage. A handler throw that is the signal's
+  own abort reason (object identity, never an error code) surrenders the
+  attempt — no completion, no failure budget — which makes passing
+  `ctx.signal` to `fetch` the correct default wiring; every other throw,
+  including store fence rejections, is adjudicated by the already-fenced
+  `failAttempt` instead of an in-process error-code check. The postgres
+  and sqlite `renewClaims` now require the listed attempt to match, so a
+  stale heartbeat can never extend or mask a successor's claim (the
+  conformance kit pins same-holder supersession on every backend). The
+  `a2.event` telemetry outcome set gains `surrendered`.
+- a80ec55: Preserve invocation order when one session client makes overlapping
+  optimistic pushes.
+- ae1fab7: Close SSE responses cleanly one second before an ambient Vercel invocation
+  deadline so clients reconnect from their last frontier without a
+  platform-timeout failure.
+- 2181989: Pin Vercel Queue recovery and scheduled appends to their publishing deployment
+  by default, with an explicit `scheduledAppends: 'deploymentless'` opt-out for
+  applications that maintain cross-deployment timer compatibility.
+- ef9b60e: Harden scheduler delivery across provider limits, deployment rollouts, retries,
+  and AI tool approval contexts.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/ai-CFNeCrRl.d.ts

@@ -0,0 +1,334 @@
+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-DUF9pjsx.js";
+import { FinishReason, JSONValue, LanguageModelUsage, UIMessage as UIMessage$1, UIMessageChunk as UIMessageChunk$1 } 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$1> = {
+  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$1[];
+};
+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$1> = {
+  generationId: string;
+  throughMessageId: string;
+  messages: M[];
+  retainedMessageIds?: string[];
+};
+type AIEventDefs<M extends UIMessage$1 = UIMessage$1> = {
+  "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$1 = UIMessage$1> = {
+  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$1[];
+  }>;
+  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$1> = {
+  status: "running" | "completed";
+  generationId: string;
+  throughMessageId: string;
+  messages?: M[];
+  retainedMessageIds?: string[];
+};
+type GenerationUsage = {
+  generationId: string;
+  usage: LanguageModelUsage;
+};
+type AIState<M extends UIMessage$1 = UIMessage$1> = {
+  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$1 = UIMessage$1, 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$1, 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$1> ? M : UIMessage$1 : UIMessage$1;
+declare function createEvents<M extends UIMessage$1 = UIMessage$1>(options?: {
+  messageSchema?: StandardSchemaV1<M>;
+}): AIEventDefs<M>;
+declare const events: AIEventDefs<UIMessage$1>;
+/** Pure projection of the built-in AI protocol. Unknown extension events are ignored. */
+declare function reduceAIState<M extends UIMessage$1>(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$1 = UIMessage$1>(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$1, 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$1>(message: M, options?: {
+    generate?: boolean;
+  }): ProtocolInput<M, "ai.message.created">[];
+  /** Record a message without requesting a generation. */
+  seed<M extends UIMessage$1>(message: M): ProtocolInput<M, "ai.message.created">[];
+  /** Answer an AI SDK tool approval. The tool barrier owns continuation. */
+  approval(response: ApprovalRespondedPayload): ProtocolInput<UIMessage$1, "ai.approval.responded">[];
+  /** Answer an application-defined input request. */
+  input(response: InputRespondedPayload): ProtocolInput<UIMessage$1, "ai.input.responded">[];
+  /** Record an application-defined request for input. */
+  requestInput(request: InputRequestedPayload): ProtocolInput<UIMessage$1, "ai.input.requested">[];
+  /** Request a fresh attempt for a failed response. */
+  retry(options: RetryGenerationOptions): ProtocolInput<UIMessage$1, "ai.retry.requested">[];
+  /** Interrupt the active response for a message. */
+  interrupt(interruption: MessageInterruptedPayload): ProtocolInput<UIMessage$1, "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$1 = UIMessage$1, E extends EventDefs = Record<never, never>>(options: AgentOptions<M, E>): AgentDefinition<M, AIEventDefs<M> & E>;
+//#endregion
+export { MessageInterruptedPayload as A, UIMessage$1 as B, GenerationUsage as C, LanguageModelUsage as D, JSONValue as E, SessionClosedPayload as F, deriveUIMessages as G, agent as H, SessionCreatedPayload as I, inputs as J, events as K, ToolActivity as L, PendingInput as M, RetryGenerationOptions as N, MessageCompletedPayload as O, RetryRequestedPayload as P, ToolCalledPayload as R, GenerationStartedPayload as S, InputRespondedPayload as T, createEvents as U, UIMessageChunk$1 as V, createReducer as W, reduceAIState as Y, GenerationCompletedPayload as _, ActiveGenerationProjection as a, GenerationReason as b, AgentStatus as c, ApprovalRequestedPayload as d, ApprovalRespondedPayload as f, FinishReason as g, CompactionState as h, ActiveGeneration as i, PendingApproval as j, MessageCreatedPayload as k, AgentToolContext as l, CompactionRequestedPayload as m, AIInputs as n, AgentDefinition as o, CompactionCompletedPayload as p, handlerContext as q, AIState as r, AgentOptions as s, AIEventDefs as t, AgentToolEventDefs as u, GenerationFailedPayload as v, InputRequestedPayload as w, GenerationRequestedPayload as x, GenerationProgressPayload as y, ToolResultPayload as z };
+//# sourceMappingURL=ai-CFNeCrRl.d.ts.map

package/dist/ai-CFNeCrRl.d.ts.map

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

package/dist/ai-server.browser.js

@@ -2,3 +2,5 @@
 /** experimental-a2/ai/server is server-only; agent definitions live in experimental-a2/ai. */
 throw new Error("experimental-a2/ai/server is server-only — a client bundle imported it. Import agent from experimental-a2/ai in browser code instead.");
 //#endregion
+
+//# sourceMappingURL=ai-server.browser.js.map

package/dist/ai-server.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-server.browser.js","names":[],"sources":["../src/ai-server.browser.ts"],"sourcesContent":["/** experimental-a2/ai/server is server-only; agent definitions live in experimental-a2/ai. */\nthrow new Error(\n  'experimental-a2/ai/server is server-only — a client bundle imported it. Import agent from experimental-a2/ai in browser code instead.',\n)\nexport {}\n"],"mappings":";;AACA,MAAM,IAAI,MACR,uIACF"}

package/dist/ai-server.d.ts

@@ -1,14 +1,40 @@
-import { a as EventDefs, r as ContractEvent } from "./contract-C_3dIIEU.js";
-import { AIEventDefs, AIState, AgentDefinition } from "./ai.js";
-import { A2Server, PushValidationContext, ServerOptions } from "./server.js";
-import { Instructions, LanguageModel, ToolSet, ToolSet as ToolSet$1, UIMessage, UIMessageChunk, streamText } from "ai";
+import { a as EventDefs, r as ContractEvent } from "./contract-jIfaR085.js";
+import { d as PushValidationContext, g as ServerOptions, n as A2Server } from "./server-DUF9pjsx.js";
+import { l as AgentToolContext, o as AgentDefinition, r as AIState, t as AIEventDefs, u as AgentToolEventDefs } from "./ai-CFNeCrRl.js";
+import { Instructions, LanguageModel, TextStreamPart, ToolSet, ToolSet as ToolSet$1, UIMessage, UIMessageChunk, streamText } from "ai";
 //#region src/ai-sdk-step.d.ts
 type StreamTextOptions<T extends ToolSet$1> = Parameters<typeof streamText<T>>[0];
 type ModelStepTimeout<T extends ToolSet$1> = number | Omit<Exclude<StreamTextOptions<T>["timeout"], number | undefined>, "toolMs" | "tools">;
-type ControlledStreamTextSetting = "_internal" | "abortSignal" | "instructions" | "messages" | "model" | "onToolExecutionEnd" | "onToolExecutionStart" | "experimental_onToolCallFinish" | "experimental_onToolCallStart" | "experimental_sandbox" | "experimental_toolCallers" | "experimental_toolApprovalSecret" | "prompt" | "prepareStep" | "stopWhen" | "system" | "tools" | "toolsContext";
+type ControlledStreamTextSetting = "_internal" | "abortSignal" | "instructions" | "messages" | "model" | "onToolExecutionEnd" | "onToolExecutionStart" | "experimental_onToolCallFinish" | "experimental_onToolCallStart" | "experimental_sandbox" | "experimental_toolCallers" | "experimental_toolApprovalSecret" | "prompt" | "prepareStep" | "stopWhen" | "system" | "tools";
+type RetypedStreamTextSetting = "experimental_onStart" | "experimental_onStepStart" | "experimental_repairToolCall" | "experimental_transform" | "onStart" | "onStepStart" | "repairToolCall";
+type ModelFacingTools<T extends ToolSet$1> = { readonly [K in keyof T]: Omit<T[K], "execute">; };
+type SettingEvent<T extends ToolSet$1, K extends keyof StreamTextOptions<T>> = NonNullable<StreamTextOptions<T>[K]> extends ((event: infer EVENT) => unknown) ? EVENT : never;
+type ModelPhaseStartEvent<T extends ToolSet$1> = Omit<SettingEvent<T, "onStart">, "tools"> & {
+  readonly tools: ModelFacingTools<T> | undefined;
+};
+type ModelPhaseStepStartEvent<T extends ToolSet$1> = Omit<SettingEvent<T, "onStepStart">, "tools"> & {
+  readonly tools: ModelFacingTools<T> | undefined;
+};
+type ModelPhaseCallback<EVENT> = (event: EVENT) => void | PromiseLike<void>;
+type StreamTextRepairToolCall<T extends ToolSet$1> = NonNullable<StreamTextOptions<T>["repairToolCall"]>;
+type ModelPhaseRepairToolCall<T extends ToolSet$1> = (options: Omit<Parameters<StreamTextRepairToolCall<T>>[0], "tools"> & {
+  tools: ModelFacingTools<T>;
+}) => ReturnType<StreamTextRepairToolCall<T>>;
+type StreamTextTransformSetting<T extends ToolSet$1> = NonNullable<StreamTextOptions<T>["experimental_transform"]>;
+type StreamTextTransform<T extends ToolSet$1> = Extract<StreamTextTransformSetting<T>, (...args: never[]) => unknown>;
+type ModelPhaseTransform<T extends ToolSet$1> = (options: Omit<Parameters<StreamTextTransform<T>>[0], "tools"> & {
+  tools: ModelFacingTools<T>;
+}) => ReturnType<StreamTextTransform<T>>;
 /** AI SDK streamText settings that remain meaningful for one durable step. */
-type AISDKStepSettings<T extends ToolSet$1> = Partial<Omit<StreamTextOptions<T>, ControlledStreamTextSetting | "timeout">> & {
+type AISDKStepSettings<T extends ToolSet$1> = Partial<Omit<StreamTextOptions<T>, ControlledStreamTextSetting | RetypedStreamTextSetting | "timeout">> & {
   timeout?: ModelStepTimeout<T>;
+  onStart?: ModelPhaseCallback<ModelPhaseStartEvent<T>>;
+  experimental_onStart?: ModelPhaseCallback<ModelPhaseStartEvent<T>>;
+  onStepStart?: ModelPhaseCallback<ModelPhaseStepStartEvent<T>>;
+  experimental_onStepStart?: ModelPhaseCallback<ModelPhaseStepStartEvent<T>>;
+  repairToolCall?: ModelPhaseRepairToolCall<T>;
+  experimental_repairToolCall?: ModelPhaseRepairToolCall<T>;
+  experimental_transform?: ModelPhaseTransform<T> | Array<ModelPhaseTransform<T>>;
 };
 //#endregion
 //#region src/ai-server.d.ts
@@ -28,6 +54,10 @@ type AgentGenerateContext<M extends UIMessage, D extends AIEventDefs<M> & EventD
   generation: AgentGenerationSettings<T>;
 };
 type AgentGenerate<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet> = (context: AgentGenerateContext<M, D, T>) => ReadableStream<UIMessageChunk> | Promise<ReadableStream<UIMessageChunk>>;
+type UIMessageMetadata<M extends UIMessage> = M extends UIMessage<infer Metadata> ? Metadata : unknown;
+type AgentMessageMetadata<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet> = (context: AgentGenerateContext<M, D, T> & {
+  part: TextStreamPart<T>;
+}) => UIMessageMetadata<M> | undefined;
 type AgentResolverContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs> = {
   event: ContractEvent<D, "ai.generation.requested">;
   state: AIState<M>;
@@ -52,9 +82,16 @@ type CreateHandlersOptions<M extends UIMessage, D extends AIEventDefs<M> & Event
   instructions?: Resolvable<Instructions | undefined, AgentResolverContext<M, D>>;
   /** Settings for each one-step AI SDK streamText call. */
   generation?: AgentGenerationSettings<T>;
-  /** Maximum model steps in one assistant response. Defaults to 20. */
+  /**
+   * Maximum model steps in one assistant response. Defaults to Infinity.
+   */
   maxSteps?: number;
-  /** Replace model generation with an AI SDK UI message chunk stream. */
+  /** Map default AI SDK stream parts to typed assistant message metadata. */
+  messageMetadata?: AgentMessageMetadata<M, D, T>;
+  /**
+   * Replace model generation with an AI SDK UI message chunk stream.
+   * The custom stream owns its metadata chunks.
+   */
   generate?: AgentGenerate<M, D, T>;
   compaction?: CompactionPolicy<M, D>;
   /** Progress is durably flushed at either limit, whichever is reached first. */
@@ -66,6 +103,8 @@ type CreateHandlersOptions<M extends UIMessage, D extends AIEventDefs<M> & Event
 type CreateAgentServerOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet> = CreateHandlersOptions<M, D, T> & Omit<ServerOptions<D>, "contract" | "handlers" | "validatePush"> & {
   handlers?: ServerOptions<D>["handlers"];
 };
+/** Run `fn` with `ctx` as the ambient tool handler context, for direct tool tests. */
+declare function runWithHandlerContext<D extends AgentToolEventDefs, R>(ctx: AgentToolContext<D>, fn: () => R): R;
 /**
  * Build the ordinary A2 handler table for the built-in agent protocol.
  * Application handlers can be spread beside this table.
@@ -74,4 +113,5 @@ declare function createHandlers<M extends UIMessage, D extends AIEventDefs<M> &
 /** Assemble an A2 server with the built-in agent handlers and app extensions. */
 declare function createAgentServer<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet>(options: CreateAgentServerOptions<M, D, T>): A2Server<D>;
 //#endregion
-export { AgentGenerate, AgentGenerateContext, AgentGenerationSettings, AgentResolverContext, CompactionPolicy, CreateAgentServerOptions, CreateHandlersOptions, type Instructions, type LanguageModel, Resolvable, type ToolSet, createAgentServer, createHandlers, validateAgentPush };
+export { AgentGenerate, AgentGenerateContext, AgentGenerationSettings, AgentMessageMetadata, AgentResolverContext, CompactionPolicy, CreateAgentServerOptions, CreateHandlersOptions, type Instructions, type LanguageModel, Resolvable, type ToolSet, createAgentServer, createHandlers, runWithHandlerContext, validateAgentPush };
+//# sourceMappingURL=ai-server.d.ts.map