experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/a2slack/c/[channel]/page.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+import { notFound } from 'next/navigation'
+import { channelIdSchema } from '@/app/a2slack/model'
+import { messagePage } from '@/app/a2slack/db/queries'
+import { ChannelView } from '@/app/a2slack/ui/ChannelView'
+
+export default async function ChannelPage({
+  params,
+}: {
+  params: Promise<{ channel: string }>
+}): Promise<ReactNode> {
+  const { channel } = await params
+  if (!channelIdSchema.safeParse(channel).success) notFound()
+
+  // The newest page, read at a log index; the client keeps it live from the
+  // workspace's events after that index.
+  const page = await messagePage(channel)
+
+  return <ChannelView key={channel} channel={channel} page={page} />
+}

package/examples/playground/app/a2slack/consumers/agent.ts

@@ -0,0 +1,63 @@
+/**
+ * The bot. A notification addressed to it wakes it, as vboard's watchers
+ * wake Pi: it consumes the feed through the message, so the feed's tables
+ * have it, reads the whole thread from them, and replies in it. Notifications for one thread wait in
+ * its lane, and a burst of them costs one reply: once the bot has answered
+ * after a message, the rest find nothing new.
+ */
+import 'server-only'
+import { generateText } from 'ai'
+import { consumer } from 'experimental-a2/server'
+import { threadPage } from '../db/queries'
+import { BOT, workspace, type ChatMessage } from '../model'
+import { feed } from './feed'
+
+/** The prompt's last messages: anyone can post, so what one call costs is capped. */
+const PROMPT_MESSAGES = 30
+const PROMPT_CHARACTERS = 12_000
+
+const promptOf = (thread: readonly ChatMessage[]): string => {
+  const lines = thread
+    .filter((message) => !message.deleted)
+    .slice(-PROMPT_MESSAGES)
+    .map((message) => `${message.author.name}: ${message.text}`)
+  let prompt = lines.join('\n')
+  while (prompt.length > PROMPT_CHARACTERS && lines.length > 1) {
+    lines.shift()
+    prompt = lines.join('\n')
+  }
+  return prompt.slice(-PROMPT_CHARACTERS)
+}
+
+export const agent = consumer({
+  contract: workspace,
+  name: 'a2slack-agent',
+  types: ['notification.sent'],
+  lane: ({ event }) =>
+    event.payload.to === BOT.id ? `thread:${event.payload.threadId}` : null,
+}).run(async ({ event, session, signal }) => {
+  const { to, channel, threadId, messageIndex } = event.payload
+  if (to !== BOT.id) return
+  await session.consume(feed, { through: messageIndex, signal })
+  const { root, replies } = await threadPage(threadId)
+  const thread = [root, ...replies].filter((message) => message !== null)
+  if (
+    thread.some(
+      (message) => message.author.id === BOT.id && message.index > messageIndex,
+    )
+  )
+    return
+
+  const { text } = await generateText({
+    model: 'openai/gpt-5.4',
+    instructions: `You are "${BOT.name}", a teammate in a team chat. Someone mentioned you, or replied in a thread you're in. Answer the thread's latest message in a few sentences, plainly. Messages are formatted as "name: text".`,
+    prompt: promptOf(thread),
+    abortSignal: signal,
+  })
+  const reply = text.trim().slice(0, 2000)
+  if (reply === '') return
+  return {
+    type: 'message.posted',
+    payload: { channel, author: BOT, text: reply, threadId },
+  }
+})

package/examples/playground/app/a2slack/consumers/feed.ts

