experimental-a2 0.4.0 → 0.5.0

package/docs/reference/01-api.mdx

@@ -123,8 +123,8 @@ Server-only by construction: `experimental-a2/server` is the only entry point th
 can reach a store backend, and its exports map resolves to a loud error
 under the browser condition.
 
-`validatePush(context)` runs only for input that came from `parsePushBody()`,
-once per plane. The events plane invokes it with `{ sessionId, events }` before
+`validatePush(context)` runs only for input that arrived over the wire
+through `handle`'s push lane, once per plane. The events plane invokes it with `{ sessionId, events }` before
 contract schema validation and before the store append, so throwing rejects the
 complete push without writing anything. The presence plane invokes it with
 `{ sessionId, events: [], presence }`, the whole pushed patch with its
@@ -132,7 +132,7 @@ participant, before field validation and the broadcast, so authorizing the
 participant id (and applying any size or cardinality policy) happens at the
 same seam. The patch arrives frozen: authorize, don't rewrite (a mutation
 attempt throws and fails the push). Direct trusted server appends, handler appends, and server-side
-`setPresence` bypass it. `parsePushBody()` creates
+`setPresence` bypass it. The envelope parser inside `handle` creates
 the runtime provenance brand after reading the envelope; a caller-supplied
 field with the same name is ignored, and the brand is not stored in the log.
 
@@ -428,8 +428,8 @@ The only way to move a session forward. Payloads are validated against
 the contract's schemas before anything is written. A multi-event append
 is atomic: all-or-nothing, consecutive positions, one transaction. Pass
 `id` to make an append idempotent across retries; re-sending an
