experimental-a2 0.11.0 → 0.13.0

package/dist/{server-DwPrMqHB.d.ts.map → server-DjZZa1wr.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"server-DwPrMqHB.d.ts","names":[],"sources":["../src/session-socket.ts","../src/server-fetch.ts","../src/scheduler-task.ts","../src/server.ts"],"mappings":";;;;;;;;;;;KAmCY;EACV,KAAK;EACL,GAAG,kBAAkB,WAAW;EAChC,GAAG,gBAAgB;EACnB,GAAG,gBAAgB,WAAW;EAC9B,MAAM,eAAe;;;EAGrB;;;;KCnBG,mBAAmB,UAAU,oBACzB,wBAAwB;KAE5B,wBAAwB,UAAU,gBAAgB,YAClD,WAAW,2BAA0B;KAG9B,YAAY,UAAU,YAAY;WACnC,MAAM,mBAAmB;WACzB;WACA;;KAGC,eAAe,UAAU,eAAe;WACzC;WACA,QAAQ,wBAAwB;WAChC;WACA;;KAGC,YACV,UAAU,YAAY,WACtB,UAAU,eAAe;WAGZ;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA,iBAAiB,YAAY;WAC7B,WAAW,eAAe;WAC1B;;KAGH,oBACV,SAAS,QAAQ,sBACd,WAAW,QAAQ;KAEZ,mBACV,UAAU,YAAY,WACtB,UAAU,eAAe;EAEzB,aAAa,WAAW,YAAY,GAAG,iBAAiB;EACxD,mBAAmB;;EAEnB;;;;;KC/EU;EACV;EACA;EACA;;;KAIU;EACV;EACA;EACA;EACA;;EAEA;;;KAIU;EACV;EACA;;EAEA;EACA;EACA;;EAEA;EACA,iBAAiB;;;KAIP,gBAAgB,qBAAqB;;;;KC8CrC,eACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe;;EAGzB,OAAO,cAAc,GAAG;;EAExB;;EAEA,SAAS,QAAQ,GAAG,cAAc,IAAI;;EAEtC,QAAQ;;KAGE,QACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe,yBAEzB,KAAK,eAAe,GAAG,GAAG,OACvB,eAAe,YAAY,cAAc,YAAY;KAE9C,YACV,UAAU,WACV,gBAAgB,mBAAmB;EAEnC;EACA,OAAO,KAAK,cAAc,GAAG;IAA4B;;;KAG/C,KACV,UAAU,WACV,gBAAgB,mBAAmB,yBACtB,SAAS,YAAY,GAAG;KAE3B,gBAAgB,UAAU,iBACjC,QAAQ,YAAY,SACpB,QAAQ,cAAc;KAEf,cAAc,UAAU,aAAa,gBAAgB;;EAE/D,UAAU,gBAAgB;;KAGhB,cAAc,UAAU,cAClC,iBACG,QAAQ,YAAY,SACpB,QAAQ,cAAc;KAEf;KAEA;EACR,OAAO;EAAe;;EAAiB,IAAI;EAAM;;KAEzC,gBAAgB,UAAU,cACpC,cACA,QAAQ,mBACL,QAAQ,YAAY,SACpB;KAEO;EACV;;;;;;;;;KAUU,gBAAgB,UAAU,WAAW,UAAU;;;;;;EAMzD,OAAO;IACL;IACA;MACE,cAAc,cAAc,KAAK,cAAc,KAAK,iBAAiB;;;;;;;EAOzE,YAAY;IACV;IACA,QAAQ,cAAc;IACtB;IACA;MACE;;EAEJ,YAAY,QAAQ,YAAY;;;KAItB,QACV,UAAU,WACV,SAAS,cAAc,IACvB,UAAU,eAAe,wBACvB,aAAa,GAAG,gBAAgB,GAAG;WAC5B;EACT,QAAQ;EACR,UAAU,gBAAgB;EAC1B,QAAQ;IAAY;IAAc;MAAiB,QAAQ,cAAc;EACzE,MAAM,GACJ,SAAS,QAAQ,GAAG,IACpB,UAAU,eACT;IAAU,OAAO;IAAG;;;;;;EAKvB,OAAO;IAAS;MAAwB,cAAc,cAAc;;;;;;;KAQ1D;WACD;aAAqB;;EAC9B,MAAM,oBAAoB;IAAU;;;;;;;;;;;;KAY1B;EACV,SAAS,MAAM,gBAAgB;EAC/B,WAAW,SAAS,qBAAqB,KAAK,YAAY,QAAQ;;KAGxD,SACV,UAAU,WACV,UAAU,eAAe;;WAGhB,UAAU,SAAS,GAAG;WACtB;KACN,SAAS,UAAU,QAAQ;KAC3B,SAAS,SAAS,SAAS,mBAAmB,GAAG,KAAK,QAAQ;;EAEjE,QAAQ,aAAa,QAAQ,GAAG,cAAc,IAAI;;;;;EAKlD,MAAM,oBAAoB;IAAU;;;;;;;;iBAiBhB,uBACpB,QAAQ,iBACR,MAAM,sBACL;;;;;;;;;KAuBS,UAAU,UAAU,WAAW,gBAAgB,cACvD,YAAY,iBAET,WAAW,uBAGN,OAAO,cAAc,GAAG,IACxB,SAAS,cAAc,GAAG,IAC1B;EAAW;;KAIX,aACV,UAAU,WACV,gBAAgB,mBAAmB,YACnC,UAAU,eAAe,wBAEvB,QAAQ,GAAG,GAAG;EAEZ,UAAU,UAAU,GAAG;;EAEvB,OAAO,KAAK,GAAG;EACf,SAAS,QAAQ,GAAG,GAAG;;KAGjB,cACV,UAAU,WACV,UAAU,eAAe;;EAGzB,UAAU,SAAS,GAAG;;EAEtB,QAAQ;;;;;;;EAOR,YAAY;;EAEZ,YAAY;;;;;;EAMZ;IAAa;;;;;;;;EAOb,cAAc,WAAW,cAAc,aAAa,GAAG,GAAG;;;iBA2K5C,aACd,UAAU,WACV,UAAU,eAAe,sBACzB,SAAS,cAAc,GAAG,KAAK,SAAS,GAAG"}
+{"version":3,"file":"server-DjZZa1wr.d.ts","names":[],"sources":["../src/session-socket.ts","../src/server-fetch.ts","../src/scheduler-task.ts","../src/server.ts"],"mappings":"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"}

