experimental-a2 0.8.0 → 0.9.0

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

@@ -0,0 +1,310 @@
+import type { FinishReason, LanguageModelUsage, UIMessage } from 'ai'
+import { agent, type AIState } from 'experimental-a2/ai'
+import { z } from 'zod'
+
+export type ChatAgentStep = {
+  generationId: string
+  model: string
+  finishReason: FinishReason
+  rawFinishReason?: string
+  usage: LanguageModelUsage
+  completedAt: string
+}
+
+export type ChatParticipantMode = 'ambient' | 'mention' | 'passive'
+export type ChatAgentMode = Exclude<ChatParticipantMode, 'passive'>
+
+export const chatPostInputSchema = z
+  .object({ message: z.string().min(1).max(2000) })
+  .strict()
+
+const agentPostEventSchema = chatPostInputSchema
+  .extend({
+    generationId: z.string().min(1),
+    responseMessageId: z.string().min(1),
+    toolCallId: z.string().min(1),
+  })
+  .strict()
+
+export type ChatMessageMetadata =
+  | {
+      kind: 'participant'
+      author: string
+      text: string
+      sentAt: string
+      mode: ChatParticipantMode
+    }
+  | {
+      kind: 'agent'
+      author: 'agent'
+      mode: ChatAgentMode
+      steps: ChatAgentStep[]
+    }
+
+export type ChatAgentTools = {
+  post: {
+    input: z.output<typeof chatPostInputSchema>
+    output: { posted: true }
+  }
+}
+
+export type ChatAgentMessage = UIMessage<
+  ChatMessageMetadata,
+  Record<never, never>,
+  ChatAgentTools
+>
+
+const usageSchema = z.object({
+  inputTokens: z.number().optional(),
+  inputTokenDetails: z.object({
+    noCacheTokens: z.number().optional(),
+    cacheReadTokens: z.number().optional(),
+    cacheWriteTokens: z.number().optional(),
+  }),
+  outputTokens: z.number().optional(),
+  outputTokenDetails: z.object({
+    textTokens: z.number().optional(),
+    reasoningTokens: z.number().optional(),
+  }),
+  totalTokens: z.number().optional(),
+  raw: z.record(z.string(), z.unknown()).optional(),
+})
+
+const participantMetadataSchema = z
+  .object({
+    kind: z.literal('participant'),
+    author: z.string().min(1).max(40),
+    text: z.string().min(1).max(2000),
+    sentAt: z.iso.datetime(),
+    mode: z.enum(['ambient', 'mention', 'passive']),
+  })
+  .strict()
+
+const agentMetadataSchema = z.object({
+  kind: z.literal('agent'),
+  author: z.literal('agent'),
+  mode: z.enum(['ambient', 'mention']),
+  steps: z.array(
+    z.object({
+      generationId: z.string(),
+      model: z.string(),
+      finishReason: z.enum([
+        'stop',
+        'length',
+        'content-filter',
+        'tool-calls',
+        'error',
+        'other',
+      ]),
+      rawFinishReason: z.string().optional(),
+      usage: usageSchema,
+      completedAt: z.iso.datetime(),
+    }),
+  ),
+})
+
+const chatMessageMetadataSchema = z.discriminatedUnion('kind', [
+  participantMetadataSchema,
+  agentMetadataSchema,
+])
+
+const participantMessageValueSchema = z
+  .object({
+    id: z.string().min(1),
+    role: z.literal('user'),
+    metadata: participantMetadataSchema,
+    parts: z.tuple([
+      z
+        .object({
+          type: z.literal('text'),
+          text: z.string(),
+        })
+        .strict(),
+    ]),
+  })
+  .strict()
+  .refine(
+    (message) =>
+      message.parts[0].text ===
+      `${message.metadata.author}: ${message.metadata.text}`,
+    { message: 'participant metadata must match the model text' },
+  )
+
+const trustedMessageValueSchema = z.object({
+  id: z.string().min(1),
+  role: z.enum(['system', 'assistant']),
+  metadata: chatMessageMetadataSchema.optional(),
+  parts: z.array(z.object({ type: z.string() }).passthrough()),
+})
+
+const chatMessageValueSchema = z.union([
+  participantMessageValueSchema,
+  trustedMessageValueSchema,
+])
+
+const chatMessageSchema = z.custom<ChatAgentMessage>(
+  (value) => chatMessageValueSchema.safeParse(value).success,
+  'invalid chat UI message',
+)
+
+const chatEvents = {
+  'message.sent': z.object({
+    author: z.string().min(1).max(40),
+    text: z.string().min(1).max(2000),
+  }),
+  typed: z.object({ author: z.string().min(1).max(40) }),
+  'agent.ambient.changed': z.object({
+    enabled: z.boolean(),
+    author: z.string().min(1).max(40),
+  }),
+  'agent.message.posted': agentPostEventSchema,
+}
+
+export const chatAgent = agent<ChatAgentMessage, typeof chatEvents>({
+  name: 'chat',
+  events: chatEvents,
+  messageSchema: chatMessageSchema,
+  reducerName: 'a2.playground.chat.ai.v1',
+})
+
+export const chat = chatAgent.contract
+
+export type ChatMessage = {
+  id: string
+  index: number
+  author: string
+  text: string
+  at: string
+}
+
+export type AgentPost = {
+  generationId: string
+  responseMessageId: string
+  toolCallId: string
+  index: number
+  text: string
+  at: string
+}
+
+export type ChatState = {
+  ai: AIState<ChatAgentMessage>
+  messages: ChatMessage[]
+  posts: AgentPost[]
+  lastTypingAt: Record<string, string>
+  ambient: {
+    enabled: boolean
+    changedBy: string | null
+    changedAt: string | null
+  }
+}
+
+const initialChatState: ChatState = {
+  ai: chatAgent.reducer.initialState,
+  messages: [],
+  posts: [],
+  lastTypingAt: {},
+  ambient: { enabled: false, changedBy: null, changedAt: null },
+}
+
+export const chatReducer = chat
+  .reducer({
+    name: 'a2.playground.chat.v1',
+    initialState: initialChatState,
+  })
+  .fold((state, event) => {
+    if (
+      event.type === 'ai.tool.called' &&
+      event.payload.toolName === 'post' &&
+      (state.ai.activeGeneration?.generationId !== event.payload.generationId ||
+        state.ai.activeGeneration.responseMessageId !== event.payload.messageId)
+    ) {
+      return state
+    }
+
+    const ai = chatAgent.reducer.fold(state.ai, event)
+    const base = ai === state.ai ? state : { ...state, ai }
+
+    switch (event.type) {
+      case 'message.sent': {
+        const stillTyping = { ...base.lastTypingAt }
+        delete stillTyping[event.payload.author]
+        return {
+          ...base,
+          messages: [
+            ...base.messages,
+            {
+              id: event.id,
+              index: event.index,
+              author: event.payload.author,
+              text: event.payload.text,
+              at: event.createdAt.toISOString(),
+            },
+          ],
+          lastTypingAt: stillTyping,
+        }
+      }
+      case 'typed':
+        return {
+          ...base,
+          lastTypingAt: {
+            ...base.lastTypingAt,
+            [event.payload.author]: event.createdAt.toISOString(),
+          },
+        }
+      case 'agent.ambient.changed':
+        return {
+          ...base,
+          ambient: {
+            enabled: event.payload.enabled,
+            changedBy: event.payload.author,
+            changedAt: event.createdAt.toISOString(),
+          },
+        }
+      case 'agent.message.posted': {
+        const payload = event.payload
+        const running = state.ai.tools.some(
+          (activity) =>
+            activity.generationId === payload.generationId &&
+            activity.messageId === payload.responseMessageId &&
+            activity.toolCallId === payload.toolCallId &&
+            activity.toolName === 'post' &&
+            activity.status === 'running',
+        )
+        if (!running) return base
+        return {
+          ...base,
+          posts: [
+            ...base.posts,
+            {
+              generationId: payload.generationId,
+              responseMessageId: payload.responseMessageId,
+              toolCallId: payload.toolCallId,
+              index: event.index,
+              text: payload.message,
+              at: event.createdAt.toISOString(),
+            },
+          ],
+        }
+      }
+      case 'ai.message.interrupted': {
+        const cutoff = event.payload.lastSeenIndex
+        if (ai === state.ai || cutoff === undefined) return base
+        return {
+          ...base,
+          posts: base.posts.filter(
+            (post) =>
+              post.responseMessageId !== event.payload.messageId ||
+              (event.payload.generationId !== undefined &&
+                post.generationId !== event.payload.generationId) ||
+              post.index <= cutoff,
+          ),
+        }
+      }
+      default:
+        return base
+    }
+  })
+
+const agentMention = /(?:^|\s)@agent(?![\w-])/i
+
+export const mentionsAgent = (text: string): boolean => agentMention.test(text)

