experimental-a2 0.21.1 → 0.22.0

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

@@ -29,6 +29,13 @@
       "when": 1792282388330,
       "tag": "0003_a2_batch",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1792693132589,
+      "tag": "0004_a2_session_event_ids",
+      "breakpoints": true
     }
   ]
-}
+}

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

@@ -136,8 +136,8 @@ const forwardToAgent = consumer({
       ? 'mention'
       : 'passive'
   const message: ChatAgentMessage = {
-    // Event ids are unique across a store's sessions, so the forward
-    // derives its own; a retried forward converges on the same id.
+    // Derived from the room event's id, so a retried forward converges on
+    // the same message in the agent's session.
     id: await idempotentId('chat.message', context.event.id),
     role: 'user',
     metadata: {

package/examples/playground/lib/store.ts

@@ -9,7 +9,7 @@ const postgresUrl = process.env.DATABASE_URL?.replace(
 )
 
 export const store: RedisStore | PostgresStore | undefined = redisUrl
-  ? redis({ url: redisUrl })
+  ? redis({ url: redisUrl, keyPrefix: 'a2-playground-tagged' })
   : postgresUrl
     ? postgres({ connectionString: postgresUrl })
     : undefined

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.21.1",
+    "experimental-a2": "0.22.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.21.1",
+  "version": "0.22.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",

package/sql/postgres/drizzle-schema.ts

@@ -7,9 +7,9 @@
  * your schema.
  *
  * Whatever creates them, A2 relies on the table and column names, the column
- * types, the primary keys, and the unique index on a2_events.event_id. The
- * other indexes keep its queries fast. Every name is spelled out, so Drizzle's
- * `casing` setting changes none of them.
+ * types, the primary keys, and the unique index on a2_events (session_id,
+ * event_id). The other indexes keep its queries fast. Every name is spelled
+ * out, so Drizzle's `casing` setting changes none of them.
  *
  * A2's tables change only when a release's changelog says so; compare your
  * copy with that release's file. Drizzle can't declare functions or
@@ -48,7 +48,10 @@ export const a2Events = pgTable(
       name: 'a2_events_pkey',
       columns: [table.sessionId, table.idx],
     }),
-    uniqueIndex('a2_events_event_id').on(table.eventId),
+    uniqueIndex('a2_events_session_event_id').on(
+      table.sessionId,
+      table.eventId,
+    ),
     index('a2_events_types').on(table.sessionId, table.eventType, table.idx),
   ],
 )

package/sql/postgres/schema.sql

@@ -254,9 +254,6 @@ end $$;
 --> statement-breakpoint
 
 do $$ begin
-  if to_regclass('a2_events_event_id') is null then
-    create unique index if not exists a2_events_event_id on a2_events (event_id);
-  end if;
   if to_regclass('a2_events_types') is null then
     create index if not exists a2_events_types
       on a2_events (session_id, event_type, idx);
@@ -274,3 +271,27 @@ do $$ begin
       on a2_snapshot_pins (session_id, reducer_name, up_to_index);
   end if;
 end $$;
+--> statement-breakpoint
+
+-- Event ids are unique per session, through the index on (session_id,
+-- event_id). It replaces a2_events_event_id, on event_id alone. The swap
+-- locks the table before it builds, so it waits for running queries instead
+-- of deadlocking with a writer when the whole file runs as one transaction.
+-- The old index goes only once the new one is valid, so a session's ids
+-- always have a unique index.
+do $$ begin
+  if to_regclass('a2_events_session_event_id') is null then
+    if to_regclass('a2_events_event_id') is not null then
+      lock table a2_events in access exclusive mode;
+    end if;
+    create unique index if not exists a2_events_session_event_id
+      on a2_events (session_id, event_id);
+  end if;
+  if to_regclass('a2_events_event_id') is not null and exists (
+    select 1 from pg_index
+     where indexrelid = to_regclass('a2_events_session_event_id')
+       and indisvalid and indisunique
+  ) then
+    drop index a2_events_event_id;
+  end if;
+end $$;

package/src/actor-shared.ts

@@ -131,7 +131,11 @@ export type ActorScheduleSend<E> = {
 export type ActorContext<D extends ActorProtocol> = {
   /** Mutable draft, committed atomically with the handler's completion. */
   state: D['state']
-  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  /**
+   * The message id — stable across re-runs and unique within the instance;
+   * the idempotency key for external I/O. An explicit send id that repeats
+   * in another instance repeats here too.
+   */
   id: string
   /** Durable 1-based dispatch ordinal of this message. */
   attempt: number
@@ -150,7 +154,11 @@ export type ActorContext<D extends ActorProtocol> = {
  * whose serial handlers decide against fresh state.
  */
 export type ActorConcurrentContext<D extends ActorProtocol> = {
-  /** The message id — stable across re-runs; the idempotency key for external I/O. */
+  /**
+   * The message id — stable across re-runs and unique within the instance;
+   * the idempotency key for external I/O. An explicit send id that repeats
+   * in another instance repeats here too.
+   */
   id: string
   /** Durable 1-based dispatch ordinal of this message. */
   attempt: number

package/src/ai-agent.ts

@@ -75,6 +75,7 @@ import type {
 import { A2Error } from './errors.ts'
 import {
   consumeSchedulerSendFailure,
+  drainSettledHooks,
   failedPreviousAttempt,
   installAmbientToolScopeStorage,
   type AmbientToolScope,
@@ -2148,6 +2149,7 @@ export function createConsumers<
       const source =
         harness !== undefined
           ? await harness.step({
+              scope: states,
               agentName: options.contract.name,
               sessionId: ctx.event.sessionId,
               requestIndex: ctx.event.index,
@@ -2556,6 +2558,17 @@ export function agent(
     consumers: [...builtIns, ...(serverOptions.consumers ?? [])],
   })
   registerHarnessStates(server, states)
+  const driver =
+    harness === undefined || harness.type === 'ai-sdk'
+      ? undefined
+      : harnessDriver(harness)
+  const release = driver?.release
+  // What a harness kept for a session's next step goes once nothing is left
+  // to run for the session here.
+  if (release !== undefined)
+    drainSettledHooks.set(server, (sessionId) =>
+      release({ scope: states, sessionId }),
+    )
   const applicationEvents = 'contract' in rest
   setServerFetchHooks(server, {
     validateIngress: (context) =>