broapp 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broapp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Build tooling and runtime for local applications made of a Bun host, a browser UI, and a Brobridge connection between them",
   "license": "MIT",

package/src/ai/host/create-ai.ts

@@ -22,7 +22,7 @@ import { createPendingApprovals, createReservedHostApp } from '../../host/index.
 import type { HostApp, HostLogger, StreamSink } from '../../host/app.ts';
 import { publicError } from '../../shared/errors.ts';
 import { aiContract, type AiContract } from '../shared/contract.ts';
-import type { ProviderInfo } from '../shared/types.ts';
+import type { ChatTurn, ProviderInfo } from '../shared/types.ts';
 
 import { AdapterError, toPublicError, type AdapterConfig, type ProviderAdapter } from './adapter.ts';
 import { createRegistry, type Registry } from './registry.ts';
@@ -64,6 +64,11 @@ export interface InProcessTurn {
   readonly message: string;
   /** The model for this turn, within the configured provider. */
   readonly modelId?: string;
+  /**
+   * Earlier turns, as a browser would send them. An assistant turn naming a
+   * run this layer kept a transcript for is expanded exactly as on `ai.chat`.
+   */
+  readonly history?: readonly ChatTurn[];
 }
 
 /** How {@link Ai.turn} is answered and stopped. */
@@ -291,6 +296,14 @@ export function createAi(options: CreateAiOptions): Ai {
     }
   });
 
+  // Opened on the first conversation route and not before: an application
+  // whose user never opens the panel should not find a database in its data
+  // directory, and `createAi` is built unconditionally by every application
+  // that offers AI at all. A turn opens it too, to keep its transcript.
+  let threads: ThreadStore | null = null;
+  const threadStore = (): ThreadStore =>
+    (threads ??= openThreads(options.dataDir, options.logger === undefined ? {} : { logger: options.logger }));
+
   const approvals = createPendingApprovals(options.logger);
   const runDeps: RunDeps = {
     registry,
@@ -303,6 +316,12 @@ export function createAi(options: CreateAiOptions): Ai {
     approvals,
     ...(options.onRunEnd === undefined ? {} : { onRunEnd: options.onRunEnd }),
     ...(options.onContext === undefined ? {} : { onContext: options.onContext }),
+    transcripts: {
+      save: (runId, messages) => {
+        threadStore().saveTranscript(runId, messages);
+      },
+      read: (runId) => threadStore().transcript(runId),
+    },
     logger: options.logger ?? console,
   };
 
@@ -315,13 +334,6 @@ export function createAi(options: CreateAiOptions): Ai {
       approvals.answer({ requestId: `${runId}:${callId}`, approved: approve }) === 'accepted',
   }));
 
-  // Opened on the first conversation route and not before: an application
-  // whose user never opens the panel should not find a database in its data
-  // directory, and `createAi` is built unconditionally by every application
-  // that offers AI at all.
-  let threads: ThreadStore | null = null;
-  const threadStore = (): ThreadStore => (threads ??= openThreads(options.dataDir));
-
   host.operation('ai.threadsList', () => ({ threads: threadStore().list() }));
   host.operation('ai.threadsCreate', (input) => threadStore().create(input));
   host.operation('ai.threadsGet', ({ id }) => threadStore().get(id));
@@ -400,7 +412,7 @@ export function createAi(options: CreateAiOptions): Ai {
             runId: turn.runId,
             message: turn.message,
             refs: [],
-            history: [],
+            history: turn.history === undefined ? [] : [...turn.history],
             ...(turn.modelId === undefined ? {} : { modelId: turn.modelId }),
           },
           sink,

package/src/ai/host/run.ts

@@ -22,6 +22,7 @@ import type { ApprovalQuestion, Approver } from '../../host/gate.ts';
 import type { Effect } from '../../shared/contract.ts';
 import { fromTransportError, isPublicError, publicError } from '../../shared/errors.ts';
 import type { ToolPermission } from '../shared/types.ts';
+import type { ChatTurn } from '../shared/types.ts';
 import type { ChatEvent, StreamChatParams } from './run-types.ts';
 
 import { AdapterError } from './adapter.ts';
@@ -29,6 +30,18 @@ import type { AdapterConfig, ProviderAdapter } from './adapter.ts';
 import type { Registry } from './registry.ts';
 import type { AiContextProviders, AiTool, ContextDocument } from './tool.ts';
 import type { DeliveredContext, RunEndDetail } from './create-ai.ts';