-identical batch returns the original rows. (Events parsed by
-`parsePushBody` are accepted directly, the push-route path.) See
+identical batch returns the original rows. (Events that arrived through
+`handle`'s push lane are accepted directly.) See
 [Durability](/concepts/durability).
 
 After the write, A2 dispatches only event types with registered handlers.
@@ -537,14 +537,14 @@ session.stream(options: {
 
 A live feed of the session's events. `startAfter` is a non-negative safe integer;
 `startAfter: 20` begins with event 21.
-Server-side only; expose it over SSE with `sseResponse`. Subscribing never
-dispatches handlers.
+Server-side only; `handle` exposes it over SSE, and over the multiplexed
+socket when `upgrade` is set. Subscribing never dispatches handlers.
 
 With `presence: true`, the feed yields one `PresenceSnapshot` first:
 `{ snapshot }`, the current pruned map with each field's own `value`,
 `seen`, and `at` stamp. Live presence patches then interleave with
-events. `sseResponse` sends both as named SSE frames, so clients that
-don't know them skip them. The return type widens only under the
+events. The stream response sends both as named SSE frames, so clients
+that don't know them skip them. The return type widens only under the
 literal `presence: true`; without it, existing consumers keep
 `AsyncIterable<Event>`. The option itself exists only on sessions of
 contracts that declare `presence`; elsewhere it is a type error, not a
@@ -580,9 +580,9 @@ by backend TTL when a participant goes silent (default 60 seconds; set
 the storage clock, not the sender stamp, so a hostile stamp can only
 vandalize its own field and still expires on schedule.
 
-The patch is structurally the `presence` object `parsePushBody` returns,
-so a push route forwards it whole: `session.setPresence(presence)`. The
-API mirrors the wire.
+The patch is structurally the `presence` sibling of the push envelope;
+`handle`'s push lane forwards it whole to `session.setPresence(presence)`.
+The API mirrors the wire.
 
 The handler-scoped form `ctx.session.setPresence(...)` is the same
 operation; `seen` defaults to the triggering event's `index`.
@@ -666,16 +666,32 @@ not affect state hydration or stream resumption.
 ### `useSession()`
 
 ```ts
-const { state, push, events, index, connection, presence, setPresence } =
-  useSession()
+const { state, push, events, index, loadHistory, history, connection,
+  presence, setPresence } = useSession()
 ```
 
 `state` starts from the initial snapshot and folds live events through the
-shared reducer. `events` is the raw observed feed. Unless `initialEvents`
-explicitly seeds earlier entries, it begins after `initialIndex`. `index` is
+shared reducer. `events` is the raw event feed: observed, explicitly
+seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
+`loadHistory` fetches them, it begins after `initialIndex`. `index` is
 the stream frontier, the `lastSeenIndex` for
 [cancellation](/guides/cancellation).
 
+`loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
+slice of the log from below the frontier (the same route, `gte`/`lte`
+query parameters) and merges it into `events`, deduped, ordered, and
+shared across every handle of the session. It resolves with the events
+in the requested range. Defaults walk backward 50 at a time from the
+oldest loaded event; `before` is an exclusive upper bound. After a
+hydrate jump (returning to a session whose frontier advanced while
+away), default paging still continues from the oldest loaded event;
+pass an explicit `before` to fill the gap between the old feed and the
+new frontier. It never touches `state` or the optimistic overlay. Calls
+serialize per session and already-loaded ranges are not refetched.
+`history` is the progress: `{ loading, complete, oldestLoaded }`, where
+`complete` means the feed reaches index 1 (or the log is empty). The `ws` api has no history lane; there `loadHistory`
+throws a `TypeError`.
+
 `presence` is the replicated ephemeral map,
 `Record<participantId, { [field]: { value, seen, at } }>`, including
 this client. `setPresence(values)` is fire-and-forget: validated
@@ -1032,10 +1048,10 @@ subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {
 initialState?, initialIndex?, initialEvents?, participant? })` returns a
 handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
-contract), `push()`, `connect()`, and `close()`. Snapshots carry
-`state`, `events`, `index`, and `connection` (the same fields
-`useSession` exposes), and `push` returns the same ack-then-`confirmed`
-result. On contracts that declare `presence` the handle also carries
+contract), `push()`, `loadHistory()`, `connect()`, and `close()`.
+Snapshots carry `state`, `events`, `index`, `history`, and `connection`
+(the same fields `useSession` exposes), and `push` returns the same
+ack-then-`confirmed` result. On contracts that declare `presence` the handle also carries
 `setPresence()` and snapshots carry the `presence` map, exactly like
 the hook; `participant` is the identity `setPresence` sends under. Use
 it directly from any other framework, or none.
@@ -1051,13 +1067,77 @@ across route transitions, while IndexedDB preserves the replica across reloads.
 
 ## `experimental-a2/http`
 
+### `handle(server, options?)`
+
+```ts
+handle(server: A2Server, options?: {
+  before?(args: { request: Request; intent: A2Intent }):
+    Response | undefined | void | Promise<Response | undefined | void>
+  after?(args: { request: Request; intent: A2Intent; outcome: A2Outcome; response: Response }):
+    Response | undefined | void | Promise<Response | undefined | void>
+  upgrade?: UpgradeFn  // e.g. (attach) => experimental_upgradeWebSocket(attach)
+  presence?: boolean   // interleave presence on every stream lane
+  deadline?: number    // epoch ms: close sockets cleanly before it
+}): { GET(req: Request): Promise<Response>; POST(req: Request): Promise<Response> }
+
+type A2Intent =
+  | { type: 'ws-upgrade' }
+  | { type: 'stream'; sessionId: string; startAfter: number; transport: 'sse' | 'ws' }
+  | { type: 'history'; sessionId: string; gte: number; lte: number }
+  | { type: 'push'; sessionId: string; events: PushedEvent[]; presence?: PushedPresence; transport: 'http' | 'ws' }
+
+type A2Outcome =
+  | { type: 'stream' }
+  | { type: 'history'; covered: boolean; events: Event[] }
+  | { type: 'push'; appended: Event[] }
+```
+
+The session route pair as one call: `export const { GET, POST } =
+handle(server)` in a route module (any framework speaking
+`(req: Request) => Promise<Response>`). A plain `GET` is the live SSE
+stream, resumed after the `index` query parameter, with a `: connected`
+prelude, a `: ping` heartbeat every 15s, and a clean close one second
+before an ambient Vercel invocation deadline when available; presence
+patches ride as named frames when `presence: true`. A `GET` with
+`gte`/`lte` query parameters is a history slice: the closed log range
+as JSON wire events, the read `loadHistory` rides. `POST` is the push
+envelope `{ sessionId, events, presence? }`, answered with the appended
+events. A `GET` carrying an upgrade header becomes the multiplexed
+WebSocket when `options.upgrade` is present, and answers `426` when it
+is not.
+
+Parsing is protocol, hooks are policy. A request that fails to parse
+(missing `sessionId`, malformed bounds, a bad push envelope) answers
+`INVALID_PAYLOAD` on the wire before any hook runs. `before` sees every
+parsed intent, HTTP requests and socket frames alike; over the socket,
+each subscribe arrives as a `stream` intent and each push as a `push`
+intent, with `request` always the original upgrade Request. Returning a
+Response short-circuits: over HTTP it is the response, verbatim; over
+the socket it is translated into the wire's own vocabulary (a denied
+subscribe answers `unsubscribed`, a denied push a non-retryable error
+ack), because a Response cannot cross a socket.
+
+`after` runs only where the library produced an HTTP response: never
+after a short-circuit, never for `ws-upgrade` or socket frames. It may
+mutate `response.headers` in place or return a replacement Response.
+`outcome.covered` on a history read means the closed range came back
+fully covered (`events.length === lte - gte + 1`): an immutable slice
+of the append-only log, safe to cache under whatever policy your
+`after` applies. The history response carries no cache headers of its
+own.
+
+The socket is one connection for all of a client's sessions:
+`subscribe`/`unsubscribe` frames open and close per-session lanes at
+their own resume frontiers, `sessionId` tags route pushes, presence,
+and acks, and a lane ending or failing answers `unsubscribed` without
+taking the socket down. See [Transports](/guides/transports).
+
+### The rest of the entry
+
 | Helper                  | What it does                                                                   |
 | ----------------------- | ------------------------------------------------------------------------------ |
 | `schedulerHandler(...servers)` | returns the delivery route after synchronously verifying one shared scheduler |
-| `parsePushBody(req)`    | validates the push envelope `{ sessionId, events, presence? }`, throws `INVALID_PAYLOAD`   |
-| `sseResponse(iterable)` | pipes a `session.stream()` iterable into an SSE `Response`, with a `: connected` prelude, a `: ping` heartbeat every 15s, and a clean close one second before an ambient Vercel invocation deadline when available; presence patches ride as named `presence` frames |
-| `sessionSocket(session, socket, options?)` | speaks the A2 wire over any `ws`-shaped socket: the stream pumps down as JSON frames, pushes and presence come up with the same validation and `validatePush` seam as the POST route; `options` carries `startAfter`, `presence`, and an optional `deadline` for clean pre-deadline closes. See [Transports](/guides/transports) |
-| `errorResponse(err)`    | serializes an `A2Error` to `{ error: { code, message, details } }` + status     |
+| `errorResponse(err)`    | serializes an `A2Error` to `{ error: { code, message, details } }` + status; the natural return value of a refusing `before` hook |
 | `deserializeError(body)` | rebuilds an `A2Error` from a wire body, or `null` if the body isn't one        |
 
 `schedulerHandler(...servers)` is the application-facing scheduler route. It
@@ -1071,8 +1151,9 @@ Different scheduler instances use different routes. Match each QStash route to
 that instance's resolved `url`; additional QStash routes pass an explicit
 `url`. Match each Vercel Queues route and trigger to that instance's `topic`.
 
-Together the last two are the `A2Error` wire format that `push` and the
-push route share. See [Errors](/reference/errors#over-the-wire).
+`errorResponse` and `deserializeError` are the `A2Error` wire format
+that `push` and the push lane share. See
+[Errors](/reference/errors#over-the-wire).
 
 ## `experimental-a2/cache-indexeddb`
 

package/docs/reference/02-errors.mdx

@@ -78,5 +78,7 @@ with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
 
 The client's `push` deserializes the body back into an `A2Error`, so client
 and server code branch on identical codes. `push` auto-retries only
-`STORE_UNAVAILABLE`. The serializer pair ships in `experimental-a2/http`, alongside
-`parsePushBody` and `sseResponse`.
+`STORE_UNAVAILABLE`. The serializer pair, `errorResponse` and
+`deserializeError`, ships in `experimental-a2/http` alongside `handle`;
+a `before` hook that wants the wire's own error shapes returns
+`errorResponse(new A2Error(...))`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "docs",
+    "src",
     "CHANGELOG.md"
   ],
   "exports": {

package/src/ai-coordinator.ts

@@ -0,0 +1,358 @@
+import type { UIMessage } from 'ai'
+import type {
+  AIEventDefs,
+  ApprovalRequestedPayload,
+  ApprovalRespondedPayload,
+  GenerationCompletedPayload,
+  GenerationFailedPayload,
+  GenerationRequestedPayload,
+  GenerationStartedPayload,
+  InputRequestedPayload,
+  MessageCreatedPayload,
+  MessageInterruptedPayload,
+  ToolCalledPayload,
+  ToolResultPayload,
+} from './ai.ts'
+import type { Contract, ContractEvent, EventDefs } from './contract.ts'
+import type { Reducer } from './reducer.ts'
+
+export type CoordinatorCall = {
+  index: number
+  call: ToolCalledPayload
+  approval?: ApprovalRequestedPayload
+  response?: ApprovalRespondedPayload
+  responseIndex?: number
+  terminal: boolean
+}
+
+export type CoordinatorResponse = {
+  rootMessageId: string
+  responseMessageId: string
+  status: 'requested' | 'generating' | 'waiting' | 'failed'
+  activeRequestId?: string
+  generation?: GenerationStartedPayload
+  completion?: GenerationCompletedPayload
+  failure?: GenerationFailedPayload
+  calls: CoordinatorCall[]
+  inputs: InputRequestedPayload[]
+  inputResponse?: {
+    index: number
+    generationId: string
+    inputId: string
+    name: string
+  }
+}
+
+export type AICoordinatorState = {
+  closed: boolean
+  queued: Array<{ index: number; messageId: string; generate: boolean }>
+  response?: CoordinatorResponse
+}
+
+const updateResponse = (
+  state: AICoordinatorState,
+  update: (response: CoordinatorResponse) => CoordinatorResponse,
+): AICoordinatorState =>
+  state.response === undefined
+    ? state
+    : { ...state, response: update(state.response) }
+
+const foldCoordinator = <M extends UIMessage, D extends EventDefs>(
+  state: AICoordinatorState,
+  event: ContractEvent<D>,
+): AICoordinatorState => {
+  switch (event.type) {
+    case 'ai.session.closed':
+      return { closed: true, queued: [] }
+    case 'ai.message.created': {
+      const payload = event.payload as MessageCreatedPayload<M>
+      const message = payload.message
+      if (message.role !== 'user') return state
+      return {
+        ...state,
+        queued: [
+          ...state.queued.filter((item) => item.messageId !== message.id),
+          {
+            index: event.index,
+            messageId: message.id,
+            generate: payload.generate !== false,
+          },
+        ].toSorted((left, right) => left.index - right.index),
+      }
+    }
+    case 'ai.generation.requested': {
+      const request = event.payload as GenerationRequestedPayload
+      if (request.reason === 'message') {
+        const responseMessageId =
+          request.responseMessageId ?? `${request.messageId}:assistant`
+        const requested = state.queued.find(
+          (item) => item.messageId === request.messageId,
+        )
+        return {
+          ...state,
+          queued:
+            requested === undefined
+              ? state.queued.filter(
+                  (item) => item.messageId !== request.messageId,
+                )
+              : state.queued.filter((item) => item.index > requested.index),
+          response: {
+            rootMessageId: request.messageId,
+            responseMessageId,
+            status: 'requested',
+            activeRequestId: event.id,
+            calls: [],
+            inputs: [],
+          },
+        }
+      }
+      if (
+        state.response === undefined ||
+        request.responseMessageId !== state.response.responseMessageId
+      ) {
+        return state
+      }
+      if (
+        (request.reason === 'tool' &&
+          (!continuationReady(state) ||
+            event.id !==
+              `ai.generate:tools:${state.response.generation?.generationId}`)) ||
+        (request.reason === 'retry' && state.response.status !== 'failed') ||
+        (request.reason === 'input' &&
+          state.response.inputResponse === undefined)
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        rootMessageId: response.rootMessageId,
+        responseMessageId: response.responseMessageId,
+        status: 'requested',
+        activeRequestId: event.id,
+        calls: [],
+        inputs: [],
+      }))
+    }
+    case 'ai.generation.started': {
+      const generation = event.payload as GenerationStartedPayload
+      if (
+        state.response?.responseMessageId !== generation.responseMessageId ||
+        state.response.activeRequestId !== generation.requestId ||
+        (state.response.generation?.requestId === generation.requestId &&
+          state.response.generation.attempt >= generation.attempt)
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        rootMessageId: response.rootMessageId,
+        responseMessageId: response.responseMessageId,
+        status: 'generating',
+        generation,
+        activeRequestId: generation.requestId,
+        calls: [],
+        inputs: [],
+      }))
+    }
+    case 'ai.generation.completed': {
+      const completion = event.payload as GenerationCompletedPayload
+      if (
+        state.response?.generation?.generationId !== completion.generationId
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        status: 'waiting',
+        completion,
+      }))
+    }
+    case 'ai.generation.failed': {
+      const failure = event.payload as GenerationFailedPayload
+      const response = state.response
+      const ownsActiveGeneration =
+        response?.generation?.generationId === failure.generationId
+      const ownsActiveStepLimit =
+        failure.stepLimit === true &&
+        response?.activeRequestId ===
+          `ai.generate:tools:${failure.generationId}` &&
+        response.responseMessageId === failure.responseMessageId
+      if (!ownsActiveGeneration && !ownsActiveStepLimit) {
+        return state
+      }
+      return updateResponse(state, (current) => ({
+        ...current,
+        status: 'failed',
+        failure,
+      }))
+    }
+    case 'ai.message.completed': {
+      const messageId = (event.payload as { messageId: string }).messageId
+      return state.response?.responseMessageId === messageId
+        ? { closed: state.closed, queued: state.queued }
+        : state
+    }
+    case 'ai.message.interrupted': {
+      const interruption = event.payload as MessageInterruptedPayload
+      const response = state.response
+      return response?.responseMessageId === interruption.messageId &&
+        (interruption.generationId === response.generation?.generationId ||
+          interruption.requestId === response.activeRequestId)
+        ? { closed: state.closed, queued: state.queued }
+        : state
+    }
+    case 'ai.tool.called': {
+      const call = event.payload as ToolCalledPayload
+      if (state.response?.generation?.generationId !== call.generationId) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        calls: [
+          ...response.calls.filter(
+            (candidate) => candidate.call.toolCallId !== call.toolCallId,
+          ),
+          { index: event.index, call, terminal: false },
+        ],
+      }))
+    }
+    case 'ai.approval.requested': {
+      const approval = event.payload as ApprovalRequestedPayload
+      if (state.response?.generation?.generationId !== approval.generationId) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        calls: response.calls.map((candidate) =>
+          candidate.call.toolCallId === approval.toolCallId
+            ? { ...candidate, approval }
+            : candidate,
+        ),
+      }))
+    }
+    case 'ai.approval.responded': {
+      const approval = event.payload as ApprovalRespondedPayload
+      if (
+        state.response?.responseMessageId !== approval.messageId ||
+        state.response.generation?.generationId !== approval.generationId
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        calls: response.calls.map((candidate) =>
+          candidate.approval?.approvalId === approval.approvalId
+            ? { ...candidate, response: approval, responseIndex: event.index }
+            : candidate,
+        ),
+      }))
+    }
+    case 'ai.tool.result': {
+      const result = event.payload as ToolResultPayload
+      if (
+        result.preliminary === true ||
+        state.response?.generation?.generationId !== result.generationId
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        calls: response.calls.map((candidate) =>
+          candidate.call.toolCallId === result.toolCallId
+            ? { ...candidate, terminal: true }
+            : candidate,
+        ),
+      }))
+    }
+    case 'ai.input.requested': {
+      const input = event.payload as InputRequestedPayload
+      if (
+        state.response?.responseMessageId !== input.messageId ||
+        state.response.generation?.generationId !== input.generationId
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        inputs: [
+          ...response.inputs.filter(
+            (candidate) =>
+              candidate.messageId !== input.messageId ||
+              candidate.generationId !== input.generationId ||
+              candidate.inputId !== input.inputId,
+          ),
+          input,
+        ],
+      }))
+    }
+    case 'ai.input.responded': {
+      const input = event.payload as {
+        messageId: string
+        generationId: string
+        inputId: string
+        name: string
+      }
+      const requested = state.response?.inputs.find(
+        (candidate) =>
+          candidate.messageId === input.messageId &&
+          candidate.generationId === input.generationId &&
+          candidate.inputId === input.inputId &&
+          candidate.name === input.name,
+      )
+      if (
+        state.response?.responseMessageId !== input.messageId ||
+        state.response.generation?.generationId !== input.generationId ||
+        requested === undefined
+      ) {
+        return state
+      }
+      return updateResponse(state, (response) => ({
+        ...response,
+        inputs: response.inputs.filter(
+          (candidate) => candidate.inputId !== input.inputId,
+        ),
+        inputResponse: {
+          index: event.index,
+          generationId: input.generationId,
+          inputId: input.inputId,
+          name: requested.name,
+        },
+      }))
+    }
+    default:
+      return state
+  }
+}
+
+export const aiCoordinatorReducer = <
+  M extends UIMessage,
+  D extends AIEventDefs<M> & EventDefs,
+>(
+  contract: Contract<D>,
+): Reducer<D, AICoordinatorState> =>
+  contract
+    .reducer({
+      name: 'a2.ai.coordinator.v3',
+      initialState: {
+        closed: false,
+        queued: [],
+      } as AICoordinatorState,
+    })
+    .fold((state, event) => foldCoordinator<M, D>(state, event))
+
+export const continuationReady = (state: AICoordinatorState): boolean => {
+  const response = state.response
+  return (
+    !state.closed &&
+    response?.completion?.finishReason === 'tool-calls' &&
+    response.generation?.generationId === response.completion.generationId &&
+    response.failure === undefined &&
+    response.calls.length > 0 &&
+    response.calls.every(
+      (call) =>
+        call.terminal ||
+        (call.call.providerExecuted === true &&
+          call.call.supportsDeferredResults !== true &&
+          call.approval !== undefined &&
+          call.response !== undefined),
+    )
+  )
+}