experimental-a2 0.22.0 → 0.24.0

package/examples/playground/app/a2slack/db/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1792693132589,
       "tag": "0004_a2_session_event_ids",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1792761727680,
+      "tag": "0005_a2slack_feed_v2",
+      "breakpoints": true
     }
   ]
-}
+}

package/examples/playground/app/a2slack/db/queries.ts

@@ -38,7 +38,7 @@ import {
 } from './schema'
 
 /** The feed consumer's name, which its position is recorded under. */
-export const FEED = 'a2slack-feed'
+export const FEED = 'a2slack-feed-v2'
 
 export const PAGE_SIZE = 50
 

package/examples/playground/app/a2slack/drills/a2slack.drill.ts

@@ -340,7 +340,7 @@ async function loadRun(store: A2Store, label: string) {
       payload: { id: channel, by: pick(USERS) },
     })
   await until(
-    () => idle(store, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(store, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     {
       timeoutMs: 60_000,
     },
@@ -350,7 +350,7 @@ async function loadRun(store: A2Store, label: string) {
 
   const posted = await post(to, MESSAGES, CONCURRENCY)
   const catchUpMs = await until(
-    () => idle(store, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(store, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     { timeoutMs: 10 * 60_000, everyMs: 100 },
   )
   const log = await logCounts(to[0]!)
@@ -361,7 +361,7 @@ async function loadRun(store: A2Store, label: string) {
   await followers.close()
   const tables = await tableCounts()
   const db = await a2slack.database()
-  const feedPosition = await a2slack.queries.position(db, 'a2slack-feed')
+  const feedPosition = await a2slack.queries.position(db, a2slack.queries.FEED)
 
   const [root] = await rows<{ id: string }>(
     "select id from a2slack_messages where thread_id is null and channel = 'room-1' order by log_index desc limit 1",
@@ -449,23 +449,23 @@ it('rebuild: a renamed feed fills empty tables from the whole log', async () =>
   const db = await a2slack.database()
   await db.execute(
     sql.raw(
-      "truncate a2slack_channels, a2slack_messages, a2slack_notifications, a2slack_reactions, a2slack_reads; delete from a2slack_positions where consumer = 'a2slack-feed'",
+      `truncate a2slack_channels, a2slack_messages, a2slack_notifications, a2slack_reactions, a2slack_reads; delete from a2slack_positions where consumer = '${a2slack.queries.FEED}'`,
     ),
   )
   const { telemetry, runs } = recorder()
-  const feedV2 = a2slack
+  const feedRebuild = a2slack
     .consumer({
       contract: a2slack.model.workspace,
-      name: 'a2slack-feed-v2',
-      lane: 'feed-v2',
+      name: 'a2slack-feed-rebuild',
+      lane: 'feed-rebuild',
       backfill: true,
     })
     .run(async ({ event }) => {
       await a2slack.feedEvent(await a2slack.database(), event)
     })
-  const [server] = servers(redisStore, [feedV2], telemetry, 1)
+  const [server] = servers(redisStore, [feedRebuild], telemetry, 1)
   const t0 = performance.now()
-  const consumed = await session(server!).consume(feedV2)
+  const consumed = await session(server!).consume(feedRebuild)
   const ms = performance.now() - t0
   const after = await tableCounts()
   const result = {
@@ -524,9 +524,12 @@ it('poison: one bad event dead-letters its consumer alone, and redrive resumes i
   await post(to, 50, 5)
 
   const t0 = performance.now()
-  await until(() => idle(redisStore, ['a2slack-feed', 'a2slack-notify']), {
-    timeoutMs: 60_000,
-  })
+  await until(
+    () => idle(redisStore, [a2slack.queries.FEED, 'a2slack-notify']),
+    {
+      timeoutMs: 60_000,
+    },
+  )
   const othersCaughtUpMs = performance.now() - t0
   const stuck = (await redisStore.cursors('a2slack\u001fworkspace')).find(
     (cursor) => cursor.consumer === 'drill-seen',
@@ -625,14 +628,14 @@ it('outage: Postgres goes away mid-load, and every event still lands once', asyn
   })
   await outage
   await until(
-    () => idle(redisStore, ['welcome', 'a2slack-feed', 'a2slack-notify']),
+    () => idle(redisStore, ['welcome', a2slack.queries.FEED, 'a2slack-notify']),
     { timeoutMs: 5 * 60_000, everyMs: 200 },
   )
   const idleAt = performance.now()
   const log = await logCounts(to[0]!)
   const tables = await tableCounts()
   const db = await a2slack.database()
-  const feedPosition = await a2slack.queries.position(db, 'a2slack-feed')
+  const feedPosition = await a2slack.queries.position(db, a2slack.queries.FEED)
   const deadLetters = await session(to[0]!).deadLetters()
   const result = {
     appended: 3_000,

package/examples/playground/app/a2slack/search-index.ts

@@ -12,7 +12,7 @@ import { Redis, s } from '@upstash/redis'
 import { searchFeed } from './db/queries'
 import type { SearchResult } from './model'
 
-const NAME = 'a2slack-messages-v1'
+const NAME = 'a2slack-messages-v2'
 const PREFIX = `${NAME}:message:`
 
 const schema = s.object({

package/examples/playground/app/a2slack/server.ts

@@ -4,8 +4,8 @@
  * either writes somewhere else or returns events into the log:
  *
  * - `welcome` posts a new channel's opening message.
- * - `a2slack-feed` keeps the tables every page reads (db/schema.ts).
- * - `a2slack-search-v1` keeps the search index in Upstash Redis Search,
+ * - `a2slack-feed-v2` keeps the tables every page reads (db/schema.ts).
+ * - `a2slack-search-v2` keeps the search index in Upstash Redis Search,
  *   where it's configured (search-index.ts).
  * - `a2slack-notify` works out who should hear about each message, and
  *   returns a notification addressed to each of them.

package/examples/playground/lib/store.ts

@@ -8,6 +8,8 @@ const postgresUrl = process.env.DATABASE_URL?.replace(
   'sslmode=verify-full',
 )
 
+// A new keyPrefix starts every log over: a2slack's feed (consumers/feed.ts)
+// has to start over with it, under a new name and with its tables cleared.
 export const store: RedisStore | PostgresStore | undefined = redisUrl
   ? redis({ url: redisUrl, keyPrefix: 'a2-playground-tagged' })
   : postgresUrl

package/examples/playground/package.json

@@ -39,7 +39,7 @@
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
     "drizzle-orm": "^0.45.3",
-    "experimental-a2": "0.22.0",
+    "experimental-a2": "0.24.0",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",
@@ -61,6 +61,7 @@
     "./store-postgres": "./dist/store-postgres.js",
     "./store-redis": "./dist/store-redis.js",
     "./store-redis-http": "./dist/store-redis-http.js",
+    "./store-valkey": "./dist/store-valkey.js",
     "./scheduler-qstash": "./dist/scheduler-qstash.js",
     "./scheduler-vercel": "./dist/scheduler-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
@@ -77,7 +78,8 @@
     "ioredis": "^5.4.0",
     "libfx": "^0.0.12",
     "pg": "^8.11.0",
-    "react": "^19.0.0"
+    "react": "^19.0.0",
+    "redis": "^5.8.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -109,6 +111,9 @@
     },
     "react": {
       "optional": true
+    },
+    "redis": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -119,6 +124,7 @@
     "@upstash/qstash": "^2.11.3",
     "ai": "^7.0.58",
     "ioredis": "^5.9.0",
+    "redis": "^6.2.1",
     "@opentelemetry/api": "^1.9.0",
     "@types/pg": "^8.15.0",
     "@types/ws": "^8.18.1",

package/src/ai-fx.ts

@@ -70,6 +70,8 @@ const SNAPSHOT_VERSION = 1
 const CATALOG_TTL_MS = 60 * 60 * 1000
 /** The Gateway model catalog libfx reads for each new kernel. */
 const CATALOG_PATH = '/coding-agent/v1/models'
+/** Times a step rebuilds its kernel for a stopped turn FX failed on replay. */
+const REPLAY_REBUILDS = 3
 
 type StreamPart = { type: string } & Record<string, unknown>
 /** A recorded tool call, with the input the kernel reads from its text. */
@@ -144,7 +146,13 @@ type KernelHooks = {
   tool: (toolName: string, input: unknown) => unknown
 }
 
-type Kernel = { agent: FxAgent; hooks: KernelHooks; waiting: Waiting[] }
+type Kernel = {
+  agent: FxAgent
+  hooks: KernelHooks
+  waiting: Waiting[]
+  /** Whether FX answered the kernel's latest prompt with an error. */
+  failed: boolean
+}
 
 /**
  * A kernel a step left waiting on its tool calls. The session's next step in
@@ -249,8 +257,12 @@ async function runStep(
       await resume(controller, turns.at(-1)!, adopted)
       return
     }
-    for (const plan of turns) {
+    let rebuilds = 0
+    let next = 0
+    while (next < turns.length) {
       if (stopped || step.signal.aborted) return
+      const plan = turns[next]!
+      next += 1
       // The step's abort cancels the turn; the turn outlives it when parked.
       const fxTurn = kernel!.agent.prompt(plan.prompt)
       const state: TurnState = {
@@ -282,6 +294,18 @@ async function runStep(
           throw diverged(
             `a recorded turn ended with ${result.stopReason}, not ${expected}`,
           )
+        if (kernel!.failed) {
+          // libfx's cancel aborts the request FX waits on as it sends the
+          // stop, and FX fails the turn when it reads the abort first. That
+          // kernel holds no interruption where the log has one, so the turns
+          // replay on a new kernel.
+          if (rebuilds === REPLAY_REBUILDS)
+            throw diverged('FX failed a stopped turn instead of cancelling it')
+          rebuilds += 1
+          await kernel!.agent.close().catch(() => {})
+          kernel = await create(read.saved)
+          next = 0
+        }
         continue
       }
       await finishLive(controller, state, drained)
@@ -577,7 +601,8 @@ async function runStep(
   const create = async (
     checkpoint: Uint8Array | undefined,
   ): Promise<Kernel> => {
-    const created = { hooks, waiting: [] as Waiting[] }
+    const created = { hooks, waiting: [] as Waiting[], failed: false }
+    let prompt: unknown
     const agent = await createFxAgent({
       apiKey: credential.token,
       model: kernelModel(step),
@@ -591,6 +616,24 @@ async function runStep(
       })),
       ...(checkpoint === undefined ? {} : { checkpoint }),
       fetch: (input, init) => created.hooks.fetch(input, init),
+      // libfx reports a turn FX failed after its cancel as cancelled; only
+      // the ACP response to the turn's prompt tells the two apart.
+      onEvent: ({ type, message }) => {
+        const rpc = (message ?? {}) as {
+          id?: unknown
+          method?: unknown
+          error?: unknown
+        }
+        if (type === 'acp.send' && rpc.method === 'session/prompt') {
+          prompt = rpc.id
+          created.failed = false
+        } else if (
+          type === 'acp.receive' &&
+          rpc.method === undefined &&
+          rpc.id === prompt
+        )
+          created.failed = rpc.error !== undefined
+      },
     })
     return Object.assign(created, { agent })
   }

package/src/errors.ts

@@ -5,6 +5,7 @@ export type A2ServerErrorCode =
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
   | 'SUPERSEDED_ATTEMPT' // consumer append from an attempt a recovery claim or a clear replaced
   | 'SESSION_CLEARED' // a read or call reached across the session's latest clear
+  | 'LAST_INDEX_MISMATCH' // a conditional append's ifLastIndex was not the head — nothing was written
   | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal
   | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written
   | 'STORE_NOT_CONFIGURED' // no `store` in production, a missing peer dependency, or Postgres lacks A2's tables
@@ -48,6 +49,44 @@ export function supersededAttemptError(
   )
 }
 
+/** A conditional append whose `ifLastIndex` is not the session's head. */
+export function lastIndexMismatchError(
+  sessionId: string,
+  ifLastIndex: number,
+  head: number,
+): A2Error {
+  return new A2Error(
+    'LAST_INDEX_MISMATCH',
+    `session '${sessionId}' is at index ${head}, not ${ifLastIndex}`,
+    { details: { index: head } },
+  )
+}
+
+/** A conditional append's condition and the head its store found. */
+export type ConditionalHead = {
+  sessionId: string
+  ifLastIndex: number
+  head: number
+}
+
+/**
+ * A batch whose ids conflict with committed events. In a conditional append
+ * whose head moved, the condition failed first, as when another writer's
+ * batch took those ids, so the conflict reports the head instead.
+ */
+export function duplicateBatchError(
+  message: string,
+  conditional: ConditionalHead | undefined,
+): A2Error {
+  return conditional && conditional.head !== conditional.ifLastIndex
+    ? lastIndexMismatchError(
+        conditional.sessionId,
+        conditional.ifLastIndex,
+        conditional.head,
+      )
+    : new A2Error('PARTIAL_DUPLICATE_BATCH', message)
+}
+
 /**
  * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
  * original as `cause`. A2Errors pass through untouched — they already

package/src/idempotent-replay.ts

@@ -1,4 +1,4 @@
-import { A2Error } from './errors.ts'
+import { duplicateBatchError, type ConditionalHead } from './errors.ts'
 import type { AppendEvent, StoredEvent } from './store.ts'
 
 const canonicalJson = (value: unknown): string =>
@@ -20,6 +20,7 @@ const canonicalJson = (value: unknown): string =>
 export const idempotentReplay = (
   events: readonly AppendEvent[],
   existing: readonly StoredEvent[],
+  conditional?: ConditionalHead,
 ): StoredEvent[] => {
   const byId = new Map(existing.map((event) => [event.id, event]))
   const ordered = events.map((event) =>
@@ -42,9 +43,9 @@ export const idempotentReplay = (
       )
     })
   ) {
-    throw new A2Error(
-      'PARTIAL_DUPLICATE_BATCH',
+    throw duplicateBatchError(
       'already-appended events do not match the retried batch',
+      conditional,
     )
   }
 

package/src/libfx.d.ts

@@ -37,5 +37,7 @@ declare module 'libfx' {
       input: string | URL | Request,
       init?: RequestInit,
     ) => Promise<Response>
+    /** Diagnostics; `acp.send` and `acp.receive` carry each ACP message. */
+    onEvent?: (event: { type: string; message?: unknown }) => void
   }): Promise<FxAgent>
 }

package/src/server.ts

@@ -155,6 +155,15 @@ export type SessionDispatch<D extends EventDefs> = (
 export type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
   dispatch: SessionDispatch<D>
+  /**
+   * Append only while `index` is the session's head, checked in the same
+   * atomic step as the write. Otherwise nothing is written and it throws
+   * `LAST_INDEX_MISMATCH`, with the head as `details.index`.
+   */
+  ifLastIndex(
+    index: number,
+    ...events: AppendInput<D>[]
+  ): Promise<ContractEvent<D>[]>
 }
 
 export type ConsumerAppend<D extends EventDefs> = (
@@ -1395,6 +1404,9 @@ export function createServer<
     })
   }
 
+  /** What the store checks before it writes, inside the append's atomic step. */
+  type AppendCondition = { originIndex?: number; ifLastIndex?: number }
+
   /**
    * Validate + write. `onAppended` runs inside the telemetry span, so
    * the drain it schedules is created in the append's active context —
@@ -1409,7 +1421,7 @@ export function createServer<
     cause?: EventCause,
     generatedIds?: readonly boolean[],
     requireDurableInitialArm = false,
-    originIndex?: number,
+    condition: AppendCondition = {},
   ): Promise<ContractEvent<D>[]> =>
     telemetry.span(
       'a2.append',
@@ -1442,7 +1454,7 @@ export function createServer<
         try {
           const result = await store.append(nsId(sessionId), validated, {
             consumers: storeConsumers,
-            ...(originIndex === undefined ? {} : { originIndex }),
+            ...condition,
           })
           rows = result.events
           // A consumer appending events no consumer takes adds no work, and
@@ -2243,7 +2255,7 @@ export function createServer<
         throw new TypeError('schedule.clear requires an ifLastIndex')
       }
       const { ifLastIndex, ...timing } = clearOptions
-      assertClearIndex(ifLastIndex)
+      assertIfLastIndex(ifLastIndex)
       const dueAt = scheduleDueAt(
         timing as ScheduleTiming,
         triggerCreatedAt ?? Date.now(),
@@ -2848,7 +2860,7 @@ export function createServer<
     attempt: ClearingAttempt | undefined,
   ): Promise<SessionClearResult> => {
     const ifLastIndex = clearOptions?.ifLastIndex
-    if (ifLastIndex !== undefined) assertClearIndex(ifLastIndex)
+    if (ifLastIndex !== undefined) assertIfLastIndex(ifLastIndex)
     const store = await resolveStore()
     if (!store.clear || !store.reclaim) {
       throw new TypeError(
@@ -4077,7 +4089,7 @@ export function createServer<
     mode: 'inline' | 'dispatch',
     events: AppendInput<D>[],
     requireDurableInitialArm = false,
-    originIndex?: number,
+    condition: AppendCondition = {},
   ): Promise<ContractEvent<D>[]> => {
     return appendCore(
       sessionId,
@@ -4088,7 +4100,7 @@ export function createServer<
       undefined,
       undefined,
       requireDurableInitialArm,
-      originIndex,
+      condition,
     )
   }
 
@@ -4100,8 +4112,19 @@ export function createServer<
       appendExternal(id, 'inline', events)
     const appendDispatch = async (...events: AppendInput<D>[]) =>
       appendExternal(id, 'dispatch', events)
+    const appendIfLastIndex = async (
+      index: number,
+      ...events: AppendInput<D>[]
+    ) => {
+      assertIfLastIndex(index)
+      if (events.length === 0) {
+        throw new TypeError('append.ifLastIndex requires at least one event')
+      }
+      return appendExternal(id, 'inline', events, false, { ifLastIndex: index })
+    }
     const append = Object.assign(appendInline, {
       dispatch: appendDispatch,
+      ifLastIndex: appendIfLastIndex,
     }) as SessionAppend<D>
     return Object.assign(makeSession(id, append, null), {
       deadLetters: () => listDeadLetters(id),
@@ -4169,7 +4192,7 @@ export function createServer<
           'inline',
           [...events],
           true,
-          originIndex,
+          originIndex === undefined ? {} : { originIndex },
         )
       } catch (error) {
         // The scheduling consumer's lifetime was cleared: an acknowledged no-op.
@@ -4186,7 +4209,7 @@ export function createServer<
       (await readHistory(sessionId, { gte })).map(toPublic),
     schedulerClear: async (sessionId, ifLastIndex) => {
       assertSessionId(sessionId)
-      assertClearIndex(ifLastIndex)
+      assertIfLastIndex(ifLastIndex)
       await clearSession(sessionId, { ifLastIndex }, undefined)
     },
   })
@@ -4232,7 +4255,7 @@ function assertRedriveIndex(value: number): void {
   }
 }
 
-function assertClearIndex(value: number): void {
+function assertIfLastIndex(value: number): void {
   if (!Number.isSafeInteger(value) || value < 0) {
     throw new TypeError('ifLastIndex must be a non-negative safe integer')
   }

package/src/store-memory.ts

@@ -7,7 +7,12 @@
  */
 
 import type { PresencePatch } from './contract.ts'
-import { A2Error, supersededAttemptError } from './errors.ts'
+import {
+  A2Error,
+  duplicateBatchError,
+  lastIndexMismatchError,
+  supersededAttemptError,
+} from './errors.ts'
 import { idempotentReplay } from './idempotent-replay.ts'
 import { nullProtoRecord } from './internal.ts'
 import { CLEAR_EVENT_TYPE, sessionClearedError } from './session-clear.ts'
@@ -664,6 +669,12 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
         return { events: [], hasPending: hasPending(sessionId, consumers) }
       }
 
+      const ifLastIndex = appendOptions?.ifLastIndex
+      const conditional =
+        ifLastIndex === undefined
+          ? undefined
+          : { sessionId, ifLastIndex, head: headOf(sessions.get(sessionId)) }
+
       // Batch-scoped idempotency (a2-implementation.md §3): all ids
       // already present → lost-ack retry, return the original rows;
       // some present → the caller mixed sent and fresh events.
@@ -671,13 +682,17 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       if (existing.length > 0) {
         if (existing.length === events.length) {
           return {
-            events: idempotentReplay(events, existing.map(toStored)),
+            events: idempotentReplay(
+              events,
+              existing.map(toStored),
+              conditional,
+            ),
             hasPending: hasPending(sessionId, consumers),
           }
         }
-        throw new A2Error(
-          'PARTIAL_DUPLICATE_BATCH',
+        throw duplicateBatchError(
           `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`,
+          conditional,
         )
       }
 
@@ -692,6 +707,13 @@ export function memory(options: MemoryStoreOptions = {}): A2Store {
       for (const event of events) {
         if (event.cause) assertCurrentCause(sessionId, event.cause)
       }
+      if (conditional && conditional.head !== conditional.ifLastIndex) {
+        throw lastIndexMismatchError(
+          sessionId,
+          conditional.ifLastIndex,
+          conditional.head,
+        )
+      }
 
       const inserted = insert(sessionId, events, clock.now(), consumers)
       notifyStreams(sessionId, inserted)