experimental-a2 0.12.0 → 0.14.0

package/docs/reference/01-api.mdx

@@ -697,6 +697,13 @@ Raw events from the session, oldest first. `gte` and `lte` are inclusive event
 indexes; omit a bound to leave that end of the log open.
 Bounds are non-negative safe integers. `lte: 0` returns `[]`; `gte > lte` throws.
 
+Redis reads a fixed committed range in pages of at most 256 events, with up to
+sixteen page reads in flight. Public history omits dispatch metadata. PostgreSQL
+uses one indexed range query selecting only public event columns. Custom store
+adapters can implement `readHistory(sessionId, options)` with the same exclusive
+`afterIndex` and inclusive `throughIndex` bounds as `read()`. A2 falls back to
+`read()` when that capability is absent.
+
 ### `session.state(reducer, options?)`
 
 ```ts
@@ -1033,14 +1040,12 @@ result and is verified against the executing server's contract: a
 mismatched agent, or a call outside any tool execution, throws a
 `TypeError`.
 
-The returned `AgentToolContext<D>` is a union of the current A2
-handler's `event`, `attempt`, `session`, and `signal`. Automatic
-execution has an `ai.tool.called` event; execution after approval has an
-`ai.approval.responded` event. Narrow `ctx.event.type` when
-event-specific payload fields matter. Both variants have a session typed
-from the supplied agent's complete event vocabulary. The agent does not
-hold a scheduler. Calls such as `ctx.session.schedule()` use the
-scheduler of the server executing the tool.
+The returned `AgentToolContext<D>` supplies the current A2 handler's `event`,
+`attempt`, `session`, and `signal`. Local tools execute the explicit
+`ai.tool.execution.requested` work event. Its payload contains the admitted
+`call`, `generation`, `turnId`, and execution `version`. The session has the
+supplied agent's complete event vocabulary. Calls such as
+`ctx.session.schedule()` use the scheduler of the server executing the tool.
 
 The context is runtime capability, not event data. A2 creates it for the
 current attempt, never persists it, and never sends it to the model or a
@@ -1060,29 +1065,72 @@ Pure typed inputs for `append()` and `push()`:
 
 | Input | Events |
 | --- | --- |
-| `inputs.message(message, { generate? })` | `ai.message.created`; pass `generate: false` to record context without scheduling |
-| `inputs.seed(message)` | `ai.message.created` with `generate: false`; non-user roles require a trusted append |
-| `inputs.approval(response)` | `ai.approval.responded` only |
-| `inputs.input(response)` | `ai.input.responded` only |
-| `inputs.requestInput(request)` | `ai.input.requested` for a trusted server append |
-| `inputs.retry(options)` | `ai.retry.requested` |
-| `inputs.interrupt(options)` | `ai.message.interrupted` |
+| `inputs.message(message, { generate? })` | queues input; `generate: false` records passive context at admission |
+| `inputs.seed(message)` | queues passive context; non-user roles require a trusted append |
+| `inputs.approval(response)` | answers a pending tool approval |
+| `inputs.input(response)` | answers a pending application input |
+| `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.queue.edit({ message, expectedRevision })` | 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 identity stays reserved |
+| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input 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.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
+| `inputs.interrupt(options)` | interrupts a specific generation/request owner |
+
+All builders emit `ai.control.requested`. Persistence and application are
+separate: `ai.control.decided` returns `{ commandId, outcome, reason? }` through
+the existing stream. Outcomes are `applied` or `rejected`. Rejection reasons
+include `already-active`, `revision-conflict`, `stale-turn`, `not-found`,
+`duplicate-input`, `not-user-input`, and `closed`. `state.receipt` holds the latest user receipt.
+
+Steering validates and prioritizes new input even if the observed turn has
+finished. A matching active turn finishes its current model response and tool
+batch, then yields before another model step. Running local workers and deferred
+provider results settle first; unanswered human approval/input waits can be
+closed at that point. Pause stays closed. Otherwise the input starts when idle
+or waits first behind a different active turn. The priority change is atomic;
+the later handoff and new work are committed atomically at the step boundary.
+Steer and Send now do not use `lastSeenIndex` to cut output.
+
+Queue removal leaves the log intact and retains the removed identity's reservation.
+Send now preserves the queued input ID and latest accepted revision. It requires
+an observed `turnId` (or null for idle), preserves pause, and only accepts
+user-role input. It promotes passive user input to generation after reserving its
+response ID. Missing targets, stale turns, and identity collisions reject before
+any queue change.
+
+`state.inbox` contains `paused` and ordered `items`. Each item contains
+`{ id, revision, message, generate, afterStepOf? }`. The optional turn ID
+`afterStepOf` records the observed steering turn while that item remains queued;
+a matching active turn hands off after its current step.
+Removal cancels it and admission consumes it. `state.active` is null or contains
+`{ turnId, input, phase }`; admission freezes `input`. On the server, pending
+inputs are absent from `messages` and model context. The `paused` status and the `pausing`/`paused`
+active phases represent retained work. Resume uses a fresh model request and
+execution version. Tools without terminal outcomes can retry; their stable
+`toolCallId` supports external idempotency.
 
 `inputs` deliberately has no session lifecycle methods. Append explicit
 `ai.session.created` and `ai.session.closed` events from trusted server code
-when an application uses them. Input event ids are stable for the interaction
-they describe, so a lost append acknowledgment can be resent safely. Browser
+when an application uses them. Message, approval, input, and retry builders use stable interaction IDs.
+Other commands use IDs assigned by `push()` or `append()`; transport retries
+preserve those IDs. Browser
 ingress accepts user messages, approval and input responses, interruptions,
 and explicit retries. Only built-in server handlers append generation requests
-and AI lifecycle events. `inputs.requestInput()` and non-user messages built
+and AI lifecycle events. `inputs.requestInput()`, `inputs.toolResult()`, and non-user messages built
 with `inputs.seed()` are for trusted server appends.
 
-`inputs.message(message, { generate: false })` is valid browser input. It keeps
-the user message in `AIState.messages` without starting a model turn. The next
+`inputs.message(message, { generate: false })` is valid browser input. It admits
+the user message to `AIState.messages` without starting a model turn. The next
 user message that allows generation includes passive user messages before it
 in model context. Passive user messages after that trigger wait for a later
 generating message. Omitting the option preserves the default scheduling
-behavior and the existing `{ message }` event payload. `inputs.seed()` writes
+behavior. `inputs.seed()` writes
 the same passive flag. Trusted assistant and system seeds are context, not user
 queue cutpoints. The server never schedules them, regardless of the `generate`
 field. Model output is generation progress rather than another
@@ -1117,12 +1165,44 @@ Completed tool results at or before `lastSeenIndex` remain completed. A final
 tool result that races an ordinary generation failure remains authoritative in
 either commit order, while the generation stays failed.
 
+Interruption and failure projections discard tool parts still in
+`input-streaming`. These argument drafts are not completed tool calls and do not
+enter later model prompts. Raw progress remains in the log. Available inputs,
+approval-waiting calls, and completed results retain their existing terminal
+handling.
+
 ### `events` and `createEvents(options?)`
 
 The built-in Standard Schema definitions. Use `events` for the default AI SDK
 `UIMessage`; use `createEvents({ messageSchema })` to validate a more specific
 message type. Both are isomorphic.
 
+### Optimistic AI client state
+
+Clients using `agent().reducer` or `createReducer()` expose `state.messages`,
+`state.inbox`, and `state.starting` with pending send, edit, move, remove,
+Send now, steer, pause, and resume commands applied for display. Idle, unpaused
+sends appear in the conversation immediately. A generating input occupies the
+optimistic turn, so subsequent sends queue. Busy or paused sessions queue new
+sends. `starting` indicates a speculative turn awaiting acceptance; it does not
+indicate model execution. Confirmed turns take precedence during reconciliation.
+Steering inputs, and Send now inputs targeting an active turn, appear in
+`state.messages` after the current response and are omitted from the client
+inbox. This display survives receipt and hydration, including while paused.
+They remain pending server inputs until admission and do not enter the model
+prompt early. Multiple steering inputs follow inbox admission order.
+
+`state.active`, model execution, and revision numbers stay confirmed.
+Server reads and reducer folds retain confirmed messages and inbox entries;
+`state.starting` is false there. Custom reducers that call `reduceAIState()` or
+nest the AI fold do not inherit the client display behavior. Disable repeat editing and Send now while an
+edit for that input is present in `state.pendingQueueCommands`.
+
+The pending-command ledger survives request echo and retires on the matching
+`ai.control.decided` receipt or session close. Failed pushes roll back through
+the client's existing optimistic overlay. This display adds no I/O and does not
+read raw history.
+
 ### `createReducer(options)`
 
 ```ts