@@ -0,0 +1,164 @@
+/**
+ * The feed: every table a page reads, kept from the whole log, in order,
+ * from the beginning. Each event's transaction first claims it by moving the
+ * feed's position up to it, and skips it when the position has already
+ * reached it, so a retry, or an attempt that lost its claim, changes nothing
+ * and every event lands exactly once. Reads return that position as the
+ * page's `through` (db/queries.ts).
+ */
+import 'server-only'
+import { and, eq, lt, sql } from 'drizzle-orm'
+import { consumer } from 'experimental-a2/server'
+import { database, type Db } from '../db'
+import { FEED } from '../db/queries'
+import {
+  channels,
+  messages,
+  notifications,
+  positions,
+  reactions,
+  reads,
+} from '../db/schema'
+import { WORKSPACE, workspace, type WorkspaceEvent } from '../model'
+
+type Tx = Parameters<Parameters<Db['transaction']>[0]>[0]
+
+async function apply(tx: Tx, event: WorkspaceEvent): Promise<void> {
+  const at = event.createdAt
+  switch (event.type) {
+    case 'channel.created':
+      await tx
+        .insert(channels)
+        .values({
+          id: event.payload.id,
+          createdByName: event.payload.by.name,
+          createdAt: at,
+          logIndex: event.index,
+        })
+        .onConflictDoNothing()
+      return
+    case 'message.posted':
+      await tx.insert(messages).values({
+        id: event.id,
+        channel: event.payload.channel,
+        logIndex: event.index,
+        threadId: event.payload.threadId ?? null,
+        authorId: event.payload.author.id,
+        authorName: event.payload.author.name,
+        text: event.payload.text,
+        postedAt: at,
+      })
+      return
+    case 'message.edited':
+      await tx
+        .update(messages)
+        .set({ text: event.payload.text, editedAt: at })
+        .where(
+          and(
+            eq(messages.id, event.payload.messageId),
+            eq(messages.deleted, false),
+          ),
+        )
+      return
+    case 'message.deleted':
+      await tx
+        .update(messages)
+        .set({ text: '', deleted: true })
+        .where(eq(messages.id, event.payload.messageId))
+      await tx
+        .delete(reactions)
+        .where(eq(reactions.messageId, event.payload.messageId))
+      return
+    case 'reaction.added':
+      await tx
+        .insert(reactions)
+        .values({
+          messageId: event.payload.messageId,
+          emoji: event.payload.emoji,
+          authorId: event.payload.by.id,
+          authorName: event.payload.by.name,
+          logIndex: event.index,
+        })
+        .onConflictDoNothing()
+      return
+    case 'reaction.removed':
+      await tx
+        .delete(reactions)
+        .where(
+          and(
+            eq(reactions.messageId, event.payload.messageId),
+            eq(reactions.emoji, event.payload.emoji),
+            eq(reactions.authorId, event.payload.by.id),
+          ),
+        )
+      return
+    case 'message.labeled':
+      await tx
+        .update(messages)
+        .set({ label: event.payload.label })
+        .where(
+          and(
+            eq(messages.id, event.payload.messageId),
+            eq(messages.deleted, false),
+          ),
+        )
+      return
+    case 'notification.sent':
+      await tx.insert(notifications).values({
+        id: event.id,
+        userId: event.payload.to,
+        threadId: event.payload.threadId,
+        channel: event.payload.channel,
+        reason: event.payload.reason,
+        messageId: event.payload.messageId,
+        fromId: event.payload.from.id,
+        fromName: event.payload.from.name,
+        text: event.payload.text,
+        logIndex: event.index,
+        sentAt: at,
+      })
+      return
+    case 'inbox.read':
+      await tx
+        .insert(reads)
+        .values({
+          userId: event.payload.by,
+          threadId: event.payload.threadId,
+          through: event.payload.through,
+        })
+        .onConflictDoUpdate({
+          target: [reads.userId, reads.threadId],
+          set: { through: sql`greatest(${reads.through}, excluded.through)` },
+        })
+  }
+}
+
+/** Applies `event` unless the feed's position has already reached it. */
+export async function feedEvent(db: Db, event: WorkspaceEvent): Promise<void> {
+  await db.transaction(async (tx) => {
+    // The claim comes first, even for a first event with no row yet: a
+    // concurrent duplicate waits on it, then finds the position caught up.
+    const claimed = await tx
+      .insert(positions)
+      .values({ consumer: FEED, logIndex: event.index })
+      .onConflictDoUpdate({
+        target: positions.consumer,
+        set: { logIndex: event.index },
+        setWhere: lt(positions.logIndex, event.index),
+      })
+      .returning({ logIndex: positions.logIndex })
+    if (claimed.length === 0) return
+    await apply(tx, event)
+  })
+}
+
+export const feed = consumer({
+  contract: workspace,
+  name: FEED,
+  lane: 'feed',
+  backfill: true,
+}).run(async ({ event, session }) => {
+  // One position for the workspace: another session's events would move it.
+  if (session.id !== WORKSPACE) return
+  await feedEvent(await database(), event)
+})

package/examples/playground/app/a2slack/consumers/notify.ts

