experimental-a2 0.17.0 → 0.18.0

package/docs/agents/03-conversations.mdx

@@ -0,0 +1,538 @@
+---
+title: Conversations
+description: "Compact long conversations, add your own events and state, and control delivery, the inbox, and turns."
+---
+
+## Compact long conversations
+
+```ts server/compacted.ts
+import { agent } from 'experimental-a2/ai/server'
+
+export const compactedAssistant = agent({
+  name: 'compacted-agent',
+  model: 'openai/gpt-5.6-terra',
+  harness: {
+    type: 'ai-sdk',
+    // optional: compaction is automatic for supported Gateway models
+    compaction: {
+      thresholdTokens: 80_000,
+      instructions: 'Preserve exact IDs.',
+    },
+  },
+})
+```
+
+Compaction belongs to the AI SDK harness, and is automatic for supported
+Gateway models. When the estimated prompt crosses the threshold, A2 sends one
+summary request to the active model with the same instructions, tools, and
+provider settings, keeping the prefix cacheable.
+Later requests get the summary plus everything after it; the raw log and
+`state.messages` stay complete, and the summary request never appears there as
+a turn. Successful compaction is permanent across failure, interruption, retry,
+and recovery, and a failed summary leaves the previous context intact.
+
+The default threshold is 75% of the context window from the Gateway model
+catalog, lowered for a larger `generation.maxOutputTokens`; it limits input
+context, not output. `thresholdTokens` overrides it, `instructions` adds
+guidance to the summary prompt, and `false` turns off compaction and the catalog
+lookup, keeping recorded summaries. A resolver can choose per generation, for
+example from `session.state(settingsReducer)`. Custom `shouldCompact(context)`
+and `compact(context)` callbacks receive the typed messages and the model-ready
+`modelMessages`, summary included.
+
+An AI SDK global provider that resolves model IDs to models outside AI
+Gateway, and Gateway fallback model lists, need an explicit `thresholdTokens`
+(for a fallback list, one that fits every model it may use). A custom `generate` keeps compaction off unless you
+configure it. Set a threshold too when importing a large conversation: a
+session does not compact before the catalog lookup lands, so an oversized first
+prompt is sent as-is, never truncated, and fails with the provider's error.
+Provider-executed tools, structured output, and forced tool choices skip
+automatic compaction, and configuring it for them throws; use custom callbacks.
+
+The first generation with each Gateway model in a session records
+`ai.model.metadata.requested`; a separate handler fetches the catalog and
+records `ai.model.metadata.resolved`, without delaying or failing the
+generation. `state.modelMetadata` holds each model's limits and status:
+pending, resolved, or unavailable (absent from the catalog). A lookup that
+exhausted its retries stays pending without a new lookup each turn, so inspect
+that handler's failure or set a threshold. The estimate is serialized UTF-8
+bytes divided by four, calibrated by the previous same-model call's usage. It is
+not a tokenizer, makes no remote calls, and does not precisely measure new image
+or audio tokens.
+
+Compaction waits until earlier tool calls have final results and all A2-owned
+tool work has settled, including work from stopped or superseded turns, with one
+extra state read before each candidate compaction. Dead-lettered tool work
+defers it until repair or session close. Queued messages stay queued. The
+summary request runs none of your generation callbacks, stream transforms, or
+tool hooks and never executes local tools; an empty summary or a summary tool
+call fails the generation, as do provider context-limit errors. See
+[`agent()`](/reference/ai#agentoptions) for every option.
+
+### Show compaction in the conversation
+
+```tsx app/agent/message-view.tsx
+'use client'
+import type { UIMessage } from 'ai'
+import { isCompactionPart, type TranscriptMessage } from 'experimental-a2/ai'
+
+const compactionLabel = {
+  running: 'Compacting…',
+  completed: 'Context compacted',
+  failed: 'Compaction did not complete',
+  interrupted: 'Compaction stopped',
+}
+
+export function MessageView({
+  message,
+}: {
+  message: TranscriptMessage<UIMessage>
+}) {
+  return (
+    <article>
+      {message.parts.map((part, index) => {
+        if (isCompactionPart(part))
+          return (
+            <details key={index}>
+              <summary>{compactionLabel[part.data.status]}</summary>
+              {part.data.summary ? <p>{part.data.summary}</p> : null}
+            </details>
+          )
+        return part.type === 'text' ? <p key={index}>{part.text}</p> : null
+      })}
+    </article>
+  )
+}
+```
+
+The reducer marks each compaction with a `data-a2-compaction` part in the
+assistant response. Its `data` holds a `status` (`running`, then `completed`,
+`failed`, or `interrupted`) and, when known, `inputTokens`, `thresholdTokens`,
+`summary`, and `usage`. The part lives in state, so it survives server
+rendering, reloads, and other tabs, and never enters model context. Because
+`state.messages` is `TranscriptMessage<M>[]`, `isCompactionPart()` narrows even
+when your message type declares its own data parts. `state.compaction` holds the
+current or latest compaction, and `indicator` is `compacting` while one runs.
+See [`isCompactionPart()`](/reference/ai#iscompactionpartpart) for how the part
+settles.
+
+## Store assistant metadata
+
+```ts server/metadata-assistant.ts
+import type { LanguageModelUsage, UIMessage } from 'ai'
+import { agentContract } from 'experimental-a2/ai'
+import { agent } from 'experimental-a2/ai/server'
+
+export type MetadataAssistantMessage = UIMessage<{
+  status: 'writing' | 'complete'
+  usage?: LanguageModelUsage
+}>
+
+export const metadataAssistant = agent({
+  contract: agentContract<MetadataAssistantMessage>({
+    name: 'metadata-assistant',
+  }),
+  model: 'openai/gpt-5.6-terra',
+  harness: {
+    type: 'ai-sdk',
+    messageMetadata: ({ part }) => {
+      if (part.type === 'start') return { status: 'writing' as const }
+      if (part.type === 'finish') {
+        return { status: 'complete' as const, usage: part.totalUsage }
+      }
+      return undefined
+    },
+  },
+})
+```
+
+A narrower `UIMessage` type, carried by `agentContract()`, keeps generation
+status and usage on the assistant message. The synchronous
+`harness.messageMetadata` callback gets the `generate` context plus the current `TextStreamPart` as
+`part`. What it returns for `start` and `finish` is logged with the stream and
+shallow-merged onto the assistant message, so the example shows `writing` at
+once and keeps final usage. `useAgent<typeof metadataAssistant>()` types
+`messages` with it.
+
+## Add your own events and state
+
+Apps carry more than the conversation: a plan, a selected ticket, a chosen
+model. Put those events and their state in a shared `agentContract()`. It takes
+a core `contract()`'s `events`, and its `reducer` takes the same `name`,
+`initialState`, and `fold`:
+
+```ts support-desk.ts
+import { z } from 'zod'
+import { agentContract } from 'experimental-a2/ai'
+
+const noFlags: string[] = []
+
+export const supportDesk = agentContract({
+  name: 'support-desk',
+  events: {
+    'plan.changed': z.object({ plan: z.enum(['free', 'pro']) }),
+    'ticket.flagged': z.object({ ticketId: z.string() }),
+  },
+  reducer: {
+    name: 'support-desk.v1',
+    initialState: { plan: 'free' as 'free' | 'pro', flagged: noFlags },
+    fold: (state, event) =>
+      event.type === 'plan.changed'
+        ? { ...state, plan: event.payload.plan }
+        : event.type === 'ticket.flagged'
+          ? { ...state, flagged: [...state.flagged, event.payload.ticketId] }
+          : state,
+  },
+})
+```
+
+Keep this module isomorphic. `fold` sees your state and every event, never the
+transcript. The session's state is `AIState` merged with yours, so a key that
+shadows one of `AIState`'s is a type error. The reducer's `name` is its snapshot
+identity: rename it when `fold` changes.
+
+Serve it with `agent({ contract })`. Every resolver receives your state as
+`state`:
+
+```ts server/support-desk.ts
+import { agent } from 'experimental-a2/ai/server'
+import { supportDesk } from '../support-desk'
+
+export const supportDeskAgent = agent({
+  contract: supportDesk,
+  model: ({ state }) =>
+    state.plan === 'pro'
+      ? { model: 'openai/gpt-5.6-terra', reasoning: 'high' }
+      : { model: 'openai/gpt-5.6-luna', speed: 'fast' },
+  handlers: {
+    'ticket.flagged': async ({ event }) => {
+      // your side effect; event.id makes a stable idempotency key:
+      // await notifyOnCall(event.payload.ticketId, { idempotencyKey: event.id })
+    },
+  },
+})
+```
+
+`state` comes from the snapshot the generation already captured, so it costs no
+extra read. Each model step resolves again, so a change during a turn applies
+from the next step. A resolver that throws fails the turn with its message, like
+a provider error; `retry()` runs it again.
+
+In the browser, pass the contract to `useAgent()`. This import is real, not
+type-only, because the browser folds your state too:
+
+```tsx app/support/desk.tsx
+'use client'
+import { useAgent } from 'experimental-a2/ai/react'
+import { supportDesk } from '@/support-desk'
+
+export function Desk({ id }: { id: string }) {
+  const { state, push, sendMessage } = useAgent({
+    api: '/api/support',
+    id,
+    contract: supportDesk,
+  })
+
+  return (
+    <section>
+      <p>
+        {state.plan} plan, {state.flagged.length} flagged tickets
+      </p>
+      <button
+        onClick={() =>
+          void push({ type: 'ticket.flagged', payload: { ticketId: 'T-1' } })
+        }
+      >
+        Flag T-1
+      </button>
+      <button onClick={() => void sendMessage('Summarize the flagged tickets.')}>
+        Ask
+      </button>
+    </section>
+  )
+}
+```
+
+Browsers push a shared contract's application events like any A2 client. The
+agent refuses only its own server-authored `ai.*` events; the route's
+`authorize` decides the rest. Here the plan comes from your billing code, not
+the browser:
+
+```ts app/api/support/route.ts
+import { supportDeskAgent } from '@/server/support-desk'
+
+function handle(request: Request): Promise<Response> {
+  // here's where you'd do auth, or any other checks:
+  return supportDeskAgent.fetch(request, {
+    authorize: (operation) =>
+      operation.type !== 'push' ||
+      operation.events.every((event) => event.type !== 'plan.changed'),
+  })
+}
+
+export const GET = handle
+export const POST = handle
+```
+
+Server appends, such as
+`supportDeskAgent.session(id).append({ type: 'plan.changed', payload })`, are
+trusted and skip `authorize`. `push()` also accepts any `inputs` builder, and
+`handlerContext(supportDesk)` types application events inside tools.
+
+The contract-free client, `createAgentClient()` or `useAgent({ api | client })`
+with a type-only import, folds only the built-in reducer. It accepts
+`agent({ name })`, or `agent({ contract })` with an `agentContract()` that has
+no `reducer`; the types enforce this through `AI_STATE_REDUCER`.
+
+When the agent belongs inside something larger, such as a shared chat room,
+keep two sessions. The room's handler appends each message the agent should see
+to the agent's session with `inputs.message()`. Event IDs are unique across a
+store's sessions, so derive the message ID from the room event's ID with
+`idempotentId()`; a retried handler then converges on the same message. A tool
+the agent calls to speak appends to the room with an `idempotentId()` of its
+`toolCallId`. Neither fold reads the other's state.
+
+### Replace generation, not durability
+
+```ts server/custom-generation.ts
+import { convertToModelMessages, streamText } from 'ai'
+import { agent } from 'experimental-a2/ai/server'
+
+export const customGeneration = agent({
+  name: 'custom-generation',
+  model: 'openai/gpt-5.6-terra',
+  harness: {
+    type: 'ai-sdk',
+    generate: async ({ event, messages, model, instructions, signal }) => {
+      const result = streamText({
+        model,
+        messages: await convertToModelMessages(messages),
+        abortSignal: signal,
+        ...(instructions === undefined ? {} : { instructions }),
+      })
+
+      return result.toUIMessageStream({
+        originalMessages: messages,
+        generateMessageId: () => event.payload.responseMessageId,
+      })
+    },
+  },
+})
+```
+
+`harness.generate` replaces only the model-facing step, for fixtures, provider routing,
+or a different AI SDK assembly. It receives the resolver context (with
+`messages` already compacted), the resolved settings, `modelMessages`, and the
+step's `generationId`, and returns exactly one model step as a
+`ReadableStream<UIMessageChunk>` that writes the assistant message
+`event.payload.responseMessageId`. A tool-aware replacement sends tool
+definitions without running local `execute` functions. A2 still owns durable
+progress, tool execution, approval, continuation, interruption, and failure.
+`messageMetadata` applies only to the default generator, so a custom `generate`
+emits its own metadata.
+
+## Checkpoints and recovery reads
+
+Samples from here on import `assistant`, the agent from
+[Agents](/agents/introduction#define-the-agent):
+
+```ts server/read-agent.ts
+import type { UIMessage } from 'ai'
+import type { TranscriptMessage } from 'experimental-a2/ai'
+import { assistant } from './assistant'
+
+export async function readMessages(
+  sessionId: string,
+): Promise<TranscriptMessage<UIMessage>[]> {
+  const snapshot = await assistant.session(sessionId).state()
+  return snapshot.state.messages
+}
+```
+
+`session(id).state()` returns `AIState` and its log index, ready for server code
+or client hydration. Tool inputs, outputs, and provider metadata live in message
+parts; `state.tools` keeps only identities and execution status.
+`reduceAIState()` is the reducer's pure transition over confirmed `AIState`, for
+projecting raw event histories.
+
+Model, instruction, compaction, and custom-generation callbacks receive prompt
+messages, the triggering request, and your contract's `state`, never a raw
+history. Read any other reducer with `session.state(yourReducer)`, at the
+captured prompt boundary unless you pass `through`. Recovery reads at fixed
+boundaries too: a tool recovered in a fresh process sees its original prompt,
+and A2 rebuilds a missing or invalid reducer snapshot from the log.
+
+While tool arguments stream, `input-streaming` parts carry a best-effort partial
+JSON `input`, so a command string can grow before its closing quote. It is a
+display draft, not validated input; `tool-input-available` supplies the
+completed input.
+
+## Delivery semantics
+
+Model steps and tools run inside at-least-once A2 handlers. A successful
+completion commits atomically with its terminal events, and deterministic IDs
+make scheduling and lifecycle appends effectively once. An incomplete model
+attempt is marked `superseded` before its replacement starts. An expired claim
+or superseded attempt keeps its abort reason through model, resolver,
+compaction-policy, and tool calls, and retries without spending its failure
+budget; an explicit interruption stays terminal. A retried tool can stream
+different preliminary output under the same tool-call ID.
+
+Provider calls and external side effects sit outside that transaction, so
+recovery may repeat a call whose effect landed before its handler committed.
+Give side-effecting tools their own idempotency, normally keyed by the AI SDK
+`toolCallId`. A fast tool can also start before its model step fails; the
+failure blocks the continuation but cannot undo the effect.
+
+For a tool whose effect must not repeat and has no idempotency key, such as a
+shell command, set `toolRecovery: { yourTool: 'report' }`. When a crash, a
+timeout, Stop, or Pause now may have cut a call short, A2 does not run it again,
+even on resume; the model gets an error result saying the call was interrupted
+and may have partly run. A call that failed before reaching the tool still
+retries, and so does one where A2 itself fails while or just after the tool
+runs. Every other tool uses the default, `'rerun'`. See
+[`agent()`](/reference/ai#agentoptions) for the exact cases.
+
+Configure a [production scheduler](/server/production) as for any A2 server. It
+recovers an incomplete generation after the original serverless invocation
+disappears.
+
+## Inbox and turn controls
+
+```tsx app/agent/[sessionId]/queue.tsx
+'use client'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { assistant } from '@/server/assistant'
+
+export function Queue({ sessionId }: { sessionId: string }) {
+  const { state, queue, steer, pause, resume } = useAgent<typeof assistant>({
+    api: '/api/agent',
+    id: sessionId,
+  })
+
+  return (
+    <section>
+      <ol aria-label="Queued messages">
+        {state.inbox.items.map((item) => (
+          <li key={item.id}>
+            {item.message.parts.map((part, index) =>
+              part.type === 'text' ? <span key={index}>{part.text}</span> : null,
+            )}
+            <button onClick={() => void queue.sendNow(item.id)}>Send now</button>
+            <button
+              onClick={() =>
+                void queue.move({ inputId: item.id, beforeId: null })
+              }
+            >
+              Move to end
+            </button>
+            <button onClick={() => void queue.remove(item.id)}>Remove</button>
+          </li>
+        ))}
+      </ol>
+      <button onClick={() => void steer('Check the billing service first.')}>
+        Steer
+      </button>
+      {state.inbox.paused ? (
+        <button onClick={() => void resume()}>Resume</button>
+      ) : (
+        <button onClick={() => void pause({ when: 'after-turn' })}>
+          Pause after this turn
+        </button>
+      )}
+    </section>
+  )
+}
+```
+
+`sendMessage()` puts a message in the durable inbox, `state.inbox.items`. The
+controller admits one input at a time, freezes its content, and adds it to
+`state.messages`; pending inputs never enter the model prompt. `state.active`
+is the logical turn: its ID, frozen `input`, and `phase`. The turn ID holds
+across model steps, tools, and a pause. Stop ends the turn and admits the next
+input when admission is running.
+
+:::note
+This input protocol requires matching client and server versions. Start a new
+agent session when adopting it; existing logs stay readable, but finish pending
+work with the runtime that created it before upgrading.
+:::
+
+`queue.edit(message)` replaces a pending input's content; edits are
+last-write-wins in log order. An edit keeps the message's identity and role;
+changing the role returns `role-mismatch`. `queue.move()` takes `beforeId: null`
+for the end. `queue.remove()` keeps the original submission in the log, so
+replay cannot recreate the prompt. Removing an input that is no longer pending
+(admitted, removed, or never queued) returns `not-pending`, as does an edit that
+loses to admission; a Stop aimed at a finished turn returns `stale-turn`.
+
+`steer()` puts new input first. If the observed turn is still active, it
+finishes its current model response and that response's tools, including
+authorized deferred provider results, then hands off before another model
+step. Output produced after the click stays, and unanswered approval and input
+requests close, so the unapproved tool never runs; a denied approval never
+blocks the handoff. With no active turn, `steer()` sends like `sendMessage()`.
+
+`queue.sendNow()` makes the same handoff with a queued message, keeping its ID
+and latest accepted content and promoting passive user input to generation.
+Non-user context returns `not-user-input`, and a stale observed turn returns
+`stale-turn` without changing the queue. Send now uses the accepted content, so
+save editor text first. `steer()` and `queue.sendNow()` both preserve pause: a
+paused queue keeps the selected input first until Resume. Stop remains the
+immediate interruption.
+
+A queued item's optional `afterStepOf` records the observed turn for steering.
+Editing keeps it, removing the item cancels it, and queue order decides which
+input is admitted at the handoff. See [`inputs`](/reference/ai#inputs) for the
+full handoff rules.
+
+### Input identity
+
+New-input commands from `inputs.message()`, `inputs.seed()`, and
+`inputs.steer()` use the message ID as their event ID, and hand-written commands
+must too. Caller IDs cannot start with the reserved `a2.ai:` prefix and must be
+unique across the store; include the contract and session when deriving them
+with `idempotentId()`. An identical submission replays without new work, even
+after removal or compaction. Reusing an ID with different content, action, or
+session rejects with `PARTIAL_DUPLICATE_BATCH`: use `queue.edit()` to change a
+pending input and a fresh ID for a new one.
+
+### Optimistic conversation display
+
+Every client folding the AI reducer, an extended `agentContract()` included,
+applies pending commands to `state` with no extra I/O, so render the
+conversation and queue from `state`. An idle, unpaused send appears in
+`state.messages` at once with `state.starting: true`: a turn awaiting
+acceptance, not a running model. Later sends, and every send while paused, wait
+in `state.inbox.items`; steering, and Send now aimed at an active turn, appear
+in `state.messages` after the current response instead. Another client's
+accepted turn can move a speculative send back into the queue, while steering
+stays visible as a message. A pending Stop clears `state.active` at once.
+Close an editor as soon as its save is pushed, and keep the draft if the push
+fails. See
+[Optimistic AI client state](/reference/ai#optimistic-ai-client-state).
+
+### Persistence and application are separate
+
+A push confirms that the command is persisted; `ai.control.decided` confirms its
+application, with `commandId` (the submitted event's ID) and an `outcome` of
+`applied` or `rejected`. A rejection carries a `reason` such as `not-pending` or
+`stale-turn`.
+`state.receipt` is the most recent user command receipt. To correlate several
+in flight, each action resolves to its persisted command events, whose `id` is
+the receipt's `commandId`, or to an empty array when there is nothing to
+address, such as Stop with no active turn. A rejection is a normal result and
+spends no handler retry.
+
+### Pause and resume
+
+`pause({ when: 'after-turn' })` closes inbox admission and lets the active turn
+finish. `pause({ when: 'now' })` also cancels current model and tool work;
+`state.active.phase` is `pausing` while old work settles, then `paused`.
+`resume()` resumes retained work before admitting another input.
+
+Resume starts a fresh model request from durable state; it does not resume the
+provider's old stream or undo completed tool effects. While paused, accepted
+tool calls are retained with their outcomes recorded, and the turn holds no
+model or tool claim. A cancelled tool without a terminal result can run again
+after resume, so use the stable `toolCallId` for external idempotency.

package/docs/agents/04-harnesses.mdx

@@ -0,0 +1,136 @@
+---
+title: Harnesses
+description: "Run FX's or Pi's own loop as the agent's, durably, behind the same conversation."
+---
+
+## Choose the loop
+
+An agent's harness is its loop: its system prompt, its tools, and how it
+decides what to do next. The default, `{ type: 'ai-sdk' }`, runs one AI SDK
+`streamText()` step per generation with the prompt and tools you give it.
+`fx()` runs [FX](https://fx.sh) and `pi()` runs [Pi](https://pi.dev) instead,
+and A2 keeps them durable. Each model call the harness makes is one step of the response,
+with streamed progress, tool calls, steering, interruption, and recovery like
+any other step. The conversation is the same `AIState`, so `useAgent()` renders
+every harness alike.
+
+## Install
+
+```bash
+pnpm add libfx                                                  # fx()
+pnpm add @earendil-works/pi-coding-agent @earendil-works/pi-ai  # pi()
+```
+
+## Run FX
+
+`fx()` runs FX's kernel in your server process. FX adds no system prompt of its
+own and brings no tools, so `instructions` is the whole prompt and `tools` is
+everything it can call:
+
+```ts server/coder.ts
+import { tool } from 'ai'
+import { Sandbox } from '@vercel/sandbox'
+import { z } from 'zod'
+import { handlerContext } from 'experimental-a2/ai'
+import { agent } from 'experimental-a2/ai/server'
+import { fx } from 'experimental-a2/ai/fx'
+
+export const coder = agent({
+  name: 'coder',
+  harness: fx(),
+  model: 'anthropic/claude-sonnet-5.5',
+  instructions: 'Fix the bug the user describes. Keep replies short.',
+  tools: {
+    bash: tool({
+      description: 'Run a shell command in the repository.',
+      inputSchema: z.object({ command: z.string() }),
+      execute: async ({ command }) => {
+        const { session, signal } = handlerContext()
+        // One Vercel Sandbox per session, created on first use.
+        const sandbox = await Sandbox.getOrCreate({
+          name: session.id,
+          persistent: true,
+          signal,
+        })
+        const result = await sandbox.runCommand({
+          cmd: 'bash',
+          args: ['-c', command],
+          signal,
+        })
+        return { exitCode: result.exitCode, output: await result.stdout() }
+      },
+    }),
+  },
+  toolRecovery: { bash: 'report' },
+})
+```
+
+## Run Pi
+
+`pi()` runs Pi's own agent session: Pi's system prompt, and Pi's `read`,
+`write`, `edit`, and `bash` tools. `instructions` adds to Pi's prompt and
+`tools` adds to Pi's tools; a tool with the name of one of Pi's replaces it.
+Pi's tools work in the session's sandbox, so `pi()` takes one:
+
+```ts server/pi-coder.ts
+import type { Experimental_SandboxSession } from 'ai'
+import { agent } from 'experimental-a2/ai/server'
+import { pi } from 'experimental-a2/ai/pi'
+
+// your sandbox: the same AI SDK sandbox session for a session every time,
+// for example from @ai-sdk/sandbox-vercel
+declare function openSandbox(
+  sessionId: string,
+): Promise<Experimental_SandboxSession>
+
+export const piCoder = agent({
+  name: 'pi-coder',
+  harness: pi({ sandbox: ({ session }) => openSandbox(session.id) }),
+  model: { model: 'anthropic/claude-sonnet-5.5', reasoning: 'low' },
+})
+```
+
+`sandbox` resolves the session's sandbox, any AI SDK sandbox session, for each
+tool execution, and for a step until Pi's session records the sandbox's
+working directory, so return the same one for a session every time and create
+it only once. Your own tools under `pi()`
+receive it as `experimental_sandbox` too. A2 never stops it; stopping it is
+yours. Pi works in the sandbox's working directory, and its `bash` runs with
+the sandbox's own environment; none of your server's environment reaches it.
+
+Pi's tools move at most 4 MiB from the sandbox to your server per file read
+or command. A larger file fails `read` or `edit`, and a command whose output
+passes 4 MiB is stopped and fails `bash`; both errors tell the model to read in
+parts. Files arrive through the sandbox's `readFile`, so implement it as a
+stream for the limit to bound the download too.
+
+## Models and credentials
+
+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.
+
+## 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
+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.
+
+## Recovery
+
+A2 records each model call and each tool result as the harness works. When a
+process dies in the middle of a response, the next attempt resumes at the
+interrupted step: finished model calls are not made again and finished tools
+do not run again. A2 stores nothing outside the log: a process that ran the
+last response resumes the harness from its state at the end of that response,
+FX's checkpoint or Pi's session, kept in memory, and any other process replays
+the session from the log. A tool call that a crash cut short reruns unless its
+`toolRecovery` is `'report'`; see [Delivery semantics](/agents/conversations#delivery-semantics).

package/docs/agents/meta.ts

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