package/dist/server.d.ts

@@ -1,4 +1,4 @@
 import { a as ContractEvent, c as PresenceDefs, d as PresenceSnapshot, i as Contract, l as PresenceMap, r as AppendInput, s as EventDefs, u as PresencePatch } from "./reducer-DJKWm3cp.js";
 import { a as EventCause, c as PresenceRow, d as StoreStateRead, f as StoredEvent, i as Event, l as StoreAppendResult, n as AppendEvent, o as FailAttemptResult, r as Clock, s as IdSource, t as A2Store, u as StoreClaimAvailableResult } from "./store-DtDOWLSn.js";
-import { A as UpgradeWebSocket, C as SchedulerAppendTask, D as A2PushEvent, E as A2Operation, O as A2PushPresence, S as ScheduledEvent, T as SchedulerTask, _ as SessionPresence, a as Handler, b as createServer, c as HandlerEntry, d as ScheduleDelay, f as ScheduleTiming, g as SessionDispatch, h as SessionAppend, i as DrainableServer, j as A2Socket, k as ServerFetchOptions, l as Lane, m as Session, n as A2Server, o as HandlerAppend, p as ServerOptions, r as AbortSpec, s as HandlerContext, t as A2Scheduler, u as LaneContext, v as SessionSchedule, w as SchedulerDrainTask, x as deliverSchedulerAppend, y as StateOptions } from "./server-DwPrMqHB.js";
-export { type A2Operation, type A2PushEvent, type A2PushPresence, A2Scheduler, A2Server, type A2Socket, type A2Store, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerDrainTask, type SchedulerTask, type ServerFetchOptions, ServerOptions, Session, SessionAppend, SessionDispatch, SessionPresence, SessionSchedule, StateOptions, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type UpgradeWebSocket, createServer, deliverSchedulerAppend };
+import { A as ServerFetchOptions, C as ScheduledEvent, D as A2Operation, E as SchedulerTask, M as A2Socket, O as A2PushEvent, S as handler, T as SchedulerDrainTask, _ as SessionPresence, a as Handler, b as createServer, c as HandlerEntry, d as ScheduleDelay, f as ScheduleTiming, g as SessionDispatch, h as SessionAppend, i as DrainableServer, j as UpgradeWebSocket, k as A2PushPresence, l as Lane, m as Session, n as A2Server, o as HandlerAppend, p as ServerOptions, r as AbortSpec, s as HandlerContext, t as A2Scheduler, u as LaneContext, v as SessionSchedule, w as SchedulerAppendTask, x as deliverSchedulerAppend, y as StateOptions } from "./server-DjZZa1wr.js";
+export { type A2Operation, type A2PushEvent, type A2PushPresence, A2Scheduler, A2Server, type A2Socket, type A2Store, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerDrainTask, type SchedulerTask, type ServerFetchOptions, ServerOptions, Session, SessionAppend, SessionDispatch, SessionPresence, SessionSchedule, StateOptions, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type UpgradeWebSocket, createServer, deliverSchedulerAppend, handler };