@@ -0,0 +1,116 @@
+/**
+ * Notify: who should hear about each message. People named with `@name` are
+ * mentioned, and everyone already in the thread hears about a reply. Each
+ * becomes a `notification.sent` event addressed to them, returned so it
+ * commits with notify's progress through the log. People read them in their
+ * inbox; the bot is woken by them (agent.ts).
+ *
+ * Notify keeps its own record of who's in each thread. It reads only what was
+ * recorded before the message, so a retry finds the same people and returns
+ * the same notifications, which A2 keeps once.
+ */
+import 'server-only'
+import { and, eq, inArray, lt, sql } from 'drizzle-orm'
+import { consumer } from 'experimental-a2/server'
+import { database } from '../db'
+import { people, threadMembers } from '../db/schema'
+import { BOT, SYSTEM, workspace, type Reason } from '../model'
+
+/** The lowercase names a message mentions with `@name`. */
+export const mentionedNames = (text: string): string[] => [
+  ...new Set(
+    [...text.matchAll(/(?:^|[^\w@])@([\w-]{1,32})/g)].map(([, name]) =>
+      name!.toLowerCase(),
+    ),
+  ),
+]
+
+/** A notification for a message this old would be news to nobody. */
+const STALE_MS = 60 * 60 * 1000
+
+export const notify = consumer({
+  contract: workspace,
+  name: 'a2slack-notify',
+  types: ['message.posted'],
+  lane: 'notify',
+  backfill: true,
+}).run(async ({ event }) => {
+  const { channel, author, text } = event.payload
+  if (author.id === SYSTEM.id) return
+  const threadId = event.payload.threadId ?? event.id
+  const names = mentionedNames(text)
+  const db = await database()
+
+  const { members, mentioned } = await db.transaction(async (tx) => {
+    const [inThread, named] = await Promise.all([
+      tx
+        .select({ id: threadMembers.personId })
+        .from(threadMembers)
+        .where(
+          and(
+            eq(threadMembers.threadId, threadId),
+            lt(threadMembers.logIndex, event.index),
+          ),
+        ),
+      names.length === 0
+        ? []
+        : tx
+            .select({ id: people.id })
+            .from(people)
+            .where(
+              and(
+                inArray(sql`lower(${people.name})`, names),
+                lt(people.logIndex, event.index),
+              ),
+            ),
+    ])
+    const mentionedIds = [
+      ...named.map((person) => person.id),
+      ...(names.includes(BOT.name) ? [BOT.id] : []),
+    ]
+    await tx
+      .insert(people)
+      .values({ id: author.id, name: author.name, logIndex: event.index })
+      .onConflictDoUpdate({
+        target: people.id,
+        set: {
+          name: author.name,
+          logIndex: sql`least(${people.logIndex}, excluded.log_index)`,
+        },
+      })
+    // The author, and whoever the message names, are in the thread from here.
+    await tx
+      .insert(threadMembers)
+      .values(
+        [author.id, ...mentionedIds].map((personId) => ({
+          threadId,
+          personId,
+          logIndex: event.index,
+        })),
+      )
+      .onConflictDoNothing()
+    return {
+      members: inThread.map((member) => member.id),
+      mentioned: mentionedIds,
+    }
+  })
+
+  if (Date.now() - event.createdAt.getTime() > STALE_MS) return
+  const recipients = new Map<string, Reason>()
+  for (const id of members) recipients.set(id, 'reply')
+  for (const id of mentioned) recipients.set(id, 'mention')
+  recipients.delete(author.id)
+  return [...recipients].map(([to, reason]) => ({
+    type: 'notification.sent' as const,
+    payload: {
+      channel,
+      messageId: event.id,
+      to,
+      reason,
+      threadId,
+      messageIndex: event.index,
+      from: author,
+      text: text.slice(0, 200),
+    },
+  }))
+})

package/examples/playground/app/a2slack/consumers/search.ts

