experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/a2slack/model.test.ts

@@ -0,0 +1,208 @@
+import type { ContractEvent } from 'experimental-a2'
+import { describe, expect, it } from 'vitest'
+import {
+  channelsReducer,
+  liveInbox,
+  liveMessages,
+  liveThread,
+  toMessage,
+  workspace,
+  type Author,
+  type InboxPage,
+  type MessagePage,
+  type WorkspaceEvent,
+} from './model'
+
+type Events = typeof workspace.events
+
+const ada: Author = { id: 'user-1', name: 'ada' }
+const bob: Author = { id: 'user-2', name: 'bob' }
+
+const event = <K extends keyof Events & string>(
+  index: number,
+  type: K,
+  payload: ContractEvent<Events, K>['payload'],
+): ContractEvent<Events, K> =>
+  ({
+    id: `event-${index}`,
+    type,
+    payload,
+    index,
+    sessionId: 'workspace',
+    createdAt: new Date(index * 1_000),
+  }) as ContractEvent<Events, K>
+
+const posted = (
+  index: number,
+  text: string,
+  extra: { channel?: string; threadId?: string; author?: Author } = {},
+) =>
+  event(index, 'message.posted', {
+    channel: extra.channel ?? 'general',
+    author: extra.author ?? ada,
+    text,
+    ...(extra.threadId === undefined ? {} : { threadId: extra.threadId }),
+  })
+
+/** The page a read at `through` would return: the log up to it, folded. */
+const pageOf = (events: WorkspaceEvent[], through: number): MessagePage => ({
+  messages: liveMessages(
+    { messages: [], through: 0, more: false },
+    events.filter((e) => e.index <= through),
+    { channel: 'general', append: true },
+  ),
+  through,
+  more: false,
+})
+
+describe('channelsReducer', () => {
+  it('lists channels once, in creation order', () => {
+    const state = [
+      event(1, 'channel.created', { id: 'general', by: ada }),
+      event(2, 'channel.created', { id: 'random', by: bob }),
+      event(3, 'channel.created', { id: 'general', by: bob }),
+    ].reduce(
+      (folded, e) => channelsReducer.fold(folded, e),
+      channelsReducer.initialState,
+    )
+    expect(state.channels).toEqual(['general', 'random'])
+  })
+})
+
+describe('liveMessages', () => {
+  const log = [
+    posted(1, 'hello'),
+    posted(2, 'elsewhere', { channel: 'random' }),
+    posted(3, 'a reply', { threadId: 'event-1', author: bob }),
+    event(4, 'reaction.added', {
+      channel: 'general',
+      messageId: 'event-1',
+      emoji: '👍',
+      by: bob,
+    }),
+    posted(5, 'second'),
+    event(6, 'message.edited', {
+      channel: 'general',
+      messageId: 'event-5',
+      text: 'second, edited',
+      by: ada,
+    }),
+    event(7, 'message.labeled', {
+      channel: 'general',
+      messageId: 'event-1',
+      label: 'question',
+    }),
+  ]
+
+  it('applies only the events after the page, to its own channel', () => {
+    for (const through of [0, 1, 3, 5, 7]) {
+      const live = liveMessages(pageOf(log, through), log, {
+        channel: 'general',
+        append: true,
+      })
+      // Wherever the page was read, the result is the same.
+      expect(live).toEqual(pageOf(log, 7).messages)
+    }
+    expect(pageOf(log, 7).messages).toMatchObject([
+      {
+        text: 'hello',
+        replyCount: 1,
+        label: 'question',
+        reactions: [{ emoji: '👍', by: [bob] }],
+      },
+      { text: 'second, edited', editedAt: new Date(6_000).toISOString() },
+    ])
+  })
+
+  it('leaves new messages off an older page, but keeps its messages live', () => {
+    const older: MessagePage = {
+      messages: [toMessage(posted(1, 'hello'))],
+      through: 1,
+      more: true,
+    }
+    expect(
+      liveMessages(older, log, { channel: 'general', append: false }),
+    ).toMatchObject([{ text: 'hello', replyCount: 1, label: 'question' }])
+  })
+})
+
+describe('liveThread', () => {
+  it('adds replies after the page once, and decorates them', () => {
+    const page = {
+      root: toMessage(posted(1, 'root')),
+      replies: [toMessage(posted(2, 'first', { threadId: 'event-1' }))],
+      through: 2,
+    }
+    const live = liveThread(
+      page,
+      [
+        posted(2, 'first', { threadId: 'event-1' }),
+        posted(3, 'second', { threadId: 'event-1', author: bob }),
+        posted(4, 'not this thread', { threadId: 'event-9' }),
+        event(5, 'message.deleted', {
+          channel: 'general',
+          messageId: 'event-2',
+          by: ada,
+        }),
+      ],
+      'event-1',
+    )
+    expect(live.root).toMatchObject({ replyCount: 1 })
+    expect(live.replies.map((m) => [m.text, m.deleted ?? false])).toEqual([
+      ['', true],
+      ['second', false],
+    ])
+  })
+})
+
+describe('liveThread, opened before the feed has its root', () => {
+  it('adopts the root and its replies as they arrive', () => {
+    const page = { root: null, replies: [], through: 0 }
+    const live = liveThread(
+      page,
+      [
+        posted(1, 'root'),
+        posted(2, 'first', { threadId: 'event-1' }),
+        posted(3, 'elsewhere', { threadId: 'event-9' }),
+      ],
+      'event-1',
+    )
+    expect(live.root).toMatchObject({ text: 'root', replyCount: 1 })
+    expect(live.replies.map((m) => m.text)).toEqual(['first'])
+  })
+})
+
+describe('liveInbox', () => {
+  const notification = (index: number, to: string, threadId: string) =>
+    event(index, 'notification.sent', {
+      channel: 'general',
+      messageId: `m-${index}`,
+      to,
+      reason: 'reply',
+      threadId,
+      messageIndex: index - 1,
+      from: bob,
+      text: `news ${index}`,
+    })
+
+  it('raises a thread for each notification to me, and clears it on read', () => {
+    const page: InboxPage = { items: [], through: 0 }
+    const events = [
+      notification(1, ada.id, 't1'),
+      notification(2, bob.id, 't1'),
+      notification(3, ada.id, 't2'),
+      notification(4, ada.id, 't1'),
+      event(5, 'inbox.read', { by: ada.id, threadId: 't2', through: 3 }),
+    ]
+    expect(
+      liveInbox(page, events, ada.id).map(({ threadId, text, unread }) => [
+        threadId,
+        text,
+        unread,
+      ]),
+    ).toEqual([
+      ['t1', 'news 4', 2],
+      ['t2', 'news 3', 0],
+    ])
+  })
+})

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