package/dist/server.js

@@ -1,2 +1,2 @@
-import { n as deliverSchedulerAppend, t as createServer } from "./server-Dkz2a84E.js";
-export { createServer, deliverSchedulerAppend };
+import { n as deliverSchedulerAppend, r as handler, t as createServer } from "./server-BeNADlCI.js";
+export { createServer, deliverSchedulerAppend, handler };

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

@@ -762,35 +762,111 @@ interaction that began elsewhere.
 
 ## Compact long conversations
 
-Compaction is optional application policy. A2 records both the decision and
-replacement messages, so later prompts remain explainable from history:
+Compaction is automatic for supported Gateway models. A2 uses the active model
+with the same instructions, tool definitions, and provider settings, and appends
+an internal user message asking for a summary. This preserves the request prefix
+for prompt caching when the provider has a matching cache entry.
 
 ```ts server/compacted.ts
-import type { UIMessage } from 'ai'
 import { createAgentServer } from 'experimental-a2/ai/server'
 import { assistant } from '../assistant'
 
 export const compactedAssistantServer = createAgentServer({
   agent: assistant,
   model: 'openai/gpt-5.6-terra',
-  compaction: {
-    shouldCompact: ({ messages }) => messages.length > 40,
-    compact: async ({ messages }) => {
-      const summary = {
-        id: crypto.randomUUID(),
-        role: 'user',
-        parts: [{ type: 'text', text: 'Summary of the earlier conversation.' }],
-      } satisfies UIMessage
-
-      return [summary, ...messages.slice(-10)]
-    },
-  },
 })
 ```
 
-The callback can call another model, create a deterministic summary, or retain
-selected messages. A2 owns only when the result enters the log and how later
-generations consume it.
+On first use of each Gateway model in a session, A2 includes
+`ai.model.metadata.requested` in the existing generation-start append. A separate
+handler fetches the public Gateway model catalog and records the selected limits
+in `ai.model.metadata.resolved`. It runs outside the AI turn lane. The first model
+request proceeds immediately; metadata that arrives afterward is available to
+later steps. Returning to a previously used model reuses its durable metadata.
+The catalog is also cached in memory for one hour across agent servers, with one
+shared in-flight request and a five-second timeout. A failed lookup follows A2's
+handler retry policy without failing the model generation. A model absent from
+the catalog is recorded as unavailable. A pending entry means no result has been
+recorded, including when the metadata handler exhausts its retry budget. A2 does
+not start a fresh lookup on every turn after exhaustion. Inspect the handler
+failure or use an explicit threshold in that case.
+
+The default threshold is 75% of the context window. A larger configured
+`generation.maxOutputTokens` lowers the threshold further to reserve that output
+allowance. This is an input-context policy, not a new output limit. Limits and
+metadata status are available in `state.modelMetadata`.
+
+`compaction: { thresholdTokens: 80_000 }` overrides discovery with an explicit
+positive safe integer. `compaction: { instructions: 'Preserve exact IDs.' }`
+adds guidance to the built-in summary prompt while keeping the derived threshold.
+`compaction: false` disables both compaction and metadata lookup. The `compaction`
+option can also be a synchronous resolver receiving the same
+`{ event, state, history, signal }` context as `model` and `instructions`. It
+returns `false`, automatic options, or a custom policy once per generation.
+Use this to select a session-specific threshold from already-recorded settings.
+Changes after resolution apply to a later model step. Disabling compaction
+preserves summaries that were already recorded. Custom provider
+models and custom global SDK providers need an explicit threshold. A custom
+`generate` callback keeps compaction disabled unless explicitly configured. Gateway
+fallback model lists also need an explicit threshold appropriate for every model
+they may use.
+
+The input estimate starts from serialized UTF-8 bytes divided by four, including
+model messages, instructions, and tool schemas. When a preceding model call has
+reported token usage for the same model and context, A2 uses that measurement as
+an anchor and estimates subsequent growth. It is not a provider tokenizer and
+does not precisely measure new image or audio tokens. A2 performs no remote token
+counting.
+
+On a cold session without recorded metadata or an explicit threshold, automatic
+compaction waits for discovery. An oversized first prompt is sent normally and
+its provider error becomes a generation failure. A2 does not silently truncate
+it or attempt automatic recovery from a context-limit error. Use an explicit threshold for
+applications that import a large initial conversation. The estimate is a
+compaction trigger, not a definitive overflow check. Provider context-limit
+errors during generation or summarization remain generation failures.
+
+Crossing the threshold adds one summary model request. Application generation
+callbacks, stream transforms, and tool hooks do not run for the summary, and it
+never executes local tools. Provider-executed tools, structured output, and forced
+tool choices disable implicit automatic compaction; explicitly configuring
+automatic compaction for those requests throws. Use a custom policy for them.
+An empty summary or a summary tool call fails the generation instead of replacing
+its context.
+
+A2 records `ai.compaction.requested` before the call and
+`ai.compaction.completed` after a successful summary. The completed event stores
+the summary, its usage, and the exact event frontier it covers. Later model
+requests receive the summary plus everything produced after that frontier,
+including later tool steps in the same assistant message. Queued user messages
+remain queued. Compaction waits until earlier tool calls have terminal results.
+The raw log and `state.messages` remain available in full.
+
+Custom `shouldCompact(context)` and `compact(context)` callbacks remain
+available for deterministic replacement messages or application-specific
+retention. Both receive the typed UI messages and `modelMessages`, the model-ready
+context including any existing summary. Custom generation callbacks also receive
+`modelMessages`; use it when forwarding context to a provider. A2 stores built-in
+summaries separately from application-typed UI messages, so a summary does not
+need your message metadata or schema.
+
+Render compaction as activity alongside the conversation:
+
+```tsx app/agent/compaction-status.tsx
+'use client'
+import { useSession } from './session'
+
+export function CompactionStatus() {
+  const { state } = useSession()
+  return state.compaction?.status === 'running' ? (
+    <p role="status">Compacting…</p>
+  ) : null
+}
+```
+
+A failed or interrupted generation restores the prior compaction state. The
+synthetic summary request is not a user turn or an assistant reply in
+`state.messages`.
 
 ## Extend the assembly
 
