experimental-a2 0.16.1 → 0.18.0

package/docs/reference/02-errors.mdx

@@ -1,149 +0,0 @@
----
-title: Errors
-description: Stable server and client error codes, transport details, and append guarantees.
----
-
-## `A2Error`
-
-A2 failures carry an `A2Error` with a stable `code`. The session client exposes
-`A2ClientError`, which extends `A2Error`, for both server failures and failures
-observed locally. Existing `instanceof A2Error` checks also match client errors.
-
-```ts
-// e.g. in a route handler:
-import { A2Error } from 'experimental-a2'
-
-export async function POST(req: Request) {
-  const { orderId, payload } = await req.json()
-  try {
-    const events = await ordersServer
-      .session(orderId)
-      .append({ type: 'created', payload })
-    return Response.json(events)
-  } catch (err) {
-    if (err instanceof A2Error && err.code === 'INVALID_PAYLOAD') {
-      // err.details carries the schema issues, in Standard Schema format
-      return Response.json({ issues: err.details }, { status: 400 })
-    }
-    throw err
-  }
-}
-```
-
-## The codes
-
-| Code                      | Thrown when                                                        | Retryable |
-| ------------------------- | ------------------------------------------------------------------ | --------- |
-| `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
-| `FORBIDDEN`               | `server.fetch` authorization denies a parsed stream, history read, push, or presence update | 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        |
-| `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 |
-
-Of these server codes, only `STORE_UNAVAILABLE` is automatically retried by
-client pushes. Reconnection has its own caller-configurable policy.
-
-## `A2ClientError`
-
-Import `A2ClientError` from `experimental-a2/client`. Connection failures,
-push failures, history read failures, and local A2 validation failures use
-this class. Server failures keep their `code`, `message`, and `details`.
-Unexpected thrown values are retained as `cause`. Invalid API arguments can
-still throw native `TypeError` or `RangeError` exceptions.
-
-| Client code | Meaning |
-| --- | --- |
-| `TIMEOUT` | A2 detected a stream stall or an unconfirmed subscription. `phase` is `stream` or `subscribe`; `timeoutMs` is the expired deadline. |
-| `HTTP_ERROR` | An unsuccessful HTTP response without a recognized A2 error body. `status` carries the HTTP status. |
-| `CONNECTION_FAILED` | The transport could not establish or retain a connection. WebSocket close events preserve `closeCode` and `closeReason` when available. |
-| `UNKNOWN` | An unexpected client failure. The original value is available as `cause`. |
-
-HTTP failures retain `status` even when they carry a recognized server code.
-A browser WebSocket handshake rejection has no readable HTTP status or body;
-it remains `CONNECTION_FAILED`. A2 does not infer an authorization failure or
-a timeout from an opaque socket error.
-
-The stream watchdog detects 35 seconds of silence after connection. A
-multiplexed subscription also has 35 seconds to receive confirmation. There
-is no A2-owned initial connection deadline for HTTP or single-session
-WebSockets. Clean stream termination has no error: the reconnection callback
-and connection snapshot carry `null`.
-
-Pushes retain their three-attempt budget for `STORE_UNAVAILABLE` and client
-transport failures. The reconnection callback controls only the live stream.
-Pausing that stream preserves the writer; it does not guarantee that a push
-can succeed while its WebSocket is unavailable.
-
-On `PARTIAL_DUPLICATE_BATCH`: retrying an *identical* batch is not an
-error. It's an idempotent success, and you get the previously appended
-events back. Mixing already-sent events with fresh ones in a single batch
-is always a caller bug, so A2 refuses it rather than quietly reinterpret
-what "atomic" meant. The same code covers two adjacent bugs: a batch that
-contains the same id twice, and an id that was already used in a
-*different* session (event ids are globally unique). In every case,
-nothing is written.
-
-## NonRetriableError
-
-Throw it (or a subclass, matched by
-`instanceof`) from a handler when the failure is deterministic: the
-event dead-letters immediately instead of consuming the ten-failure
-retry budget, because a guard that refuses this attempt will refuse
-every retry identically. Any other thrown error keeps the ordinary
-retry contract.
-
-```ts
-import { z } from 'zod'
-import * as a2 from 'experimental-a2'
-import { NonRetriableError } from 'experimental-a2'
-import { createServer } from 'experimental-a2/server'
-
-const orders = a2.contract({
-  name: 'orders',
-  events: { created: z.object({ chargeable: z.boolean() }) },
-})
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ event }) => {
-      if (!event.payload.chargeable) {
-        throw new NonRetriableError('this order cannot be charged')
-      }
-      // transient failures below retry as usual
-    },
-  },
-})
-```
-
-## What append never throws for
-
-- **A failing handler.** Appends always land; handler failures are retried
-  and, if persistent, [dead-letter the event](/concepts/durability#when-a-handler-keeps-failing).
-  `append` never fails because a downstream handler is failing.
-- **A duplicate of an identical batch.** That's a lost ack, not a bug.
-
-## Over the wire
-
-The push route serializes an `A2Error` as:
-
-```json
-{ "error": { "code": "INVALID_PAYLOAD", "message": "...", "details": [] } }
-```
-
-with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
-`PARTIAL_DUPLICATE_BATCH` are 400; `FORBIDDEN` is 403;
-`SUPERSEDED_ATTEMPT` is 409; `STORE_UNAVAILABLE` is 503.
-
-The session client deserializes the body into an `A2ClientError`, so client
-and server code branch on identical server codes. `server.fetch` owns HTTP
-serialization. Multiplexed WebSocket subscription failures carry the same
-error envelope in their `unsubscribed` frame, alongside the legacy `reason`
-string. Older reason-only frames remain readable as `CONNECTION_FAILED`.
-Unknown server exceptions become `STORE_UNAVAILABLE`; their private causes
-are not sent to clients.

package/examples/playground/app/agent/[agentId]/compaction/route.ts

@@ -1,14 +0,0 @@
-import { updateCompactionSettings } from '../../compaction-settings'
-import { agentServer } from '../../server'
-
-export async function POST(
-  request: Request,
-  context: { params: Promise<{ agentId: string }> },
-): Promise<Response> {
-  const { agentId } = await context.params
-  return updateCompactionSettings({
-    request,
-    sessionId: agentId,
-    append: (event) => agentServer.session(agentId).append(event),
-  })
-}

package/examples/playground/app/agent/compaction-settings.test.ts

@@ -1,144 +0,0 @@
-import { expect, it } from 'vitest'
-import { createAgentServer } from 'experimental-a2/ai/server'
-import { memory } from 'experimental-a2/store-memory'
-import {
-  compactionOptions,
-  compactionSettings,
-  demoAgent,
-  latestCompactionSettings,
-} from './model'
-import { updateCompactionSettings } from './compaction-settings'
-
-const request = (
-  settings: unknown,
-  options: { origin?: string; contentType?: string; id?: string } = {},
-): Request =>
-  new Request('https://example.test/agent/session/compaction', {
-    method: 'POST',
-    headers: {
-      origin: options.origin ?? 'https://example.test',
-      'content-type': options.contentType ?? 'application/json',
-    },
-    body: JSON.stringify({ id: options.id ?? crypto.randomUUID(), settings }),
-  })
-
-it('uses the request Host when Next normalizes the internal URL', async () => {
-  let writes = 0
-  const response = await updateCompactionSettings({
-    request: new Request('http://localhost:3107/agent/s/compaction', {
-      method: 'POST',
-      headers: {
-        host: '127.0.0.1:3107',
-        origin: 'http://127.0.0.1:3107',
-        'content-type': 'application/json',
-      },
-      body: JSON.stringify({
-        id: crypto.randomUUID(),
-        settings: { mode: 'manual', thresholdTokens: 1 },
-      }),
-    }),
-    sessionId: 's',
-    append: async () => {
-      writes += 1
-    },
-  })
-  expect(response.status).toBe(200)
-  expect(writes).toBe(1)
-})
-
-it('saves session settings durably and idempotently without starting a turn', async () => {
-  let generations = 0
-  const server = createAgentServer({
-    agent: demoAgent,
-    store: memory(),
-    model: 'test/model',
-    compaction: async ({ session }) =>
-      compactionOptions((await session.state(compactionSettings)).state),
-    generate: () => {
-      generations += 1
-      return new ReadableStream({
-        start(controller) {
-          controller.close()
-        },
-      })
-    },
-  })
-  const session = server.session('settings-test')
-  const id = crypto.randomUUID()
-  const save = () =>
-    updateCompactionSettings({
-      request: request({ mode: 'manual', thresholdTokens: 1 }, { id }),
-      sessionId: session.id,
-      append: (event) => session.append(event),
-    })
-  expect((await save()).status).toBe(200)
-  expect((await save()).status).toBe(200)
-  await server.drain(session.id)
-  const history = await session.history()
-  expect(history.map((event) => event.type)).toEqual([
-    'compaction.settings.updated',
-  ])
-  expect(latestCompactionSettings(history).settings).toEqual({
-    mode: 'manual',
-    thresholdTokens: 1,
-  })
-  expect(
-    compactionOptions((await session.state(compactionSettings)).state),
-  ).toEqual({ thresholdTokens: 1 })
-  expect(
-    compactionOptions(
-      (await server.session('other').state(compactionSettings)).state,
-    ),
-  ).toEqual({})
-  expect(generations).toBe(0)
-
-  await updateCompactionSettings({
-    request: request({ mode: 'disabled' }),
-    sessionId: session.id,
-    append: (event) => session.append(event),
-  })
-  expect(
-    compactionOptions((await session.state(compactionSettings)).state),
-  ).toBe(false)
-  await updateCompactionSettings({
-    request: request({ mode: 'automatic' }),
-    sessionId: session.id,
-    append: (event) => session.append(event),
-  })
-  expect(
-    compactionOptions((await session.state(compactionSettings)).state),
-  ).toEqual({})
-})
-
-it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, '1', null])(
-  'rejects invalid threshold %s',
-  async (thresholdTokens) => {
-    let writes = 0
-    const response = await updateCompactionSettings({
-      request: request({ mode: 'manual', thresholdTokens }),
-      sessionId: 's',
-      append: async () => {
-        writes += 1
-      },
-    })
-    expect(response.status).toBe(400)
-    expect(writes).toBe(0)
-  },
-)
-
-it.each([
-  { origin: 'https://other.test', status: 403 },
-  { contentType: 'text/plain', status: 415 },
-  { id: 'not-an-id', status: 400 },
-])('rejects invalid request boundaries %j', async ({ status, ...options }) => {
-  let writes = 0
-  const response = await updateCompactionSettings({
-    request: request({ mode: 'automatic' }, options),
-    sessionId: 's',
-    append: async () => {
-      writes += 1
-    },
-  })
-  expect(response.status).toBe(status)
-  expect(writes).toBe(0)
-})