@@ -0,0 +1,369 @@
+/**
+ * a2slack's contract, and how the client keeps a page live.
+ *
+ * The whole workspace is one A2 session, as vboard's board is: every
+ * channel's messages, reactions, labels, and notifications are events in one
+ * log. Nothing folds that log into one big state. Consumers build tables from
+ * it (server/), every read comes from those tables, and a page read at log
+ * index `through` stays live by applying the events after `through`, with
+ * the functions below.
+ */
+import { z } from 'zod'
+import { contract, reducer, type ContractEvent } from 'experimental-a2'
+
+/** The feed writes these to Postgres, whose text can't hold NUL: refused at the door. */
+const text = () =>
+  z.string().refine((value) => !value.includes('\u0000'), 'contains NUL')
+
+export const authorSchema = z.object({
+  id: text().min(1).max(64),
+  name: text().min(1).max(32),
+})
+
+export type Author = z.output<typeof authorSchema>
+
+export const channelIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/)
+
+/** The one session the workspace is. */
+export const WORKSPACE = 'workspace'
+
+/** Posts each channel's opening message. */
+export const SYSTEM: Author = { id: 'system', name: 'system' }
+
+/** The bot: `@bot` notifies it, and so does a reply in a thread it's in. */
+export const BOT: Author = { id: 'a2slack-bot', name: 'bot' }
+
+const messageText = text().min(1).max(2000)
+
+/** What triage calls a channel's top-level message. */
+export const LABELS = ['question', 'idea', 'update', 'chatter'] as const
+
+export const labelSchema = z.enum(LABELS)
+
+export type Label = z.output<typeof labelSchema>
+
+/** Why someone was notified: named in the message, or in its thread. */
+export const REASONS = ['mention', 'reply'] as const
+
+export type Reason = (typeof REASONS)[number]
+
+/** A message's id, which is its post's event id: a UUID. Postgres indexes it, so it's capped. */
+const messageId = () => text().max(64)
+
+const ref = { channel: channelIdSchema, messageId: messageId() }
+
+const a2slack = contract({
+  name: 'a2slack',
+  events: {
+    'channel.created': z.object({ id: channelIdSchema, by: authorSchema }),
+    'message.posted': z.object({
+      channel: channelIdSchema,
+      author: authorSchema,
+      text: messageText,
+      threadId: messageId().optional(),
+    }),
+    'message.edited': z.object({ ...ref, text: messageText, by: authorSchema }),
+    'message.deleted': z.object({ ...ref, by: authorSchema }),
+    'reaction.added': z.object({
+      ...ref,
+      emoji: text().min(1).max(8),
+      by: authorSchema,
+    }),
+    'reaction.removed': z.object({
+      ...ref,
+      emoji: text().min(1).max(8),
+      by: authorSchema,
+    }),
+    'message.labeled': z.object({ ...ref, label: labelSchema }),
+    /** A message someone should hear about, addressed to them. */
+    'notification.sent': z.object({
+      ...ref,
+      to: authorSchema.shape.id,
+      reason: z.enum(REASONS),
+      threadId: messageId(),
+      messageIndex: z.number().int().positive(),
+      from: authorSchema,
+      text: text(),
+    }),
+    /** `by` has seen a thread's notifications through log index `through`. */
+    'inbox.read': z.object({
+      by: authorSchema.shape.id,
+      threadId: messageId(),
+      through: z.number().int().nonnegative(),
+    }),
+  },
+  presence: {
+    typing: z.object({ name: z.string().min(1).max(32), channel: z.string() }),
+  },
+})
+
+export type WorkspaceEvent = ContractEvent<typeof a2slack.events>
+
+const reactionSchema = z.object({
+  emoji: z.string(),
+  by: z.array(authorSchema),
+})
+
+export type Reaction = z.output<typeof reactionSchema>
+
+export type ChatMessage = {
+  id: string
+  index: number
+  channel: string
+  author: Author
+  text: string
+  at: string
+  editedAt?: string
+  deleted?: boolean
+  reactions: Reaction[]
+  threadId?: string
+  replyCount: number
+  lastReplyAt?: string
+  label?: Label
+}
+
+/** A channel's top-level messages, oldest first, read at log index `through`. */
+export type MessagePage = {
+  messages: ChatMessage[]
+  through: number
+  /** Older messages exist before this page. */
+  more: boolean
+}
+
+/** A thread's root and replies, oldest first, read at log index `through`. */
+export type ThreadPage = {
+  root: ChatMessage | null
+  replies: ChatMessage[]
+  through: number
+}
+
+/** One thread with news for someone: its latest notification, and how many are unread. */
+export type InboxItem = {
+  threadId: string
+  channel: string
+  reason: Reason
+  from: Author
+  text: string
+  messageId: string
+  at: string
+  /** The latest notification's log index. */
+  index: number
+  unread: number
+}
+
+export type InboxPage = { items: InboxItem[]; through: number }
+
+/** One hit from the search route. */
+export type SearchResult = {
+  channel: string
+  id: string
+  threadId?: string
+  author: Author
+  text: string
+  at: string
+}
+
+const channelsState = z.object({
+  channels: z.array(z.string()),
+  /** The log index each channel was first created at. */
+  opened: z.record(z.string(), z.number()),
+})
+
+/**
+ * The channel list: the one state anything folds whole, because it stays
+ * small. The client folds it live; welcome reads `opened` to tell a new
+ * channel from one created twice. Re-applying a `channel.created` changes
+ * nothing, so a page may hand it events it already reflects.
+ */
+export const channelsReducer = reducer({
+  contract: a2slack,
+  name: 'channels',
+  initialState: { channels: [], opened: {} },
+  stateSchema: channelsState,
+}).fold((state, event) => {
+  if (event.type !== 'channel.created') return state
+  if (state.channels.includes(event.payload.id)) return state
+  return {
+    channels: [...state.channels, event.payload.id],
+    opened: { ...state.opened, [event.payload.id]: event.index },
+  }
+})
+
+export const workspace = { ...a2slack, reducer: channelsReducer }
+
+export function toMessage(
+  event: ContractEvent<typeof a2slack.events, 'message.posted'>,
+): ChatMessage {
+  return {
+    id: event.id,
+    index: event.index,
+    channel: event.payload.channel,
+    author: event.payload.author,
+    text: event.payload.text,
+    at: event.createdAt.toISOString(),
+    reactions: [],
+    replyCount: 0,
+    ...(event.payload.threadId !== undefined
+      ? { threadId: event.payload.threadId }
+      : {}),
+  }
+}
+
+/** Applies an edit, deletion, label, or reaction; the same message otherwise. */
+export function decorate(
+  message: ChatMessage,
+  event: WorkspaceEvent,
+): ChatMessage {
+  switch (event.type) {
+    case 'message.edited':
+      if (event.payload.messageId !== message.id || message.deleted)
+        return message
+      return {
+        ...message,
+        text: event.payload.text,
+        editedAt: event.createdAt.toISOString(),
+      }
+    case 'message.deleted':
+      if (event.payload.messageId !== message.id) return message
+      return { ...message, deleted: true, text: '', reactions: [] }
+    case 'message.labeled':
+      if (event.payload.messageId !== message.id || message.deleted)
+        return message
+      return { ...message, label: event.payload.label }
+    case 'reaction.added': {
+      if (event.payload.messageId !== message.id || message.deleted)
+        return message
+      const { emoji, by } = event.payload
+      const existing = message.reactions.find((r) => r.emoji === emoji)
+      if (existing?.by.some((a) => a.id === by.id)) return message
+      const reactions = existing
+        ? message.reactions.map((r) =>
+            r.emoji === emoji ? { ...r, by: [...r.by, by] } : r,
+          )
+        : [...message.reactions, { emoji, by: [by] }]
+      return { ...message, reactions }
+    }
+    case 'reaction.removed': {
+      if (event.payload.messageId !== message.id) return message
+      const { emoji, by } = event.payload
+      const reactions = message.reactions
+        .map((r) =>
+          r.emoji === emoji
+            ? { ...r, by: r.by.filter((a) => a.id !== by.id) }
+            : r,
+        )
+        .filter((r) => r.by.length > 0)
+      return { ...message, reactions }
+    }
+    default:
+      return message
+  }
+}
+
+/** The events after `through`, in log order. */
+const after = (
+  events: readonly WorkspaceEvent[],
+  through: number,
+): WorkspaceEvent[] =>
+  events
+    .filter((event) => event.index > through)
+    .toSorted((a, b) => a.index - b.index)
+
+/** A reply's effect on its root: one more reply, and when the last one was. */
+const bump = (root: ChatMessage, reply: ChatMessage): ChatMessage => ({
+  ...root,
+  replyCount: root.replyCount + 1,
+  lastReplyAt: reply.at,
+})
+
+/**
+ * A page of `channel`'s top-level messages, live: the events after the page
+ * edit, react to, label, and reply to its messages. With `append`, the
+ * newest page, top-level messages posted after it join the end.
+ */
+export function liveMessages(
+  page: MessagePage,
+  events: readonly WorkspaceEvent[],
+  { channel, append }: { channel: string; append: boolean },
+): ChatMessage[] {
+  let messages = page.messages
+  for (const event of after(events, page.through)) {
+    if (!('channel' in event.payload) || event.payload.channel !== channel)
+      continue
+    if (event.type === 'message.posted') {
+      const posted = toMessage(event)
+      const rootId = posted.threadId
+      if (rootId !== undefined) {
+        messages = messages.map((m) => (m.id === rootId ? bump(m, posted) : m))
+      } else if (append && !messages.some((m) => m.id === posted.id)) {
+        messages = [...messages, posted]
+      }
+      continue
+    }
+    messages = messages.map((m) => decorate(m, event))
+  }
+  return messages
+}
+
+/** A thread, live: replies posted after the page join it, and edits apply. */
+export function liveThread(
+  page: ThreadPage,
+  events: readonly WorkspaceEvent[],
+  rootId: string,
+): { root: ChatMessage | null; replies: ChatMessage[] } {
+  let { root, replies } = page
+  for (const event of after(events, page.through)) {
+    if (event.type === 'message.posted') {
+      // A root the feed hadn't applied when the page was read.
+      if (event.id === rootId && root === null) {
+        root = toMessage(event)
+        for (const reply of replies) root = bump(root, reply)
+        continue
+      }
+      if (event.payload.threadId !== rootId) continue
+      const reply = toMessage(event)
+      if (replies.some((m) => m.id === reply.id)) continue
+      replies = [...replies, reply]
+      if (root) root = bump(root, reply)
+      continue
+    }
+    if (root) root = decorate(root, event)
+    replies = replies.map((m) => decorate(m, event))
+  }
+  return { root, replies }
+}
+
+/** `me`'s inbox, live: new notifications raise a thread, and reads clear it. */
+export function liveInbox(
+  page: InboxPage,
+  events: readonly WorkspaceEvent[],
+  me: string,
+): InboxItem[] {
+  let items = page.items
+  for (const event of after(events, page.through)) {
+    if (event.type === 'notification.sent' && event.payload.to === me) {
+      const { threadId } = event.payload
+      const previous = items.find((item) => item.threadId === threadId)
+      const item: InboxItem = {
+        threadId,
+        channel: event.payload.channel,
+        reason: event.payload.reason,
+        from: event.payload.from,
+        text: event.payload.text,
+        messageId: event.payload.messageId,
+        at: event.createdAt.toISOString(),
+        index: event.index,
+        unread: (previous?.unread ?? 0) + 1,
+      }
+      items = [item, ...items.filter((other) => other.threadId !== threadId)]
+    } else if (event.type === 'inbox.read' && event.payload.by === me) {
+      const { threadId, through } = event.payload
+      items = items.map((item) =>
+        item.threadId === threadId && item.index <= through
+          ? { ...item, unread: 0 }
+          : item,
+      )
+    }
+  }
+  return items
+}

