experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/a2slack/ui/Sidebar.tsx

@@ -0,0 +1,199 @@
+'use client'
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import Link from 'next/link'
+import { usePathname, useRouter } from 'next/navigation'
+import { SiteNav } from '@/app/components/site-header'
+import { channelIdSchema } from '@/app/a2slack/model'
+import { useIdentity } from '../identity'
+import { useWorkspace } from '../sessions'
+import { useInboxPanel } from './InboxContext'
+import { useSearch } from './SearchContext'
+
+const MIN_WIDTH = 180
+const MAX_WIDTH = 400
+const WIDTH_KEY = 'a2slack-sidebar-width'
+
+function slugify(raw: string): string {
+  return raw
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/^-+/, '')
+    .slice(0, 32)
+}
+
+type SidebarSession = ReturnType<typeof useWorkspace> & {
+  state: NonNullable<ReturnType<typeof useWorkspace>['state']>
+}
+
+export function Sidebar(): ReactNode {
+  const session = useWorkspace()
+  if (session.state === undefined) {
+    const error =
+      'error' in session.connection ? session.connection.error : null
+    return (
+      <p className="a2slack-loading" role="status">
+        {error?.message ?? 'Loading…'}
+      </p>
+    )
+  }
+  return <SidebarView session={{ ...session, state: session.state }} />
+}
+
+function SidebarView({
+  session,
+}: Record<never, never> & { session: SidebarSession }): ReactNode {
+  const identity = useIdentity()
+  const search = useSearch()
+  const inbox = useInboxPanel()
+  const { state, push } = session
+  const pathname = usePathname()
+  const router = useRouter()
+  const [draft, setDraft] = useState('')
+  const [width, setWidth] = useState(224)
+  const [resizing, setResizing] = useState(false)
+  const startRef = useRef({ x: 0, width: 224 })
+
+  useEffect(() => {
+    const stored = Number(localStorage.getItem(WIDTH_KEY))
+    if (stored >= MIN_WIDTH && stored <= MAX_WIDTH) setWidth(stored)
+  }, [])
+
+  const create = (): void => {
+    const id = slugify(draft)
+    if (!identity || !channelIdSchema.safeParse(id).success) return
+    if (!state.channels.includes(id)) {
+      push({ type: 'channel.created', payload: { id, by: identity } }).catch(
+        () => {},
+      )
+    }
+    setDraft('')
+    search.clear()
+    inbox.setOpen(false)
+    router.push(`/a2slack/c/${id}`)
+  }
+
+  return (
+    <nav className="a2slack-sidebar" style={{ width }}>
+      <div className="site-header a2slack-head">
+        <SiteNav />
+      </div>
+      <form
+        className="a2slack-form a2slack-search"
+        role="search"
+        onSubmit={(e) => {
+          e.preventDefault()
+          search.submit()
+        }}
+      >
+        <input
+          ref={search.input}
+          className="a2slack-input"
+          aria-label="search messages"
+          enterKeyHint="search"
+          placeholder="search…"
+          value={search.query}
+          onChange={(e) => {
+            search.setQuery(e.target.value)
+            inbox.setOpen(false)
+          }}
+          onKeyDown={(e) => {
+            if (e.key !== 'Escape') return
+            e.preventDefault()
+            search.clear()
+          }}
+        />
+      </form>
+      <div className="a2slack-list">
+        <button
+          type="button"
+          className="a2slack-channel a2slack-inbox-row"
+          aria-current={inbox.open ? 'page' : undefined}
+          aria-label={`inbox, ${inbox.unread} unread`}
+          onClick={() => {
+            search.clear()
+            inbox.setOpen(!inbox.open)
+          }}
+        >
+          <span>inbox</span>
+          {inbox.unread > 0 && (
+            <span className="a2slack-unread">{inbox.unread}</span>
+          )}
+        </button>
+        <span className="a2slack-label a2slack-label-spaced">channels</span>
+        {state.channels.map((id) => (
+          <Link
+            key={id}
+            href={`/a2slack/c/${id}`}
+            className="a2slack-channel"
+            aria-current={
+              !inbox.open && pathname === `/a2slack/c/${id}`
+                ? 'page'
+                : undefined
+            }
+            onClick={() => {
+              search.clear()
+              inbox.setOpen(false)
+            }}
+          >
+            #{id}
+          </Link>
+        ))}
+      </div>
+      <form
+        className="a2slack-form"
+        onSubmit={(e) => {
+          e.preventDefault()
+          create()
+        }}
+      >
+        <input
+          className="a2slack-input"
+          placeholder="+ new channel"
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+        />
+      </form>
+      {identity && (
+        <div className="a2slack-you">
+          <span>you: {identity.name}</span>
+          <Link className="a2slack-lag-link" href="/a2slack/lag">
+            lag
+          </Link>
+        </div>
+      )}
+      <div
+        className="a2slack-handle"
+        onPointerDown={(e) => {
+          e.preventDefault()
+          startRef.current = { x: e.clientX, width }
+          setResizing(true)
+          e.currentTarget.setPointerCapture(e.pointerId)
+        }}
+        onPointerMove={(e) => {
+          if (!resizing) return
+          const next = Math.min(
+            MAX_WIDTH,
+            Math.max(
+              MIN_WIDTH,
+              startRef.current.width + e.clientX - startRef.current.x,
+            ),
+          )
+          setWidth(next)
+        }}
+        onPointerUp={(e) => {
+          if (!resizing) return
+          setResizing(false)
+          e.currentTarget.releasePointerCapture(e.pointerId)
+          localStorage.setItem(WIDTH_KEY, String(width))
+        }}
+      >
+        <span
+          className="a2slack-handle-line"
+          data-active={resizing || undefined}
+        />
+      </div>
+    </nav>
+  )
+}