package/examples/playground/app/chat/new-conversation.tsx

@@ -0,0 +1,16 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useRouter } from 'next/navigation'
+
+export function NewConversation(): ReactNode {
+  const router = useRouter()
+  return (
+    <p>
+      <button
+        onClick={() => router.push(`/chat/${crypto.randomUUID().slice(0, 8)}`)}
+      >
+        New conversation
+      </button>
+    </p>
+  )
+}

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

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+import { NewConversation } from './new-conversation'
+
+export default function ChatPage(): ReactNode {
+  return (
+    <article>
+      <h1>Multiplayer chat, with an agent in the room</h1>
+      <p className="lede">
+        Messages, presence, and a real AI agent all live in one log. By default,
+        only an <code>@agent</code> mention calls the model; a durable room-wide
+        switch can make every message ambient. The agent can stay silent, or
+        call <code>post</code> to add one visible message to the room.
+      </p>
+      <NewConversation />
+      <p className="hint">
+        Each conversation is one session. Open the same URL in two tabs:
+        messages converge, “is typing…” rides throttled <code>typed</code>{' '}
+        extension events, the ambient setting is an event too, and AI SDK
+        progress, tools, metadata, and usage are durable AI events. Private
+        model tokens render as a thinking or writing indicator, not an inline
+        reply.
+      </p>
+    </article>
+  )
+}

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

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

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

