experimental-a2 0.18.0 → 0.19.0

package/docs/agents/04-harnesses.mdx

@@ -110,17 +110,63 @@ Both harnesses call models through Vercel AI Gateway. `model` is a Gateway
 model ID, or [`ModelSettings`](/reference/ai#modelsettings) with one, resolved
 for each step like any agent's model; `pi()` takes the Gateway models Pi's own
 catalog lists. `reasoning` becomes FX's effort or Pi's thinking level, and
-`speed: 'fast'` asks FX for the faster tier. Credentials come from
-`AI_GATEWAY_API_KEY`, or from Vercel's OIDC token on Vercel. The harness reads
-the text of each user message; files and seeded assistant messages do not
-reach it.
+`speed: 'fast'` asks AI Gateway for the model's faster tier under either
+harness. Credentials come from `AI_GATEWAY_API_KEY`, or from Vercel's OIDC
+token on Vercel. Seeded assistant messages do not reach the harness.
+
+## Images and files
+
+The harness reads each user message's text and its image files. Neither FX nor
+Pi takes URLs, so A2 fetches each image from its `https:` or `data:` URL and
+hands the harness its bytes. The fetch goes through the
+AI SDK's download, which refuses private addresses, checks each redirect, and
+stops past 32 MiB of one message's files. Each step of a response replays its
+turn, so a process keeps the images it fetched instead of fetching them again.
+
+A file that isn't an image, or that A2 can't fetch, fails the turn with an
+error that names it. So does a steer with files under FX, which steers with
+text only. The harness applies its own rules to the images it gets: FX fails a
+turn whose model doesn't take images, and Pi resizes them. Every step sends the
+conversation so far, files and all, so a file that fails one turn fails the
+turns after it too.
+
+A2 fetches whatever URL a user message names, so check file URLs on the way
+in. An agent's `messageSchema` can require them to point at your storage:
+
+```ts server/reviewer.ts
+import type { UIMessage } from 'ai'
+import { agent } from 'experimental-a2/ai/server'
+import { fx } from 'experimental-a2/ai/fx'
+import { z } from 'zod'
+
+// your storage's public URL:
+const uploads = 'https://uploads.example.com/'
+
+export const reviewer = agent({
+  name: 'reviewer',
+  harness: fx(),
+  model: 'anthropic/claude-sonnet-5.5',
+  instructions: 'Review the screenshots the user sends. Keep replies short.',
+  messageSchema: z
+    .custom<UIMessage>()
+    .refine(
+      (message) =>
+        message.role !== 'user' ||
+        message.parts.every(
+          (part) => part.type !== 'file' || part.url.startsWith(uploads),
+        ),
+      "A user's files must be uploads",
+    ),
+})
+```
 
 ## What the harness owns
 
 The harness owns its loop, its prompt, and its compaction, so `generation`,
 `generate`, `compaction`, and `messageMetadata` exist only in
 `{ type: 'ai-sdk' }`. A harness runs its tools without approval, so a tool that
-sets `needsApproval` is rejected. `maxSteps` limits the model calls in one
+sets `needsApproval` is rejected. It hands the engine only tools A2 runs, so a
+provider-defined tool, such as a provider's web search, is rejected too. `maxSteps` limits the model calls in one
 response under every harness. Steering enters at the next step, as with any
 agent: the harness sees the steered message before its next model call.
 

package/docs/contract/03-sessions.mdx

@@ -109,7 +109,7 @@ append returned.
 Delivery runs the same conditional clear and finishes the deletion before it
 acknowledges, so provider retries complete an interrupted delete. No event is
 appended. The clear happens at delivery, not at an exact deadline, within
-provider limits: Vercel Queues accepts delays up to six days.
+provider limits: Vercel Queues accepts delays up to seven days.
 
 ## Sessions and your database
 

package/docs/index.mdx

@@ -197,9 +197,9 @@ derived view exactly. See [Cancellation](/server/cancellation).
 <details>
 <summary>What happens when a handler keeps failing?</summary>
 
-It retries with backoff, then dead-letters after ten caught failures. Later
-events in the same lane wait until you retry or skip it; unlaned events and
-other lanes continue.
+It retries with backoff, then dead-letters after ten failed attempts, whether
+the handler threw or its process ended. Later events in the same lane wait
+until you retry or skip it; unlaned events and other lanes continue.
 [Guarantees](/server/guarantees) has the exact guarantees and the
 recovery story behind them.
 

package/docs/reference/02-server.mdx

@@ -252,7 +252,8 @@ server.drain(sessionId: string): Promise<{ settled: boolean }>
 ```
 
 Claims every eligible event and runs their handlers concurrently.
-`settled` means no actionable or live-claimed work remains. A dead-lettered
+`settled` means no actionable or live-claimed work remains. Past the
+invocation's deadline it claims nothing and returns `settled: false`. A dead-lettered
 event can block later work in its lane while other lanes continue, until
 [`session.redrive()`](#sessionredriveindex-options) resolves it. Scheduler
 callbacks use it; you'll rarely call it yourself. The public result stays this
@@ -343,6 +344,7 @@ interface A2Store {
     ttlMs: number
     expiresAtMs?: number
     excludeIndexes?: readonly number[]
+    maxFailures?: number
   }): Promise<StoreClaimAvailableResult>
 
   renewClaims(options: {
@@ -366,6 +368,7 @@ interface A2Store {
     attempt: number
     error: string
     maxFailures: number
+    retryAfterMs?: number
   }): Promise<{
     outcome: 'failed' | 'dead_lettered' | 'superseded'
     failureCount: number
@@ -376,10 +379,10 @@ interface A2Store {
 | Method | Atomic effect |
 | --- | --- |
 | `append` | Write a consecutive batch and report session-wide pending handler work as `hasPending`. Events with the internal `settled` flag get `processedAt` in the same transaction, with no dispatch attempt. An event with a `cause` commits only while `cause.attempt` is the parent's latest attempt and the parent isn't dead-lettered; otherwise throw `SUPERSEDED_ATTEMPT`. The check serializes against a concurrent claim, after the idempotent-replay path. |
-| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. |
+| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. Taking over a lapsed claim, one its holder never completed or failed, adds one to `failureCount`; when that reaches `maxFailures`, dead-letter the event instead of claiming it: advance `attemptCount` to fence the lapsed attempt, leave `lastFailedAttempt` unchanged, and return it with `failedAt` set. A failure's retry hold has no holder, so it is no lapsed claim. |
 | `renewClaims` | Extend the listed live claims the holder still owns. `renewed` lists those; `superseded` lists claims whose event's `attemptCount` passed the listed attempt. An expired claim no successor took is in neither and may still complete; renewal never revives it. |
 | `completeAttempt` | In one transaction: fence on the current attempt, mark the parent processed, store its exact ordered `returnedEventIds`, and append the returned batch. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
-| `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. A repeated acknowledgment is idempotent; a stale attempt returns `superseded`. |
+| `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. Short of that, with `retryAfterMs` the event stays unclaimable for that long: set its claim expiry with no holder, so `claimAvailable` reports it `busy` until then. A repeated acknowledgment is idempotent; a stale attempt returns `superseded`. |
 | `clear` | Serialized with `append`. Check `ifLastIndex` against the head and the latest marker, then append a settled clear marker at the next index, touching no existing rows. A `cause` is fenced like a handler append. |
 | `reclaim` | Delete one bounded batch of rows below the latest clear marker, with their bookkeeping, event-id records, lane pointers, and cached state. Report how many rows went, and `done` when none are left. Never wait on a lock other methods hold. |
 | `deadLetters` | Return the unprocessed events with `failedAt` set above the latest clear marker, oldest first. |
@@ -412,7 +415,8 @@ stores support both.
 Stored fields:
 
 - `attemptCount` counts claims, including abandoned ones. `failureCount`
-  counts caught failures and dead-letters at ten. See
+  counts failed attempts: caught failures, and lapsed claims a later claim
+  took over. Ten dead-letter the event. See
   [Guarantees](/server/guarantees#one-event-many-attempts).
 - `cause` names the event and handler attempt whose `ctx.session.append` or
   return value first persisted the child; `null` means a top-level event.
@@ -679,9 +683,10 @@ type DeadLetter = Event & {
 The session's dead-lettered events, oldest first, each with why it failed. See
 [When an event dead-letters](/server/production#3-when-an-event-dead-letters).
 
-- `failureCount` counts the caught failures that spent its budget;
-  `attemptCount` also counts claims abandoned by hard kills. `lastError` is the
-  last failure, stringified.
+- `failureCount` counts the attempts that spent its budget: caught failures,
+  and attempts that ended before they finished. `attemptCount` counts every
+  claim. `lastError` is the last error a handler threw, stringified, or null
+  when every failed attempt ended before it finished.
 - Events at or below the latest clear marker are never listed.
 - Only on `server.session(id)`. `DeadLetter` is exported from
   `experimental-a2/server`.

package/docs/reference/04-ai.mdx

@@ -39,8 +39,8 @@ state: serve it with `agent({ contract })` and use it with
   through.
 - An `initialState` key that `AIState` also has throws a `TypeError` and fails
   to typecheck.
-- The reducer name is `AI_STATE_REDUCER` (`a2.ai.state.v26`) without
-  `reducer`, else `${reducer.name}+a2.ai.state.v26`, so checkpoints advance when
+- The reducer name is `AI_STATE_REDUCER` (`a2.ai.state.v27`) without
+  `reducer`, else `${reducer.name}+a2.ai.state.v27`, so checkpoints advance when
   either fold changes. `AgentReducer` types that name (so
   [`createAgentClient()`](#createagentclientoptions) accepts a plain
   `agentContract()`) and carries `X` to `agent()`'s resolvers.
@@ -61,9 +61,9 @@ even when `M` declares its own data parts.
 
 ### `AIMessageOf<Events>`
 
-The `UIMessage` type a contract's `ai.message.created` schema carries, such as
-`AIMessageOf<typeof contract.events>`; `UIMessage` otherwise. `agent()` types
-messages with it.
+The `UIMessage` type a contract's input commands (`ai.control.requested`)
+carry, such as `AIMessageOf<typeof contract.events>`; `UIMessage` otherwise.
+`agent()` types messages with it.
 
 ### `handlerContext(contract?)`
 
@@ -105,13 +105,13 @@ Pure typed builders of `ai.control.requested` commands, for `append()` and
 | `inputs.requestInput(request)` | requests application input from trusted server code |
 | `inputs.retry(options)` | retries a failed response |
 | `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances when admission is open |
-| `inputs.steer({ turnId, message, lastSeenIndex? })` | puts the new input first for a handoff after the observed turn's current step |
+| `inputs.steer({ turnId, message, lastSeenIndex? })` | queues the new input right after the observed turn's earlier steering, or first, for a handoff after its current step; the turn's steering enters together, its last generating input starting the turn |
 | `inputs.queue.edit({ message })` | changes a pending input; its ID stays fixed |
 | `inputs.queue.move({ inputId, beforeId })` | moves pending input before an ID; `null` means the end |
 | `inputs.queue.remove({ inputId })` | removes pending input; its submission stays in the log |
-| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input for a handoff after the current step; preserves pause |
+| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input, after the observed turn's earlier steering, for a handoff after the current step; preserves pause |
 | `inputs.pause({ when: 'now' \| 'after-turn' })` | pauses execution now or inbox admission after the turn |
-| `inputs.resume()` | resumes retained work, then inbox admission |
+| `inputs.resume()` | resumes retained work, then inbox admission; a turn paused now with steering hands it off instead |
 | `inputs.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
 | `inputs.interrupt(options)` | interrupts a specific generation/request owner |
 
@@ -174,7 +174,9 @@ Pure typed builders of `ai.control.requested` commands, for `append()` and
 - **Interruption.** `ai.message.interrupted` is `{ messageId, requestId,
   reason?, lastSeenIndex? }` or `{ messageId, generationId, reason?,
   lastSeenIndex? }`: copy `activeRequestId` before the generation starts,
-  `activeGeneration.generationId` after. A request-owned interruption survives
+  `activeGeneration.generationId` after. A2 writes the reason
+  `'steered after step'` itself when steering ends a response, so an
+  interruption you send can't use it. A request-owned interruption survives
   that request starting first. An older or mismatched message/owner pair is a
   no-op. An accepted one fences its owner for good: later events stay in raw
   history but cannot alter `AIState`, satisfy pending work, or reactivate the
@@ -249,7 +251,7 @@ extra I/O or raw-history reads.
   win.
 - Steer, and Send now against an active turn, show in `state.messages` after
   the current response, not the inbox, until admission; they stay out of the
-  prompt. Several steering inputs show in admission order, most recent first,
+  prompt. Several steering inputs show in the order they were sent,
   and the display survives receipt and hydration, including while paused.
 - A pending Stop clears the displayed `state.active`, generation, and pending
   approvals and inputs, previews an idle status (paused when the inbox is), and
@@ -274,8 +276,8 @@ events. Encoding is internal; no event or tool payload is truncated.
 | Field | What it holds |
 | --- | --- |
 | `messages` | [`TranscriptMessage<M>`](#transcriptmessagem) values; server-side, without pending inputs |
-| `inbox` | `{ paused, items }`; items are `{ id, message, generate, afterStepOf? }`, where `afterStepOf` is an observed steering turn that hands off after its current step (removal cancels it, admission consumes it) |
-| `active` | `null` or `{ turnId, input, phase }`; admission freezes `input` |
+| `inbox` | `{ paused, items }`; items are `{ id, role, message, generate, afterStepOf? }`, where `afterStepOf` is an observed steering turn that hands off after its current step (removal cancels it, admission consumes it) |
+| `active` | `null` or `{ turnId, input, phase }`, where `input` is the admitted input's `{ id, role, generate }` |
 | `status` | generation status |
 | `starting` | a speculative optimistic turn |
 | `receipt` | the latest user command receipt |
@@ -311,7 +313,10 @@ See [What happens after a send](/agents/introduction#what-happens-after-a-send).
 
 `deriveUIMessages()` folds a raw event history into `TranscriptMessage<M>[]`.
 `reduceAIState()` is the event-at-a-time form the standard reducer uses. Both
-project the same chunk-only protocol synchronously.
+project the same chunk-only protocol synchronously. A message's content is in
+the command that brought it in, so a fold needs each `ai.message.created`'s
+command before it; one without throws. Only A2's control lane writes
+`ai.message.created`.
 
 ## `experimental-a2/ai/server`
 
@@ -525,7 +530,11 @@ name the harness's own tools, such as Pi's `bash`. `model` is resolved per step
 as for any agent. `instructions` and `tools` reach the harness; how they
 combine with its own prompt and tools depends on the harness. Tool approval
 policy lives in `harness.generation`, so a harness agent's tools run without
-approval, and a tool that sets `needsApproval` is rejected.
+approval, and a tool that sets `needsApproval` is rejected. So is a
+provider-defined tool (`type: 'provider'`), which the engine can't run. A user
+message reaches the harness as its text and its images, which A2 fetches from
+their `https:` or `data:` URLs; any other file fails the turn. See
+[Images and files](/agents/harnesses#images-and-files).
 
 A harness resumes after a crash at the interrupted step. Finished model calls
 are not made again and finished tool calls do not run again. A2 rebuilds the
@@ -577,7 +586,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.
 
@@ -586,8 +598,8 @@ continue a response, A2 restores FX's latest checkpoint and replays the
 response so far from the log: recorded model responses and tool results answer
 the kernel without network calls or tool runs, then FX makes its next model
 call. Replay grows with the response, roughly 0.1 to 0.5 seconds for one of 80
-to 200 tool calls. FX checkpoints hold at most 4 MiB of conversation; past that,
-A2 replays from an earlier checkpoint.
+to 200 tool calls. When libfx can't take a checkpoint, A2 replays from an
+earlier one.
 
 Credentials come from `AI_GATEWAY_API_KEY`, or Vercel's OIDC token on Vercel.
 This entry point is server-only.
@@ -607,12 +619,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 `speed: 'fast'` asks AI Gateway for the model's fast
+tier; `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;
@@ -189,8 +189,8 @@ export const scheduler = vercelQueues()
   Deploymentless delivery lets Vercel choose an eligible consumer, not the
   latest production deployment; every eligible consumer must use
   `deploymentId: null` and stay compatible with pending tasks and session work.
-- Tasks are retained for seven days. Delays are accepted through six days,
-  leaving the final day for delivery and retries.
+- Tasks are retained for seven days, Vercel Queues' maximum. A delay goes out
+  as asked; Vercel Queues refuses one longer than the retention.
 - `transport` and `clock` are advanced injection seams for tests and custom
   delivery. An injected transport receives the topic, an exact
   `SchedulerTask`, and send options, and owns its provider configuration;
@@ -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/02-timers.mdx

@@ -119,7 +119,7 @@ handler schedule the next one.
 
 | Adapter | Maximum one-shot delay |
 | --- | --- |
-| Vercel Queues | 6 days |
+| Vercel Queues | 7 days |
 | QStash free | 7 days |
 | QStash usage-based | 1 year |
 | QStash fixed | no fixed maximum |

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

@@ -143,8 +143,8 @@ The trigger is required. It connects the route to Vercel Queues and makes the
 function private, so only queue infrastructure can invoke it. Don't expose the
 callback as a public route or wrap it in a second authentication scheme.
 
-The adapter keeps messages for 7 days (Vercel Queues' default is 24 hours) and
-accepts scheduled appends and clears up to 6 days out.
+The adapter keeps messages for 7 days (Vercel Queues' default is 24 hours), so
+scheduled appends and clears can be up to 7 days out.
 
 ### QStash
 
@@ -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

@@ -116,12 +116,19 @@ 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: the conversation that stays in the log still links
+them.
+
 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>
   )