@@ -900,6 +976,12 @@ 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.
 
+An expired claim or superseded attempt preserves its abort reason through model,
+resolver, compaction-policy, and tool calls. A2 retries that attempt without
+spending its failure budget. Explicit user interruption remains terminal.
+Streaming tool progress belongs to an execution attempt, so a retry can produce
+different preliminary output while preserving the tool-call id for idempotency.
+
 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

package/docs/reference/01-api.mdx

@@ -65,6 +65,64 @@ client exposes its `A2ClientError` subclass. See
 
 ## `experimental-a2/server`
 
+### `handler(entry)`
+
+Define handlers inline in `createServer({ handlers })` for ordinary use.
+Use this helper when composing an existing handler.
+
+Accepts a handler function or an object with `handler` and optional `lane` and
+`abortOn`. Returns the object shape: a function becomes `{ handler: entry }`,
+and an object is returned unchanged. The original function and object types
+are preserved. Use it to compose an existing handler without branching on its
+shape.
+
+```ts server/composed-orders.ts
+import * as a2 from 'experimental-a2'
+import { createServer, handler, type HandlerContext } from 'experimental-a2/server'
+import { z } from 'zod'
+
+const orders = a2.contract({
+  name: 'composed-orders',
+  events: {
+    created: z.object({ shopId: z.string() }),
+    notified: z.object({ shopId: z.string() }),
+  },
+})
+
+const created = handler({
+  lane: 'orders',
+  handler: async (ctx: HandlerContext<typeof orders.events, 'created'>) => {
+    return orders.batch({ type: 'notified', payload: ctx.event.payload })
+  },
+})
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: {
+      ...created,
+      handler: async (ctx) => {
+        const result = await created.handler(ctx)
+        // Your additional work goes here:
+        // await notifyShop(ctx.event.payload, { idempotencyKey: ctx.event.id })
+        return result
+      },
+    },
+  },
+})
+```
+
+Spreading the object preserves its `lane` and `abortOn`. Set either property
+after the spread to override it. Changing a built-in AI handler's lane can
+separate it from the handlers it coordinates with.
+
+Composition runs in one handler attempt. Work after the original function
+resolves still runs before its returned events commit. A thrown error fails
+the composed attempt; on retry, the wrapper and original handler can run again.
+For a new handler, annotate its context as above or pass an already typed
+function. `handler` does not bind a handler to a contract;
+`createServer({ handlers })` checks that it matches the contract.
+
 ### `createServer(options)`
 
 ```ts
@@ -1091,7 +1149,7 @@ 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`.
+Extension events are ignored. The default reducer name is `a2.ai.state.v10`.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
@@ -1185,9 +1243,46 @@ 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`.
+The resolver runs synchronously once per generation and must return a valid policy
+or `false`. Custom `shouldCompact` and `compact` callbacks can still be asynchronous.
+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.
 
@@ -1205,7 +1300,12 @@ it into `createServer({ handlers })` beside application handlers when you need
 a custom assembly. The table handles input facts, generation requests, model
 step completion, tool calls, approval responses, and terminal tool results.
 Application handlers spread later can deliberately replace a built-in
-handler. A custom assembly owns its browser ingress policy. Use
+handler. Use `handler` from `experimental-a2/server` to normalize an
+existing entry before wrapping its `handler` and spreading its execution
+policy. Entries in this table's type are optional; narrow an entry before
+passing it to `handler`.
+
+A custom assembly owns its browser ingress policy. Use
 `server.fetch(request, { authorize })` to reject server-authored AI event names
 before they reach the server. `createAgentServer()` installs the built-in
 browser allowlist automatically.

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

@@ -10,6 +10,9 @@ import { inputs } 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'
 
 type MessagePart = UIMessage['parts'][number]
 type ToolPartView = {
@@ -169,10 +172,12 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
   const [responding, setResponding] = useState(false)
 
   const generating = state.status === 'generating'
+  const compacting = state.compaction?.status === 'running'
   const canSend = state.status === 'idle' || state.status === 'failed'
+  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> => {
@@ -250,32 +255,43 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
             state.status === 'waiting' ? ' waiting' : ''
           }${state.status === 'failed' ? ' cut' : ''}`}
         >
