experimental-a2 0.3.0 → 0.5.0

package/docs/reference/02-errors.mdx

@@ -36,11 +36,15 @@ export async function POST(req: Request) {
 | ------------------------- | ------------------------------------------------------------------ | --------- |
 | `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
 | `UNKNOWN_EVENT_TYPE`      | an event type isn't in the contract's `events` map                  | no        |
+| `UNKNOWN_PRESENCE_FIELD`  | a presence field isn't in the contract's `presence` map             | no        |
+| `PRESENCE_NOT_SUPPORTED`  | the contract declares `presence` but the configured store has no presence capability (thrown at construction; for environment-resolved stores, deferred to the first store use) | no |
 | `PARTIAL_DUPLICATE_BATCH` | a batch mixed already-appended and fresh events                     | no        |
-| `LOG_UNAVAILABLE`         | the log backend failed; nothing was written, original error as `cause` | **yes**   |
-| `LOG_NOT_CONFIGURED`      | production boot with no `log` configured (during `next build` page collection, deferred to first use) | no |
+| `SUPERSEDED_ATTEMPT`      | a handler append from an attempt a recovery claim has replaced; nothing was written, the successor owns the event. Also the abort reason on that handler's `ctx.signal` | no        |
+| `CLAIM_EXPIRED`           | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no        |
+| `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
+| `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |
 
-Retryability is derivable from the code. `LOG_UNAVAILABLE` is the only one
+Retryability is derivable from the code. `STORE_UNAVAILABLE` is the only one
 worth retrying; the rest are deterministic caller bugs, and retrying them
 is wasted work.
 
@@ -69,9 +73,12 @@ The push route serializes an `A2Error` as:
 ```
 
 with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
-`PARTIAL_DUPLICATE_BATCH` are 400; `LOG_UNAVAILABLE` is 503.
+`PARTIAL_DUPLICATE_BATCH` are 400; `SUPERSEDED_ATTEMPT` is 409;
+`STORE_UNAVAILABLE` is 503.
 
 The client's `push` deserializes the body back into an `A2Error`, so client
 and server code branch on identical codes. `push` auto-retries only
-`LOG_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,9 +1,12 @@
 {
   "name": "experimental-a2",
-  "version": "0.3.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",
+  "bin": {
+    "a2": "./dist/cli-bin.js"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=22.13"
@@ -20,6 +23,7 @@
   "files": [
     "dist",
     "docs",
+    "src",
     "CHANGELOG.md"
   ],
   "exports": {
@@ -36,22 +40,29 @@
       "default": "./dist/ai-server.js"
     },
     "./http": "./dist/http.js",
-    "./log-memory": "./dist/log-memory.js",
-    "./log-sqlite": "./dist/log-sqlite.js",
-    "./log-postgres": "./dist/log-postgres.js",
-    "./log-redis": "./dist/log-redis.js",
-    "./log-redis-http": "./dist/log-redis-http.js",
-    "./recovery-vercel": "./dist/recovery-vercel.js",
+    "./store-memory": "./dist/store-memory.js",
+    "./store-sqlite": "./dist/store-sqlite.js",
+    "./store-postgres": "./dist/store-postgres.js",
+    "./store-redis": "./dist/store-redis.js",
+    "./store-redis-http": "./dist/store-redis-http.js",
+    "./scheduler-qstash": "./dist/scheduler-qstash.js",
+    "./scheduler-vercel": "./dist/scheduler-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
     "./otel": "./dist/otel.js",
+    "./devtools": "./dist/devtools.js",
     "./devtools/server": {
       "browser": "./dist/devtools-server.browser.js",
       "default": "./dist/devtools-server.js"
     },
+    "./testing": {
+      "browser": "./dist/testing.browser.js",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@upstash/qstash": "^2.11.0",
     "@vercel/queue": "*",
     "ai": "^7.0.0",
     "ioredis": "^5.4.0",
@@ -62,6 +73,9 @@
     "@opentelemetry/api": {
       "optional": true
     },
+    "@upstash/qstash": {
+      "optional": true
+    },
     "@vercel/queue": {
       "optional": true
     },
@@ -80,12 +94,15 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",
+    "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
     "@opentelemetry/api": "^1.9.0",
     "@types/pg": "^8.15.0",
+    "@types/ws": "^8.18.1",
     "@vercel/queue": "^0.2.0",
     "pg": "^8.16.0",
+    "ws": "^8.21.3",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^19.0.0",
     "esbuild": "^0.25.0",

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),
+    )
+  )
+}