@@ -0,0 +1,184 @@
+import 'server-only'
+import { tool } from 'ai'
+import { handlerContext, inputs } from 'experimental-a2/ai'
+import { createHandlers } from 'experimental-a2/ai/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { createServer, type A2Operation } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import {
+  chatAgent,
+  chatPostInputSchema,
+  mentionsAgent,
+  type ChatAgentMessage,
+  type ChatAgentMode,
+  type ChatParticipantMode,
+} from './model'
+
+const tools = {
+  post: tool({
+    description:
+      'Post a visible message to the multiplayer chat. Call it once for each chat bubble you want to send; this tool is the only way to speak in the room.',
+    inputSchema: chatPostInputSchema,
+    execute: async ({ message }, { toolCallId }) => {
+      const context = handlerContext(chatAgent)
+      if (context.event.type !== 'ai.tool.called') {
+        throw new Error('The chat post tool must execute automatically')
+      }
+      context.signal.throwIfAborted()
+      await context.session.append('post', {
+        type: 'agent.message.posted',
+        payload: {
+          message,
+          generationId: context.event.payload.generationId,
+          responseMessageId: context.event.payload.messageId,
+          toolCallId,
+        },
+      })
+      return { posted: true as const }
+    },
+  }),
+}
+
+const aiHandlers = createHandlers({
+  agent: chatAgent,
+  model: 'openai/gpt-5.4',
+  tools,
+  instructions: `You are "agent", a participant in a multiplayer chat.
+The latest participant message invited you either by mentioning @agent or by enabling the room's ambient mode. Messages are formatted as "name: message"; earlier passive messages are useful conversation context.
+Sound like a sharp, relaxed person in the chat, not a customer-support bot. Match the room's language and energy. Keep messages specific and conversational; avoid canned acknowledgements, assistant-y disclaimers, and explanations of your own mechanics.
+Only contribute when you have something useful, relevant, or friendly to add. It is fine to stay silent or stop whenever you have nothing else to say.
+To speak, call post once for each visible chat bubble. Never communicate through ordinary assistant text because it is private and is not shown in the room.
+Use as many post calls as the moment naturally calls for. Several short messages are welcome when they create better rhythm, separate distinct thoughts, or fulfill a request for a sequence. A single message is fine too. Do not spam. After post results, continue only when another message genuinely improves the conversation.`,
+  generation: {
+    maxOutputTokens: 500,
+    temperature: 0.4,
+  },
+  progress: {
+    maxChunks: 4,
+    maxDelayMs: 30,
+  },
+  messageMetadata: (context) => {
+    const previous = context.state.messages.find(
+      (message) => message.id === context.responseMessageId,
+    )?.metadata
+    const trigger = context.state.messages.find(
+      (message) => message.id === context.request.payload.messageId,
+    )?.metadata
+    const steps = previous?.kind === 'agent' ? previous.steps : []
+    const mode: ChatAgentMode | undefined =
+      previous?.kind === 'agent'
+        ? previous.mode
+        : trigger?.kind === 'participant' && trigger.mode !== 'passive'
+          ? trigger.mode
+          : undefined
+    if (mode === undefined) return undefined
+    const metadata = {
+      kind: 'agent' as const,
+      author: 'agent' as const,
+      mode,
+      steps,
+    }
+    if (context.part.type === 'start') return metadata
+    if (context.part.type !== 'finish') return undefined
+    return {
+      ...metadata,
+      steps: [
+        ...steps,
+        {
+          generationId: context.generationId,
+          model: context.state.activeGeneration?.model ?? 'custom',
+          finishReason: context.part.finishReason,
+          ...(context.part.rawFinishReason === undefined
+            ? {}
+            : { rawFinishReason: context.part.rawFinishReason }),
+          usage: context.part.totalUsage,
+          completedAt: new Date().toISOString(),
+        },
+      ],
+    }
+  },
+})
+
+export const authorizeChatOperation = (
+  operation: A2Operation<(typeof chatAgent.contract)['events']>,
+): boolean => {
+  if (operation.type !== 'push') return true
+  const serverOnly = operation.events.find(
+    (event) =>
+      event.type === 'ai.message.created' ||
+      event.type === 'agent.message.posted',
+  )
+  if (serverOnly !== undefined) return false
+  const rejected = operation.events.find((event) => {
+    if (
+      event.type === 'message.sent' ||
+      event.type === 'typed' ||
+      event.type === 'agent.ambient.changed'
+    ) {
+      return false
+    }
+    return !(
+      event.type === 'ai.approval.responded' ||
+      event.type === 'ai.input.responded' ||
+      event.type === 'ai.message.interrupted' ||
+      event.type === 'ai.retry.requested'
+    )
+  })
+  return rejected === undefined
+}
+
+const toolCalledHandler = aiHandlers['ai.tool.called']
+if (toolCalledHandler === undefined) {
+  throw new Error('A2 AI handlers must include ai.tool.called')
+}
+const serializedToolCalledHandler =
+  typeof toolCalledHandler === 'function'
+    ? { handler: toolCalledHandler, lane: 'a2.chat.agent-tools' }
+    : { ...toolCalledHandler, lane: 'a2.chat.agent-tools' }
+
+export const chatScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-chat' })
+    : undefined
+
+export const chatServer = createServer({
+  ...(store ? { store } : {}),
+  ...(chatScheduler ? { scheduler: chatScheduler } : {}),
+  contract: chatAgent.contract,
+  handlers: {
+    ...aiHandlers,
+    'ai.tool.called': serializedToolCalledHandler,
+    'message.sent': {
+      lane: 'a2.chat.ingress',
+      handler: async (context) => {
+        let ambient = false
+        for (const event of await context.session.history()) {
+          if (event.index > context.event.index) break
+          if (event.type === 'agent.ambient.changed') {
+            ambient = event.payload.enabled
+          }
+        }
+
+        const { author, text } = context.event.payload
+        const mode: ChatParticipantMode = ambient
+          ? 'ambient'
+          : mentionsAgent(text)
+            ? 'mention'
+            : 'passive'
+        const message: ChatAgentMessage = {
+          id: context.event.id,
+          role: 'user',
+          metadata: {
+            kind: 'participant',
+            author,
+            text,
+            sentAt: context.event.createdAt.toISOString(),
+            mode,
+          },
+          parts: [{ type: 'text', text: `${author}: ${text}` }],
+        }
+        return inputs.message(message, { generate: mode !== 'passive' })
+      },
+    },
+  },
+})