-          {STATUS_LABEL[state.status]}
+          {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 &&
+                    !compacting &&
+                    entry.lastSegment &&
+                    entry.message.id ===
+                      state.activeGeneration?.responseMessageId &&
+                    !hasVisibleParts(entry.message)
+                  }
+                />
+              ),
+            )
           )}
-          {generating && state.messages.at(-1)?.role === 'user' ? (
+          {generating &&
+          !compacting &&
+          state.messages.at(-1)?.role === 'user' ? (
             <div className="agent-message assistant">
               <span className="agent-role">Agent</span>
               <div>
@@ -340,7 +356,6 @@ export function AgentClient({ agentId }: { agentId: string }): ReactNode {
             Message
             <textarea
               ref={promptRef}
-              autoFocus
               rows={3}
               value={prompt}
               onChange={(event) => setPrompt(event.target.value)}

package/examples/playground/app/agent/[agentId]/compaction/route.ts

@@ -0,0 +1,14 @@
+import { updateCompactionSettings } from '../../compaction-settings'
+import { agentServer } from '../../server'
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ agentId: string }> },
+): Promise<Response> {
+  const { agentId } = await context.params
+  return updateCompactionSettings({
+    request,
+    sessionId: agentId,
+    append: (event) => agentServer.session(agentId).append(event),
+  })
+}

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

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+import { formatActivityTime } from '@/app/components/activity-feed'
+import type { CompactionEntry } from '../compaction-timeline'
+
+export function CompactionEvent({
+  entry,
+}: {
+  entry: CompactionEntry
+}): ReactNode {
+  const { event, running, outcome } = entry
+  const completed = event.type === 'ai.compaction.completed'
+  const label = completed
+    ? 'Context compacted'
+    : running
+      ? 'Compacting…'
+      : 'Compaction did not complete'
+
+  return (
+    <details className="agent-compaction-event">
+      <summary>
+        <span role={running ? 'status' : undefined}>{label}</span>
+        <time dateTime={event.createdAt.toISOString()}>
+          {formatActivityTime(event.createdAt)}
+        </time>
+      </summary>
+      <p className="hint">
+        Event #{event.index} ·{' '}
+        {event.payload.throughIndex === undefined
+          ? `Through message ${event.payload.throughMessageId}`
+          : `Summarized through event #${event.payload.throughIndex}`}
+        {outcome === undefined ? null : ` · Generation ${outcome}`}
+      </p>
+      {completed && event.payload.summary ? (
+        <pre>{event.payload.summary}</pre>
+      ) : null}
+    </details>
+  )
+}