experimental-a2 0.18.1 → 0.20.0

package/docs/stores/04-postgres.mdx

@@ -0,0 +1,121 @@
+---
+title: Postgres
+description: Any Postgres database. You create A2's tables; A2 never changes your schema.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/store-postgres'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+```package-install
+npm i pg
+```
+
+Works with Neon, Supabase, RDS, or your own server, including transaction-mode
+poolers.
+
+## Create the tables
+
+A2 doesn't create tables in your database. This is the SQL it needs:
+[`schema.sql`](https://github.com/vercel-labs/a2/blob/main/packages/a2/sql/postgres/schema.sql),
+also in the package at `node_modules/experimental-a2/sql/postgres/schema.sql`.
+Apply it once before your first deploy, however you run SQL against your
+database, as the role your app connects with.
+
+## Upgrade
+
+When a release changes the schema, its changelog says so. Apply that
+release's `schema.sql` before you deploy it. The version you're running keeps
+working against the new schema.
+
+If the tables are missing or out of date, the store's first query throws
+`STORE_NOT_CONFIGURED` naming the file to apply. Once it's applied, the next
+request works, with no redeploy. The store checks with one read before its
+first query, which never waits on or blocks writes.
+
+## Live updates (polling)
+
+By default, live streams poll every 25ms while a session is busy, backing off
+to every two seconds when it's quiet, so an update from another client can take
+up to two seconds, plus query latency, to reach a quiet stream. A client's own
+`push()` refreshes its stream immediately, even when the write and the stream
+run in different invocations.
+
+## Live updates (notifications)
+
+For instant updates, pass `listenConnectionString`, a direct connection to the
+same database (not through a pooler), and apply
+[`notifications.sql`](https://github.com/vercel-labs/a2/blob/main/packages/a2/sql/postgres/notifications.sql)
+once, the same way as `schema.sql`.
+
+Its triggers notify listeners of every write, including writes from stores
+without the option. Notifications arrive after commit, a reconnect catches up
+from the cursor, and subscriptions also reconcile every ten seconds. Every
+serverless instance opens its own direct connection, so leave connection
+headroom.
+
+## Use postgres.js
+
+`connectionString` creates a `pg` pool. To use
+[postgres.js](https://github.com/porsager/postgres) instead, wrap it as
+`client`:
+
+```ts server/store.ts
+import postgresJs from 'postgres'
+import { postgres } from 'experimental-a2/store-postgres'
+
+const url = process.env.DATABASE_URL
+if (!url) throw new Error('set DATABASE_URL')
+
+const sql = postgresJs(url, {
+  // A2 sends JSON as text; this keeps postgres.js from encoding it again.
+  types: {
+    json: {
+      to: 114,
+      from: [114, 3802],
+      serialize: (x: unknown) => (typeof x === 'string' ? x : JSON.stringify(x)),
+      parse: (x: string) => JSON.parse(x),
+    },
+  },
+})
+
+export const store = postgres({
+  client: {
+    query: async (text, values = []) => ({
+      rows: [...(await sql.unsafe(text, values))],
+    }),
+    connect: async () => {
+      const connection = await sql.reserve()
+      return {
+        query: async (text, values = []) => ({
+          rows: [...(await connection.unsafe(text, values))],
+        }),
+        release: () => connection.release(),
+      }
+    },
+    end: () => sql.end(),
+  },
+})
+```
+
+`listenConnectionString` still opens its listener with `pg`, so live
+notifications need `pg` installed too.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `connectionString` | creates a `pg` pool, shared by stores with the same settings |
+| `client` | your own pool instead: a `pg` `Pool`, PGlite, or a pooler wrapper. Its lifecycle is yours |
+| `listenConnectionString` | a direct connection for notifications |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/05-sqlite.mdx

@@ -0,0 +1,34 @@
+---
+title: SQLite
+description: The development default, in a file at `.a2/dev.db`.
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { sqlite } from 'experimental-a2/store-sqlite'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: sqlite({ path: '.a2/orders.db' }),
+  handlers: {
+    /* ... */
+  },
+})
+```
+
+In development, a server without a `store` uses SQLite at `.a2/dev.db`, so
+your sessions survive `next dev` restarts. Pass it yourself to pick another
+file.
+
+It runs on `node:sqlite`, with no dependencies, and creates its tables when it
+opens the file. It's for development: a serverless filesystem doesn't last or
+share one file across instances, so production needs another
+[store](/stores/overview).
+
+## Options
+
+| Option | |
+| --- | --- |
+| `path` | the database file. Default `.a2/dev.db`; `:memory:` works |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/06-memory.mdx

@@ -0,0 +1,22 @@
+---
+title: Memory
+description: An in-process store for tests, the default when `NODE_ENV=test`.
+---
+
+```ts
+// in a test:
+import { createServer } from 'experimental-a2/server'
+import { memory } from 'experimental-a2/store-memory'
+import { orders } from '@/contracts'
+
+const ordersServer = createServer({ contract: orders, store: memory() })
+```
+
+Sessions live in the process and vanish when it exits. Under `NODE_ENV=test`, a
+server without a `store` already uses memory.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `clock`, `ids` | test seams for timestamps and generated event ids |

package/docs/stores/meta.ts

@@ -0,0 +1 @@
+export default { order: 4 }

package/examples/playground/DEPLOY.md

@@ -2,8 +2,9 @@
 
 The event log runs with zero setup in development (SQLite at `.a2/dev.db`,
 no scheduler). The Agent demo and A0 also need AI Gateway and Vercel Sandbox
-credentials. Production needs the deliberate pieces from
-`node_modules/experimental-a2/docs/server/05-production.mdx`.
+credentials. Production needs a store
+(`node_modules/experimental-a2/docs/stores/01-overview.mdx`) and a scheduler
+(`node_modules/experimental-a2/docs/schedulers/01-overview.mdx`).
 
 ## 1. A store
 
@@ -23,7 +24,12 @@ Redis, poll cadence elsewhere. Upstash is durable by default; use its TCP
 `rediss://` URL, not the REST one. Each feature creates its own server with
 the shared store; storage remains namespaced per contract. Without either variable, a
 production boot fails fast with `STORE_NOT_CONFIGURED` (by design).
-Schemas/keys are created lazily on first use; no migration step.
+Redis needs no setup. With Postgres, create A2's tables once before the
+first deploy (A2 never creates them at runtime):
+
+```sh
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/experimental-a2/sql/postgres/schema.sql
+```
 
 To verify a provider before leaning on it, run the full conformance
 kit against it (throwaway database; the suite isolates by key prefix
@@ -105,8 +111,8 @@ A sandbox stays up while it's used: each tool call keeps it running at least
 10 more minutes, and so does the preview while it's on screen. Otherwise it
 stops, and resumes with its files the next time it's needed. A new or resumed
 sandbox starts `next dev` in the background, so commands don't wait for it;
-the preview does. Deleting an app stops its turn and deletes its sandbox; its
-conversation stays in the log. An app nobody uses for 14 days loses its files.
+the preview does. Deleting an app clears its conversation from the log and
+deletes its sandbox. An app nobody uses for 14 days loses its files.
 
 App ids are the only access control: anyone with an A0 URL can open that app,
 and anyone who can reach the deployment can start new apps, each with its own
@@ -116,6 +122,14 @@ of a public deployment. A0's sandboxes are named `a2-a0-*`, which is where to
 look when cleaning up. The sidebar lists the apps this browser opened, from a
 cookie.
 
+Files attached in A0's chat upload from the browser straight to a public
+Vercel Blob store, through a token from `/a0/uploads`. Connect a Blob store to
+the project, which sets `BLOB_READ_WRITE_TOKEN`; `vercel env pull` brings it
+to local runs. Images go to the model with the message; other files go into
+its text as links, which the agent downloads in its sandbox. Each lives at an
+unguessable public URL under `a0/<app id>/`, which anyone with the URL can
+read. Nothing deletes them, not even deleting their app.
+
 A0's dev tools have a Crash button, which ends the function instance running
 an app's agent, mid-turn, so the scheduler resumes the turn in a fresh one.
 Crashing ends everything else that instance is serving, and under `next dev`

package/examples/playground/app/a0/a0.css

@@ -345,10 +345,140 @@ body:has(.a0-splitter[data-dragging]) iframe {
 .a0-text[data-role='user'] {
   align-self: flex-end;
   padding: 0.5rem 0.75rem;
+  overflow-wrap: anywhere;
   background: var(--shade);
   color: var(--ink);
 }
 
+/* ── attachments ─────────────────────────────────────────────────── */
+
+.a0-chat-drop {
+  display: contents;
+}
+
+/* Over the whole chat column, which positions it. */
+.a0-drop {
+  position: absolute;
+  z-index: 2;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  background: color-mix(in oklab, var(--bg) 85%, transparent);
+  outline: 2px dashed var(--muted);
+  outline-offset: -0.75rem;
+  color: var(--bright);
+  pointer-events: none;
+}
+
+.a0-files {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  max-width: 85%;
+}
+
+.a0-files[data-role='user'] {
+  align-self: flex-end;
+  justify-content: flex-end;
+}
+
+.a0-files[data-role='assistant'] {
+  align-self: flex-start;
+}
+
+.a0-files img {
+  display: block;
+  max-width: 12rem;
+  max-height: 9rem;
+  border: 1px solid var(--line);
+  object-fit: cover;
+}
+
+.a0-file {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  color: inherit;
+  text-decoration: underline dotted var(--faint);
+  text-underline-offset: 3px;
+  vertical-align: bottom;
+}
+
+.a0-files .a0-file {
+  padding: 0.25rem 0.5rem;
+  border: 1px dashed var(--line);
+  text-decoration: none;
+}
+
+.a0-attachments {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+  margin: 0;
+  padding: 0.625rem 0.75rem 0;
+  list-style: none;
+  font-size: 0.75rem;
+}
+
+.a0-attachments li {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+  max-width: 100%;
+  color: var(--muted);
+}
+
+.a0-attachments li[data-kind='link'] {
+  height: 1.75rem;
+  padding-left: 0.5rem;
+  border: 1px dashed var(--line);
+}
+
+.a0-attachments li[data-kind='link'] span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.a0-attachments img {
+  display: block;
+  width: 3rem;
+  height: 3rem;
+  border: 1px solid var(--line);
+  object-fit: cover;
+}
+
+.a0-attachments li[data-kind='image'][data-uploading] img {
+  opacity: 0.5;
+}
+
+/* On the thumbnail's corners: the spinner, and the button that removes it. */
+.a0-attachments li[data-kind='image'] .a0-spin {
+  position: absolute;
+  top: calc(50% - 6px);
+  left: calc(1.5rem - 6px);
+}
+
+.a0-attachments li[data-kind='image'] .a0-icon-button {
+  position: absolute;
+  top: -0.375rem;
+  right: -0.375rem;
+  width: 1.125rem;
+  height: 1.125rem;
+  border: 1px solid var(--line);
+  border-radius: 50%;
+  background: var(--bg);
+}
+
+.a0-attachments li[data-kind='link'] .a0-icon-button {
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
 .a0-text[data-role='assistant'] {
   align-self: flex-start;
   color: var(--muted);
@@ -428,6 +558,86 @@ body:has(.a0-splitter[data-dragging]) iframe {
   white-space: nowrap;
 }
 
+/* A tool step that shows what the call writes, folded once it's done. */
+.a0-tool {
+  align-self: stretch;
+  min-width: 0;
+}
+
+.a0-tool summary {
+  width: fit-content;
+  cursor: pointer;
+  list-style: none;
+}
+
+.a0-tool summary::-webkit-details-marker {
+  display: none;
+}
+
+.a0-tool summary:hover .a0-step-label {
+  color: var(--ink);
+}
+
+.a0-tool[data-failed] summary,
+.a0-tool[data-failed] .a0-step-label {
+  color: var(--danger);
+}
+
+.a0-tool-text {
+  max-height: 14rem;
+  margin: 0.375rem 0 0 1.125rem;
+  padding: 0.5rem 0.625rem;
+  overflow: auto;
+  background: color-mix(in oklab, var(--shade) 60%, transparent);
+  color: var(--muted);
+  font-size: 0.6875rem;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+  scrollbar-color: var(--faint) transparent;
+  scrollbar-width: thin;
+  white-space: pre-wrap;
+}
+
+/* Messages waiting for the turn to end, just above the composer. */
+.a0-queue {
+  display: flex;
+  flex-shrink: 0;
+  flex-direction: column;
+  gap: 0.25rem;
+  margin: 0 0.75rem;
+  padding: 0;
+  list-style: none;
+  font-size: 0.75rem;
+}
+
+.a0-queue li {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.25rem 0.25rem 0.25rem 0.625rem;
+  border: 1px dashed var(--line);
+  color: var(--muted);
+}
+
+.a0-queue span {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.a0-queue button {
+  height: 1.375rem;
+  padding: 0 0.375rem;
+}
+
+.a0-queue .a0-icon-button {
+  width: 1.375rem;
+  padding: 0;
+  color: var(--faint);
+}
+
 .a0-send-error {
   margin: 0;
   padding: 0 1.25rem 0.5rem;
@@ -533,16 +743,45 @@ body:has(.a0-splitter[data-dragging]) iframe {
   gap: 0.5rem;
 }
 
-.a0-queued {
-  color: var(--faint);
-  font-size: 0.75rem;
-}
-
 .a0-composer-actions button {
   height: 1.75rem;
   padding: 0 0.625rem;
 }
 
+.a0-composer-actions > .a0-icon-button {
+  padding: 0;
+}
+
+/* Pause or resume, then stop, as a player's buttons. */
+.a0-player {
+  display: flex;
+  align-items: center;
+  gap: 0.125rem;
+}
+
+.a0-composer-actions .a0-player button {
+  width: 1.75rem;
+  padding: 0;
+  color: var(--muted);
+}
+
+/* Send, or during a turn Steer or Queue with its mode on the chevron. */
+.a0-send {
+  display: flex;
+  align-items: center;
+  gap: 1px;
+}
+
+.a0-composer-actions .a0-send-mode {
+  width: 1.5rem;
+  padding: 0;
+}
+
+.a0-menu-check {
+  margin-right: 0.375rem;
+  vertical-align: -0.125rem;
+}
+
 .a0-ghost {
   color: var(--muted);
 }

package/examples/playground/app/a0/app-view.tsx

@@ -44,11 +44,12 @@ export function AppView({
       <section aria-label="Chat" className="a0-chat">
         <h1 className="a0-title">{name}</h1>
         <Chat
+          appId={appId}
           harness={harness}
           onPrompt={(text) =>
             prompted({
               id: appId,
-              name: titleFromPrompt(prompt ?? text),
+              name: titleFromPrompt(prompt || text),
               harness,
             })
           }

package/examples/playground/app/a0/apps/[appId]/route.ts

@@ -1,11 +1,11 @@
-import { inputs } from 'experimental-a2/ai'
 import { isAppId } from '../../apps'
 import { deleteAppSandbox } from '../../sandbox'
 import { agentServers } from '../../server'
 
 /**
- * Stops the agent's current turn, so no later tool call brings the sandbox
- * back, then deletes it. The conversation stays in the A2 log.
+ * Deletes the app: its conversation, then its sandbox. A clear reads no
+ * state, so it also deletes a log this A2 can no longer fold, and no pending
+ * step of the old conversation runs to bring the sandbox back.
  */
 export async function DELETE(
   _request: Request,
@@ -14,14 +14,10 @@ export async function DELETE(
   const { appId } = await context.params
   if (!isAppId(appId))
     return Response.json({ error: 'Unknown app.' }, { status: 404 })
-  // The app's agent is whichever harness's agent has its log.
+  // Only one harness's agent has the app's log; clearing the others writes
+  // nothing.
   await Promise.all(
-    Object.values(agentServers).map(async (server) => {
-      const session = server.session(appId)
-      const { state } = await session.state()
-      if (state.active)
-        await session.append(...inputs.stop({ turnId: state.active.turnId }))
-    }),
+    Object.values(agentServers).map((server) => server.session(appId).clear()),
   )
   await deleteAppSandbox({ appId })
   return Response.json({ ok: true })

package/examples/playground/app/a0/attachments.ts

@@ -0,0 +1,133 @@
+'use client'
+import { upload as uploadToBlob } from '@vercel/blob/client'
+import type { FileUIPart } from 'ai'
+import { useEffect, useRef, useState } from 'react'
+import { isAttachmentUrl } from './model'
+
+/**
+ * A file the user attached. An image goes out with the message, for the
+ * model to see; any other file goes into the message's text as a link, which
+ * the agent downloads in its sandbox.
+ */
+export type Attachment = {
+  id: string
+  file: File
+  kind: 'image' | 'link'
+  /** Once Blob has it. */
+  part?: FileUIPart
+}
+
+export type Attachments = {
+  list: Attachment[]
+  add: (files: File[]) => void
+  /** Stops its upload, if it's still running. */
+  remove: (id: string) => void
+  clear: () => void
+  /** Puts back what a failed send took, before anything attached since. */
+  restore: (sent: Attachment[]) => void
+}
+
+const isImage = (file: File): boolean => file.type.startsWith('image/')
+
+/** Uploads straight to Blob, with a token from the app's uploads route. */
+async function upload({
+  appId,
+  file,
+  signal,
+}: {
+  appId: string
+  file: File
+  signal: AbortSignal
+}): Promise<FileUIPart> {
+  const blob = await uploadToBlob(`a0/${appId}/${file.name}`, file, {
+    access: 'public',
+    handleUploadUrl: '/a0/uploads',
+    clientPayload: appId,
+    ...(file.type ? { contentType: file.type } : {}),
+    abortSignal: signal,
+  }).catch((cause: unknown) => {
+    throw new Error(
+      `Couldn't upload ${file.name}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause },
+    )
+  })
+  return {
+    type: 'file',
+    mediaType: blob.contentType,
+    filename: file.name,
+    url: blob.url,
+  }
+}
+
+/** The line a file that isn't an image adds to the message. */
+const linkLine = (part: FileUIPart): string =>
+  `${part.filename ?? 'file'}: ${part.url}`
+
+/** One of the composer's link lines, as the file it names. */
+export function attachedLink(
+  line: string,
+): { name: string; url: string } | null {
+  const match = /^(.+): (https:\/\/\S+)$/.exec(line)
+  return match?.[1] && match[2] && isAttachmentUrl(match[2])
+    ? { name: match[1], url: match[2] }
+    : null
+}
+
+/** The files attached to the next message, each uploading as it's added. */
+export function useAttachments({
+  appId,
+  onLink,
+  onError,
+}: {
+  appId: string
+  /** A file that isn't an image finished uploading: its line for the text. */
+  onLink: (line: string) => void
+  onError: (cause: unknown) => void
+}): Attachments {
+  const [list, setList] = useState<Attachment[]>([])
+  // The uploads still running, which removing their file or leaving the app
+  // stops.
+  const uploads = useRef(new Map<string, AbortController>())
+  useEffect(() => {
+    const running = uploads.current
+    return () => {
+      for (const controller of running.values()) controller.abort()
+    }
+  }, [])
+  const drop = (id: string): void =>
+    setList((current) => current.filter((item) => item.id !== id))
+  const attach = async (file: File): Promise<void> => {
+    const id = crypto.randomUUID()
+    const kind = isImage(file) ? 'image' : 'link'
+    const controller = new AbortController()
+    uploads.current.set(id, controller)
+    setList((current) => [...current, { id, file, kind }])
+    try {
+      const part = await upload({ appId, file, signal: controller.signal })
+      if (kind === 'link') {
+        drop(id)
+        onLink(linkLine(part))
+      } else
+        setList((current) =>
+          current.map((item) => (item.id === id ? { ...item, part } : item)),
+        )
+    } catch (cause) {
+      drop(id)
+      if (!controller.signal.aborted) onError(cause)
+    } finally {
+      uploads.current.delete(id)
+    }
+  }
+  return {
+    list,
+    add: (files) => {
+      for (const file of files) void attach(file)
+    },
+    remove: (id) => {
+      uploads.current.get(id)?.abort()
+      drop(id)
+    },
+    clear: () => setList([]),
+    restore: (sent) => setList((current) => [...sent, ...current]),
+  }
+}