package/examples/playground/app/agent/compaction-settings.ts

@@ -1,49 +0,0 @@
-import { z } from 'zod'
-import { compactionSettingsSchema, type CompactionSettings } from './model'
-
-const updateSchema = z.strictObject({
-  id: z.uuid(),
-  settings: compactionSettingsSchema,
-})
-
-export async function updateCompactionSettings(options: {
-  request: Request
-  sessionId: string
-  append: (event: {
-    id: string
-    type: 'compaction.settings.updated'
-    payload: CompactionSettings
-  }) => Promise<unknown>
-}): Promise<Response> {
-  const { request, sessionId } = options
-  const origin = request.headers.get('origin')
-  const requestUrl = new URL(request.url)
-  requestUrl.host = request.headers.get('host') ?? requestUrl.host
-  if (origin !== null && origin !== requestUrl.origin) {
-    return Response.json(
-      { error: 'Use this page to update compaction settings.' },
-      { status: 403 },
-    )
-  }
-  if (
-    request.headers.get('content-type')?.split(';')[0]?.trim() !==
-    'application/json'
-  ) {
-    return Response.json({ error: 'Expected JSON settings.' }, { status: 415 })
-  }
-  if (sessionId.length === 0)
-    return Response.json({ error: 'Session is required.' }, { status: 400 })
-  const parsed = updateSchema.safeParse(await request.json().catch(() => null))
-  if (!parsed.success) {
-    return Response.json(
-      { error: 'Choose a mode and a positive whole-number threshold.' },
-      { status: 400 },
-    )
-  }
-  await options.append({
-    id: `agent.compaction.settings:${encodeURIComponent(sessionId)}:${parsed.data.id}`,
-    type: 'compaction.settings.updated',
-    payload: parsed.data.settings,
-  })
-  return Response.json({ settings: parsed.data.settings })
-}