@@ -0,0 +1,37 @@
+/**
+ * Keeps the search index (search-index.ts): one document per message,
+ * rewritten by edits and removed by deletions, from the whole log in order.
+ * Every write sets a document to its event's value, so a retry is harmless.
+ */
+import 'server-only'
+import { consumer } from 'experimental-a2/server'
+import { WORKSPACE, workspace } from '../model'
+import { deleteDocument, putDocument, setDocumentText } from '../search-index'
+
+export const searchIndex = consumer({
+  contract: workspace,
+  name: 'a2slack-search-v1',
+  types: ['message.posted', 'message.edited', 'message.deleted'],
+  lane: 'search',
+  backfill: true,
+}).run(async ({ event, session }) => {
+  // One index for the workspace.
+  if (session.id !== WORKSPACE) return
+  switch (event.type) {
+    case 'message.posted':
+      await putDocument(event.id, {
+        channel: event.payload.channel,
+        threadId: event.payload.threadId ?? '',
+        authorId: event.payload.author.id,
+        authorName: event.payload.author.name,
+        text: event.payload.text,
+        postedAt: event.createdAt.getTime(),
+      })
+      return
+    case 'message.edited':
+      await setDocumentText(event.payload.messageId, event.payload.text)
+      return
+    case 'message.deleted':
+      await deleteDocument(event.payload.messageId)
+  }
+})

package/examples/playground/app/a2slack/consumers/triage.ts

@@ -0,0 +1,31 @@
+/**
+ * Triage labels each top-level message with a model, as vboard's triage
+ * watcher labels threads. The label is a returned event, so it commits with
+ * triage's progress through the log.
+ */
+import 'server-only'
+import { generateText, Output } from 'ai'
+import { consumer } from 'experimental-a2/server'
+import { BOT, LABELS, SYSTEM, workspace } from '../model'
+
+export const triage = consumer({
+  contract: workspace,
+  name: 'a2slack-triage',
+  types: ['message.posted'],
+}).run(async ({ event, signal }) => {
+  const { author, channel, text, threadId } = event.payload
+  if (threadId !== undefined || author.id === SYSTEM.id || author.id === BOT.id)
+    return
+  const { output } = await generateText({
+    model: 'openai/gpt-6-luna-decisions',
+    output: Output.choice({ options: [...LABELS] }),
+    instructions:
+      'Label one message from a team chat channel. question: it asks something. idea: it proposes something. update: it reports news or progress. chatter: anything else.',
+    prompt: text,
+    abortSignal: signal,
+  })
+  return {
+    type: 'message.labeled',
+    payload: { channel, messageId: event.id, label: output },
+  }
+})

package/examples/playground/app/a2slack/consumers/welcome.ts

@@ -0,0 +1,25 @@
+/**
+ * Welcome posts a new channel's opening message, committed with its progress.
+ * The channel list, folded through this event, says whether it's the
+ * channel's first `channel.created`; a second one gets no welcome.
+ */
+import 'server-only'
+import { consumer } from 'experimental-a2/server'
+import { channelsReducer, SYSTEM, workspace } from '../model'
+
+export const welcome = consumer({
+  contract: workspace,
+  name: 'welcome',
+  types: ['channel.created'],
+}).run(async ({ event, session }) => {
+  const { state } = await session.state(channelsReducer)
+  if (state.opened[event.payload.id] !== event.index) return
+  return {
+    type: 'message.posted',
+    payload: {
+      channel: event.payload.id,
+      author: SYSTEM,
+      text: `#${event.payload.id} is open — ${event.payload.by.name} started it.`,
+    },
+  }
+})

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

