experimental-a2 0.16.1 → 0.18.0

package/examples/playground/app/chat/[chatId]/chat-client.tsx

@@ -13,19 +13,21 @@ import {
   useRef,
   useState,
 } from 'react'
-import { inputs } from 'experimental-a2/ai'
+import type { InitialSnapshot } from 'experimental-a2'
+import { inputs, type AIState } from 'experimental-a2/ai'
+import { useAgent } from 'experimental-a2/ai/react'
 import { ActivityFeed } from '@/app/components/activity-feed'
 import { ConnectionPill } from '@/app/components/connection-pill'
-import {
-  AgentStreamDrawer,
-  type AgentStreamStatus,
-} from './agent-stream-drawer'
+import { AgentStreamDrawer } from './agent-stream-drawer'
 import {
   buildChatTranscript,
+  agentRetry,
+  agentStreamStatus,
   selectAgentStream,
   type AgentMessageMetadata,
 } from './chat-view'
 import { insertComposerText, isComposerTypingKey } from './composer'
+import { chatAgent, type ChatAgentMessage } from '../model'
 import { useSession } from './session'
 
 /** Max one durable presence ping per author in this window. */
@@ -180,8 +182,22 @@ const hasImportantFocus = (element: EventTarget | null): boolean =>
   (element.matches(IMPORTANT_FOCUS_SELECTOR) ||
     element.closest('dialog[open]') !== null)
 