package/examples/playground/app/components/activity-feed.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+
+/** The structural shape every machine's events share — enough for a
+ * feed that shows the log itself. */
+export type FeedEvent = {
+  id: string
+  index: number
+  type: string
+  payload: unknown
+  createdAt: Date
+}
+
+export function formatActivityTime(createdAt: Date): string {
+  return `${createdAt.toISOString().slice(11, 19)} UTC`
+}
+
+export function ActivityFeed({
+  events,
+  index,
+  status,
+}: {
+  events: readonly FeedEvent[]
+  index: number
+  status?: ReactNode
+}): ReactNode {
+  return (
+    <section>
+      <h2>Activity</h2>
+      {events.length === 0 ? (
+        <p className="hint">
+          Nothing observed yet — events appear here the moment they land.
+        </p>
+      ) : (
+        <ol className="feed">
+          {events.map((event) => (
+            <li key={event.id}>
+              <span className="idx">#{event.index}</span>
+              <span className="type">{event.type}</span>
+              <span className="payload">{JSON.stringify(event.payload)}</span>
+              <time dateTime={event.createdAt.toISOString()}>
+                {formatActivityTime(event.createdAt)}
+              </time>
+            </li>
+          ))}
+        </ol>
+      )}
+      {status ? <p className="activity-status">{status}</p> : null}
+      <p className="frontier">
+        Stream frontier: <code>{index}</code> — the last server-confirmed log
+        position this browser has folded.
+      </p>
+    </section>
+  )
+}