@@ -1130,7 +1210,8 @@ createReducer({ contract, name? }): Reducer<AIState>
 ```
 
 Builds the standard AI projection for a compatible contract. `AIState`
-contains session lifecycle, messages, generation status, pending approvals
+contains `inbox`, `active`, `starting`, the latest command `receipt`, session lifecycle,
+messages, generation status, pending approvals
 and input, tool activity, compaction, usage, the last error, and
 `activeRequestId`, `activeResponseMessageId`,
 `responseGenerationIds: Record<string, string>`, and terminal request and
@@ -1140,7 +1221,7 @@ delayed requests before their generation starts. `activeResponseMessageId`
 identifies the requested response until `activeGeneration` exists.
 `activeProjection` holds the indexed generation frontier while a generation is
 active, after a generation step completes while its response waits on tool,
-approval, or input barriers, and after a generation fails while it awaits retry
+approval, or input barriers, while paused, and after a generation fails while it awaits retry
 or interruption. Response completion, interruption, supersession, retry, or a
 later generation clears or replaces it. `responseGenerationIds` keeps the
 latest generation owner for each response message, so late events from a
@@ -1149,7 +1230,19 @@ superseded owner cannot alter the projection. `terminalRequestIds` and
 and supersession fences across snapshots and recovery. They are optional
 snapshot-compatible fields with the shapes `Record<string, true>` and
 `Record<string, 'completed' | 'failed' | 'interrupted' | 'superseded'>`.
-Extension events are ignored. The default reducer name is `a2.ai.state.v8`.
+The active projection also stores its prompt boundary and a serializable stream
+cursor for open text, reasoning, and tool-input parts. Ordered progress applies
+only its new chunks. `activeProjection.batches` stores indexed batches as
+`{ length, tail, blocks }`: a bounded tail and shared completed blocks. Appending
+ordered progress does not copy the full retained batch list. The blocks are
+ordinary JSON with logarithmic nesting depth, so checkpoints can be serialized
+and cloned. Retained batches support exact interruption cutoffs and out-of-order
+reconstruction. The cursor and blocks share the active projection's lifetime.
+Checkpoint size and serialization cost still grow with retained progress.
+Tool-input deltas update `input-streaming` parts with best-effort partial JSON
+for display. The state stays `input-streaming` until a completed input arrives;
+partial parsing does not authorize execution or change interruption handling.
+Extension events are ignored. The default reducer name is `a2.ai.state.v17`.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
@@ -1243,9 +1336,48 @@ support wait for their provider result instead of a local executor. An
 authenticated provider callback appends the terminal `ai.tool.result` through
 the trusted server session API; the browser push allowlist rejects it.
 
-`compaction` has `shouldCompact(context)` and `compact(context)` callbacks.
-When selected, both the request and the replacement messages enter the log.
-`progress` controls durable batching with `maxChunks` and `maxDelayMs`.
+`compaction` defaults to automatic for supported Gateway requests. It accepts
+`false` to disable compaction and discovery, `{ thresholdTokens?, instructions? }`
+to override automatic behavior, or the existing custom
+`{ shouldCompact(context), compact(context) }` policy. It also accepts a
+resolver `(context: AgentResolverContext) => CompactionOptions | Promise<CompactionOptions>`.
+The resolver runs once per generation and returns a valid policy or `false`.
+It can await application reducers through `context.session.state(reducer)`, whose
+default boundary is the captured prompt frontier. Model, instruction, compaction,
+metadata, and custom-generation contexts expose state access and omit raw history.
+Static options are validated at construction; resolved options are validated
+before that generation starts. Each session uses its own resolved value. `thresholdTokens` is an
+optional positive safe integer. `instructions` adds to A2's internal summary
+prompt without replacing the agent's instructions.
+
+Without an explicit threshold, the first generation batches a metadata request
+into its existing start write. An independent handler reads the public Gateway
+catalog and records that session/model's limits. It does not delay model dispatch.
+The default threshold is 75% of the context window, lowered for a larger configured
+output allowance. A pending or unavailable lookup leaves the threshold unknown;
+the first request proceeds, and provider context-limit errors fail normally.
+`state.modelMetadata` retains each model's pending, resolved, or unavailable state.
+Pending also covers exhausted handler retries; no new request is added per turn.
+The catalog has a shared one-hour process cache and a five-second fetch timeout.
+
+Direct/custom providers, fallback model lists, and custom generators need explicit
+compaction configuration. Provider-executed tools, structured output, and forced
+tool choices skip implicit compaction and reject explicit automatic policies.
+Custom policies remain available for these configurations.
+
+The input estimate includes messages, tools, and instructions, and uses prior
+reported input usage to anchor later growth where applicable. It is not a provider
+tokenizer. Completed generations record `inputTokenEstimate` beside usage. The
+built-in summary adds one model request and preserves the request prefix for
+caching. It does not invoke application generation callbacks, transforms, or tool
+hooks. Both custom policy callbacks and `generate` receive `modelMessages`, the
+model-ready prompt including summaries, alongside typed UI `messages`.
+
+Built-in summaries remain separate from application-typed messages. Render
+`state.compaction?.status === 'running'` as current activity, and the durable
+`ai.compaction.*` events as historical timeline markers. The conversation in
+`state.messages` remains intact. `progress` controls durable batching with
+`maxChunks` and `maxDelayMs`.
 
 This entry point is server-only and resolves to a throwing browser stub.
 

package/examples/playground/app/agent/[agentId]/agent-client.tsx

@@ -6,10 +6,14 @@ import type {
 } from 'react'
 import { useEffect, useRef, useState } from 'react'
 import type { UIMessage } from 'ai'
-import { inputs } from 'experimental-a2/ai'
+import { inputs, type ControlCommand } from 'experimental-a2/ai'
 import { ActivityFeed } from '@/app/components/activity-feed'
 import { ConnectionPill } from '@/app/components/connection-pill'
 import { useSession } from '../session'
+import { compactionTimeline } from '../compaction-timeline'
+import { CompactionEvent } from './compaction-event'
+import { CompactionPanel } from './compaction-panel'
+import { AgentQueue } from './agent-queue'
 
 type MessagePart = UIMessage['parts'][number]
 type ToolPartView = {
@@ -26,6 +30,7 @@ const STATUS_LABEL = {
   waiting: 'approval needed',
   failed: 'failed',
   closed: 'closed',
+  paused: 'paused',
 } as const
 
 const toolTitle = (name: string): string =>
@@ -113,11 +118,11 @@ const hasVisibleParts = (message: UIMessage): boolean =>
       toolPartView(part) !== null,
   )
 
-function Thinking(): ReactNode {
+function Thinking({ starting = false }: { starting?: boolean }): ReactNode {
   return (
     <p className="agent-thinking" role="status">
       <span aria-hidden="true" />
-      Thinking…
+      {starting ? 'Starting…' : 'Thinking…'}
     </p>
   )
 }
@@ -163,24 +168,32 @@ function submitOnEnter(event: ReactKeyboardEvent<HTMLTextAreaElement>): void {
 
 export function AgentClient({ agentId }: { agentId: string }): ReactNode {
   const { state, push, events, index, connection } = useSession()
+  const { inbox } = state
   const promptRef = useRef<HTMLTextAreaElement>(null)
   const [prompt, setPrompt] = useState('')
   const [error, setError] = useState<string | null>(null)
   const [responding, setResponding] = useState(false)
 
   const generating = state.status === 'generating'
-  const canSend = state.status === 'idle' || state.status === 'failed'
+  const compacting = state.compaction?.status === 'running'
+  const canSend = state.status !== 'closed'
+  const responseMessageId =
+    state.activeGeneration?.responseMessageId ??
+    state.activeResponseMessageId ??
+    state.activeProjection?.responseMessageId
+  const timeline = compactionTimeline({ state, events })
 
   useEffect(() => {
-    if (canSend) promptRef.current?.focus()
+    if (canSend) promptRef.current?.focus({ preventScroll: true })
   }, [canSend])
 
-  const send = async (event: FormEvent): Promise<void> => {
-    event.preventDefault()
+  const send = async (event?: FormEvent, steer = false): Promise<void> => {
+    event?.preventDefault()
     const submittedPrompt = prompt
     const text = prompt.trim()
     if (!text || !canSend) return
     setPrompt('')
+    promptRef.current?.focus({ preventScroll: true })
     setError(null)
     try {
       const message: UIMessage = {
@@ -188,7 +201,14 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
         role: 'user',
         parts: [{ type: 'text', text }],
       }
-      await push(...inputs.message(message))
+      await push(
+        ...(steer && state.active
+          ? inputs.steer({
+              turnId: state.active.turnId,
+              message,
+            })
+          : inputs.message(message)),
+      )
     } catch (err) {
       setPrompt((current) => (current === '' ? submittedPrompt : current))
       setError(err instanceof Error ? err.message : String(err))
@@ -220,18 +240,27 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
     }
   }
 
+  const command = async (
+    commands: {
+      type: 'ai.control.requested'
+      payload: ControlCommand
+      id?: string
+    }[],
+  ): Promise<void> => {
+    setError(null)
+    try {
+      await push(...commands)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
   const stop = async (): Promise<void> => {
-    const active = state.activeGeneration
-    if (!active) return
+    if (!state.active) return
     setError(null)
     try {
       await push(
-        ...inputs.interrupt({
-          messageId: active.responseMessageId,
-          generationId: active.generationId,
-          reason: 'operator stopped the agent',
-          lastSeenIndex: index,
-        }),
+        ...inputs.stop({ turnId: state.active.turnId, lastSeenIndex: index }),
       )
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
@@ -250,36 +279,56 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
             state.status === 'waiting' ? ' waiting' : ''
           }${state.status === 'failed' ? ' cut' : ''}`}
         >