+import type { ResponseMessage } from './threads.ts';
+
+/**
+ * Where a turn's own transcript is kept and read back.
+ *
+ * Both sides are the host's: `save` is handed what the AI SDK produced, and
+ * `read` returns only what `save` wrote. A browser never supplies either.
+ */
+export interface RunTranscripts {
+  save(runId: string, messages: readonly ResponseMessage[]): void;
+  read(runId: string): readonly ResponseMessage[] | null;
+}
 
 /** What the run loop needs from the `Ai` that owns it. */
 export interface RunDeps {
@@ -62,6 +75,11 @@ export interface RunDeps {
   ) => void;
   /** Called once per turn with what the model is about to be given. */
   readonly onContext?: (runId: string, delivered: DeliveredContext) => void;
+  /**
+   * The turn transcripts. Absent, every history turn is text and nothing is
+   * written, which is exactly the layer before transcripts existed.
+   */
+  readonly transcripts?: RunTranscripts;
 }
 
 /** What a turn counts as it goes, for {@link RunEndDetail}. */
@@ -217,6 +235,120 @@ async function assembleContext(
   return fitToBudget(documents, deps.contextBudgetChars);
 }
 
+/** The bounds on history expanded from transcripts. */
+export interface HistoryLimits {
+  /** Assistant turns expanded, newest first. */
+  readonly turns: number;
+  /** Characters of one tool call's input, as JSON. */
+  readonly inputChars: number;
+  /** Characters of one tool result's output, as JSON. */
+  readonly outputChars: number;
+  /** Characters of every expanded message together, as JSON. */
+  readonly totalChars: number;
+}
+
+/** The bounds a turn uses. */
+export const HISTORY_LIMITS: HistoryLimits = {
+  turns: 6,
+  inputChars: 1_000,
+  outputChars: 2_000,
+  totalChars: 60_000,
+};
+
+/** The head of a long string, and how much was left out. Never a summary. */
+function cut(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}<omitted ${String(text.length - max)} chars>`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A tool result's output, bounded.
+ *
+ * An `error` is kept whole wherever it is — an error-typed output, or the
+ * `{ error }` a failed tool returns — because it is the one thing a model
+ * needs verbatim to avoid repeating the call that caused it.
+ */
+function boundOutput(output: unknown, max: number): unknown {
+  if (!isRecord(output)) return output;
+  const type = output['type'];
+  if (type === 'error-text' || type === 'error-json' || type === 'execution-denied') return output;
+  if (type === 'text' && typeof output['value'] === 'string') {
+    return { type: 'text', value: cut(output['value'], max) };
+  }
+  const json = JSON.stringify(type === 'json' ? output['value'] : output) ?? '';
+  if (json.length <= max) return output;
+  const value = type === 'json' ? output['value'] : undefined;
+  if (isRecord(value) && 'error' in value) {
+    const { error, ...rest } = value;
+    return { type: 'json', value: { error, rest: cut(JSON.stringify(rest), max) } };
+  }
+  return { type: 'text', value: cut(json, max) };
+}
+
+/** One transcript message with every tool input and output bounded. */
+function boundMessage(message: ResponseMessage, limits: HistoryLimits): ModelMessage {
+  if (!Array.isArray(message.content)) return message;
+  const content = (message.content as readonly unknown[]).map((part) => {
+    if (!isRecord(part)) return part;
+    if (part['type'] === 'tool-call') {
+      const json = JSON.stringify(part['input']) ?? '';
+      return json.length <= limits.inputChars ? part : { ...part, input: cut(json, limits.inputChars) };
+    }
+    if (part['type'] === 'tool-result') return { ...part, output: boundOutput(part['output'], limits.outputChars) };
+    return part;
+  });
+  return { ...message, content } as ModelMessage;
+}
+
+/**
+ * History as the model is given it.
+ *
+ * Walking from the newest turn back, an assistant turn whose `runId` names a
+ * transcript the host holds is replaced by that transcript — its own tool calls
+ * and results, bounded — while fewer than `limits.turns` have been and the total
+ * stays under `limits.totalChars`. The first turn that would cross the total
+ * stays text, and so does every turn older than it. Every other turn is its text,
+ * exactly as before. User turns keep their place.
+ */
+export function expandHistory(
+  history: readonly ChatTurn[],
+  read: (runId: string) => readonly ResponseMessage[] | null,
+  limits: HistoryLimits = HISTORY_LIMITS,
+): ModelMessage[] {
+  const segments: ModelMessage[][] = [];
+  let expanded = 0;
+  let total = 0;
+  let full = false;
+  for (let index = history.length - 1; index >= 0; index -= 1) {
+    const turn = history[index];
+    if (turn === undefined) continue;
+    const text: ModelMessage[] = [{ role: turn.role, content: turn.content }];
+    if (turn.role !== 'assistant' || turn.runId === undefined || full || expanded >= limits.turns) {
+      segments.push(text);
+      continue;
+    }
+    const transcript = read(turn.runId);
+    if (transcript === null || transcript.length === 0) {
+      segments.push(text);
+      continue;
+    }
+    const bounded = transcript.map((message) => boundMessage(message, limits));
+    const chars = JSON.stringify(bounded).length;
+    if (total + chars > limits.totalChars) {
+      full = true;
+      segments.push(text);
+      continue;
+    }
+    total += chars;
+    expanded += 1;
+    segments.push(bounded);
+  }
+  return segments.reverse().flat();
+}
+
 /**
  * A message the model may see, without whatever a caller invented.
  *
@@ -224,13 +356,21 @@ async function assembleContext(
  * are strings by contract, so an earlier turn's picture is already a
  * `[image: name]` line the browser put there — the alternative, resending
  * every image on every turn, would cost the user the same upload again on each
- * question.
+ * question. An assistant turn that names its run is expanded from the host's
+ * own transcript by {@link expandHistory}.
  */
-function toModelMessages(params: StreamChatParams): ModelMessage[] {
-  const messages: ModelMessage[] = params.history.map((turn) => ({
-    role: turn.role,
-    content: turn.content,
-  }));
+function toModelMessages(params: StreamChatParams, transcripts: RunTranscripts | undefined, logger: HostLogger): ModelMessage[] {
+  const read = (runId: string): readonly ResponseMessage[] | null => {
+    if (transcripts === undefined) return null;
+    try {
+      return transcripts.read(runId);
+    } catch (cause) {
+      // A store that cannot be read has no transcript to give; the turn is text.
+      logger.error(`[broapp] ai could not read the transcript of run ${runId}: ${String(cause instanceof Error ? cause.message : cause)}`);
+      return null;
+    }
+  };
+  const messages: ModelMessage[] = expandHistory(params.history, read);
   const files = params.files ?? [];
   if (files.length === 0) {
     messages.push({ role: 'user', content: params.message });
@@ -366,6 +506,7 @@ function buildTools(
   deps: RunDeps,
   sink: StreamSink<ChatEvent>,
   approver: Approver,
+  recorder: TranscriptRecorder,
 ): ToolSet {
   const tools: ToolSet = {};
   for (const [name, definition] of Object.entries(deps.tools)) {
@@ -374,6 +515,7 @@ function buildTools(
       inputSchema: jsonSchema(definition.inputSchema),
       execute: async (input: unknown, options: { toolCallId: string }): Promise<unknown> => {
         const callId = options.toolCallId;
+        recorder.called(callId, name, input);
         await sink.emit({
           type: 'tool-call',
           callId,
@@ -409,12 +551,14 @@ function buildTools(
               output: DECLINED,
               denied: true,
             });
+            recorder.answered(callId, DECLINED);
             return DECLINED;
           }
           // One tool failing is not the turn failing. The model gets the
           // reason and can carry on or explain.
           output = { error: safeToolMessage(cause, name, deps.logger) };
         }
+        recorder.answered(callId, output);
         await sink.emit({ type: 'tool-result', callId, tool: name, output });
         return output;
       },
@@ -442,6 +586,59 @@ function safeToolMessage(cause: unknown, name: string, logger: HostLogger): stri
   return 'The tool failed.';
 }
 
+/**
+ * What a turn has produced so far, for a turn that does not reach `finish`.
+ *
+ * A finished turn's transcript is the AI SDK's own `responseMessages`. A turn
+ * that is stopped never gets one, and a stopped turn is exactly the one whose
+ * "continue" needs it most; so the steps the SDK finished are kept as it gave
+ * them, and the step in flight is kept from its text and from the calls this
+ * layer ran. Storage removes a call that never got its result.
+ */
+class TranscriptRecorder {
+  /** Set once the model has been asked; before that there is nothing to keep. */
+  started = false;
+  private readonly finished: ResponseMessage[] = [];
+  private text = '';
+  private calls = new Map<string, { name: string; input: unknown; output?: { value: unknown } }>();
+
+  stepEnded(messages: readonly ResponseMessage[]): void {
+    this.finished.push(...messages);
+    this.text = '';
+    this.calls = new Map();
+  }
+
+  wrote(text: string): void {
+    this.text += text;
+  }
+
+  called(callId: string, name: string, input: unknown): void {
+    this.calls.set(callId, { name, input });
+  }
+
+  answered(callId: string, output: unknown): void {
+    const call = this.calls.get(callId);
+    if (call !== undefined) call.output = { value: output };
+  }
+
+  /** Every finished step, then the step in flight. */
+  sofar(): ResponseMessage[] {
+    const assistant: Array<{ type: 'text'; text: string } | { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }> = [];
+    if (this.text !== '') assistant.push({ type: 'text', text: this.text });
+    const results: Array<{ type: 'tool-result'; toolCallId: string; toolName: string; output: { type: 'json'; value: never } }> = [];
+    for (const [toolCallId, call] of this.calls) {
+      assistant.push({ type: 'tool-call', toolCallId, toolName: call.name, input: call.input });
+      if (call.output !== undefined) {
+        results.push({ type: 'tool-result', toolCallId, toolName: call.name, output: { type: 'json', value: call.output.value as never } });
+      }
+    }
+    const out = [...this.finished];
+    if (assistant.length > 0) out.push({ role: 'assistant', content: assistant });
+    if (results.length > 0) out.push({ role: 'tool', content: results });
+    return out;
+  }
+}
+
 /** How much of the person's message stands in for the whole turn. */
 const SUMMARY_CHARS = 200;
 
@@ -457,6 +654,18 @@ export async function runChat(
   let ended = false;
   const started = Date.now();
   const tally: TurnTally = { steps: 0 };
+  const recorder = new TranscriptRecorder();
+  const transcript = new TranscriptWriter(params.runId, deps);
+  // A turn that never reaches `finish` — stopped, failed, or cut off by the
+  // provider — still leaves what it did. A stop is written the moment it
+  // happens rather than when the loop notices: the AI SDK waits for a running
+  // tool before it ends the stream, and what the turn did is what had come back
+  // when the person stopped it, which is also what the browser was shown.
+  // Written once: a finished turn has already written the SDK's own messages.
+  const keepSoFar = (): void => {
+    if (recorder.started) transcript.write(recorder.sofar());
+  };
+  sink.signal.addEventListener('abort', keepSoFar, { once: true });
   const end = (status: 'succeeded' | 'failed' | 'cancelled'): void => {
     if (ended) return;
     ended = true;
@@ -472,11 +681,43 @@ export async function runChat(
     );
   };
   try {
-    await runTurn(params, sink, deps, end, tally);
+    await runTurn(params, sink, deps, end, tally, recorder, transcript);
     end(sink.signal.aborted ? 'cancelled' : 'succeeded');
   } catch (cause) {
     end(sink.signal.aborted ? 'cancelled' : 'failed');
     throw cause;
+  } finally {
+    sink.signal.removeEventListener('abort', keepSoFar);
+    keepSoFar();
+  }
+}
+
+/**
+ * Writes one turn's transcript, once, without ever failing the turn.
+ *
+ * A store that cannot write loses the transcript, not the turn: the error is
+ * logged, `done` still goes out, and the next turn's history for this run is
+ * its text.
+ */
+class TranscriptWriter {
+  private written = false;
+
+  constructor(
+    private readonly runId: string,
+    private readonly deps: RunDeps,
+  ) {}
+
+  write(messages: readonly ResponseMessage[]): void {
+    const transcripts = this.deps.transcripts;
+    if (this.written || transcripts === undefined) return;
+    this.written = true;
+    try {
+      transcripts.save(this.runId, messages);
+    } catch (cause) {
+      this.deps.logger.error(
+        `[broapp] ai could not keep the transcript of run ${this.runId}: ${String(cause instanceof Error ? cause.message : cause)}`,
+      );
+    }
   }
 }
 
@@ -487,6 +728,8 @@ async function runTurn(
   deps: RunDeps,
   end: (status: 'succeeded' | 'failed' | 'cancelled') => void,
   tally: TurnTally,
+  recorder: TranscriptRecorder,
+  transcript: TranscriptWriter,
 ): Promise<void> {
   // Throws a PublicError when nothing is configured. `runStream` in host/app.ts
   // turns that into the right thing on the wire, so it is not caught here.
@@ -535,19 +778,29 @@ async function runTurn(
     );
   }
 
+  // From here the model has been asked, so there is a transcript to keep
+  // however the turn ends. A turn refused before this point has none.
+  recorder.started = true;
   const result = streamText({
     // Always a model *instance*. A string here would be resolved by the AI
     // SDK's gateway, over the global fetch, to a Vercel host — see
     // reports/01-spike.md. Nothing in this layer may pass one.
     model: resolved.adapter.model(resolved.config, resolved.modelId),
     system,
-    messages: toModelMessages(params),
-    tools: buildTools(params, deps, sink, approver),
+    messages: toModelMessages(params, deps.transcripts, deps.logger),
+    tools: buildTools(params, deps, sink, approver, recorder),
     stopWhen: stepCountIs(deps.maxSteps),
     abortSignal: sink.signal,
     // The default handler prints the error; this layer reports it as an event
     // and decides for itself what is safe to say.
     onError: () => undefined,
+    // Both from the SDK's own pipeline rather than from the loop below, so a
+    // step's text and the step's end are seen in the order they happened even
+    // when the loop is behind, waiting on a slow socket.
+    onChunk: ({ chunk }) => {
+      if (chunk.type === 'text-delta') recorder.wrote(chunk.text);
+    },
+    onStepEnd: (step) => recorder.stepEnded(step.response.messages),
   });
 
   for await (const part of result.fullStream) {
@@ -569,6 +822,9 @@ async function runTurn(
           outputTokens: part.totalUsage.outputTokens ?? 0,
         };
         tally.usage = usage;
+        // Before `done`: a client that saves the conversation on `done` and
+        // sends it back at once must find the run's transcript already there.
+        transcript.write(await result.responseMessages);
         await sink.emit({ type: 'usage', ...usage });
         await sink.emit({ type: 'done' });
         break;

package/src/ai/host/threads.ts

@@ -14,6 +14,10 @@ import { Database } from 'bun:sqlite';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+import type { AssistantModelMessage, ToolModelMessage } from 'ai';
+
+import type { HostLogger } from '../../host/app.ts';
+import { canonicalJson } from '../../host/gate.ts';
 import { publicError } from '../../shared/errors.ts';
 import type { StoredMessage, Thread } from '../shared/types.ts';
 
@@ -58,8 +62,40 @@ const MIGRATIONS: readonly string[] = [
         OR (earlier.updated_at = threads.updated_at AND earlier.rowid <= threads.rowid)
    );
    CREATE INDEX threads_seq ON threads (seq DESC);`,