package/examples/playground/app/components/connection-pill.tsx

@@ -0,0 +1,29 @@
+'use client'
+import type { ReactNode } from 'react'
+import type { Connection } from 'experimental-a2/client'
+
+export function ConnectionPill({
+  connection,
+}: {
+  connection: Connection
+}): ReactNode {
+  const label =
+    connection.status === 'connecting'
+      ? connection.reconnects > 0
+        ? 'reconnecting…'
+        : 'connecting…'
+      : connection.status
+
+  return (
+    <span
+      className={`conn ${connection.status}`}
+      title={
+        connection.status === 'connecting'
+          ? connection.error?.message
+          : undefined
+      }
+    >
+      {label}
+    </span>
+  )
+}

package/examples/playground/app/counter/counter-client.tsx

@@ -0,0 +1,72 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+import { useSession } from './session'
+
+type CounterEventType = 'incremented' | 'decremented'
+const ACTIVITY_LIMIT = 50
+
+export function CounterClient(): ReactNode {
+  const { state, push, events, index, connection } = useSession()
+  const [error, setError] = useState<string | null>(null)
+  const visibleEvents = events.slice(-ACTIVITY_LIMIT)
+
+  const change = async (type: CounterEventType): Promise<void> => {
+    setError(null)
+    try {
+      const event =
+        type === 'incremented'
+          ? { type: 'incremented' as const, payload: {} }
+          : { type: 'decremented' as const, payload: {} }
+      await push(event)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <article>
+      <header className="session-header">
+        <h1>Counter</h1>
+        <ConnectionPill connection={connection} />
+        <span className="badge live">shared</span>
+      </header>
+      <p className="lede">
+        Every click appends one fact to a durable log. This page folds those
+        facts into a value on the server for the first paint, then keeps folding
+        the live stream in your browser.
+      </p>
+
+      <section className="counter-panel" aria-label="Shared counter controls">
+        <output className="counter-value" aria-live="polite">
+          {state.value}
+        </output>
+        <div className="counter-actions">
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void change('decremented')}
+          >
+            −1
+          </button>
+          <button type="button" onClick={() => void change('incremented')}>
+            +1
+          </button>
+        </div>
+      </section>
+
+      {error ? <p className="error">{error}</p> : null}
+      <p className="hint">
+        Pushes apply optimistically, then reconcile with the server. Open this
+        page in another tab and both counters converge on the same shared log.
+      </p>
+
+      <ActivityFeed events={visibleEvents} index={index} />
+      {events.length > ACTIVITY_LIMIT ? (
+        <p className="hint">Showing the latest {ACTIVITY_LIMIT} events.</p>
+      ) : null}
+    </article>
+  )
+}