package/examples/playground/app/a2slack/ui/ThreadPanel.tsx

@@ -0,0 +1,134 @@
+'use client'
+import { useEffect, useMemo, useState, type ReactNode } from 'react'
+import { X } from 'lucide-react'
+import {
+  liveThread,
+  type ChatMessage,
+  type ThreadPage,
+} from '@/app/a2slack/model'
+import { useWorkspace } from '../sessions'
+import { Composer } from './Composer'
+import { useInboxPanel } from './InboxContext'
+import { MessageRow } from './MessageRow'
+
+/**
+ * One thread, read from `/a2slack/thread` when it opens and kept live from
+ * the workspace's events. Until the read answers it shows the root as the
+ * feed has it, if the feed has it.
+ */
+export function ThreadPanel({
+  channel,
+  rootId,
+  known,
+  onClose,
+}: {
+  channel: string
+  rootId: string
+  /** The root, live, when it's on the channel's newest page. */
+  known: ChatMessage | null
+  onClose: () => void
+}): ReactNode {
+  const { events } = useWorkspace()
+  const inbox = useInboxPanel()
+  const [page, setPage] = useState<ThreadPage | null>(null)
+  const [failed, setFailed] = useState(false)
+
+  useEffect(() => {
+    const controller = new AbortController()
+    const read = async (): Promise<void> => {
+      try {
+        const response = await fetch(
+          `/a2slack/thread?root=${encodeURIComponent(rootId)}`,
+          { signal: controller.signal },
+        )
+        if (!response.ok) throw new Error(`thread: ${response.status}`)
+        setPage((await response.json()) as ThreadPage)
+      } catch {
+        if (!controller.signal.aborted) setFailed(true)
+      }
+    }
+    void read()
+    return () => controller.abort()
+  }, [rootId])
+
+  const thread = useMemo(
+    () => (page ? liveThread(page, events, rootId) : null),
+    [page, events, rootId],
+  )
+  const root = thread?.root ?? known
+  const replies = thread?.replies ?? []
+
+  // Reading the thread reads its notifications, including any that arrive
+  // while it's open.
+  const unread =
+    inbox.items.find((item) => item.threadId === rootId)?.unread ?? 0
+  const { markRead } = inbox
+  useEffect(() => {
+    if (unread > 0) markRead(rootId)
+  }, [unread, rootId, markRead])
+
+  return (
+    <aside className="a2slack-thread">
+      <header className="a2slack-thread-header">
+        <span className="a2slack-thread-title">thread</span>
+        <button className="a2slack-close" onClick={onClose} title="close">
+          <X size={15} strokeWidth={1.75} />
+        </button>
+      </header>
+      <div className="a2slack-thread-scroll">
+        {root === null ? (
+          <div className="a2slack-divider">
+            <span>
+              {failed
+                ? "this thread didn't load"
+                : page
+                  ? 'this message is gone'
+                  : 'loading…'}
+            </span>
+            <span className="a2slack-divider-line" />
+          </div>
+        ) : (
+          <>
+            <MessageRow message={root} grouped={false} inThread />
+            <div className="a2slack-divider">
+              <span>
+                {root.replyCount === 0
+                  ? 'no replies yet'
+                  : `${root.replyCount} ${root.replyCount === 1 ? 'reply' : 'replies'}`}
+                {thread === null &&
+                  root.replyCount > 0 &&
+                  (failed ? " · these didn't load" : ' · loading…')}
+              </span>
+              <span className="a2slack-divider-line" />
+            </div>
+            {replies.map((reply, i) => {
+              const prev = replies[i - 1]
+              const grouped =
+                prev !== undefined &&
+                !prev.deleted &&
+                prev.author.id === reply.author.id &&
+                Date.parse(reply.at) - Date.parse(prev.at) < 5 * 60 * 1000
+              return (
+                <MessageRow
+                  key={reply.id}
+                  message={reply}
+                  grouped={grouped}
+                  inThread
+                />
+              )
+            })}
+          </>
+        )}
+      </div>
+      {root !== null && (
+        <Composer
+          channel={channel}
+          threadId={root.id}
+          placeholder="reply… or ask @bot"
+          autoFocus
+          compact
+        />
+      )}
+    </aside>
+  )
+}