package/examples/playground/app/a2slack/models.test.ts

@@ -0,0 +1,72 @@
+import { MockLanguageModelV4 } from 'ai/test'
+import { beforeEach, expect, it, vi } from 'vitest'
+
+// Triage and the bot run only where AI Gateway is reachable; these models
+// stand in for the two they call.
+vi.hoisted(() => {
+  process.env.AI_GATEWAY_API_KEY = 'test'
+})
+
+const { threadPage } = await import('./db/queries')
+const { BOT, WORKSPACE } = await import('./model')
+const { a2slackServer } = await import('./server')
+
+const usage = {
+  inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
+  outputTokens: { total: 1, text: 1, reasoning: 0 },
+}
+
+const prompts: Record<string, string[]> = {}
+
+/** A model that answers every call with `text`, recording its prompts. */
+const answering = (id: string, text: string) =>
+  new MockLanguageModelV4({
+    modelId: id,
+    doGenerate: async (options) => {
+      ;(prompts[id] ??= []).push(JSON.stringify(options.prompt))
+      return {
+        content: [{ type: 'text', text }],
+        finishReason: { unified: 'stop', raw: 'stop' },
+        usage,
+        warnings: [],
+      }
+    },
+  })
+
+beforeEach(() => {
+  const models = {
+    'openai/gpt-6-luna-decisions': answering(
+      'openai/gpt-6-luna-decisions',
+      '{"result":"question"}',
+    ),
+    'openai/gpt-5.4': answering('openai/gpt-5.4', 'ask ada, she owns it.'),
+  }
+  vi.stubGlobal('AI_SDK_DEFAULT_PROVIDER', {
+    specificationVersion: 'v4',
+    languageModel: (id: keyof typeof models) => models[id],
+  })
+})
+
+const room = a2slackServer.session(WORKSPACE)
+const ada = { id: 'user-1', name: 'ada' }
+
+it('wakes the bot when someone mentions it, and it answers in the thread', async () => {
+  const [asked] = await room.append({
+    type: 'message.posted',
+    payload: { channel: 'bot', author: ada, text: '@bot who owns the deploy?' },
+  })
+
+  await vi.waitFor(
+    async () => {
+      const { replies } = await threadPage(asked!.id)
+      expect(replies.map(({ author, text }) => [author.name, text])).toEqual([
+        [BOT.name, 'ask ada, she owns it.'],
+      ])
+    },
+    { timeout: 10_000 },
+  )
+  expect(prompts['openai/gpt-5.4']).toHaveLength(1)
+  expect(prompts['openai/gpt-5.4']![0]).toContain(
+    'ada: @bot who owns the deploy?',
+  )
+})

