experimental-a2 0.8.0 → 0.9.0

package/examples/playground/app/chat/[chatId]/chat-view.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import type { AgentPost, ChatAgentMessage, ChatMessage } from '../model'
+import {
+  buildChatTranscript,
+  selectAgentStream,
+  shouldGroupMessage,
+} from './chat-view'
+
+const participant = (
+  index: number,
+  author: string,
+  at: string,
+): ChatMessage => ({
+  id: `message-${index}`,
+  index,
+  author,
+  text: `message ${index}`,
+  at,
+})
+
+const post = (
+  index: number,
+  responseMessageId: string,
+  at: string,
+): AgentPost => ({
+  generationId: `generation-${index}`,
+  responseMessageId,
+  toolCallId: `call-${index}`,
+  index,
+  text: `post ${index}`,
+  at,
+})
+
+describe('chat transcript view', () => {
+  it('groups only adjacent messages from the same author within 60 seconds', () => {
+    const transcript = buildChatTranscript(
+      [
+        participant(6, 'lovelace', '2026-08-16T12:01:04.000Z'),
+        participant(1, 'lovelace', '2026-08-16T11:59:59.000Z'),
+        participant(5, 'lovelace', '2026-08-16T12:00:04.000Z'),
+        participant(2, 'lovelace', '2026-08-16T12:00:01.000Z'),
+      ],
+      [
+        post(4, 'assistant-2', '2026-08-16T12:00:03.000Z'),
+        post(3, 'assistant-1', '2026-08-16T12:00:02.000Z'),
+      ],
+    )
+
+    expect(transcript.map((entry) => entry.index)).toEqual([1, 2, 3, 4, 5, 6])
+    expect(
+      transcript.map(({ author, showHeader }) => ({ author, showHeader })),
+    ).toEqual([
+      { author: 'lovelace', showHeader: true },
+      { author: 'lovelace', showHeader: false },
+      { author: 'agent', showHeader: true },
+      { author: 'agent', showHeader: false },
+      { author: 'lovelace', showHeader: true },
+      { author: 'lovelace', showHeader: true },
+    ])
+  })
+
+  it('does not group different authors, invalid time, or reversed time', () => {
+    const at = '2026-08-16T12:00:00.000Z'
+    expect(
+      shouldGroupMessage(
+        { kind: 'participant', author: 'lovelace', at },
+        { kind: 'participant', author: 'hopper', at },
+      ),
+    ).toBe(false)
+    expect(
+      shouldGroupMessage(
+        { kind: 'participant', author: 'lovelace', at },
+        { kind: 'participant', author: 'lovelace', at: 'not-a-date' },
+      ),
+    ).toBe(false)
+    expect(
+      shouldGroupMessage(
+        { kind: 'participant', author: 'lovelace', at },
+        {
+          kind: 'participant',
+          author: 'lovelace',
+          at: '2026-08-16T11:59:59.999Z',
+        },
+      ),
+    ).toBe(false)
+  })
+
+  it('does not group a participant named agent with the AI agent', () => {
+    const transcript = buildChatTranscript(
+      [participant(1, 'agent', '2026-08-16T12:00:00.000Z')],
+      [post(2, 'assistant-1', '2026-08-16T12:00:01.000Z')],
+    )
+
+    expect(transcript.map(({ showHeader }) => showHeader)).toEqual([true, true])
+  })
+})
+
+describe('agent stream selection', () => {
+  const firstParts: ChatAgentMessage['parts'] = [
+    { type: 'step-start' },
+    { type: 'reasoning', text: 'Consider whether a post helps.' },
+    {
+      type: 'tool-post',
+      toolCallId: 'call-1',
+      state: 'output-available',
+      input: { message: 'A useful reply' },
+      output: { posted: true },
+    },
+    { type: 'text', text: 'Private continuation' },
+  ]
+  const first: ChatAgentMessage = {
+    id: 'assistant-1',
+    role: 'assistant',
+    metadata: {
+      kind: 'agent',
+      author: 'agent',
+      mode: 'mention',
+      steps: [],
+    },
+    parts: firstParts,
+  }
+  const second: ChatAgentMessage = {
+    id: 'assistant-2',
+    role: 'assistant',
+    metadata: {
+      kind: 'agent',
+      author: 'agent',
+      mode: 'ambient',
+      steps: [],
+    },
+    parts: [{ type: 'text', text: 'A different response' }],
+  }
+
+  it('returns the exact response message with all parts in stream order', () => {
+    const selection = selectAgentStream([second, first], first.id)
+
+    expect(selection).toEqual({
+      message: first,
+      parts: firstParts,
+      metadata: first.metadata,
+    })
+    expect(selection?.message).toBe(first)
+    expect(selection?.parts).toBe(firstParts)
+  })
+
+  it('isolates response ids and returns null when the response is absent', () => {
+    expect(selectAgentStream([first, second], second.id)?.parts).toEqual([
+      { type: 'text', text: 'A different response' },
+    ])
+    expect(selectAgentStream([first, second], 'assistant-missing')).toBeNull()
+  })
+})