@@ -0,0 +1,209 @@
+/**
+ * An example: A2's tables for experimental-a2/store-postgres as Drizzle
+ * definitions, the same tables schema.sql next to this file creates. It isn't
+ * an API, and nothing imports it. Use it however fits your setup, for example
+ * as a copy next to your own schema, so your migrations create A2's tables
+ * with yours. Adapt it to your Drizzle version, your ORM, and how you lay out
+ * 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 (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
+ * triggers: add schema.sql's `a2_batch` function, which A2 runs its writes
+ * through, as a custom migration (`drizzle-kit generate --custom`), and the
+ * triggers `listenConnectionString` needs are in notifications.sql.
+ */
+import { sql } from 'drizzle-orm'
+import {
+  bigint,
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  uniqueIndex,
+} from 'drizzle-orm/pg-core'
+
+const int8 = (name: string) => bigint(name, { mode: 'number' })
+
+export const a2Events = pgTable(
+  'a2_events',
+  {
+    sessionId: text('session_id').notNull(),
+    idx: int8('idx').notNull(),
+    eventType: text('event_type').notNull(),
+    payload: jsonb('payload').notNull(),
+    eventId: text('event_id').notNull(),
+    createdAt: int8('created_at').notNull(),
+    cause: jsonb('cause'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_events_pkey',
+      columns: [table.sessionId, table.idx],
+    }),
+    uniqueIndex('a2_events_session_event_id').on(
+      table.sessionId,
+      table.eventId,
+    ),
+    index('a2_events_types').on(table.sessionId, table.eventType, table.idx),
+  ],
+)
+
+/**
+ * One row per run of a cursor: an event cursor's one event, a lane's run of
+ * queued events, or a log cursor's position.
+ */
+export const a2Cursors = pgTable(
+  'a2_cursors',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    epoch: int8('epoch').notNull(),
+    lane: text('lane'),
+    kind: text('kind').notNull(),
+    position: int8('position').notNull(),
+    head: int8('head'),
+    types: jsonb('types'),
+    attemptCount: integer('attempt_count').notNull().default(0),
+    firstClaimedAt: int8('first_claimed_at'),
+    lastClaimedAt: int8('last_claimed_at'),
+    claimHolder: text('claim_holder'),
+    claimExpiresAt: int8('claim_expires_at'),
+    failureCount: integer('failure_count').notNull().default(0),
+    lastFailedAt: int8('last_failed_at'),
+    lastFailedAttempt: integer('last_failed_attempt'),
+    lastError: text('last_error'),
+    failedAt: int8('failed_at'),
+    completedIdx: int8('completed_idx'),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_cursors_pkey',
+      columns: [table.sessionId, table.cursorKey, table.consumer, table.epoch],
+    }),
+    index('a2_cursors_heads')
+      .on(table.sessionId, table.head)
+      .where(sql`head is not null`),
+    index('a2_cursors_lanes')
+      .on(table.sessionId)
+      .where(sql`kind = 'lane'`),
+  ],
+)
+
+/** A lane cursor's queue: the events appended for the lane, in log order. */
+export const a2LaneEvents = pgTable(
+  'a2_lane_events',
+  {
+    sessionId: text('session_id').notNull(),
+    consumer: text('consumer').notNull(),
+    lane: text('lane').notNull(),
+    idx: int8('idx').notNull(),
+    done: boolean('done').notNull().default(false),
+    completedAttempt: integer('completed_attempt'),
+    returnedEventIds: jsonb('returned_event_ids'),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_lane_events_pkey',
+      columns: [table.sessionId, table.consumer, table.lane, table.idx],
+    }),
+  ],
+)
+
+export const a2Snapshots = pgTable(
+  'a2_snapshots',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshots_pkey',
+      columns: [table.sessionId, table.reducerName],
+    }),
+  ],
+)
+
+export const a2SnapshotHistory = pgTable(
+  'a2_snapshot_history',
+  {
+    sessionId: text('session_id').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+    state: jsonb('state').notNull(),
+    updatedAt: int8('updated_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_history_pkey',
+      columns: [table.sessionId, table.reducerName, table.upToIndex],
+    }),
+  ],
+)
+
+export const a2SnapshotPins = pgTable(
+  'a2_snapshot_pins',
+  {
+    sessionId: text('session_id').notNull(),
+    eventIndex: int8('event_index').notNull(),
+    consumer: text('consumer').notNull(),
+    cursorKey: text('cursor_key').notNull(),
+    reducerName: text('reducer_name').notNull(),
+    upToIndex: int8('up_to_index').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_snapshot_pins_pkey',
+      columns: [
+        table.sessionId,
+        table.eventIndex,
+        table.consumer,
+        table.cursorKey,
+        table.reducerName,
+        table.upToIndex,
+      ],
+    }),
+    index('a2_snapshot_pins_checkpoint').on(
+      table.sessionId,
+      table.reducerName,
+      table.upToIndex,
+    ),
+  ],
+)
+
+export const a2Clears = pgTable('a2_clears', {
+  sessionId: text('session_id').primaryKey(),
+  clearIndex: int8('clear_index').notNull(),
+})
+
+export const a2Presence = pgTable(
+  'a2_presence',
+  {
+    ns: text('ns').notNull(),
+    participant: text('participant').notNull(),
+    field: text('field').notNull(),
+    value: jsonb('value').notNull(),
+    seen: int8('seen').notNull(),
+    at: int8('at').notNull(),
+    expiresAt: int8('expires_at').notNull(),
+  },
+  (table) => [
+    primaryKey({
+      name: 'a2_presence_pkey',
+      columns: [table.ns, table.participant, table.field],
+    }),
+  ],
+)