experimental-a2 0.0.0 → 0.1.0

package/docs/guides/06-ai-agents.mdx

@@ -60,9 +60,14 @@ default. `model` also accepts any AI SDK `LanguageModel`, such as a provider
 model returned by `openai('gpt-5.6-terra')`, or an async resolver that chooses a
 model for each generation.
 
-`generation` accepts the remaining AI SDK `ToolLoopAgent` settings: sampling,
-token limits, stop conditions, provider options, step callbacks, and tool
-approval policy. Individual providers decide which settings they support.
+Each durable generation runs one AI SDK `streamText()` step. `generation`
+contains per-step settings such as sampling, token limits, provider options,
+and tool approval policy. A2 owns the stop condition, local tool execution,
+and continuation between steps. `maxSteps` limits one complete assistant
+response and defaults to 20. Individual providers decide which model settings
+they support. `generation` therefore excludes `stopWhen`, tool execution
+callbacks, tool callers, tool context, sandbox execution, and the tool approval
+secret. Model-step timeouts are supported; tool-execution timeouts are not.
 
 `experimental-a2/ai/server` is server-only. The isomorphic `experimental-a2/ai` entry point contains the
 contract, reducer, schemas, and pure inputs; it never imports a model provider
@@ -106,9 +111,10 @@ export async function POST(req: Request): Promise<Response> {
 }
 ```
 
-The route never calls the model directly. Appending
-`ai.generation.requested` wakes the built-in handler, which runs the AI SDK on
-the server and appends progress back to the same log.
+The route never calls the model directly. The browser appends user facts such
+as `ai.message.created`. Built-in server handlers schedule
+`ai.generation.requested`, run the AI SDK, and append progress back to the same
+log.
 
 ## Bind the reducer to React
 
@@ -182,13 +188,7 @@ export async function openAgent(
   message: UIMessage,
   router: { push(href: string): void },
 ): Promise<void> {
-  await assistantClient.session(sessionId).push(
-    {
-      type: 'ai.session.created',
-      payload: { metadata: {} },
-    },
-    ...inputs.message(message),
-  )
+  await assistantClient.session(sessionId).push(...inputs.message(message))
   router.push(`/agent/${sessionId}`)
 }
 ```