package/examples/playground/app/chat/[chatId]/chat-view.ts

@@ -0,0 +1,101 @@
+import type {
+  AgentPost,
+  ChatAgentMessage,
+  ChatMessage,
+  ChatMessageMetadata,
+} from '../model'
+
+const MESSAGE_BURST_MS = 60_000
+
+export type ChatTranscriptMoment = {
+  kind: 'participant' | 'agent'
+  author: string
+  at: string
+}
+
+export const shouldGroupMessage = (
+  previous: ChatTranscriptMoment,
+  current: ChatTranscriptMoment,
+): boolean => {
+  if (previous.kind !== current.kind || previous.author !== current.author) {
+    return false
+  }
+  const elapsed = Date.parse(current.at) - Date.parse(previous.at)
+  return Number.isFinite(elapsed) && elapsed >= 0 && elapsed < MESSAGE_BURST_MS
+}
+
+type ParticipantTranscriptEntry = {
+  kind: 'participant'
+  index: number
+  author: string
+  at: string
+  message: ChatMessage
+}
+
+type AgentTranscriptEntry = {
+  kind: 'agent'
+  index: number
+  author: 'agent'
+  at: string
+  post: AgentPost
+}
+
+export type ChatTranscriptEntry = (
+  ParticipantTranscriptEntry | AgentTranscriptEntry
+) & { showHeader: boolean }
+
+export const buildChatTranscript = (
+  messages: ChatMessage[],
+  posts: AgentPost[],
+): ChatTranscriptEntry[] => {
+  const ordered = [
+    ...messages.map((message): ParticipantTranscriptEntry => ({
+      kind: 'participant',
+      index: message.index,
+      author: message.author,
+      at: message.at,
+      message,
+    })),
+    ...posts.map((post): AgentTranscriptEntry => ({
+      kind: 'agent',
+      index: post.index,
+      author: 'agent',
+      at: post.at,
+      post,
+    })),
+  ].toSorted((left, right) => left.index - right.index)
+
+  return ordered.map((entry, position) => {
+    const previous = ordered[position - 1]
+    return Object.assign(entry, {
+      showHeader:
+        previous === undefined || !shouldGroupMessage(previous, entry),
+    })
+  })
+}
+
+export type AgentMessageMetadata = Extract<
+  ChatMessageMetadata,
+  { kind: 'agent' }
+>
+
+export type AgentStreamSelection = {
+  message: ChatAgentMessage
+  parts: ChatAgentMessage['parts']
+  metadata: AgentMessageMetadata | null
+}
+
+export const selectAgentStream = (
+  messages: ChatAgentMessage[],
+  responseMessageId: string,
+): AgentStreamSelection | null => {
+  const message = messages.find(
+    (candidate) => candidate.id === responseMessageId,
+  )
+  if (message === undefined) return null
+  return {
+    message,
+    parts: message.parts,
+    metadata: message.metadata?.kind === 'agent' ? message.metadata : null,
+  }
+}