package/examples/playground/app/a2slack/ui/useInbox.ts

@@ -0,0 +1,71 @@
+'use client'
+import { useEffect, useMemo, useState } from 'react'
+import { liveInbox, type InboxItem, type InboxPage } from '@/app/a2slack/model'
+import { useWorkspace } from '../sessions'
+
+export type Inbox = {
+  /** One per thread with news for `me`, newest first. */
+  items: InboxItem[]
+  /** Unread notifications across every thread. */
+  unread: number
+  /** The page hasn't answered yet. */
+  loading: boolean
+  error: string | null
+}
+
+/**
+ * `me`'s inbox: the page `/a2slack/inbox` read, kept live from the
+ * workspace's events after it. A new `me` reads a new page.
+ */
+export function useInbox(me: string | null): Inbox {
+  const { events } = useWorkspace()
+  const [read, setRead] = useState<{
+    me: string
+    page: InboxPage | null
+    error: string | null
+  } | null>(null)
+
+  useEffect(() => {
+    if (me === null) return
+    const controller = new AbortController()
+    const load = async (): Promise<void> => {
+      try {
+        const response = await fetch(
+          `/a2slack/inbox?user=${encodeURIComponent(me)}`,
+          { signal: controller.signal },
+        )
+        const body = (await response.json().catch(() => ({}))) as
+          InboxPage | { error?: string }
+        if (response.ok && 'items' in body) {
+          setRead({ me, page: body, error: null })
+          return
+        }
+        const error = 'error' in body ? body.error : undefined
+        setRead({
+          me,
+          page: null,
+          error: error ?? `the inbox failed (${response.status})`,
+        })
+      } catch {
+        if (controller.signal.aborted) return
+        setRead({ me, page: null, error: "the inbox didn't answer" })
+      }
+    }
+    void load()
+    return () => controller.abort()
+  }, [me])
+
+  const current = me !== null && read?.me === me ? read : null
+  const items = useMemo(
+    () =>
+      current?.page && me !== null ? liveInbox(current.page, events, me) : [],
+    [current, events, me],
+  )
+
+  return {
+    items,
+    unread: items.reduce((sum, item) => sum + item.unread, 0),
+    loading: me !== null && current === null,
+    error: current?.error ?? null,
+  }
+}

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