+  /*
+   * What the model itself saw and did on each turn, by run id.
+   *
+   * Written by the host from the AI SDK's own response messages, never from
+   * anything a browser saved: a history turn that names a run gets these back
+   * in place of its text. Not tied to a thread, because the host does not know
+   * which conversation a run belongs to; the age and count caps are the bound.
+   */
+  `CREATE TABLE transcripts (
+     run_id     TEXT    PRIMARY KEY,
+     messages   TEXT    NOT NULL,
+     chars      INTEGER NOT NULL,
+     created_at INTEGER NOT NULL
+   );
+   CREATE INDEX transcripts_created_at ON transcripts (created_at);`,
 ];
 
+/**
+ * One message a turn produced: what `StreamTextResult.responseMessages` holds.
+ *
+ * `ai` declares `ResponseMessage` as exactly this union but does not export the
+ * name, so it is spelled out here from the two types it does export.
+ */
+export type ResponseMessage = AssistantModelMessage | ToolModelMessage;
+
+/** The most characters one transcript may be; a longer turn stays text. */
+export const MAX_TRANSCRIPT_CHARS = 200_000;
+
+/** How long a transcript is kept. */
+const TRANSCRIPT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** How many transcripts are kept, newest first. */
+const TRANSCRIPT_MAX_COUNT = 2_000;
+
 /** What a conversation is called until it has been named. */
 export const DEFAULT_THREAD_TITLE = 'New conversation';
 