package/examples/playground/app/chat/[chatId]/composer.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { insertComposerText, isComposerTypingKey } from './composer'
+
+const key = (
+  value: string,
+  overrides: Partial<Parameters<typeof isComposerTypingKey>[0]> = {},
+): Parameters<typeof isComposerTypingKey>[0] => ({
+  key: value,
+  altKey: false,
+  ctrlKey: false,
+  metaKey: false,
+  isComposing: false,
+  defaultPrevented: false,
+  ...overrides,
+})
+
+describe('composer keyboard routing', () => {
+  it('captures printable keys, including shifted characters and spaces', () => {
+    expect(isComposerTypingKey(key('A'))).toBe(true)
+    expect(isComposerTypingKey(key(' '))).toBe(true)
+  })
+
+  it('leaves shortcuts, composition, navigation, and handled keys alone', () => {
+    expect(isComposerTypingKey(key('k', { metaKey: true }))).toBe(false)
+    expect(isComposerTypingKey(key('a', { ctrlKey: true }))).toBe(false)
+    expect(isComposerTypingKey(key('Enter'))).toBe(false)
+    expect(isComposerTypingKey(key('ArrowDown'))).toBe(false)
+    expect(isComposerTypingKey(key('a', { isComposing: true }))).toBe(false)
+    expect(isComposerTypingKey(key('a', { defaultPrevented: true }))).toBe(
+      false,
+    )
+  })
+
+  it('inserts the first routed character at the current selection', () => {
+    expect(insertComposerText('hello room', '!', 5, 10)).toEqual({
+      value: 'hello!',
+      caret: 6,
+    })
+    expect(insertComposerText('hello', '?', null, null)).toEqual({
+      value: 'hello?',
+      caret: 6,
+    })
+  })
+})

package/examples/playground/app/chat/[chatId]/composer.ts

@@ -0,0 +1,30 @@
+export type ComposerKey = {
+  key: string
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  isComposing: boolean
+  defaultPrevented: boolean
+}
+
+export const isComposerTypingKey = (event: ComposerKey): boolean =>
+  !event.defaultPrevented &&
+  !event.isComposing &&
+  !event.altKey &&
+  !event.ctrlKey &&
+  !event.metaKey &&
+  event.key.length === 1
+
+export const insertComposerText = (
+  value: string,
+  text: string,
+  selectionStart: number | null,
+  selectionEnd: number | null,
+): { value: string; caret: number } => {
+  const start = selectionStart ?? value.length
+  const end = selectionEnd ?? start
+  return {
+    value: `${value.slice(0, start)}${text}${value.slice(end)}`,
+    caret: start + text.length,
+  }
+}

package/examples/playground/app/chat/[chatId]/page.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+import { chatReducer } from '../model'
+import { chatServer } from '../server'
+import { SessionProvider } from './session'
+import { ChatClient } from './chat-client'
+
+export default async function ChatSessionPage({
+  params,
+}: {
+  params: Promise<{ chatId: string }>
+}): Promise<ReactNode> {
+  const { chatId } = await params
+  const session = chatServer.session(chatId)
+  const { state, index } = await session.state(chatReducer)
+  const events = (await session.history()).filter(
+    (event) => event.index <= index,
+  )
+
+  return (
+    <SessionProvider
+      sessionId={chatId}
+      api="/chat/events"
+      initialState={state}
+      initialIndex={index}
+      initialEvents={events}
+    >
+      <ChatClient chatId={chatId} />
+    </SessionProvider>
+  )
+}

package/examples/playground/app/chat/[chatId]/session.ts

@@ -0,0 +1,7 @@
+'use client'
+import { createReact } from 'experimental-a2/react'
+import { chatReducer } from '../model'
+
+export const { SessionProvider, useSession } = createReact({
+  reducer: chatReducer,
+})

package/examples/playground/app/chat/events/route.ts

@@ -0,0 +1,7 @@
+import { authorizeChatOperation, chatServer } from '../server'
+
+export const GET = chatServer.fetch
+
+export function POST(request: Request): Promise<Response> {
+  return chatServer.fetch(request, { authorize: authorizeChatOperation })
+}

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