-          {STATUS_LABEL[state.status]}
+          {state.starting
+            ? 'starting…'
+            : compacting
+              ? 'compacting…'
+              : STATUS_LABEL[state.status]}
         </span>
       </header>
 
+      <CompactionPanel agentId={agentId} state={state} events={events} />
+
       <section className="agent-conversation" aria-label="Conversation">
         <div className="agent-transcript" aria-live="polite">
-          {state.messages.length === 0 ? (
+          {timeline.length === 0 ? (
             <p className="agent-empty">
               Ask the agent to investigate an incident, run a Bash command, or
               set a reminder for itself. Its tools and decisions will appear
               here as they enter the log.
             </p>
           ) : (
-            state.messages.map((message) => (
-              <AgentMessage
-                key={message.id}
-                message={message}
-                thinking={
-                  generating &&
-                  message.role === 'assistant' &&
-                  !hasVisibleParts(message)
-                }
-              />
-            ))
+            timeline.map((entry) =>
+              entry.type === 'compaction' ? (
+                <CompactionEvent key={entry.id} entry={entry} />
+              ) : (
+                <AgentMessage
+                  key={entry.id}
+                  message={entry.message}
+                  thinking={
+                    generating &&
+                    !state.starting &&
+                    !compacting &&
+                    entry.lastSegment &&
+                    entry.message.id ===
+                      state.activeGeneration?.responseMessageId &&
+                    !hasVisibleParts(entry.message)
+                  }
+                />
+              ),
+            )
           )}
-          {generating && state.messages.at(-1)?.role === 'user' ? (
+          {state.starting ||
+          (generating &&
+            !compacting &&
+            state.messages.at(-1)?.role === 'user' &&
+            !state.messages.some(
+              (message) => message.id === responseMessageId,
+            )) ? (
             <div className="agent-message assistant">
               <span className="agent-role">Agent</span>
               <div>
-                <Thinking />
+                <Thinking starting={state.starting} />
               </div>
             </div>
           ) : null}
@@ -335,12 +384,43 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
           </p>
         ) : null}
 
+        <AgentQueue
+          items={inbox.items}
+          paused={inbox.paused}
+          pendingEdits={(state.pendingQueueCommands ?? []).flatMap(
+            ({ command: pending }) =>
+              pending.action === 'edit' ? [pending.message.id] : [],
+          )}
+          remove={async (inputId) => {
+            await command(inputs.queue.remove({ inputId }))
+          }}
+          sendNow={async (inputId) => {
+            await command(
+              inputs.queue.sendNow({
+                inputId,
+                turnId: state.active?.turnId ?? null,
+              }),
+            )
+          }}
+          edit={async (message, expectedRevision) => {
+            await push(...inputs.queue.edit({ message, expectedRevision }))
+          }}
+          move={(inputId, beforeId) =>
+            void command(inputs.queue.move({ inputId, beforeId }))
+          }
+        />
+        {state.receipt?.outcome === 'rejected' ? (
+          <p className="error" role="alert">
+            Command rejected: {state.receipt.reason}. Refresh the input or turn
+            you want to change.
+          </p>
+        ) : null}
+
         <form className="agent-form" onSubmit={(event) => void send(event)}>
           <label>
             Message
             <textarea
               ref={promptRef}
-              autoFocus
               rows={3}
               value={prompt}
               onChange={(event) => setPrompt(event.target.value)}
@@ -355,11 +435,43 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
             <button
               type="button"
               className="danger"
-              disabled={!generating}
+              disabled={!state.active}
               onClick={() => void stop()}
             >
               Stop
             </button>
+            <button
+              type="button"
+              disabled={!canSend || !prompt.trim()}
+              onClick={() => void send(undefined, true)}
+            >
+              Steer
+            </button>
+            {state.inbox.paused ? (
+              <button
+                type="button"
+                onClick={() => void command(inputs.resume())}
+              >
+                Resume
+              </button>
+            ) : (
+              <>
+                <button
+                  type="button"
+                  onClick={() =>
+                    void command(inputs.pause({ when: 'after-turn' }))
+                  }
+                >
+                  Pause after turn
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void command(inputs.pause({ when: 'now' }))}
+                >
+                  Pause now
+                </button>
+              </>
+            )}
           </div>
         </form>
       </section>