experimental-a2 0.18.0 → 0.18.1

package/docs/reference/04-ai.mdx

@@ -577,7 +577,10 @@ fx(): Harness<'fx'>
 The [FX](https://fx.sh) harness for `agent({ harness })`, running FX's kernel
 from `libfx` (an optional peer dependency) in the server process. FX adds no
 system prompt and brings no tools: `instructions` is the whole system prompt
-and the agent's `tools` are all FX can call. `reasoning` becomes FX's effort and
+and the agent's `tools` are all FX can call. A call's input goes through its
+tool's schema, as under `{ type: 'ai-sdk' }`: `execute` receives the schema's
+output, defaults included, and input the schema rejects goes back to the model
+as an error, without running the tool. `reasoning` becomes FX's effort and
 `speed: 'fast'` its fast tier. FX compacts its own context; a compaction
 appears in the transcript as a `data-a2-compaction` part with its summary.
 
@@ -607,12 +610,18 @@ agent session from `@earendil-works/pi-coding-agent` (with
 `@earendil-works/pi-ai`, both optional peer dependencies). Pi brings its system
 prompt and its `read`, `write`, `edit`, and `bash` tools, which run in the
 session's sandbox. `instructions` is added to Pi's prompt. The agent's `tools`
-are added to Pi's; a tool with one of their names replaces Pi's. `reasoning`
-becomes Pi's thinking level, and `model` is one of the Gateway models Pi's
-catalog lists. Pi works in the sandbox's working directory; its `bash` runs
-with the sandbox's environment, never the server's. Pi compacts its own
-context; a compaction appears in the transcript as a `data-a2-compaction` part
-with its summary.
+are added to Pi's; a tool with one of their names replaces Pi's. Every call
+first passes Pi's own checks: Pi coerces its arguments to the tool's JSON Schema
+(the string `"5"` becomes `5` for a number) and rejects what that schema
+forbids, such as a property it does not list. A call to one of the agent's tools
+then goes through the tool's schema, as under `{ type: 'ai-sdk' }`: `execute`
+receives the schema's output, defaults included. Input either check rejects goes
+back to the model as an error, without running the tool. `reasoning` becomes
+Pi's thinking level, and `model` is one of the Gateway models Pi's catalog
+lists. Pi works in the sandbox's working directory; its `bash` runs with the
+sandbox's environment, never the server's. Pi compacts its own context; a
+compaction appears in the transcript as a `data-a2-compaction` part with its
+summary.
 
 - `sandbox` (`HarnessSandbox`, given a `HarnessSandboxContext`) resolves the
   session's AI SDK sandbox session (`Experimental_SandboxSession` from `ai`).

package/docs/reference/05-adapters.mdx

@@ -104,8 +104,8 @@ mid-span.
 | `a2.ai.ack.report_id` | `a2.ai.ack` | start | work report event id, matching the control span's id |
 
 - Drain outcomes: `settled` means nothing actionable is left; `busy` means live
-  per-event claims remain; `stalled` means a caught failure needs a later
-  retry.
+  per-event claims or a failed event's retry hold remain; `stalled` means a
+  caught failure in this drain needs a later retry.
 - A failing handler marks its `a2.event` span with the exception and error
   status. Alert on `a2.event.outcome = dead_lettered`. A dead-lettered event
   blocks only later events in its lane, until `session.redrive()` resolves it;
@@ -294,8 +294,8 @@ export const POST = scheduler.handler(ordersServer, billingServer)
   signatures return 401.
 - A signed malformed envelope, or a declared or streamed body over
   `maxBodyBytes`, returns 489 with `Upstash-NonRetryable-Error: true`.
-- Returns 200 when settled; when busy, after a durable successor watchdog
-  exists; when stalled, after publishing a fresh successor, which resets the
+- Returns 200 when settled; when busy or stalled, after a durable successor
+  watchdog exists, so each caught failure gets a fresh message and a fresh
   per-message retry budget. Append tasks return 200 after their fixed-id append
   succeeds and any recovery watchdog for pending handler work is durable; clear
   tasks after their conditional clear and its deletion finish.

package/docs/server/01-handlers.mdx

@@ -192,7 +192,7 @@ records completion runs the handler again.
 ## When handlers throw
 
 Throwing means "retry me." A2 records the failure and retries with backoff.
-The failed event blocks only its lane. After ten caught failures it
+The failed event blocks only its lane. After ten failed attempts it
 dead-letters and keeps blocking its lane until
 [you retry or skip it](/server/production#3-when-an-event-dead-letters).
 

package/docs/server/03-cancellation.mdx

@@ -70,8 +70,9 @@ what stops it racing its successor outside A2.
 Pass `ctx.signal` to your I/O and let the abort propagate. That handles every
 case:
 
-- **A propagated lease abort** surrenders the attempt: no completion, no
-  failure budget spent, normal recovery.
+- **A propagated lease abort** surrenders the attempt: no completion, and
+  normal recovery. Like a crash, it costs the event one attempt of its
+  failure budget.
 - **A user cancellation** (`abortOn`) is the one to catch and return normally
   from. The stop is the outcome, so the completion counts.
 - **Return normally after a lease abort** only when the work is done. A lapsed

package/docs/server/05-production.mdx

@@ -241,7 +241,8 @@ import { ordersServer } from '@/server'
 const order = ordersServer.session(orderId)
 const [dead] = await order.deadLetters()
 if (dead) {
-  // dead.lastError says why; deploy the handler fix first, then:
+  // dead.lastError says why (null if every attempt timed out or crashed);
+  // deploy the handler fix first, then:
   await order.redrive(dead.index, { action: 'retry' })
 }
 ```

package/docs/server/06-guarantees.mdx

@@ -22,8 +22,9 @@ and the log decides what remains. Reads never dispatch handlers.
 Each claim expires. If its holder dies, the claim lapses and the next wakeup
 claims the event again with a larger `ctx.attempt`. The retry gets the same
 event id, index, type, and payload. A kill after the claim can use up an
-attempt before your code runs, but it doesn't count as a caught failure. An
-older attempt can never overwrite a newer one's completion or failure.
+attempt before your code runs, and that attempt counts toward the event's
+[failure budget](#when-a-handler-keeps-failing). An older attempt can never
+overwrite a newer one's completion or failure.
 
 :::note[Recovery is not an event]
 A2 does not append `recovered` or `continued`. Recovery retries the same event.
@@ -86,20 +87,28 @@ keeps its original cause.
 ## A chain that crosses the function timeout
 
 A function killed mid-handler restarts that handler from its entry point in a
-fresh invocation: same event, new attempt, no caught failure. Events already
-processed stay processed, so a chain of handlers can outlast one invocation,
-but each handler must fit in a fresh one. Split longer work into smaller
-events or increase the function duration. On Vercel, A2 caps the claim window
+fresh invocation: same event, new attempt. Events already processed stay
+processed, so a chain of handlers can outlast one invocation, but each handler
+must fit in a fresh one: an attempt that runs out of time is a failed attempt,
+and a handler that never fits dead-letters after ten. Split longer work into
+smaller events or increase the function duration. On Vercel, A2 caps the claim window
 at the function deadline when the platform exposes it, so a retry starts
-promptly after a timeout.
+promptly after a timeout. Once the deadline passes, A2 claims nothing more in
+that invocation, so a timeout costs the event one attempt.
 
 ## When a handler keeps failing
 
 A caught failure counts against that event, releases its claim, and leaves
-other eligible events running. A2 retries it with backoff. Ten caught failures
-dead-letter the event: later events in its lane stay blocked, while unlaned
-events and other lanes continue. Hard kills don't consume this budget.
-The event waits until you
+other eligible events running. A2 holds it back for a delay that starts at
+one second and doubles with each failed attempt up to 30 seconds, then retries
+it on the session's next wake. With a scheduler, that's a few seconds at first,
+then the delay itself. An attempt that ends before it finishes, because its
+process timed out, crashed, or lost its claim, counts too, once the next
+attempt takes its claim over. Ten failed attempts dead-letter the event: later
+events in its lane stay blocked, while unlaned events and other lanes continue.
+A crash costs every event it interrupts one attempt, so a session whose work
+keeps outrunning its function dead-letters: bound its fan-out, or put work that
+waits on the same resource in one lane. The event waits until you
 [retry or skip it](/server/production#3-when-an-event-dead-letters) with
 `session.redrive()`.
 

package/examples/playground/DEPLOY.md

@@ -118,10 +118,8 @@ cookie.
 
 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, so only preview
-deployments allow it, behind Deployment Protection. Set `A0_CRASHES=on` to
-allow it anywhere else. Under `next dev` that takes the dev server down with
-it, so it's for trying recovery, not for everyday local runs.
+Crashing ends everything else that instance is serving, and under `next dev`
+it takes the dev server down with it.
 
 ## 6. WebSockets for the canvas
 

package/examples/playground/app/a0/[appId]/page.tsx

@@ -4,7 +4,7 @@ import { AppView } from '../app-view'
 import { isAppId } from '../apps'
 import { DevTools } from '../devtools'
 import { harnessFrom, logPage } from '../model'
-import { agentServers, crashesAllowed } from '../server'
+import { agentServers } from '../server'
 import { SessionProvider } from '../session'
 
 /** An app, from its current state; the provider follows its log from there. */
@@ -40,13 +40,7 @@ export default async function A0App({
       <AppView
         appId={appId}
         harness={harness}
-        devtools={
-          <DevTools
-            appId={appId}
-            deployed={!!process.env.VERCEL}
-            crashesAllowed={crashesAllowed}
-          />
-        }
+        devtools={<DevTools appId={appId} deployed={!!process.env.VERCEL} />}
       />
     </SessionProvider>
   )

package/examples/playground/app/a0/devtools.tsx

@@ -20,12 +20,10 @@ const gap = (ms: number): string =>
 export function DevTools({
   appId,
   deployed,
-  crashesAllowed,
 }: {
   appId: string
   /** Function limits and crashes only mean something on Vercel. */
   deployed: boolean
-  crashesAllowed: boolean
 }): ReactNode {
   const { state, events, index, history, hydrated, loadHistory } = useSession()
   const short = useSearchParams().get('limit') === '5s'
@@ -83,12 +81,8 @@ export function DevTools({
           <button
             type="button"
             className="a0-ghost a0-devtools-crash"
-            disabled={!crashesAllowed || crashes.state}
-            title={
-              crashesAllowed
-                ? 'Ends the process running the agent, right now'
-                : 'Crashes need a preview deployment, or A0_CRASHES=on'
-            }
+            disabled={crashes.state}
+            title="Ends the process running the agent, right now"
             onClick={crash}
           >
             <Zap size={13} aria-hidden />

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

@@ -106,16 +106,14 @@ function chosenModel({
 }) {
   // Every step starts here, in the process that runs it, which is what
   // the dev tools' crash has to end.
-  if (crashesAllowed) {
-    const appId = event.sessionId
-    waitUntil(
-      crashOnRequest({
-        appId,
-        app: agentServers[harness].session(appId),
-        log: crashServer.session(crashLogId(appId)),
-      }).catch(() => {}),
-    )
-  }
+  const appId = event.sessionId
+  waitUntil(
+    crashOnRequest({
+      appId,
+      app: agentServers[harness].session(appId),
+      log: crashServer.session(crashLogId(appId)),
+    }).catch(() => {}),
+  )
   const { model, reasoning, fast } = state.modelChoice
   return { model, reasoning, speed: fast ? 'fast' : 'standard' } as const
 }
@@ -193,20 +191,11 @@ export const crashServer = createServer({
   contract: crashLog,
 })
 
-/**
- * A crash ends the function instance, and anything else it's serving, so
- * only previews allow it, behind Deployment Protection, unless A0_CRASHES
- * is on. Under next dev it would take the dev server down.
- */
-export const crashesAllowed =
-  process.env.VERCEL_ENV === 'preview' || process.env.A0_CRASHES === 'on'
-
 /** The browser can only ask for a crash; the process it ends records it. */
 export function crashEvents(request: Request): Promise<Response> {
   return crashServer.fetch(request, {
     authorize: (operation) =>
       isCrashLogId(operation.sessionId) &&
-      (crashesAllowed || operation.type !== 'push') &&
       (operation.type !== 'push' ||
         operation.events.every((event) => event.type === 'crash.requested')),
   })

package/examples/playground/package.json

@@ -28,7 +28,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.18.0",
+    "experimental-a2": "0.18.1",
     "geist": "^1.7.2",
     "ioredis": "^5.9.0",
     "libfx": "0.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Syncs your immutable event log, from server to browser: one contract, handlers, derived state, and a live client per session.",
   "license": "MIT",
   "type": "module",

package/src/ai-agent.ts

@@ -680,7 +680,15 @@ async function* consumeGeneration(options: {
     chunks: mergeDeltas(pending.splice(0)),
   })
   const reader = options.source.stream.getReader()
-  let pendingChunk = reader.read()
+  // The next read starts before a batch is yielded, and the consumer may
+  // take a while to ask again: a stream that fails meanwhile must not leave
+  // that read rejected with no handler, which ends the process.
+  const readAhead = (): Promise<StreamRead<UIMessageChunk>> => {
+    const read = reader.read()
+    read.catch(() => {})
+    return read
+  }
+  let pendingChunk = readAhead()
   try {
     for (;;) {
       let result: StreamRead<UIMessageChunk>
@@ -701,7 +709,7 @@ async function* consumeGeneration(options: {
       pending.push(chunk)
       if (chunk.type === 'finish') streamedFinishReason = chunk.finishReason
       if (chunk.type === 'error') streamedError = chunk.errorText
-      pendingChunk = reader.read()
+      pendingChunk = readAhead()
 
       if (pending.length >= maxChunks || isBoundaryChunk(pending.at(-1))) {
         yield batch()
@@ -712,7 +720,6 @@ async function* consumeGeneration(options: {
     if (pending.length > 0) yield batch()
     throw error
   } finally {
-    void pendingChunk.catch(() => {})
     try {
       await reader.cancel()
     } catch {

package/src/ai-fx.ts

@@ -30,6 +30,7 @@ import {
   saveHarness,
 } from './ai-harness.ts'
 import type { CompactionPartData, GenerationCompletedPayload } from './ai.ts'
+import { schemaInput } from './ai-tool-input.ts'
 import { boundedCache } from './bounded-cache.ts'
 
 export type { Harness } from './ai-harness.ts'
@@ -49,6 +50,7 @@ const SNAPSHOT_VERSION = 1
 const CATALOG_TTL_MS = 60 * 60 * 1000
 
 type StreamPart = { type: string } & Record<string, unknown>
+/** A recorded tool call, with the input the kernel reads from its text. */
 type ToolCall = { toolCallId: string; toolName: string; input: unknown }
 
 /** A model response A2 recorded, in the Gateway's stream format. */
@@ -108,6 +110,10 @@ async function runStep(step: HarnessStep): Promise<HarnessGeneration> {
 
   let completion: Completion = {}
   let stopped = false
+  // Live responses belong to the step: the kernel aborts its fetch once it
+  // has read a response's finish, while A2 may still be reading its copy.
+  const released = new AbortController()
+  const network = AbortSignal.any([step.signal, released.signal])
   let agent: FxAgent | undefined
   let turn: TurnState | undefined
 
@@ -245,9 +251,18 @@ async function runStep(step: HarnessStep): Promise<HarnessGeneration> {
     const response = await fetch(url, {
       ...init,
       headers: withAuth(init.headers, credential),
+      signal: network,
     })
+    // Abandoned before its headers came: the kernel has moved on without it.
+    if (init.signal?.aborted) {
+      void response.body?.cancel()
+      throw init.signal.reason
+    }
     if (!response.ok || response.body === null) return response
-    const [forKernel, forLog] = response.body.tee()
+    const [fromNetwork, forLog] = response.body.tee()
+    const forKernel = init.signal
+      ? fromNetwork.pipeThrough(new TransformStream(), { signal: init.signal })
+      : fromNetwork
     // Live responses reach the log in request order: a compaction's part
     // precedes the step that follows it.
     const previous = state.parsed
@@ -268,8 +283,13 @@ async function runStep(step: HarnessStep): Promise<HarnessGeneration> {
       state.parsed = (async () => {
         await previous
         emit({ type: 'start-step' })
-        await streamStep(forLog, emit, (finished) => {
-          completion = finished
+        await streamStep({
+          body: forLog,
+          tools: step.tools,
+          emit,
+          finished: (finished) => {
+            completion = finished
+          },
         })
       })()
     }
@@ -357,6 +377,7 @@ async function runStep(step: HarnessStep): Promise<HarnessGeneration> {
             step.signal.aborted ? step.signal.reason : error,
           )
         } finally {
+          released.abort()
           step.signal.removeEventListener('abort', abort)
           await agent?.close().catch(() => {})
         }
@@ -365,6 +386,7 @@ async function runStep(step: HarnessStep): Promise<HarnessGeneration> {
     cancel() {
       closed = true
       stopped = true
+      released.abort()
       turn?.fxTurn.cancel()
     },
   })
@@ -448,36 +470,35 @@ function recordedCalls(
         })
         break
       case 'tool-input-error':
-        // A call whose input did not parse: FX answered it itself.
-        if (inputText.has(chunk.toolCallId))
-          parts.push({ type: 'tool-input-end', id: chunk.toolCallId })
-        parts.push({
-          type: 'tool-call',
-          toolCallId: chunk.toolCallId,
-          toolName: chunk.toolName,
-          input:
-            inputText.get(chunk.toolCallId) ||
-            (typeof chunk.input === 'string'
-              ? chunk.input
-              : JSON.stringify(chunk.input)),
-        })
-        break
-      case 'tool-input-available':
+      case 'tool-input-available': {
+        // A call recorded without its text: input that failed to parse is
+        // that text.
+        const text =
+          inputText.get(chunk.toolCallId) ||
+          (chunk.type === 'tool-input-error' && typeof chunk.input === 'string'
+            ? chunk.input
+            : JSON.stringify(chunk.input))
         if (inputText.has(chunk.toolCallId))
           parts.push({ type: 'tool-input-end', id: chunk.toolCallId })
-        toolCalls.push({
-          toolCallId: chunk.toolCallId,
-          toolName: chunk.toolName,
-          input: chunk.input,
-        })
+        // The kernel calls back with this text's JSON, not the input the
+        // tool's schema made of it. A call it answers itself, such as one
+        // whose text is not JSON, is never asked for.
+        const input = parseJson(text)
+        if (input !== undefined)
+          toolCalls.push({
+            toolCallId: chunk.toolCallId,
+            toolName: chunk.toolName,
+            input,
+          })
         parts.push({
           type: 'tool-call',
           toolCallId: chunk.toolCallId,
           toolName: chunk.toolName,
-          input: inputText.get(chunk.toolCallId) || JSON.stringify(chunk.input),
+          input: text,
           ...metadata,
         })
         break
+      }
     }
   }
   parts.push({
@@ -505,11 +526,19 @@ function compactionSse(data: CompactionPartData): string {
 // ------------------------------------------------------- live responses
 
 /** Streams one live step response as UI chunks and reports its finish. */
-async function streamStep(
-  body: ReadableStream<Uint8Array>,
-  emit: (chunk: UIMessageChunk) => void,
-  finished: (completion: Completion) => void,
-): Promise<void> {
+async function streamStep({
+  body,
+  tools,
+  emit,
+  finished,
+}: {
+  body: ReadableStream<Uint8Array>
+  tools: ToolSet
+  emit: (chunk: UIMessageChunk) => void
+  finished: (completion: Completion) => void
+}): Promise<void> {
+  // The tool calls whose input started streaming, and whether text arrived.
+  const streamed = new Map<string, boolean>()
   for await (const part of sseParts(body)) {
     const metadata =
       part['providerMetadata'] === undefined
@@ -532,6 +561,7 @@ async function streamStep(
         })
         break
       case 'tool-input-start':
+        streamed.set(part['id'] as string, false)
         emit({
           type: 'tool-input-start',
           toolCallId: part['id'] as string,
@@ -540,6 +570,7 @@ async function streamStep(
         })
         break
       case 'tool-input-delta':
+        if (part['delta'] !== '') streamed.set(part['id'] as string, true)
         emit({
           type: 'tool-input-delta',
           toolCallId: part['id'] as string,
@@ -547,27 +578,39 @@ async function streamStep(
         })
         break
       case 'tool-call': {
+        const toolCallId = part['toolCallId'] as string
+        const toolName = part['toolName'] as string
         const text = part['input'] as string
-        let input: unknown
-        try {
-          input = JSON.parse(text)
-        } catch (error) {
-          emit({
-            type: 'tool-input-error',
-            toolCallId: part['toolCallId'] as string,
-            toolName: part['toolName'] as string,
-            input: text,
-            errorText: error instanceof Error ? error.message : String(error),
-          })
-          break
+        // Replay hands the kernel the text the log holds, so the log keeps
+        // the provider's text when it streamed none.
+        if (streamed.get(toolCallId) !== true && text !== '') {
+          if (!streamed.has(toolCallId))
+            emit({ type: 'tool-input-start', toolCallId, toolName })
+          emit({ type: 'tool-input-delta', toolCallId, inputTextDelta: text })
         }
-        emit({
-          type: 'tool-input-available',
-          toolCallId: part['toolCallId'] as string,
-          toolName: part['toolName'] as string,
-          input,
-          ...metadata,
+        const input = await parseToolInput({
+          tools,
+          toolName,
+          text,
         })
+        emit(
+          input.success
+            ? {
+                type: 'tool-input-available',
+                toolCallId,
+                toolName,
+                input: input.value,
+                ...metadata,
+              }
+            : {
+                type: 'tool-input-error',
+                toolCallId,
+                toolName,
+                input: input.input,
+                errorText: input.errorText,
+                ...metadata,
+              },
+        )
         break
       }
       case 'finish': {
@@ -587,6 +630,34 @@ async function streamStep(
   }
 }
 
+type ToolInput =
+  | { success: true; value: unknown }
+  | { success: false; input: unknown; errorText: string }
+
+/**
+ * A live call's input as the AI SDK step reads it: JSON, then the tool's
+ * schema with its defaults. Input that fails either is an input error, which
+ * A2 answers without running the tool.
+ */
+async function parseToolInput({
+  tools,
+  toolName,
+  text,
+}: {
+  tools: ToolSet
+  toolName: string
+  text: string
+}): Promise<ToolInput> {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch (error) {
+    return { success: false, input: text, errorText: errorText(error) }
+  }
+  const input = await schemaInput({ tools, toolName, value })
+  return input.success ? input : { ...input, input: value }
+}
+
 async function readParts(
   body: ReadableStream<Uint8Array>,
 ): Promise<StreamPart[]> {
@@ -760,6 +831,14 @@ function decodeBody(body: BodyInit | null | undefined): string {
   throw new TypeError('FX sent an unexpected request body')
 }
 
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
 function sameJson(a: unknown, b: unknown): boolean {
   return JSON.stringify(a) === JSON.stringify(b)
 }