@@ -100,9 +136,104 @@ export interface ThreadStore {
   remove(id: string): boolean;
   /** Every conversation. Returns how many were deleted. */
   clear(): number;
+  /**
+   * Keep one turn's response messages under its run id.
+   *
+   * Unpaired tool calls are removed first, provider metadata is dropped, and a
+   * transcript over {@link MAX_TRANSCRIPT_CHARS} is not written. Returns whether
+   * a row was written. Throws when the store cannot write.
+   */
+  saveTranscript(runId: string, messages: readonly ResponseMessage[]): boolean;
+  /** A transcript this store wrote, or null when it holds none that reads back whole. */
+  transcript(runId: string): readonly ResponseMessage[] | null;
+  /** Delete transcripts older than 30 days or beyond the newest 2,000. Returns how many went. */
+  retainTranscripts(): number;
   close(): void;
 }
 
+/** Options for {@link openThreads}. */
+export interface OpenThreadsOptions {
+  /** Where an oversized or unreadable transcript is reported. Default `console`. */
+  readonly logger?: HostLogger;
+}
+
+/** A plain object, for reading a stored or SDK-given value without trusting its type. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A copy of an object without the provider's own fields, which no later prompt needs. */
+function withoutProviderFields(value: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(value)) {
+    if (key === 'providerOptions' || key === 'providerMetadata' || key === 'providerExecuted') continue;
+    out[key] = member;
+  }
+  return out;
+}
+
+/**
+ * A turn's response messages as they are kept.
+ *
+ * Two edits and nothing else. A tool call with no result — a turn stopped while
+ * the tool ran — is removed, because a provider refuses a prompt that has a call
+ * without its answer; a message that edit leaves empty goes with it. Provider
+ * metadata is dropped at the message, part and output level: it belongs to the
+ * request it came from, and tool inputs and outputs are left exactly as given.
+ */
+export function transcriptForStorage(messages: readonly ResponseMessage[]): ResponseMessage[] {
+  const answered = new Set<string>();
+  for (const message of messages) {
+    if (!Array.isArray(message.content)) continue;
+    for (const part of message.content as readonly unknown[]) {
+      if (isRecord(part) && part['type'] === 'tool-result' && typeof part['toolCallId'] === 'string') {
+        answered.add(part['toolCallId']);
+      }
+    }
+  }
+  const out: ResponseMessage[] = [];
+  for (const message of messages) {
+    if (!Array.isArray(message.content)) {
+      out.push(withoutProviderFields(message as unknown as Record<string, unknown>) as unknown as ResponseMessage);
+      continue;
+    }
+    const content: unknown[] = [];
+    for (const part of message.content as readonly unknown[]) {
+      if (!isRecord(part)) continue;
+      if (part['type'] === 'tool-call' && !answered.has(String(part['toolCallId']))) continue;
+      const kept = withoutProviderFields(part);
+      if (isRecord(kept['output'])) kept['output'] = withoutProviderFields(kept['output']);
+      content.push(kept);
+    }
+    if (content.length === 0) continue;
+    out.push({ ...withoutProviderFields(message as unknown as Record<string, unknown>), content } as unknown as ResponseMessage);
+  }
+  return out;
+}
+
+/**
+ * Whether a stored value reads back as response messages.
+ *
+ * The row was written by this process, but a file can be edited or damaged, and
+ * what comes back goes into a prompt. Only an assistant or tool message with a
+ * string or an array of typed parts passes; a `system` role never does.
+ */
+function isTranscript(value: unknown): value is ResponseMessage[] {
+  if (!Array.isArray(value)) return false;
+  return value.every((message) => {
+    if (!isRecord(message)) return false;
+    const role = message['role'];
+    const content = message['content'];
+    if (role === 'assistant') {
+      return typeof content === 'string' || (Array.isArray(content) && content.every((part) => isRecord(part) && typeof part['type'] === 'string'));
+    }
+    if (role === 'tool') {
+      return Array.isArray(content) && content.every((part) => isRecord(part) && typeof part['type'] === 'string');
+    }
+    return false;
+  });
+}
+
 /** A row of `threads`, joined with its message count. */
 interface ThreadRow {
   id: string;
@@ -181,7 +312,8 @@ function derivedTitle(messages: readonly StoredMessage[]): string | null {
 }
 
 /** Open the conversation store for one data directory, migrating it as needed. */
-export function openThreads(dataDir: string): ThreadStore {
+export function openThreads(dataDir: string, options: OpenThreadsOptions = {}): ThreadStore {
+  const logger = options.logger ?? console;
   const directory = join(dataDir, 'ai');
   // The same mode the settings store uses: this directory holds what somebody
   // wrote to their assistant, which is nobody else's business.
@@ -235,8 +367,32 @@ export function openThreads(dataDir: string): ThreadStore {
     remove: db.query<{ id: string }, [string]>('DELETE FROM threads WHERE id = ? RETURNING id'),
     count: db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM threads'),
     clear: db.query<unknown, []>('DELETE FROM threads'),
+    saveTranscript: db.query<unknown, [string, string, number, number]>(
+      `INSERT INTO transcripts (run_id, messages, chars, created_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT (run_id) DO UPDATE SET messages = excluded.messages, chars = excluded.chars,
+         created_at = excluded.created_at`,
+    ),
+    transcript: db.query<{ messages: string }, [string]>('SELECT messages FROM transcripts WHERE run_id = ?'),
+    expireTranscripts: db.query<{ run_id: string }, [number]>(
+      'DELETE FROM transcripts WHERE created_at < ? RETURNING run_id',
+    ),
+    capTranscripts: db.query<{ run_id: string }, [number]>(
+      `DELETE FROM transcripts WHERE rowid NOT IN (
+         SELECT rowid FROM transcripts ORDER BY created_at DESC, rowid DESC LIMIT ?
+       ) RETURNING run_id`,
+    ),
   };
 
+  /** One unreadable transcript is reported once, not on every turn that names it. */
+  const reported = new Set<string>();
+
+  /** Both caps, in one transaction, so a crash never leaves one applied without the other. */
+  const retain = (): number =>
+    db.transaction(() => {
+      const expired = statements.expireTranscripts.all(Date.now() - TRANSCRIPT_MAX_AGE_MS).length;
+      return expired + statements.capTranscripts.all(TRANSCRIPT_MAX_COUNT).length;
+    })();
+
   /** The row, or the sentence a browser shows when a conversation is gone. */
   function mustGet(id: string): ThreadRow {
     const row = statements.byId.get(id);
@@ -244,6 +400,10 @@ export function openThreads(dataDir: string): ThreadStore {
     return row;
   }
 
+  // Retention runs on open as well as on every save, so a store that is only
+  // read still sheds what has aged out.
+  retain();
+
   const store: ThreadStore = {
     path,
 
@@ -318,6 +478,43 @@ export function openThreads(dataDir: string): ThreadStore {
       return before;
     },
 
+    saveTranscript(runId, messages) {
+      const kept = transcriptForStorage(messages);
+      const json = canonicalJson(kept);
+      if (json.length > MAX_TRANSCRIPT_CHARS) {
+        logger.warn(
+          `[broapp] ai transcript for run ${runId} is ${String(json.length)} characters, over ${String(MAX_TRANSCRIPT_CHARS)}; the turn stays text`,
+        );
+        return false;
+      }
+      db.transaction(() => {
+        statements.saveTranscript.run(runId, json, json.length, Date.now());
+        retain();
+      })();
+      return true;
+    },
+
+    transcript(runId) {
+      const row = statements.transcript.get(runId);
+      if (row === null) return null;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(row.messages);
+      } catch {
+        parsed = undefined;
+      }
+      if (!isTranscript(parsed) || row.messages.length > MAX_TRANSCRIPT_CHARS) {
+        if (!reported.has(runId)) {
+          reported.add(runId);
+          logger.warn(`[broapp] ai transcript for run ${runId} does not read back as messages; the turn stays text`);
+        }
+        return null;
+      }
+      return parsed;
+    },
+
+    retainTranscripts: retain,
+
     close() {
       // Checkpointing folds the WAL back into the main file, so what is left
       // behind is one complete database rather than one that needs its

package/src/ai/react/AiChat.tsx

@@ -71,20 +71,24 @@ function ToolCall({
         <div
           className={`ai-chat__confirm${urgent ? ' ai-chat__confirm--urgent' : ''}`}
           role="group"
-          aria-label={`Allow ${call.tool}?`}
+          aria-label={`Allow ${call.asks ?? call.tool}?`}
         >
-          <span>Allow this?</span>
+          {/* A question about one of this call's own steps says which step. */}
+          <span>{call.asks === undefined ? 'Allow this?' : `Allow ${call.asks}?`}</span>
+          {call.asks === undefined || call.asksInput === undefined ? null : (
+            <pre className="ai-chat__json">{JSON.stringify(call.asksInput, null, 2)}</pre>
+          )}
           {call.expiresAt === undefined ? null : (
             <span className="ai-chat__expires">expires in {countdown(call.expiresAt, now)}</span>
           )}
           <button
             className="button button--primary"
             type="button"
-            onClick={() => onConfirm(call.callId, true)}
+            onClick={() => onConfirm(call.confirmId ?? call.callId, true)}
           >
             Allow
           </button>
-          <button className="button" type="button" onClick={() => onConfirm(call.callId, false)}>
+          <button className="button" type="button" onClick={() => onConfirm(call.confirmId ?? call.callId, false)}>
             Decline
           </button>
         </div>

package/src/ai/react/use-ai-chat.ts

@@ -24,6 +24,56 @@ export interface ToolCallState {
   readonly output?: unknown;
   /** While awaiting confirmation: when the question stops waiting. */
   readonly expiresAt?: number;
+  /**
+   * While awaiting confirmation for one of this call's own steps: the id the
+   * answer goes to (`<callId>.<step>`), what that step runs and its input.
+   * Absent when the question is about the call itself.
+   */
+  readonly confirmId?: string;
+  readonly asks?: string;
+  readonly asksInput?: unknown;
+}
+
+/**
+ * Put a question on the card it belongs to.
+ *
+ * A question about the call itself names the call's own id. A tool that runs
+ * several gated steps — the launcher's `candidate.cycle` builds and previews
+ * after the patch it was called with — asks once per step, as `<callId>.<step>`,
+ * so each answer is to exactly one action. Those questions go on the parent's
+ * card, which then says what it is asking about.
+ */
+export function attachConfirm(
+  calls: readonly ToolCallState[],
+  event: { readonly callId?: string; readonly tool?: string; readonly input?: unknown; readonly expiresAt?: number },
+): ToolCallState[] {
+  const id = event.callId ?? '';
+  const exact = calls.some((call) => call.callId === id);
+  return calls.map((call) => {
+    const own = call.callId === id;
+    const step = !exact && id.startsWith(`${call.callId}.`);
+    if (!own && !step) return call;
+    const { confirmId: _confirmId, asks: _asks, asksInput: _asksInput, ...rest } = call;
+    return {
+      ...rest,
+      status: 'awaiting-confirmation',
+      ...(event.expiresAt === undefined ? {} : { expiresAt: event.expiresAt }),
+      ...(step ? { confirmId: id, asks: event.tool ?? '', asksInput: event.input } : {}),
+    };
+  });
+}
+
+/**
+ * An answer was accepted: the card goes back to running until its result or
+ * its next question arrives. Without this a card whose tool asks again later
+ * would keep offering buttons for a question already answered.
+ */
+export function settleAnswer(calls: readonly ToolCallState[], answeredId: string): ToolCallState[] {
+  return calls.map((call) => {
+    if (call.status !== 'awaiting-confirmation' || (call.callId !== answeredId && call.confirmId !== answeredId)) return call;
+    const { confirmId: _confirmId, asks: _asks, asksInput: _asksInput, expiresAt: _expiresAt, ...rest } = call;
+    return { ...rest, status: 'running' };
+  });
 }
 
 /** One message in the transcript. */
@@ -35,6 +85,8 @@ export type ChatMessage =
       readonly content: string;
       readonly toolCalls: ToolCallState[];
       readonly pending: boolean;
+      /** The run that wrote it, sent back in `history` so the host can use its transcript. */
+      readonly runId: string;
     };
 
 /** What {@link useAiChat} returns. */
@@ -57,12 +109,16 @@ function newRunId(): string {
   return crypto.randomUUID().replace(/-/g, '');
 }
 
-/** Every completed turn, as the model should see it. */
-function toHistory(messages: readonly ChatMessage[]): ChatTurn[] {
+/** Every completed turn, as the model should see it. Exported for its test; not part of `broapp/ai/react`. */
+export function toHistory(messages: readonly ChatMessage[]): ChatTurn[] {
   const turns: ChatTurn[] = [];
   for (const message of messages) {
     if (message.role === 'assistant' && (message.pending || message.content === '')) continue;
-    turns.push({ role: message.role, content: message.content });
+    turns.push(
+      message.role === 'assistant'
+        ? { role: 'assistant', content: message.content, runId: message.runId }
+        : { role: 'user', content: message.content },
+    );
   }
   return turns.slice(-MAX_HISTORY);
 }
@@ -152,18 +208,7 @@ export function useAiChat(options: AiChatOptions = {}): AiChatHook {
           break;
         case 'confirm':
           setStatus('awaiting-confirmation');
-          patchPending((message) => ({
-            ...message,
-            toolCalls: message.toolCalls.map((call) =>
-              call.callId === event.callId
-                ? {
-                    ...call,
-                    status: 'awaiting-confirmation',
-                    ...(event.expiresAt === undefined ? {} : { expiresAt: event.expiresAt }),
-                  }
-                : call,
-            ),
-          }));
+          patchPending((message) => ({ ...message, toolCalls: attachConfirm(message.toolCalls, event) }));
           break;
         case 'tool-result': {
           setStatus((current) => (current === 'awaiting-confirmation' ? 'streaming' : current));
@@ -228,7 +273,7 @@ export function useAiChat(options: AiChatOptions = {}): AiChatHook {
       setMessages((current) => [
         ...current,
         { id: `${id}-user`, role: 'user', content: trimmed },
-        { id: `${id}-assistant`, role: 'assistant', content: '', toolCalls: [], pending: true },
+        { id: `${id}-assistant`, role: 'assistant', content: '', toolCalls: [], pending: true, runId: id },
       ]);
 
       try {
@@ -296,12 +341,15 @@ export function useAiChat(options: AiChatOptions = {}): AiChatHook {
           // Nobody was waiting: the turn timed out or was cancelled while the
           // question was on screen.
           setError('That request has expired.');
+          return;
         }
+        patchPending((message) => ({ ...message, toolCalls: settleAnswer(message.toolCalls, callId) }));
+        setStatus((current) => (current === 'awaiting-confirmation' ? 'streaming' : current));
       } catch (cause) {
         setError(cause instanceof BroappError ? cause.message : 'That answer could not be sent.');
       }
     },
-    [shared],
+    [shared, patchPending],
   );
 
   const clear = React.useCallback((): void => {

package/src/ai/shared/contract.ts

@@ -53,6 +53,9 @@ const settings = s.object({
 const chatTurn = s.object({
   role: s.enum(['user', 'assistant']),
   content: s.string({ max: 20_000 }),
+  // Names a run whose transcript the host wrote. It only ever selects
+  // something the host already holds; an id it does not hold is ignored.
+  runId: s.optional(runId),
 });
 
 /**

package/src/ai/shared/types.ts

@@ -59,6 +59,12 @@ export type ToolPermission = 'read' | 'confirm';
 export interface ChatTurn {
   role: 'user' | 'assistant';
   content: string;
+  /**
+   * On an assistant turn: the run that produced it. The host expands a turn
+   * whose run it holds a transcript for into that turn's own tool calls and
+   * results; any other turn, and any run it does not hold, is `content`.
+   */
+  runId?: string;
 }
 
 /**