-export function ChatClient({ chatId }: { chatId: string }): ReactNode {
-  const { state, push, events, index, connection } = useSession()
+export function ChatClient({
+  chatId,
+  agentInitial,
+}: {
+  chatId: string
+  agentInitial: InitialSnapshot<AIState<ChatAgentMessage>>
+}): ReactNode {
+  const { state, push, events, index, connection, history, loadHistory } =
+    useSession()
+  const agent = useAgent({
+    api: '/chat/agent',
+    id: chatId,
+    initial: agentInitial,
+    contract: chatAgent,
+  })
+  const ai = agent.state
 
   const [name, setName] = useState('')
   const [draft, setDraft] = useState('')
@@ -277,14 +293,14 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
     .filter(([, at]) => now - Date.parse(at) < TYPING_TTL_MS)
     .map(([author]) => author)
 
-  const runningTool = state.ai.tools.find((tool) => tool.status === 'running')
+  const runningTool = ai.tools.find((tool) => tool.status === 'running')
   const activeResponseId =
-    state.ai.activeGeneration?.responseMessageId ??
-    state.ai.activeResponseMessageId ??
+    ai.activeGeneration?.responseMessageId ??
+    ai.activeResponseMessageId ??
     runningTool?.messageId ??
     null
   const activeMessage = activeResponseId
-    ? state.ai.messages.find((message) => message.id === activeResponseId)
+    ? ai.messages.find((message) => message.id === activeResponseId)
     : undefined
   const writing =
     activeMessage?.parts.some(
@@ -294,11 +310,11 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
     ) === true ||
     (runningTool?.toolName === 'post' && runningTool.status === 'running')
   const agentActivity =
-    state.ai.status === 'generating' ? (writing ? 'writing' : 'thinking') : null
+    ai.status === 'generating' ? (writing ? 'writing' : 'thinking') : null
   const presence = presenceLine(typingAuthors, agentActivity)
 
   const aiMessages = new Map(
-    state.ai.messages.map((message) => [message.id, message]),
+    ai.messages.map((message) => [message.id, message]),
   )
   const lastPostByResponse = new Map<string, (typeof state.posts)[number]>()
   for (const post of state.posts) {
@@ -309,7 +325,7 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
   }
   const transcript = buildChatTranscript(state.messages, state.posts)
   const selectedAgentStream = openResponseId
-    ? selectAgentStream(state.ai.messages, openResponseId)
+    ? selectAgentStream(ai.messages, openResponseId)
     : null
   const selectedStreamSummary = usageLabel(
     selectedAgentStream?.metadata ?? null,
@@ -317,32 +333,12 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
   const selectedStreamLive =
     openResponseId !== null &&
     openResponseId === activeResponseId &&
-    state.ai.status === 'generating'
-  const selectedStreamStatus = (() => {
-    if (selectedStreamLive) return 'streaming'
-    if (openResponseId === null) return 'completed'
-    for (const event of events.toReversed()) {
-      if (
-        event.type === 'ai.message.interrupted' &&
-        event.payload.messageId === openResponseId
-      ) {
-        return 'interrupted'
-      }
-      if (
-        event.type === 'ai.generation.failed' &&
-        event.payload.responseMessageId === openResponseId
-      ) {
-        return 'failed'
-      }
-      if (
-        event.type === 'ai.message.completed' &&
-        event.payload.messageId === openResponseId
-      ) {
-        return 'completed'
-      }
-    }
-    return 'completed'
-  })() satisfies AgentStreamStatus
+    ai.status === 'generating'
+  const selectedStreamStatus = agentStreamStatus({
+    state: ai,
+    responseMessageId: openResponseId,
+    streaming: selectedStreamLive,
+  })
 
   const participants = useMemo(() => {
     const seen = new Set<string>(['agent'])
@@ -358,26 +354,11 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
       )
     : []
 
-  const totalTokens = state.ai.usage.reduce(
+  const totalTokens = ai.usage.reduce(
     (total, entry) => total + (entry.usage.totalTokens ?? 0),
     0,
   )
-  const failedGeneration =
-    state.ai.status === 'failed'
-      ? events.findLast(
-          (
-            event,
-          ): event is Extract<
-            (typeof events)[number],
-            { type: 'ai.generation.failed' }
-          > =>
-            event.type === 'ai.generation.failed' &&
-            event.payload.superseded !== true,
-        )
-      : undefined
-  const failedRootMessageId = failedGeneration
-    ? state.ai.active?.input.id
-    : undefined
+  const retry = agentRetry(ai)
 
   const sendTypingPing = useCallback((): void => {
     if (!name) return
@@ -535,29 +516,23 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
   }
 
   const stopAgent = async (): Promise<void> => {
-    if (!state.ai.active) return
+    if (!ai.active) return
     setError(null)
     try {
-      await push(
-        ...inputs.stop({
-          turnId: state.ai.active.turnId,
-          lastSeenIndex: index,
-        }),
-      )
+      await agent.stop()
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
     }
   }
 
   const retryAgent = async (): Promise<void> => {
-    if (!failedGeneration || !failedRootMessageId) return
+    if (!retry) return
     setError(null)
     setRetrying(true)
     try {
-      await push(
+      await agent.push(
         ...inputs.retry({
-          messageId: failedRootMessageId,
-          responseMessageId: failedGeneration.payload.responseMessageId,
+          ...retry,
           retryId: crypto.randomUUID(),
         }),
       )
@@ -606,12 +581,12 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
             {state.messages.length}{' '}
             {state.messages.length === 1 ? 'message' : 'messages'}
           </span>
-          {state.ai.usage.length > 0 ? (
+          {ai.usage.length > 0 ? (
             <span className="badge">
               {totalTokens.toLocaleString()} AI tokens
             </span>
           ) : null}
-          {state.ai.status === 'failed' ? (
+          {ai.status === 'failed' ? (
             <span className="badge cut">agent paused</span>
           ) : null}
         </div>
@@ -730,18 +705,16 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
           </div>
 
           <div className="chat-composer-dock" ref={composerDockRef}>
-            {state.ai.status === 'failed' ? (
+            {ai.status === 'failed' ? (
               <div className="chat-agent-error" role="alert">
                 <p>
                   <strong>Agent paused.</strong>{' '}
-                  {state.ai.error ?? 'The model step failed.'}
+                  {ai.error ?? 'The model step failed.'}
                 </p>
                 <button
                   type="button"
                   className="secondary compact"
-                  disabled={
-                    !failedGeneration || !failedRootMessageId || retrying
-                  }
+                  disabled={!retry || retrying}
                   onClick={() => void retryAgent()}
                 >
                   {retrying ? 'Retrying…' : 'Retry agent'}
@@ -888,10 +861,15 @@ export function ChatClient({ chatId }: { chatId: string }): ReactNode {
             onClick={() => setSidebarOpen((open) => !open)}
           >
             <span>Room details</span>
-            <span className="badge">{events.length} events</span>
+            <span className="badge">{events.length} loaded events</span>
           </button>
           <div className="chat-sidebar-body" id="chat-sidebar-body">
-            <ActivityFeed events={events} index={index} />
+            <ActivityFeed
+              events={events}
+              index={index}
+              history={history}
+              loadHistory={loadHistory}
+            />
           </div>
         </aside>
       </div>

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

@@ -1,9 +1,43 @@
+import type { AIState, TranscriptMessage } from 'experimental-a2/ai'
 import type {
   AgentPost,
   ChatAgentMessage,
   ChatMessage,
   ChatMessageMetadata,
 } from '../model'
+import type { AgentStreamStatus } from './agent-stream-drawer'
+
+export function agentStreamStatus({
+  state,
+  responseMessageId,
+  streaming,
+}: {
+  state: AIState<ChatAgentMessage>
+  responseMessageId: string | null
+  streaming: boolean
+}): AgentStreamStatus {
+  if (streaming) return 'streaming'
+  const owner =
+    responseMessageId === null
+      ? undefined
+      : state.responseOwners[responseMessageId]
+  const terminal = owner && state.terminalGenerations?.[owner.generationId]
+  return terminal === 'failed' || terminal === 'interrupted'
+    ? terminal
+    : 'completed'
+}
+
+export function agentRetry(state: AIState<ChatAgentMessage>): {
+  messageId: string
+  responseMessageId: string
+} | null {
+  if (state.status !== 'failed' || state.active === null) return null
+  const responseMessageId =
+    state.activeResponseMessageId ?? state.activeProjection?.responseMessageId
+  return responseMessageId
+    ? { messageId: state.active.input.id, responseMessageId }
+    : null
+}
 
 const MESSAGE_BURST_MS = 60_000
 
@@ -80,13 +114,13 @@ export type AgentMessageMetadata = Extract<
 >
 
 export type AgentStreamSelection = {
-  message: ChatAgentMessage
-  parts: ChatAgentMessage['parts']
+  message: TranscriptMessage<ChatAgentMessage>
+  parts: TranscriptMessage<ChatAgentMessage>['parts']
   metadata: AgentMessageMetadata | null
 }
 
 export const selectAgentStream = (
-  messages: ChatAgentMessage[],
+  messages: TranscriptMessage<ChatAgentMessage>[],
   responseMessageId: string,
 ): AgentStreamSelection | null => {
   const message = messages.find(

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

@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react'
-import { chatReducer } from '../model'
-import { chatServer } from '../server'
+import { chatAgentServer, chatServer } from '../server'
 import { SessionProvider } from './session'
 import { ChatClient } from './chat-client'
 
@@ -10,21 +9,14 @@ export default async function ChatSessionPage({
   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,
-  )
+  const [initial, agentInitial] = await Promise.all([
+    chatServer.session(chatId).state(),
+    chatAgentServer.session(chatId).state(),
+  ])
 
   return (
-    <SessionProvider
-      sessionId={chatId}
-      api="/chat/events"
-      initialState={state}
-      initialIndex={index}
-      initialEvents={events}
-    >
-      <ChatClient chatId={chatId} />
+    <SessionProvider sessionId={chatId} api="/chat/events" initial={initial}>
+      <ChatClient chatId={chatId} agentInitial={agentInitial} />
     </SessionProvider>
   )
 }

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

@@ -1,22 +1,5 @@
 'use client'
 import { createReact } from 'experimental-a2/react'
-import { chatReducer, viewChatState, type ChatViewState } from '../model'
-import { useMemo } from 'react'
+import { chat } from '../model'
 
-const { SessionProvider, useSession: useStoredSession } = createReact({
-  reducer: chatReducer,
-})
-
-export { SessionProvider }
-
-type ChatSession = Omit<ReturnType<typeof useStoredSession>, 'state'> & {
-  state: ChatViewState
-}
-
-export function useSession(): ChatSession {
-  const session = useStoredSession()
-  return useMemo(
-    () => ({ ...session, state: viewChatState(session.state) }),
-    [session],
-  )
-}
+export const { SessionProvider, useSession } = createReact({ contract: chat })

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

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

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

@@ -1,6 +1,6 @@
 import type { ContractEvent } from 'experimental-a2'
-import { describe, expect, it } from 'vitest'
-import { chat, chatReducer, viewChatState, type ChatState } from './model'
+import { expect, it } from 'vitest'
+import { chat, chatReducer, type ChatState } from './model'
 
 type ChatEvents = typeof chat.events
 type ChatEvent<
@@ -21,31 +21,10 @@ const event = <K extends keyof ChatEvents & string>(
     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,
+    generationId: 'generation-1',
+    responseMessageId: 'assistant-1',
     toolCallId,
     message,
   })
@@ -56,100 +35,48 @@ const fold = (...events: ChatEvent[]): ChatState =>
     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(viewChatState(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(viewChatState(state).ai.activeGeneration).toBeNull()
-
-    state = chatReducer.fold(
-      state,
-      toolCalled(7, 'call-3', 'Called after stop'),
-    )
-
-    expect(viewChatState(state).ai.activeGeneration).toBeNull()
-
-    state = chatReducer.fold(
-      state,
-      messagePosted(8, 'call-3', 'Late after stop'),
-    )
+it("orders the agent's posts among everyone's messages by log index", () => {
+  const state = fold(
+    event(1, 'typed', { author: 'alice' }),
+    event(2, 'message.sent', { author: 'alice', text: '@agent hi' }),
+    messagePosted(3, 'call-1', 'Hello'),
+    event(4, 'message.sent', { author: 'bob', text: 'mid-reply' }),
+    messagePosted(5, 'call-2', 'And more'),
+  )
+  expect(state.lastTypingAt).toEqual({})
+  expect(
+    state.messages.map(({ index, author }) => ({ index, author })),
+  ).toEqual([
+    { index: 2, author: 'alice' },
+    { index: 4, author: 'bob' },
+  ])
+  expect(state.posts).toEqual([
+    {
+      generationId: 'generation-1',
+      responseMessageId: 'assistant-1',
+      toolCallId: 'call-1',
+      index: 3,
+      text: 'Hello',
+      at: new Date(3_000).toISOString(),
+    },
+    {
+      generationId: 'generation-1',
+      responseMessageId: 'assistant-1',
+      toolCallId: 'call-2',
+      index: 5,
+      text: 'And more',
+      at: new Date(5_000).toISOString(),
+    },
+  ])
+})
 
-    expect(state.posts.map((post) => post.toolCallId)).toEqual(['call-1'])
+it('records who changed ambient mode', () => {
+  const state = fold(
+    event(1, 'agent.ambient.changed', { enabled: true, author: 'alice' }),
+  )
+  expect(state.ambient).toEqual({
+    enabled: true,
+    changedBy: 'alice',
+    changedAt: new Date(1_000).toISOString(),
   })
 })