@@ -0,0 +1,155 @@
+import type { ContractEvent } from 'experimental-a2'
+import { describe, expect, it } from 'vitest'
+import { chat, chatReducer, type ChatState } from './model'
+
+type ChatEvents = typeof chat.events
+type ChatEvent<
+  K extends keyof ChatEvents & string = keyof ChatEvents & string,
+> = ContractEvent<ChatEvents, K>
+
+const event = <K extends keyof ChatEvents & string>(
+  index: number,
+  type: K,
+  payload: ChatEvent<K>['payload'],
+): ChatEvent<K> =>
+  ({
+    id: `event-${index}`,
+    type,
+    payload,
+    index,
+    sessionId: 'chat-1',
+    createdAt: new Date(index * 1_000),
+  }) as ChatEvent<K>
+
+const generation = {
+  requestId: 'request-1',
+  messageId: 'participant-1',
+  generationId: 'generation-1',
+  responseMessageId: 'assistant-1',
+  attempt: 1,
+  model: 'test/model',
+} satisfies ChatEvent<'ai.generation.started'>['payload']
+
+const setup = (): ChatEvent[] => [event(1, 'ai.generation.started', generation)]
+
+const toolCalled = (index: number, toolCallId: string, message: string) =>
+  event(index, 'ai.tool.called', {
+    requestId: generation.requestId,
+    messageId: generation.responseMessageId,
+    generationId: generation.generationId,
+    toolCallId,
+    toolName: 'post',
+    input: { message },
+  })
+
+const messagePosted = (index: number, toolCallId: string, message: string) =>
+  event(index, 'agent.message.posted', {
+    generationId: generation.generationId,
+    responseMessageId: generation.responseMessageId,
+    toolCallId,
+    message,
+  })
+
+const fold = (...events: ChatEvent[]): ChatState =>
+  events.reduce(
+    (state, nextEvent) => chatReducer.fold(state, nextEvent),
+    chatReducer.initialState,
+  )
+
+describe('chat agent post projection', () => {
+  it('keeps tool calls invisible until the tool appends its post event', () => {
+    const called = toolCalled(2, 'call-1', 'Hello from the tool')
+    let state = fold(...setup(), called)
+
+    expect(state.posts).toEqual([])
+    expect(state.ai.tools).toEqual([
+      expect.objectContaining({
+        generationId: generation.generationId,
+        toolCallId: 'call-1',
+        status: 'running',
+      }),
+    ])
+
+    state = chatReducer.fold(
+      state,
+      messagePosted(3, 'call-1', 'Hello from the tool'),
+    )
+
+    expect(state.posts).toEqual([
+      {
+        generationId: generation.generationId,
+        responseMessageId: generation.responseMessageId,
+        toolCallId: 'call-1',
+        index: 3,
+        text: 'Hello from the tool',
+        at: new Date(3_000).toISOString(),
+      },
+    ])
+  })
+
+  it('projects every explicit post in durable event order', () => {
+    const firstCall = toolCalled(2, 'call-1', 'First post')
+    const secondCall = toolCalled(3, 'call-2', 'Second post')
+    const state = fold(
+      ...setup(),
+      firstCall,
+      secondCall,
+      messagePosted(4, 'call-1', 'First post'),
+      messagePosted(5, 'call-2', 'Second post'),
+    )
+
+    expect(
+      state.posts.map(({ toolCallId, index, text }) => ({
+        toolCallId,
+        index,
+        text,
+      })),
+    ).toEqual([
+      { toolCallId: 'call-1', index: 4, text: 'First post' },
+      { toolCallId: 'call-2', index: 5, text: 'Second post' },
+    ])
+  })
+
+  it('rewinds posts past an interruption cutpoint and ignores late appends', () => {
+    const firstCall = toolCalled(2, 'call-1', 'Visible before stop')
+    const secondCall = toolCalled(4, 'call-2', 'Not visible at stop')
+    let state = fold(
+      ...setup(),
+      firstCall,
+      messagePosted(3, 'call-1', 'Visible before stop'),
+      secondCall,
+      messagePosted(5, 'call-2', 'Not visible at stop'),
+    )
+
+    expect(state.posts.map((post) => post.toolCallId)).toEqual([
+      'call-1',
+      'call-2',
+    ])
+
+    state = chatReducer.fold(
+      state,
+      event(6, 'ai.message.interrupted', {
+        messageId: generation.responseMessageId,
+        generationId: generation.generationId,
+        lastSeenIndex: 3,
+      }),
+    )
+
+    expect(state.posts.map((post) => post.toolCallId)).toEqual(['call-1'])
+    expect(state.ai.activeGeneration).toBeNull()
+
+    state = chatReducer.fold(
+      state,
+      toolCalled(7, 'call-3', 'Called after stop'),
+    )
+
+    expect(state.ai.activeGeneration).toBeNull()
+
+    state = chatReducer.fold(
+      state,
+      messagePosted(8, 'call-3', 'Late after stop'),
+    )
+
+    expect(state.posts.map((post) => post.toolCallId)).toEqual(['call-1'])
+  })
+})