package/examples/playground/app/a2slack/page.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react'
+
+export default function HomePage(): ReactNode {
+  return (
+    <div className="a2slack-empty">
+      <p className="a2slack-empty-title">a2slack</p>
+      <p className="a2slack-empty-hint">pick a channel — or start one</p>
+    </div>
+  )
+}

package/examples/playground/app/a2slack/scheduler/route.ts

@@ -0,0 +1,5 @@
+import { a2slackScheduler, a2slackServer } from '../server'
+
+export const POST =
+  a2slackScheduler?.handler(a2slackServer) ??
+  (() => new Response('a2slack scheduler is not configured', { status: 503 }))

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

@@ -0,0 +1,40 @@
+import { A2Error } from 'experimental-a2'
+import { feed } from '../consumers/feed'
+import { searchIndex } from '../consumers/search'
+import { WORKSPACE } from '../model'
+import { hasSearchIndex, indexed, search } from '../search-index'
+import { a2slackServer } from '../server'
+
+const ms = (from: number, to: number): string => (to - from).toFixed(0)
+
+/** Searches every channel's messages. */
+export async function GET(request: Request): Promise<Response> {
+  const q = new URL(request.url).searchParams.get('q')?.trim() ?? ''
+  if (q.length === 0) return Response.json({ results: [] })
+  // The index fills in the background after each message. Catch it up first,
+  // and let Upstash finish indexing, so a message posted a moment ago is found.
+  const started = performance.now()
+  await a2slackServer
+    .session(WORKSPACE)
+    .consume(hasSearchIndex ? searchIndex : feed, { signal: request.signal })
+    .catch((error: unknown) => {
+      // A message the index gave up on leaves the rest searchable.
+      if (!(
+        error instanceof A2Error && error.code === 'CONSUMER_DEAD_LETTERED'
+      ))
+        throw error
+    })
+  const consumed = performance.now()
+  await indexed()
+  const waited = performance.now()
+  const results = await search(q.slice(0, 200))
+  const done = performance.now()
+  return Response.json(
+    { results },
+    {
+      headers: {
+        'server-timing': `consume;dur=${ms(started, consumed)}, indexing;dur=${ms(consumed, waited)}, query;dur=${ms(waited, done)}`,
+      },
+    },
+  )
+}