@@ -3,7 +3,7 @@ import { Buffer } from 'node:buffer'
 import { createHash } from 'node:crypto'
 import { Sandbox } from '@vercel/sandbox'
 import { tool } from 'ai'
-import { handlerContext, inputs } from 'experimental-a2/ai'
+import { consumerContext, inputs } from 'experimental-a2/ai'
 import { agent } from 'experimental-a2/ai/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
 import { otel } from 'experimental-a2/otel'
@@ -45,7 +45,7 @@ const tools = {
       command: z.string().min(1).describe('The Bash command to execute.'),
     }),
     execute: async ({ command }) => {
-      const context = handlerContext(demoAgent)
+      const context = consumerContext(demoAgent)
       const sandbox = await Sandbox.getOrCreate({
         name: sandboxName(context.session.id),
         persistent: true,
@@ -109,7 +109,7 @@ const tools = {
       reminder: z.string().min(1).max(500),
     }),
     execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
-      const context = handlerContext(demoAgent)
+      const context = consumerContext(demoAgent)
       await context.session.schedule(
         `reminder:${toolCallId}`,
         { delay: `${delaySeconds}s` },

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

@@ -488,7 +488,7 @@ export function ChatClient({
       inputRef.current?.focus({ preventScroll: true }),
     )
     try {
-      // The browser authors only the room fact. A serialized server handler
+      // The browser authors only the room fact. A serialized server consumer
       // derives AI metadata and generation policy from its durable log index.
       await push({
         type: 'message.sent',

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

@@ -1,10 +1,14 @@
 import 'server-only'
 import { tool } from 'ai'
 import { idempotentId } from 'experimental-a2'
-import { handlerContext, inputs } from 'experimental-a2/ai'
+import { consumerContext, inputs } from 'experimental-a2/ai'
 import { agent } from 'experimental-a2/ai/server'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { createServer, type A2Operation } from 'experimental-a2/server'
+import {
+  consumer,
+  createServer,
+  type A2Operation,
+} from 'experimental-a2/server'
 import { store } from '@/lib/store'
 import {
   chat,
@@ -22,7 +26,7 @@ const tools = {
       '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)
+      const context = consumerContext(chatAgent)
       context.signal.throwIfAborted()
       const { generationId, messageId } = context.event.payload.call
       // The agent's session shares the room's id. The explicit id makes a
@@ -114,42 +118,48 @@ Use as many post calls as the moment naturally calls for. Several short messages
   },
 })
 
-/** The room. Each message goes on to the agent's session, marked for whether it should answer. */
+/**
+ * Each room message goes on to the agent's session, marked for whether it
+ * should answer. One lane keeps the agent's messages in the room's order.
+ */
+const forwardToAgent = consumer({
+  contract: chat,
+  name: 'forward-to-agent',
+  types: ['message.sent'],
+  lane: 'a2.chat.ingress',
+}).run(async (context) => {
+  const ambient = (await context.session.state()).state.ambient.enabled
+  const { author, text } = context.event.payload
+  const mode: ChatParticipantMode = ambient
+    ? 'ambient'
+    : mentionsAgent(text)
+      ? 'mention'
+      : 'passive'
+  const message: ChatAgentMessage = {
+    // Derived from the room event's id, so a retried forward converges on
+    // the same message in the agent's session.
+    id: await idempotentId('chat.message', context.event.id),
+    role: 'user',
+    metadata: {
+      kind: 'participant',
+      author,
+      text,
+      sentAt: context.event.createdAt.toISOString(),
+      mode,
+    },
+    parts: [{ type: 'text', text: `${author}: ${text}` }],
+  }
+  await chatAgentServer
+    .session(context.session.id)
+    .append(...inputs.message(message, { generate: mode !== 'passive' }))
+})
+
+/** The room. Its messages reach the agent through `forwardToAgent`. */
 export const chatServer = createServer({
   ...(store ? { store } : {}),
   ...(chatScheduler ? { scheduler: chatScheduler } : {}),
   contract: chat,
-  handlers: {
-    'message.sent': {
-      lane: 'a2.chat.ingress',
-      handler: async (context) => {
-        const ambient = (await context.session.state()).state.ambient.enabled
-        const { author, text } = context.event.payload
-        const mode: ChatParticipantMode = ambient
-          ? 'ambient'
-          : mentionsAgent(text)
-            ? 'mention'
-            : 'passive'
-        const message: ChatAgentMessage = {
-          // Event ids are unique across a store's sessions, so the forward
-          // derives its own; a retried forward converges on the same id.
-          id: await idempotentId('chat.message', context.event.id),
-          role: 'user',
-          metadata: {
-            kind: 'participant',
-            author,
-            text,
-            sentAt: context.event.createdAt.toISOString(),
-            mode,
-          },
-          parts: [{ type: 'text', text: `${author}: ${text}` }],
-        }
-        await chatAgentServer
-          .session(context.session.id)
-          .append(...inputs.message(message, { generate: mode !== 'passive' }))
-      },
-    },
-  },
+  consumers: [forwardToAgent],
 })
 
 /** Room pushes: people's messages, typing, and ambient mode. Posts are the agent's. */

package/examples/playground/app/components/demo-icons.tsx

@@ -40,6 +40,13 @@ export const ChatIcon = (): ReactNode => (
   </Glyph>
 )
 
+export const A2slackIcon = (): ReactNode => (
+  <Glyph>
+    <path d="M3 4h18v13H10l-4 3.5V17H3z" />
+    <path className="accent" d="M10.5 7l-1 7M14.5 7l-1 7M8 9h8M7.5 12h8" />
+  </Glyph>
+)
+
 export const AgentIcon = (): ReactNode => (
   <Glyph>
     <rect x="3" y="3" width="18" height="18" />

package/examples/playground/app/components/demos.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import {
   A0Icon,
+  A2slackIcon,
   AgentIcon,
   CanvasIcon,
   ChatIcon,
@@ -24,6 +25,12 @@ export const demos: Demo[] = [
   { href: '/a0', name: 'A0', icon: <A0Icon />, fullWindow: true },
   { href: '/orders', name: 'Orders', icon: <OrdersIcon /> },
   { href: '/chat', name: 'Chat', icon: <ChatIcon /> },
+  {
+    href: '/a2slack',
+    name: 'a2slack',
+    icon: <A2slackIcon />,
+    fullWindow: true,
+  },
   { href: '/agent', name: 'Agent', icon: <AgentIcon /> },
   { href: '/canvas', name: 'Canvas', icon: <CanvasIcon /> },
   { href: '/documents', name: 'Documents', icon: <DocumentsIcon /> },

package/examples/playground/app/orders/[orderId]/order-client.tsx

@@ -118,7 +118,7 @@ export function OrderClient({ sessionId }: { sessionId: string }): ReactNode {
           <p className="hint">
             The button pushes <code>shop.started</code> optimistically — the
             badge flips before the server acks. Everything after that is
-            handlers appending the next fact: courier assigned, picked up,
+            consumers appending the next fact: courier assigned, picked up,
             delivered — watch it arrive over the stream, hands off.
           </p>
         </>
@@ -129,7 +129,7 @@ export function OrderClient({ sessionId }: { sessionId: string }): ReactNode {
         </p>
       ) : (
         <p className="hint">
-          Hands off from here — each status lands on its own as handlers append
+          Hands off from here — each status lands on its own as consumers append
           the next fact.
         </p>
       )}

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

@@ -8,7 +8,7 @@ export default function OrdersPage(): ReactNode {
       <p className="lede">
         Creating an order appends a single <code>created</code> event.
         Everything after that — the shop notification, the courier, the delivery
-        itself — is handlers appending the next fact to the same log, all the
+        itself — is consumers appending the next fact to the same log, all the
         way to <code>delivered</code>.
       </p>
       <NewOrderForm />