@@ -216,7 +216,7 @@ export function AgentClient() {
   const [draft, setDraft] = useState('')
   const [error, setError] = useState<string | null>(null)
 
-  const canSend = state.status === 'idle' || state.status === 'failed'
+  const canSend = state.status !== 'closed'
   const lastMessage = state.messages.at(-1)
   const lastText =
     lastMessage?.parts
@@ -289,16 +289,21 @@ export function AgentClient() {
 }
 ```
 
-There is no separate message state to reconcile. `push()` folds
-`ai.message.created` and `ai.generation.requested` locally before starting the
-request. The user message and generating state appear immediately. If the
-request fails, A2 removes both optimistic events; the component only restores
-the draft.
+There is no separate message state to reconcile. `push()` folds the
+`ai.message.created` fact locally before starting the request, so the user
+message appears immediately. If the request fails, A2 removes that optimistic
+event and the component restores the draft. The server owns the corresponding
+generation request.
 
 The form gives Enter its normal submit behavior. The thinking row is also
-derived from `AIState`: it appears with the Agent label as soon as the
-optimistic generation request folds, then the first visible assistant content
-replaces it. Empty stream-start messages never create a blank conversation row.
+derived from `AIState`: it appears with the Agent label when the server's
+generation request folds, then the first visible assistant content replaces
+it. Empty stream-start messages never create a blank conversation row.
+
+Users can send another message while a response is active. The message enters
+the durable log immediately, but its turn waits until the active assistant
+response, including every tool step and approval, reaches a terminal event.
+Queued messages keep log order.
 
 ## What happens after `push()`
 
@@ -306,26 +311,52 @@ One user interaction becomes a durable sequence:
 
 ```text
 browser  ai.message.created             optimistic, then durable
-browser  ai.generation.requested         optimistic, then durable
+server   ai.generation.requested         scheduled from durable facts
 server   ai.generation.started
 server   ai.generation.progress          batched UIMessageChunk[]
 server   ai.tool.called                  when present
-server   ai.tool.result                  when present
 server   ai.approval.requested           when present
-server   ai.generation.completed
+server   ai.tool.result                  after concurrent execution or denial
+server   ai.generation.completed         closes this model step
+server   ai.generation.requested         after all sibling tools are terminal
+         ...                             another one-step generation
 server   ai.message.completed
+server   ai.generation.requested         next queued user turn, when present
 ```
 
+Tool results and generation completion may arrive in either order. A fast
+automatic tool can finish while the model stream is still open. The join waits
+for both step closure and every required terminal result.
+
 The SSE connection delivers the server events to the same reducer. Progress
 stores every AI SDK chunk once. The reducer and the exported
 `deriveUIMessages()` apply those chunks synchronously to produce the current
 `UIMessage`; cumulative message snapshots are not duplicated in the log.
 
-`AIState` exposes `messages`, `status`, `activeGeneration`, `activeProjection`,
+`AIState` exposes `messages`, `status`, `activeGeneration`, `activeRequestId`,
+`activeResponseMessageId`, `activeProjection`, `responseGenerationIds`,
 `pendingApprovals`, `pendingInputs`, `tools`, `compaction`, per-generation
-`usage`, and the last generation `error`. `activeProjection` is the temporary
-indexed chunk/tool frontier used for exact interruption and becomes `null` at
-a terminal event.
+`usage`, and the last generation `error`.
+`activeProjection` is the temporary indexed chunk/tool frontier used for exact
+interruption and becomes `null` at a terminal event.
+
+`activeRequestId` identifies the server-authorized generation request. It
+prevents a delayed request or recovered attempt from taking ownership from the
+current response before its generation starts.
+
+`activeResponseMessageId` identifies that request's response before
+`activeGeneration` exists. It is `null` after the generation starts.
+
+`responseGenerationIds` keeps the latest generation owner for each response
+message. Late lifecycle events from a superseded generation stay in raw
+history but cannot alter the projected message, even after its replacement
+finishes.
+
+Generation requests share one durable lane, so model calls do not overlap.
+The queued-turn policy is the stronger ordering rule: a later user message is
+not scheduled until the current response's complete tool loop finishes. Lane
+FIFO alone would not prevent a newly appended user turn from overtaking a tool
+continuation that has not been appended yet.
 
 ## The built-in inputs
 
@@ -333,27 +364,32 @@ a terminal event.
 
 | Input | Events |
 | --- | --- |
-| `inputs.message(message)` | records a message and requests generation when its role is `user` |
-| `inputs.seed(message)` | records a message without requesting generation |
-| `inputs.approval(response)` | records an approval decision and requests continuation |
-| `inputs.input(response)` | records application input and requests continuation |
-| `inputs.requestInput(request)` | records an application-defined input request |
-| `inputs.retry(options)` | requests a fresh attempt after a failed partial response |
+| `inputs.message(message)` | records a message fact; the server schedules user turns |
+| `inputs.seed(message)` | records a trusted server message without scheduling a turn |
+| `inputs.approval(response)` | records an approval decision fact |
+| `inputs.input(response)` | records an application input response fact |
+| `inputs.requestInput(request)` | records a trusted server request for application input |
+| `inputs.retry(options)` | records `ai.retry.requested` for a failed response |
 | `inputs.interrupt(options)` | interrupts an active response |
 
 The builders hide stable event ids, so the same interaction is safe to resend.
-They return plain values accepted by both browser `push()` and server
-`append()`.
+Browser `push()` accepts user messages, approval and input responses,
+interruptions, and explicit retries. `inputs.seed()` and
+`inputs.requestInput()` are for trusted server appends. Browser inputs never
+append server scheduling, seeded non-user messages, or lifecycle events.
+Approval and input request/response payloads carry the active `generationId`;
+clients copy it from the pending request so a stale interaction cannot satisfy
+a later model step.
 
 `inputs` deliberately has no session lifecycle methods. The A2 log begins with
 the first append. Apps that use explicit `ai.session.created` or
-`ai.session.closed` lifecycle events push those ordinary contract events
+`ai.session.closed` lifecycle events append those trusted server facts
 directly.
 
 ## Add tools and approval
 
 Pass ordinary AI SDK tools to the server. Approval policy belongs in
-`generation`, beside the other `ToolLoopAgent` settings:
+`generation`, beside the other per-step settings:
 
 ```ts server/with-tools.ts
 import { tool } from 'ai'
@@ -405,6 +441,7 @@ export function ApprovalControls() {
           void push(
             ...inputs.approval({
               messageId: approval.messageId,
+              generationId: approval.generationId,
               approvalId: approval.approvalId,
               approved: true,
             }),
@@ -418,6 +455,7 @@ export function ApprovalControls() {
           void push(
             ...inputs.approval({
               messageId: approval.messageId,
+              generationId: approval.generationId,
               approvalId: approval.approvalId,
               approved: false,
               reason: 'Denied by the user',
@@ -432,9 +470,10 @@ export function ApprovalControls() {
 }
 ```
 
-`inputs.approval()` updates the approval part in the projected `UIMessage` and
-requests another model turn. The server then executes the approved tool or
-returns the denial to the model.
+`inputs.approval()` records only the decision and updates the approval part in
+the projected `UIMessage`. A built-in handler executes the approved tool or
+records a denied result. It never bypasses the same sibling join used by
+automatic tools.
 
 Tool activity follows the full AI SDK chunk lifecycle. Input validation errors,
 execution errors, denials, and preliminary and final outputs become durable
@@ -443,11 +482,36 @@ output completes it. Each result has its own event id, so a preliminary result
 cannot deduplicate the final one. Dynamic-tool, provider-executed, provider
 metadata, and tool metadata fields are preserved in the projection.
 
+Independent tool handlers run concurrently as soon as their durable inputs and
+authorization are ready. There is no fixed tool concurrency limit. A private
+coordinator reducer tracks generation closure, cancellation, calls, approvals,
+and terminal results for the active response. Its retained state is bounded;
+completed responses do not accumulate in the coordinator. Each join reads a
+durable reducer snapshot plus the log tail through `ctx.session.state()`. The snapshot
+is only a cache. Recovery can rebuild the same coordinator state from the event
+log after process death.
+
+A continuation needs the generation to close and every sibling tool to have a
+terminal success, error, or denied result. Racing join handlers call
+`ctx.session.append()` with the same deterministic continuation ID, so append
+idempotency resolves the race. A handler's single-owner terminal result is
+returned and committed atomically with that handler's completion. Preliminary
+streaming tool outputs use immediate appends. An approved provider-executed
+call can satisfy the join through its response. A provider tool that declares
+deferred-result support can wait for its provider result instead of a local
+executor. The authenticated provider callback appends that `ai.tool.result`
+through the trusted server session API. Browser `push()` rejects lifecycle
+events, including provider results.
+
 `inputs.input()` provides the same durable request/response shape for
 application-defined input. Its value stays in raw history and
 `state.pendingInputs`; resolve instructions dynamically or replace `generate`
 when the value should become model context.
 
+Approval and application-input request/response facts carry the active
+`generationId`. Echo that value from the pending request so a delayed UI action
+cannot authorize or resume a later model step.
+
 ## Interrupt and retry
 
 Interrupt the active response from the client:
@@ -489,10 +553,18 @@ keeps the partial response the user actually saw, and turns incomplete visible
 tools into `output-error`. Progress, completion, or failure from that generation
 cannot reactivate it after the interruption.
 
+`generationId` is optional only between `ai.generation.requested` and
+`ai.generation.started`, when no generation id exists yet. In that phase, use
+`state.activeResponseMessageId` as `messageId` and omit `generationId`. Once
+`activeGeneration` exists, copy both ids from it so a delayed interruption
+cannot stop a later generation.
+
 After a failed model call, `inputs.retry({ messageId, responseMessageId,
-retryId })` starts a fresh attempt. `retryId` identifies the user's action, so
-resending one retry is safe while a later retry remains distinct. Failed
-partial progress remains in raw history but is excluded from the new prompt.
+retryId })` records a retry request. The server schedules its fresh attempt.
+`retryId` identifies the user's action, so resending one retry is safe while a
+later retry remains distinct. Failed partial progress remains in raw history
+but is excluded from the new prompt. Later user messages remain queued while
+the failed response awaits an explicit retry or interruption.
 
 ## Append from the server
 
@@ -567,7 +639,10 @@ different server assembly:
 ```ts server/custom.ts
 import { z } from 'zod'
 import { agent } from 'experimental-a2/ai'
-import { createHandlers } from 'experimental-a2/ai/server'
+import {
+  createHandlers,
+  validateAgentPush,
+} from 'experimental-a2/ai/server'
 import { createServer } from 'experimental-a2/server'
 
 const supportAgent = agent({
@@ -584,6 +659,7 @@ const aiHandlers = createHandlers({
 
 export const customAssistantServer = createServer({
   contract: supportAgent.contract,
+  validatePush: validateAgentPush,
   handlers: {
     ...aiHandlers,
     'ticket.linked': async ({ event }) => {
@@ -596,16 +672,18 @@ export const customAssistantServer = createServer({
 
 Application events stay fully typed. The standard AI reducer ignores unknown
 events, so another reducer can project application state without forking the AI
-protocol.
+protocol. `validateAgentPush` preserves the same browser boundary as
+`createAgentServer()`: user facts may enter through a parsed push, while model
+scheduling, tool lifecycle, and trusted seed messages stay server-authored.
 
 ### Replace generation, not durability
 
-The default generator uses the AI SDK `ToolLoopAgent`. Replace only that
-model-facing step for fixtures, provider routing, or a different AI SDK
-assembly:
+The default generator uses AI SDK `streamText()` for one model step. Replace
+only that model-facing step for fixtures, provider routing, or a different AI
+SDK assembly:
 
 ```ts server/custom-generation.ts
-import { ToolLoopAgent, createAgentUIStream } from 'ai'
+import { convertToModelMessages, streamText } from 'ai'
 import { createAgentServer } from 'experimental-a2/ai/server'
 import { assistant } from '../assistant'
 
@@ -615,26 +693,20 @@ export const customGenerationServer = createAgentServer({
   generate: async ({
     messages,
     model,
-    tools,
     instructions,
-    generation,
-    generationId,
     responseMessageId,
     signal,
   }) => {
-    const sdkAgent = new ToolLoopAgent<never, typeof tools>({
-      ...generation,
-      id: generationId,
+    const result = streamText({
       model,
-      tools,
+      messages: await convertToModelMessages(messages),
+      abortSignal: signal,
       ...(instructions === undefined ? {} : { instructions }),
     })
 
-    return createAgentUIStream({
-      agent: sdkAgent,
-      uiMessages: messages,
+    return result.toUIMessageStream({
+      originalMessages: messages,
       generateMessageId: () => responseMessageId,
-      abortSignal: signal,
     })
   },
 })
@@ -642,17 +714,26 @@ export const customGenerationServer = createAgentServer({
 
 `generate` receives compacted messages, resolved model and instructions, tools,
 generation settings, durable request identity, current state and history, and
-the abort signal. It returns one `ReadableStream<UIMessageChunk>`. A2 still
-records progress, tool and approval events, completion, interruption, and
-failure.
+the abort signal. It returns exactly one model step as a
+`ReadableStream<UIMessageChunk>`. A tool-aware replacement sends definitions to
+the model without running local `execute` functions. A2 still owns durable
+progress, tool execution, approval, continuation, interruption, and failure.
 
 ## Delivery semantics
 
-Model calls and tools run inside an at-least-once A2 handler. Durable event ids
-make lifecycle appends effectively once, and A2 marks an incomplete attempt
-`superseded` before starting its replacement. Model providers and external tool
-side effects remain outside the log. Give side-effecting tools their own
-idempotency strategy, normally keyed by the AI SDK tool call id.
+Model steps and tools run inside at-least-once A2 handlers. The returned-event
+transaction makes each successful handler completion and its terminal events
+one atomic durable operation. Deterministic ids make scheduling and lifecycle
+appends effectively once, and A2 marks an incomplete model attempt
+`superseded` before starting its replacement.
+
+Provider calls and external tool side effects remain outside that transaction.
+A process can die after an external effect succeeds and before its handler
+completion commits, so recovery may run the call again. Give side-effecting
+tools their own idempotency strategy, normally keyed by the AI SDK tool call
+id. This is the same at-least-once boundary as every other A2 handler. A fast
+tool may also start before its model step later fails. The failure prevents a
+continuation, but it cannot roll back that external effect.
 
 Configure [production recovery](/guides/production) exactly as for any other A2
 server. Recovery wakes an interrupted generation after the original serverless

package/docs/guides/07-devtools.mdx

@@ -44,7 +44,7 @@ returning a `Response` supports a redirect or authentication challenge.
 ## Causal forest
 
 Every stored `cause` connects a child to the event index and handler attempt
-whose `ctx.append` first persisted it. The dashboard builds that forest
+whose `ctx.session.append` first persisted it. The dashboard builds that forest
 directly from the session log. It does not need a trace table or another write
 on the append path.
 
@@ -75,10 +75,13 @@ dashboard shows the first dispatch time as unknown instead of moving it to
 `createdAt` or `lastClaimedAt`.
 
 The bar is event lifetime, not handler execution time. A2 stores lifecycle
-summaries, not one span row for every attempt. Time spent waiting, running a
-handler, coordinating a lease, or waiting for recovery remains one honest
+summaries, not one span row for every attempt. Time spent waiting for a lane,
+running a handler, holding a claim, or waiting for recovery remains one honest
 interval.
 
+An event type without a handler is complete at append. Its bar has no waiting
+time or dispatch marker, and its attempt count stays at zero.
+
 Snapshots appear as their reducer name, event frontier, and last update time.
 The dashboard does not send cached snapshot state to the browser.
 

package/docs/guides/08-application-data.mdx

@@ -34,9 +34,9 @@ orders / order-43
 agents / run-abc
 ```
 
-The session is the boundary A2 orders, recovers, folds, and streams. Put events
-in the same session when they must be ordered or viewed together. Split work
-that should progress independently.
+The session is the boundary A2 logs, recovers, folds, and streams. Put events
+in the same session when they form one history or view. Handler execution is
+concurrent unless events share a lane.
 
 A contract is not a table. A session is not a table either. One contract
 usually serves many sessions, and one session may describe changes that touch
@@ -77,8 +77,7 @@ a cost: boards and search span many sessions and need another query model. If
 those collection views are the center of the product, let the database lead.
 
 Do not put an entire workspace in one session just to make cross-issue queries
-possible. Every event in one session is ordered together, and every client of
-that session follows the same growing log.
+possible. Every event joins the same growing log and every client follows it.
 
 ## Database writes from handlers
 
@@ -99,7 +98,7 @@ integration:
 
 - it is eventually consistent with the session logs;
 - writes must be idempotent;
-- A2 orders events within one session, not across sessions;
+- A2 assigns log order within one session, not across sessions;
 - A2 does not expose one API that scans and replays every session to rebuild
   the index.
 

package/docs/index.mdx

@@ -10,7 +10,7 @@ pnpm add experimental-a2
 A2 is durable sync and reactions for things with a lifecycle.
 
 An order, agent run, approval, or import gets a session. You append events.
-Handlers react to them, and usually append the next one. The browser follows
+Handlers react to them, and usually return the next one. The browser follows
 the same log and folds the same state as the server. That's the whole model;
 the rest of this page is it happening.
 
@@ -41,7 +41,7 @@ export const orders = a2.contract({
 
 Handlers are plain async functions: no determinism rules, no replay, no
 wrappers around side effects. Each one reacts to a fact and usually
-appends the next one.
+returns the next one.
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
@@ -50,10 +50,10 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   handlers: {
-    created: async ({ event, append }) => {
+    created: async ({ event }) => {
       // your side effect; event.id makes a stable idempotency key:
       // await notifyShop(event.payload, { idempotencyKey: event.id })
-      await append({ type: 'shop.notified', payload: {} })
+      return { type: 'shop.notified', payload: {} }
     },
   },
 })
@@ -61,8 +61,8 @@ export const ordersServer = createServer({
 
 ## Open a session
 
-A session is one instance of the contract, with its own log and its own
-ordering. It is the thing A2 keeps durable and live. The id is yours:
+A session is one instance of the contract, with its own ordered log. It is the
+thing A2 keeps durable and live. The id is yours:
 
 - `session('order-8194')`: an order moving through fulfillment
 - `session('chat-a8c1')`: an agent chat streaming its reply
@@ -70,7 +70,8 @@ ordering. It is the thing A2 keeps durable and live. The id is yours:
 - `session('doc-roadmap')`: a document with three people typing in it
 
 Anything whose story spans more than one request. Put events in the same
-session when they must be ordered or viewed together. Any server code can open
+session when they form one history or view. Handlers are concurrent unless
+they share a lane. Any server code can open
 one and append: a route handler, a webhook, a cron job.
 
 ```ts app/api/orders/route.ts
@@ -165,11 +166,13 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 ## The properties
 
-- **Handlers are plain async functions.** If it runs on your laptop, it
-  runs in production.
+- **Handlers are plain async functions.** They run concurrently by default.
+  Use a lane for selective FIFO execution.
+- **Handlers are optional per event type.** A log-only event settles during
+  append and creates no reaction or recovery work.
 - **History is real.** [`history()`](/concepts/state) returns what
   actually happened, in order. Debugging is reading, not reconstructing.
-- **Nothing inside a session is sacred except its log.** Snapshots, leases, queue
+- **Nothing inside a session is sacred except its log.** Snapshots, claims, queue
   messages: all disposable caches. Delete them and A2 rebuilds
   everything from the log.
 
@@ -201,6 +204,18 @@ framework. A contract, a log, handlers, reducers.
 
 </details>
 
+<details>
+<summary>Can I use A2 without handlers?</summary>
+
+Yes. Omit `handlers` and use `append`, `history`, reducers, and live streams as
+a durable event log. Events settle in their append transaction, with no drain,
+claim, or queue message. A contract can also mix handled and log-only event
+types. A2 decides per event type.
+
+See [Events without handlers](/concepts/handlers#events-without-handlers).
+
+</details>
+
 <details>
 <summary>How do I wait five days?</summary>
 
@@ -223,8 +238,8 @@ derived view exactly. See [Cancellation](/guides/cancellation).
 <details>
 <summary>What happens when a handler keeps failing?</summary>
 
-It retries with backoff, then dead-letters after ten caught failures, and the
-session stalls at that event, visibly, instead of silently skipping it.
+It retries with backoff, then dead-letters after ten caught failures. Later
+events in the same lane wait; unlaned events and other lanes continue.
 [Durability](/concepts/durability) has the exact guarantees and the
 recovery story behind them.
 
@@ -233,8 +248,9 @@ recovery story behind them.
 <details>
 <summary>What does production need?</summary>
 
-Two decisions: a log backend (Postgres or Redis) and queue-backed
-recovery. Development needs neither. SQLite appears under `.a2/` and
+A durable log backend, such as Postgres or Redis. Add queue-backed recovery
+when the contract has handlers. A log-only contract needs no reaction
+infrastructure. Development needs neither: SQLite appears under `.a2/` and
 state survives restarts. See [Going to production](/guides/production).
 
 </details>