@tanstack/ai-persistence 0.6.4 → 0.6.7

package/dist/esm/reconstruct.js

@@ -1,4 +1,5 @@
 import { validateReconstructChatStores } from "./types.js";
+import { storedSubagentInfo } from "./subagent-runs.js";
 import { modelMessagesToUIMessages } from "@tanstack/ai";
 //#region src/reconstruct.ts
 var MAX_PAGE_SIZE = 500;
@@ -76,7 +77,7 @@ async function reconstructChat(persistence, request, options) {
 		before
 	}) : windowFromMessagePage(stored, pageSize);
 	const body = {
-		messages: transcript.messages,
+		messages: await attachSubagentCards(transcript.messages, persistence.stores.runs, messageStore, threadId, pending),
 		activeRun: active ? { runId: active.runId } : null,
 		interrupts: firstPending ? {
 			runId: firstPending.runId,
@@ -89,6 +90,94 @@ async function reconstructChat(persistence, request, options) {
 		"cache-control": "no-store"
 	} });
 }
+function messageRunId(message) {
+	const metadata = message.metadata;
+	if (!metadata || typeof metadata !== "object") return;
+	const tanstack = metadata.tanstack;
+	if (!tanstack || typeof tanstack !== "object") return;
+	const runId = tanstack.runId;
+	return typeof runId === "string" && runId !== "" ? runId : void 0;
+}
+/** Rebuild one child card from its run record and stored transcript. */
+async function childCard(child, runs, messageStore, pending, depth) {
+	const subagentRunId = child.subagentRunId ?? child.runId;
+	const stored = await messageStore.loadThread(child.threadId);
+	const info = storedSubagentInfo(stored);
+	const messages = modelMessagesToUIMessages(stored.filter((message) => storedSubagentInfo([message])?.placeholder !== true));
+	const nested = runs.listByParentRun && depth < 8 ? await runs.listByParentRun(subagentRunId) : [];
+	if (nested.length > 0) {
+		const cards = await Promise.all(nested.map((run) => childCard(run, runs, messageStore, pending, depth + 1)));
+		const last = messages.findLastIndex((m) => m.role === "assistant");
+		if (last === -1) messages.push({
+			id: `child-cards:${subagentRunId}`,
+			role: "assistant",
+			parts: cards
+		});
+		else {
+			const host = messages[last];
+			if (host) messages[last] = {
+				...host,
+				parts: [...host.parts, ...cards]
+			};
+		}
+	}
+	const failed = child.status === "failed" || child.status === "aborted";
+	const interruptIds = pending.filter((record) => record.payload.subagentRunId === subagentRunId).map((record) => record.interruptId);
+	return {
+		type: "subagent",
+		subagent: {
+			id: subagentRunId,
+			name: child.name ?? info?.name ?? "subagent",
+			status: failed ? "error" : child.status === "running" ? "running" : child.status === "interrupted" ? "suspended" : "finished",
+			...child.parentRunId !== void 0 && { parentRunId: child.parentRunId },
+			...info?.parentToolCallId !== void 0 && { parentToolCallId: info.parentToolCallId },
+			...interruptIds.length > 0 && { interruptIds },
+			...info?.metadata !== void 0 && { metadata: info.metadata },
+			messages,
+			...failed && child.error ? { error: child.error } : {}
+		}
+	};
+}
+/**
+* Put stored subagent cards back on the transcript. A routed child sits on
+* the parent assistant message of its run. A child that a tool call started
+* sits on the message that holds that tool call.
+*/
+async function attachSubagentCards(messages, runs, messageStore, threadId, pending) {
+	if (!runs?.listByParentRun) return messages;
+	const parentRunIds = /* @__PURE__ */ new Set();
+	for (const message of messages) {
+		const runId = messageRunId(message);
+		if (runId) parentRunIds.add(runId);
+	}
+	if (messages.some((message) => message.parts.some((part) => part.type === "tool-call")) && runs.listByThread && threadId !== "") for (const run of await runs.listByThread(threadId)) parentRunIds.add(run.runId);
+	const cardsByRun = /* @__PURE__ */ new Map();
+	const cardsByToolCall = /* @__PURE__ */ new Map();
+	for (const runId of parentRunIds) for (const child of await runs.listByParentRun(runId)) {
+		const card = await childCard(child, runs, messageStore, pending, 0);
+		const toolCallId = card.subagent.parentToolCallId;
+		const target = toolCallId === void 0 ? cardsByRun : cardsByToolCall;
+		const key = toolCallId ?? runId;
+		target.set(key, [...target.get(key) ?? [], card]);
+	}
+	if (cardsByRun.size === 0 && cardsByToolCall.size === 0) return messages;
+	return messages.map((message) => {
+		if (message.role !== "assistant") return message;
+		const runId = messageRunId(message);
+		const routed = runId !== void 0 ? cardsByRun.get(runId) : void 0;
+		const started = message.parts.flatMap((part) => part.type === "tool-call" ? cardsByToolCall.get(part.id) ?? [] : []);
+		if (!routed && started.length === 0) return message;
+		const parts = routed ? message.parts.filter((part) => part.type !== "text") : message.parts;
+		return {
+			...message,
+			parts: [
+				...routed ?? [],
+				...parts,
+				...started
+			]
+		};
+	});
+}
 function parsePageSize(raw) {
 	if (raw == null) return;
 	const pageSize = Number(raw);

package/dist/esm/reconstruct.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconstruct.js","names":[],"sources":["../../src/reconstruct.ts"],"sourcesContent":["import { modelMessagesToUIMessages } from '@tanstack/ai'\nimport type { ModelMessage, UIMessage } from '@tanstack/ai'\nimport { validateReconstructChatStores } from './types'\nimport type {\n  AIPersistence,\n  ChatTranscriptStores,\n  MessagePage,\n  MessageStore,\n} from './types'\n\nconst MAX_PAGE_SIZE = 500\n\n/**\n * The JSON body `reconstructChat` returns and a server-authoritative client\n * hydrates from on mount.\n *\n * `messages` is the stored transcript as UI messages (ready to paint).\n * `activeRun` is a cursor to a run still generating for the thread, or `null` —\n * resolved from the STABLE thread id via `stores.runs.findActiveRun`, so the\n * client learns \"there is a live run to tail\" without ever handling a run id.\n * `interrupts` is the thread's pending human-in-the-loop interrupts (tool\n * approvals, client-tool/generic waits) and the run they paused, or `null` —\n * so a reload (or another device) re-prompts the approval from the SERVER, not\n * from client storage. Resolved via `stores.interrupts.listPending`.\n * `page` is set only when the GET included a valid `limit`. `truncated` is true\n * when older UI messages exist. `cursor` is the opaque `before` token for the\n * next older window.\n */\nexport interface ReconstructedChat {\n  messages: Array<UIMessage>\n  activeRun: { runId: string } | null\n  interrupts: {\n    runId: string\n    pending: Array<Record<string, unknown>>\n  } | null\n  page?: { truncated: false } | { truncated: true; cursor: string }\n}\n\nexport interface ReconstructChatOptions {\n  /** Query parameter carrying the thread id. Defaults to `threadId`. */\n  param?: string\n  /**\n   * Authorize access to the requested thread before loading history.\n   *\n   * ⚠️ Without this, any caller who knows or guesses `?threadId=` receives the\n   * full transcript. Multi-user / multi-tenant deployments **must** supply\n   * an authorization check (session → owned threads) or resolve a validated\n   * thread id in the route and pass it via a custom `param` that only your\n   * server sets.\n   *\n   * Return:\n   * - `true` to allow the load\n   * - `false` for a default `403` response\n   * - a `Response` to return as-is (e.g. `401` with a body)\n   */\n  authorize?: (\n    threadId: string,\n    request: Request,\n  ) => boolean | Response | Promise<boolean | Response>\n}\n\n/**\n * Build the JSON `Response` a server-authoritative client hydrates from on load\n * (see the client-persistence guide). Reads the thread id from the request query\n * (`?threadId=` by default) and returns `{ messages, activeRun, interrupts }`\n * ({@link ReconstructedChat}):\n *\n * - `messages` — the stored transcript as UI messages.\n * - `activeRun` — `{ runId }` if a run is still generating for the thread (so the\n *   client tails it via the durability stream), else `null`. Resolved via the\n *   required `stores.runs.findActiveRun`; `null` when the `runs` store is absent.\n * - `interrupts` — `{ runId, pending }` if the thread has pending human-in-the-loop\n *   interrupts (a paused approval / wait) and the run they paused, else `null`, so\n *   a reload re-prompts the decision from the server. Resolved via the optional\n *   `stores.interrupts.listPending`; `null` when that store is absent.\n *\n * Paging is opt-in. A valid `?limit=` (positive integer, capped at 500) returns\n * the newest window of UI messages plus `page`. `?before=` walks to an older\n * window. Invalid `limit` (`0`, negative, NaN) is ignored and the full\n * transcript is returned. `activeRun` and `interrupts` are never paged.\n *\n * Requires `stores.messages`. Returns an empty transcript with no active run\n * and no interrupts when the thread id is missing or the thread is unknown, so\n * the caller never has to special-case a first load.\n *\n * This helper does **not** enforce tenancy by itself. Pass\n * {@link ReconstructChatOptions.authorize} (or wrap the call in your own\n * session gate) before exposing it on a public route.\n *\n * ```ts\n * export async function GET(request: Request) {\n *   return reconstructChat(persistence, request, {\n *     authorize: async (threadId, req) => {\n *       const userId = await getSessionUserId(req)\n *       return userId != null && (await userOwnsThread(userId, threadId))\n *     },\n *   })\n * }\n * ```\n */\nexport async function reconstructChat(\n  persistence: AIPersistence<ChatTranscriptStores>,\n  request: Request,\n  options?: ReconstructChatOptions,\n): Promise<Response> {\n  validateReconstructChatStores(persistence)\n  const messageStore = persistence.stores.messages\n  if (!messageStore) {\n    // validateReconstructChatStores already throws; this narrows for TypeScript.\n    throw new Error('reconstructChat requires stores.messages.')\n  }\n\n  const requestUrl = new URL(request.url)\n  const param = options?.param ?? 'threadId'\n  const threadId = requestUrl.searchParams.get(param) ?? ''\n  const pageSize = parsePageSize(requestUrl.searchParams.get('limit'))\n  const before = parseBefore(requestUrl.searchParams.get('before'))\n\n  if (threadId && options?.authorize) {\n    const decision = await options.authorize(threadId, request)\n    if (decision instanceof Response) {\n      return decision\n    }\n    if (!decision) {\n      return new Response(JSON.stringify({ error: 'Forbidden' }), {\n        status: 403,\n        headers: {\n          'content-type': 'application/json',\n          'cache-control': 'no-store',\n        },\n      })\n    }\n  }\n\n  // Resolve the active run BEFORE reading the transcript. `withPersistence`\n  // persists the final transcript BEFORE marking a run complete, so observing\n  // \"no active run\" here guarantees the transcript read below is the FINAL one.\n  // Reading them in the other order opens a finish-window race: a fast run that\n  // completes between the two reads would return a stale streaming snapshot with\n  // `activeRun: null`, leaving the client stuck on the partial (no run to tail).\n  const active = threadId\n    ? await persistence.stores.runs?.findActiveRun(threadId)\n    : null\n  const stored =\n    threadId === ''\n      ? []\n      : pageSize === undefined\n        ? await messageStore.loadThread(threadId)\n        : await messageStore.loadThread(threadId, {\n            limit: pageSize + 1,\n            ...(before === undefined ? {} : { before }),\n          })\n  // Pending interrupts for the thread, so a reload re-prompts the approval from\n  // the server. Each stored `payload` is the full interrupt descriptor the\n  // client hydrates; they share the run they paused.\n  const pending = threadId\n    ? ((await persistence.stores.interrupts?.listPending(threadId)) ?? [])\n    : []\n  const firstPending = pending[0]\n  const isPaging = pageSize !== undefined && threadId !== ''\n  const transcript = !isPaging\n    ? {\n        messages: modelMessagesToUIMessages(threadMessages(stored)),\n      }\n    : Array.isArray(stored)\n      ? await windowFromArray({\n          stored,\n          messageStore,\n          threadId,\n          pageSize,\n          before,\n        })\n      : windowFromMessagePage(stored, pageSize)\n  const body: ReconstructedChat = {\n    messages: transcript.messages,\n    activeRun: active ? { runId: active.runId } : null,\n    interrupts: firstPending\n      ? {\n          runId: firstPending.runId,\n          pending: pending.map((record) => record.payload),\n        }\n      : null,\n    ...('page' in transcript ? { page: transcript.page } : {}),\n  }\n  return new Response(JSON.stringify(body), {\n    headers: {\n      'content-type': 'application/json',\n      'cache-control': 'no-store',\n    },\n  })\n}\n\nfunction parsePageSize(raw: string | null) {\n  if (raw == null) return\n  const pageSize = Number(raw)\n  const isValidPageSize = Number.isInteger(pageSize) && pageSize > 0\n  if (!isValidPageSize) return\n  return Math.min(pageSize, MAX_PAGE_SIZE)\n}\n\nfunction parseBefore(raw: string | null) {\n  if (raw == null || raw === '') return\n  return raw\n}\n\nfunction threadMessages(\n  loaded: Array<ModelMessage> | MessagePage,\n): Array<ModelMessage> {\n  return Array.isArray(loaded) ? loaded : loaded.messages\n}\n\nfunction completePage() {\n  return { truncated: false as const }\n}\n\nfunction truncatedPage(cursor: string) {\n  return { truncated: true as const, cursor }\n}\n\nfunction pageFromCursor(cursor: string | undefined) {\n  if (cursor === undefined || cursor === '') {\n    return completePage()\n  }\n  return truncatedPage(cursor)\n}\n\nfunction newestUiWindow(messages: Array<UIMessage>, pageSize: number) {\n  const truncated = messages.length > pageSize\n  if (!truncated) {\n    return { messages, page: completePage() }\n  }\n  const uiWindow = messages.slice(messages.length - pageSize)\n  return {\n    messages: uiWindow,\n    page: pageFromCursor(uiWindow[0]?.id),\n  }\n}\n\nfunction uiBeforeCursor(messages: Array<UIMessage>, cursor: string) {\n  const cut = messages.findIndex((message) => message.id === cursor)\n  if (cut === -1) return\n  return messages.slice(0, cut)\n}\n\nfunction windowFromMessagePage(page: MessagePage, pageSize: number) {\n  const ui = modelMessagesToUIMessages(page.messages)\n  if (ui.length > pageSize) {\n    // Extra slice uses a library-minted cursor. Keeping the adapter cursor\n    // after dropping the oldest row would skip that row on the next GET.\n    return newestUiWindow(ui, pageSize)\n  }\n  if (page.truncated) {\n    return {\n      messages: ui,\n      page: pageFromCursor(page.cursor),\n    }\n  }\n  return { messages: ui, page: completePage() }\n}\n\nasync function windowFromArray(input: {\n  stored: Array<ModelMessage>\n  messageStore: MessageStore\n  threadId: string\n  pageSize: number\n  before: string | undefined\n}) {\n  const { stored, messageStore, threadId, pageSize, before } = input\n  if (before === undefined) {\n    return newestUiWindow(modelMessagesToUIMessages(stored), pageSize)\n  }\n  // Array adapters own no cursor. Apply `before` to the full transcript so an\n  // adapter that ignored the hint cannot return the same newest page forever.\n  const full = threadMessages(await messageStore.loadThread(threadId))\n  const older = uiBeforeCursor(modelMessagesToUIMessages(full), before)\n  if (older === undefined) {\n    return { messages: [], page: truncatedPage(before) }\n  }\n  return newestUiWindow(older, pageSize)\n}\n"],"mappings":"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"}
+{"version":3,"file":"reconstruct.js","names":[],"sources":["../../src/reconstruct.ts"],"sourcesContent":["import { modelMessagesToUIMessages } from '@tanstack/ai'\nimport type {\n  ModelMessage,\n  RunRecord,\n  SubagentPart,\n  UIMessage,\n} from '@tanstack/ai'\nimport { storedSubagentInfo } from './subagent-runs'\nimport { validateReconstructChatStores } from './types'\nimport type {\n  AIPersistence,\n  ChatTranscriptStores,\n  InterruptRecord,\n  MessagePage,\n  MessageStore,\n} from './types'\n\nconst MAX_PAGE_SIZE = 500\n\n/**\n * The JSON body `reconstructChat` returns and a server-authoritative client\n * hydrates from on mount.\n *\n * `messages` is the stored transcript as UI messages (ready to paint).\n * `activeRun` is a cursor to a run still generating for the thread, or `null` —\n * resolved from the STABLE thread id via `stores.runs.findActiveRun`, so the\n * client learns \"there is a live run to tail\" without ever handling a run id.\n * `interrupts` is the thread's pending human-in-the-loop interrupts (tool\n * approvals, client-tool/generic waits) and the run they paused, or `null` —\n * so a reload (or another device) re-prompts the approval from the SERVER, not\n * from client storage. Resolved via `stores.interrupts.listPending`.\n * `page` is set only when the GET included a valid `limit`. `truncated` is true\n * when older UI messages exist. `cursor` is the opaque `before` token for the\n * next older window.\n */\nexport interface ReconstructedChat {\n  messages: Array<UIMessage>\n  activeRun: { runId: string } | null\n  interrupts: {\n    runId: string\n    pending: Array<Record<string, unknown>>\n  } | null\n  page?: { truncated: false } | { truncated: true; cursor: string }\n}\n\nexport interface ReconstructChatOptions {\n  /** Query parameter carrying the thread id. Defaults to `threadId`. */\n  param?: string\n  /**\n   * Authorize access to the requested thread before loading history.\n   *\n   * ⚠️ Without this, any caller who knows or guesses `?threadId=` receives the\n   * full transcript. Multi-user / multi-tenant deployments **must** supply\n   * an authorization check (session → owned threads) or resolve a validated\n   * thread id in the route and pass it via a custom `param` that only your\n   * server sets.\n   *\n   * Return:\n   * - `true` to allow the load\n   * - `false` for a default `403` response\n   * - a `Response` to return as-is (e.g. `401` with a body)\n   */\n  authorize?: (\n    threadId: string,\n    request: Request,\n  ) => boolean | Response | Promise<boolean | Response>\n}\n\n/**\n * Build the JSON `Response` a server-authoritative client hydrates from on load\n * (see the client-persistence guide). Reads the thread id from the request query\n * (`?threadId=` by default) and returns `{ messages, activeRun, interrupts }`\n * ({@link ReconstructedChat}):\n *\n * - `messages` — the stored transcript as UI messages.\n * - `activeRun` — `{ runId }` if a run is still generating for the thread (so the\n *   client tails it via the durability stream), else `null`. Resolved via the\n *   required `stores.runs.findActiveRun`; `null` when the `runs` store is absent.\n * - `interrupts` — `{ runId, pending }` if the thread has pending human-in-the-loop\n *   interrupts (a paused approval / wait) and the run they paused, else `null`, so\n *   a reload re-prompts the decision from the server. Resolved via the optional\n *   `stores.interrupts.listPending`; `null` when that store is absent.\n *\n * Paging is opt-in. A valid `?limit=` (positive integer, capped at 500) returns\n * the newest window of UI messages plus `page`. `?before=` walks to an older\n * window. Invalid `limit` (`0`, negative, NaN) is ignored and the full\n * transcript is returned. `activeRun` and `interrupts` are never paged.\n *\n * Requires `stores.messages`. Returns an empty transcript with no active run\n * and no interrupts when the thread id is missing or the thread is unknown, so\n * the caller never has to special-case a first load.\n *\n * This helper does **not** enforce tenancy by itself. Pass\n * {@link ReconstructChatOptions.authorize} (or wrap the call in your own\n * session gate) before exposing it on a public route.\n *\n * ```ts\n * export async function GET(request: Request) {\n *   return reconstructChat(persistence, request, {\n *     authorize: async (threadId, req) => {\n *       const userId = await getSessionUserId(req)\n *       return userId != null && (await userOwnsThread(userId, threadId))\n *     },\n *   })\n * }\n * ```\n */\nexport async function reconstructChat(\n  persistence: AIPersistence<ChatTranscriptStores>,\n  request: Request,\n  options?: ReconstructChatOptions,\n): Promise<Response> {\n  validateReconstructChatStores(persistence)\n  const messageStore = persistence.stores.messages\n  if (!messageStore) {\n    // validateReconstructChatStores already throws; this narrows for TypeScript.\n    throw new Error('reconstructChat requires stores.messages.')\n  }\n\n  const requestUrl = new URL(request.url)\n  const param = options?.param ?? 'threadId'\n  const threadId = requestUrl.searchParams.get(param) ?? ''\n  const pageSize = parsePageSize(requestUrl.searchParams.get('limit'))\n  const before = parseBefore(requestUrl.searchParams.get('before'))\n\n  if (threadId && options?.authorize) {\n    const decision = await options.authorize(threadId, request)\n    if (decision instanceof Response) {\n      return decision\n    }\n    if (!decision) {\n      return new Response(JSON.stringify({ error: 'Forbidden' }), {\n        status: 403,\n        headers: {\n          'content-type': 'application/json',\n          'cache-control': 'no-store',\n        },\n      })\n    }\n  }\n\n  // Resolve the active run BEFORE reading the transcript. `withPersistence`\n  // persists the final transcript BEFORE marking a run complete, so observing\n  // \"no active run\" here guarantees the transcript read below is the FINAL one.\n  // Reading them in the other order opens a finish-window race: a fast run that\n  // completes between the two reads would return a stale streaming snapshot with\n  // `activeRun: null`, leaving the client stuck on the partial (no run to tail).\n  const active = threadId\n    ? await persistence.stores.runs?.findActiveRun(threadId)\n    : null\n  const stored =\n    threadId === ''\n      ? []\n      : pageSize === undefined\n        ? await messageStore.loadThread(threadId)\n        : await messageStore.loadThread(threadId, {\n            limit: pageSize + 1,\n            ...(before === undefined ? {} : { before }),\n          })\n  // Pending interrupts for the thread, so a reload re-prompts the approval from\n  // the server. Each stored `payload` is the full interrupt descriptor the\n  // client hydrates; they share the run they paused.\n  const pending = threadId\n    ? ((await persistence.stores.interrupts?.listPending(threadId)) ?? [])\n    : []\n  const firstPending = pending[0]\n  const isPaging = pageSize !== undefined && threadId !== ''\n  const transcript = !isPaging\n    ? {\n        messages: modelMessagesToUIMessages(threadMessages(stored)),\n      }\n    : Array.isArray(stored)\n      ? await windowFromArray({\n          stored,\n          messageStore,\n          threadId,\n          pageSize,\n          before,\n        })\n      : windowFromMessagePage(stored, pageSize)\n  const messages = await attachSubagentCards(\n    transcript.messages,\n    persistence.stores.runs,\n    messageStore,\n    threadId,\n    pending,\n  )\n  const body: ReconstructedChat = {\n    messages,\n    activeRun: active ? { runId: active.runId } : null,\n    interrupts: firstPending\n      ? {\n          runId: firstPending.runId,\n          pending: pending.map((record) => record.payload),\n        }\n      : null,\n    ...('page' in transcript ? { page: transcript.page } : {}),\n  }\n  return new Response(JSON.stringify(body), {\n    headers: {\n      'content-type': 'application/json',\n      'cache-control': 'no-store',\n    },\n  })\n}\n\nfunction messageRunId(message: UIMessage) {\n  const metadata = message.metadata\n  if (!metadata || typeof metadata !== 'object') return\n  const tanstack = metadata.tanstack\n  if (!tanstack || typeof tanstack !== 'object') return\n  const runId = (tanstack as { runId?: unknown }).runId\n  return typeof runId === 'string' && runId !== '' ? runId : undefined\n}\n\ntype Runs = NonNullable<ChatTranscriptStores['runs']>\n\n/** Rebuild one child card from its run record and stored transcript. */\nasync function childCard(\n  child: RunRecord,\n  runs: Runs,\n  messageStore: MessageStore,\n  pending: ReadonlyArray<InterruptRecord>,\n  depth: number,\n): Promise<SubagentPart> {\n  const subagentRunId = child.subagentRunId ?? child.runId\n  const stored = await messageStore.loadThread(child.threadId)\n  const info = storedSubagentInfo(stored)\n  const messages = modelMessagesToUIMessages(\n    stored.filter(\n      (message) => storedSubagentInfo([message])?.placeholder !== true,\n    ),\n  )\n  const nested =\n    runs.listByParentRun && depth < 8\n      ? await runs.listByParentRun(subagentRunId)\n      : []\n  if (nested.length > 0) {\n    const cards = await Promise.all(\n      nested.map((run) =>\n        childCard(run, runs, messageStore, pending, depth + 1),\n      ),\n    )\n    const last = messages.findLastIndex((m) => m.role === 'assistant')\n    if (last === -1) {\n      messages.push({\n        id: `child-cards:${subagentRunId}`,\n        role: 'assistant',\n        parts: cards,\n      })\n    } else {\n      const host = messages[last]\n      if (host) messages[last] = { ...host, parts: [...host.parts, ...cards] }\n    }\n  }\n  const failed = child.status === 'failed' || child.status === 'aborted'\n  const interruptIds = pending\n    .filter((record) => record.payload.subagentRunId === subagentRunId)\n    .map((record) => record.interruptId)\n  return {\n    type: 'subagent',\n    subagent: {\n      id: subagentRunId,\n      name: child.name ?? info?.name ?? 'subagent',\n      status: failed\n        ? 'error'\n        : child.status === 'running'\n          ? 'running'\n          : child.status === 'interrupted'\n            ? 'suspended'\n            : 'finished',\n      ...(child.parentRunId !== undefined && {\n        parentRunId: child.parentRunId,\n      }),\n      ...(info?.parentToolCallId !== undefined && {\n        parentToolCallId: info.parentToolCallId,\n      }),\n      ...(interruptIds.length > 0 && { interruptIds }),\n      ...(info?.metadata !== undefined && { metadata: info.metadata }),\n      messages,\n      ...(failed && child.error ? { error: child.error } : {}),\n    },\n  }\n}\n\n/**\n * Put stored subagent cards back on the transcript. A routed child sits on\n * the parent assistant message of its run. A child that a tool call started\n * sits on the message that holds that tool call.\n */\nasync function attachSubagentCards(\n  messages: Array<UIMessage>,\n  runs: ChatTranscriptStores['runs'],\n  messageStore: MessageStore,\n  threadId: string,\n  pending: ReadonlyArray<InterruptRecord>,\n) {\n  if (!runs?.listByParentRun) return messages\n  const parentRunIds = new Set<string>()\n  for (const message of messages) {\n    const runId = messageRunId(message)\n    if (runId) parentRunIds.add(runId)\n  }\n  const hasToolCalls = messages.some((message) =>\n    message.parts.some((part) => part.type === 'tool-call'),\n  )\n  if (hasToolCalls && runs.listByThread && threadId !== '') {\n    for (const run of await runs.listByThread(threadId)) {\n      parentRunIds.add(run.runId)\n    }\n  }\n\n  const cardsByRun = new Map<string, Array<SubagentPart>>()\n  const cardsByToolCall = new Map<string, Array<SubagentPart>>()\n  for (const runId of parentRunIds) {\n    for (const child of await runs.listByParentRun(runId)) {\n      const card = await childCard(child, runs, messageStore, pending, 0)\n      const toolCallId = card.subagent.parentToolCallId\n      const target = toolCallId === undefined ? cardsByRun : cardsByToolCall\n      const key = toolCallId ?? runId\n      target.set(key, [...(target.get(key) ?? []), card])\n    }\n  }\n  if (cardsByRun.size === 0 && cardsByToolCall.size === 0) return messages\n\n  return messages.map((message) => {\n    if (message.role !== 'assistant') return message\n    const runId = messageRunId(message)\n    const routed = runId !== undefined ? cardsByRun.get(runId) : undefined\n    const started = message.parts.flatMap((part) =>\n      part.type === 'tool-call' ? (cardsByToolCall.get(part.id) ?? []) : [],\n    )\n    if (!routed && started.length === 0) return message\n    // A routed parent message holds only the children's text. The cards\n    // replace it.\n    const parts = routed\n      ? message.parts.filter((part) => part.type !== 'text')\n      : message.parts\n    return {\n      ...message,\n      parts: [...(routed ?? []), ...parts, ...started],\n    }\n  })\n}\n\nfunction parsePageSize(raw: string | null) {\n  if (raw == null) return\n  const pageSize = Number(raw)\n  const isValidPageSize = Number.isInteger(pageSize) && pageSize > 0\n  if (!isValidPageSize) return\n  return Math.min(pageSize, MAX_PAGE_SIZE)\n}\n\nfunction parseBefore(raw: string | null) {\n  if (raw == null || raw === '') return\n  return raw\n}\n\nfunction threadMessages(\n  loaded: Array<ModelMessage> | MessagePage,\n): Array<ModelMessage> {\n  return Array.isArray(loaded) ? loaded : loaded.messages\n}\n\nfunction completePage() {\n  return { truncated: false as const }\n}\n\nfunction truncatedPage(cursor: string) {\n  return { truncated: true as const, cursor }\n}\n\nfunction pageFromCursor(cursor: string | undefined) {\n  if (cursor === undefined || cursor === '') {\n    return completePage()\n  }\n  return truncatedPage(cursor)\n}\n\nfunction newestUiWindow(messages: Array<UIMessage>, pageSize: number) {\n  const truncated = messages.length > pageSize\n  if (!truncated) {\n    return { messages, page: completePage() }\n  }\n  const uiWindow = messages.slice(messages.length - pageSize)\n  return {\n    messages: uiWindow,\n    page: pageFromCursor(uiWindow[0]?.id),\n  }\n}\n\nfunction uiBeforeCursor(messages: Array<UIMessage>, cursor: string) {\n  const cut = messages.findIndex((message) => message.id === cursor)\n  if (cut === -1) return\n  return messages.slice(0, cut)\n}\n\nfunction windowFromMessagePage(page: MessagePage, pageSize: number) {\n  const ui = modelMessagesToUIMessages(page.messages)\n  if (ui.length > pageSize) {\n    // Extra slice uses a library-minted cursor. Keeping the adapter cursor\n    // after dropping the oldest row would skip that row on the next GET.\n    return newestUiWindow(ui, pageSize)\n  }\n  if (page.truncated) {\n    return {\n      messages: ui,\n      page: pageFromCursor(page.cursor),\n    }\n  }\n  return { messages: ui, page: completePage() }\n}\n\nasync function windowFromArray(input: {\n  stored: Array<ModelMessage>\n  messageStore: MessageStore\n  threadId: string\n  pageSize: number\n  before: string | undefined\n}) {\n  const { stored, messageStore, threadId, pageSize, before } = input\n  if (before === undefined) {\n    return newestUiWindow(modelMessagesToUIMessages(stored), pageSize)\n  }\n  // Array adapters own no cursor. Apply `before` to the full transcript so an\n  // adapter that ignored the hint cannot return the same newest page forever.\n  const full = threadMessages(await messageStore.loadThread(threadId))\n  const older = uiBeforeCursor(modelMessagesToUIMessages(full), before)\n  if (older === undefined) {\n    return { messages: [], page: truncatedPage(before) }\n  }\n  return newestUiWindow(older, pageSize)\n}\n"],"mappings":"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"}

package/dist/esm/subagent-runs.d.ts

@@ -0,0 +1,40 @@
+import { Interrupt, ModelMessage, RunAgentResumeItem, RunStore, StreamChunk, SubagentWireInfo, UIMessage } from '@tanstack/ai';
+import { InterruptStore, MessageStore } from './types.js';
+/**
+ * Card data for a stored child transcript. It rides on the first message, in
+ * `metadata.tanstack.subagent`, the same shape the wire uses.
+ */
+export declare function storedSubagentInfo(messages: ReadonlyArray<ModelMessage>): SubagentWireInfo | undefined;
+export declare function createSubagentRunRecorder(stores: {
+    messages: MessageStore;
+    runs?: RunStore;
+    interrupts?: InterruptStore;
+    /** Minimum milliseconds between writes while a child streams. */
+    intervalMs?: number;
+}): {
+    start(input: {
+        threadId: string;
+        runId: string;
+        messages: ReadonlyArray<UIMessage | ModelMessage>;
+        resume?: ReadonlyArray<RunAgentResumeItem>;
+    }): Promise<void>;
+    chunk(input: {
+        threadId: string;
+        runId: string;
+        chunk: StreamChunk;
+    }): Promise<void>;
+    suspend(input: {
+        threadId: string;
+        runId: string;
+        interrupts: ReadonlyArray<Interrupt>;
+    }): Promise<void>;
+    finish(input: {
+        threadId: string;
+        runId: string;
+    }): Promise<void>;
+    abort(input: {
+        threadId: string;
+        runId: string;
+        error?: unknown;
+    }): Promise<void>;
+};

package/dist/esm/subagent-runs.js

@@ -0,0 +1,366 @@
+import { mergeStoredMessages } from "./merge-stored.js";
+import { StreamProcessor, convertMessagesToModelMessages, modelMessagesToUIMessages, subagentHostMessageId, wireSubagentInfo } from "@tanstack/ai";
+//#region src/subagent-runs.ts
+function withSubagentInfo(metadata, info) {
+	const source = metadata != null && typeof metadata === "object" ? metadata : {};
+	const tanstack = source.tanstack != null && typeof source.tanstack === "object" ? source.tanstack : {};
+	return {
+		...source,
+		tanstack: {
+			...tanstack,
+			subagent: info
+		}
+	};
+}
+function childStoreId(subagentRunId) {
+	return `subagent:${subagentRunId}`;
+}
+function readSubagentRunId(chunk) {
+	if (!("subagentRunId" in chunk)) return;
+	const id = chunk.subagentRunId;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function assistantId(runId) {
+	return subagentHostMessageId(runId);
+}
+function messageText(message) {
+	return typeof message.content === "string" ? message.content : "";
+}
+function readModelRunId(message) {
+	const metadata = message.metadata;
+	if (metadata == null || typeof metadata !== "object") return;
+	if (!("tanstack" in metadata)) return;
+	const tanstack = metadata.tanstack;
+	if (tanstack == null || typeof tanstack !== "object") return;
+	if (!("runId" in tanstack)) return;
+	const runId = tanstack.runId;
+	return typeof runId === "string" && runId !== "" ? runId : void 0;
+}
+function withRunId(message, runId) {
+	const metadata = message.metadata;
+	const tanstack = metadata != null && typeof metadata === "object" && "tanstack" in metadata && metadata.tanstack != null && typeof metadata.tanstack === "object" ? metadata.tanstack : {};
+	return {
+		...message,
+		metadata: {
+			...metadata,
+			tanstack: {
+				...tanstack,
+				runId
+			}
+		}
+	};
+}
+function sameChildText(stored, incoming) {
+	if (stored === "" || incoming === "") return false;
+	if (stored === incoming) return true;
+	const blocks = stored.split("\n\n").filter((block) => block.includes(":\n"));
+	if (blocks.length === 0) return false;
+	return blocks.every((block) => incoming.includes(block));
+}
+function keepSubagentRunIds(stored, merged) {
+	const dropped = stored.filter((message) => {
+		if (readModelRunId(message) === void 0) return false;
+		return !merged.some((item) => item.id !== void 0 && item.id === message.id);
+	});
+	const turnOf = (list, index) => list.slice(0, index).findLast((message) => message.role === "user")?.id;
+	const used = /* @__PURE__ */ new Set();
+	for (const previous of dropped) {
+		const runId = readModelRunId(previous);
+		if (runId === void 0) continue;
+		if (merged.some((message) => readModelRunId(message) === runId)) continue;
+		const previousText = messageText(previous);
+		const previousTurn = turnOf(stored, stored.indexOf(previous));
+		const index = merged.findIndex((message, messageIndex) => {
+			if (used.has(messageIndex)) return false;
+			if (message.role !== "assistant") return false;
+			if (readModelRunId(message) !== void 0) return false;
+			if (previousText === "") return previousTurn !== void 0 && turnOf(merged, messageIndex) === previousTurn && merged[messageIndex - 1]?.role === "user";
+			return sameChildText(previousText, messageText(message));
+		});
+		if (index === -1) continue;
+		const host = merged[index];
+		if (!host) continue;
+		used.add(index);
+		merged[index] = withRunId(host, runId);
+	}
+	return merged;
+}
+function childText(messages) {
+	return messages.flatMap((message) => message.role === "assistant" ? message.parts.flatMap((part) => part.type === "text" && part.content.trim() !== "" ? [part.content.trim()] : []) : []).join("\n\n");
+}
+function withoutCards(messages) {
+	return messages.map((message) => ({
+		...message,
+		parts: message.parts.filter((part) => part.type !== "subagent")
+	}));
+}
+/**
+* Card data for a stored child transcript. It rides on the first message, in
+* `metadata.tanstack.subagent`, the same shape the wire uses.
+*/
+function storedSubagentInfo(messages) {
+	return wireSubagentInfo(messages[0]);
+}
+function createSubagentRunRecorder(stores) {
+	const children = /* @__PURE__ */ new Map();
+	const intervalMs = stores.intervalMs ?? 1e3;
+	const answered = /* @__PURE__ */ new Map();
+	const parentSavedAt = /* @__PURE__ */ new Map();
+	async function loadMessages(threadId) {
+		return stores.messages.loadThread(threadId);
+	}
+	function lineage(subagentRunId) {
+		const notes = [];
+		let id = subagentRunId;
+		for (let depth = 0; id !== void 0 && depth < 64; depth++) {
+			const note = children.get(id);
+			if (!note) break;
+			notes.push(note);
+			id = note.parentSubagentRunId;
+		}
+		return notes;
+	}
+	async function saveChild(subagentRunId) {
+		const note = children.get(subagentRunId);
+		if (!note) return;
+		note.savedAt = Date.now();
+		const info = {
+			name: note.name,
+			status: note.status,
+			...note.parentSubagentRunId !== void 0 && { parentSubagentRunId: note.parentSubagentRunId },
+			...note.parentToolCallId !== void 0 && { parentToolCallId: note.parentToolCallId },
+			...note.interruptIds !== void 0 && { interruptIds: note.interruptIds },
+			...note.error !== void 0 && { error: note.error },
+			...note.metadata !== void 0 && { metadata: note.metadata }
+		};
+		const [first, ...rest] = convertMessagesToModelMessages(withoutCards(note.processor.getMessages()));
+		const head = first ? {
+			...first,
+			metadata: withSubagentInfo(first.metadata, info)
+		} : {
+			id: `child:${subagentRunId}`,
+			role: "assistant",
+			content: "",
+			metadata: withSubagentInfo(void 0, {
+				...info,
+				placeholder: true
+			})
+		};
+		await stores.messages.saveThread(childStoreId(subagentRunId), [head, ...rest]);
+	}
+	async function saveParent(threadId, runId) {
+		const notes = [...children.values()].filter((note) => note.parentRunId === runId && note.parentSubagentRunId === void 0 && note.parentToolCallId === void 0);
+		if (notes.length === 0) return;
+		const content = notes.map((note) => {
+			const text = childText(note.processor.getMessages());
+			return text === "" ? "" : `${note.name}:\n${text}`;
+		}).filter((block) => block !== "").join("\n\n");
+		const stored = await loadMessages(threadId);
+		const index = stored.findIndex((message) => readModelRunId(message) === runId);
+		const host = stored[index];
+		if (host) {
+			const next = [...stored];
+			next[index] = {
+				...host,
+				content
+			};
+			await stores.messages.saveThread(threadId, next);
+			return;
+		}
+		const assistant = {
+			id: assistantId(runId),
+			role: "assistant",
+			content,
+			metadata: { tanstack: { runId } }
+		};
+		await stores.messages.saveThread(threadId, [...stored, assistant]);
+	}
+	async function startChild(input, chunk) {
+		const id = chunk.subagentRunId;
+		const record = await stores.runs?.createOrResume({
+			runId: id,
+			threadId: childStoreId(id),
+			startedAt: Date.now(),
+			parentRunId: chunk.parentSubagentRunId ?? input.runId,
+			subagentRunId: id,
+			name: chunk.name
+		});
+		const existing = children.get(id);
+		if (existing) {
+			existing.threadId = input.threadId;
+			existing.runId = input.runId;
+			existing.status = "running";
+			delete existing.interruptIds;
+			if (chunk.metadata !== void 0) existing.metadata = chunk.metadata;
+		} else {
+			const stored = (await loadMessages(childStoreId(id))).filter((message) => storedSubagentInfo([message])?.placeholder !== true);
+			children.set(id, {
+				name: chunk.name,
+				threadId: input.threadId,
+				runId: input.runId,
+				savedAt: 0,
+				parentRunId: record?.parentRunId ?? chunk.parentSubagentRunId ?? input.runId,
+				...chunk.parentSubagentRunId !== void 0 && { parentSubagentRunId: chunk.parentSubagentRunId },
+				...chunk.parentToolCallId !== void 0 && { parentToolCallId: chunk.parentToolCallId },
+				...chunk.metadata !== void 0 && { metadata: chunk.metadata },
+				processor: new StreamProcessor({
+					subagentRunId: id,
+					initialMessages: modelMessagesToUIMessages(stored)
+				}),
+				status: "running"
+			});
+		}
+		if (record && record.status !== "running") await stores.runs?.update(id, { status: "running" });
+		if (chunk.parentSubagentRunId !== void 0) children.get(chunk.parentSubagentRunId)?.processor.processChunk(chunk);
+		await saveChild(id);
+	}
+	async function settleChild(chunk) {
+		const id = chunk.subagentRunId;
+		const note = children.get(id);
+		if (!note) return;
+		try {
+			await writeSettled(note, id, chunk);
+		} finally {
+			if (note.parentSubagentRunId !== void 0 || note.parentToolCallId !== void 0) children.delete(id);
+		}
+	}
+	async function writeSettled(note, id, chunk) {
+		note.processor.finalizeStream();
+		if (note.parentSubagentRunId !== void 0) children.get(note.parentSubagentRunId)?.processor.processChunk(chunk);
+		if (chunk.type === "SUBAGENT_ERROR") {
+			const stopped = chunk.message === "Stopped";
+			note.status = "error";
+			note.error = { message: chunk.message };
+			await saveChild(id);
+			await stores.runs?.update(id, {
+				status: stopped ? "aborted" : "failed",
+				finishedAt: Date.now(),
+				...!stopped ? { error: { message: chunk.message } } : {}
+			});
+			return;
+		}
+		if (chunk.outcome?.type === "suspended") {
+			note.status = "suspended";
+			note.interruptIds = chunk.outcome.interruptIds ?? [];
+			await saveChild(id);
+			await stores.runs?.update(id, { status: "interrupted" });
+			return;
+		}
+		note.status = "finished";
+		await saveChild(id);
+		await stores.runs?.update(id, {
+			status: "completed",
+			finishedAt: Date.now()
+		});
+	}
+	async function commitAnswers(runId) {
+		const entries = answered.get(runId) ?? [];
+		answered.delete(runId);
+		for (const entry of entries) if (entry.status === "cancelled") await stores.interrupts?.cancel(entry.interruptId);
+		else await stores.interrupts?.resolve(entry.interruptId, entry.payload);
+	}
+	/** The notes a run fed. */
+	function notesOf(runId) {
+		return [...children].filter(([, note]) => note.runId === runId);
+	}
+	function forget(runId) {
+		for (const [id] of notesOf(runId)) children.delete(id);
+		parentSavedAt.delete(runId);
+	}
+	async function settleOpenChildren(runId, status, error) {
+		for (const [subagentRunId] of notesOf(runId)) {
+			await saveChild(subagentRunId);
+			const current = await stores.runs?.get(subagentRunId);
+			if (current && current.status !== "running") continue;
+			await stores.runs?.update(subagentRunId, {
+				status,
+				finishedAt: Date.now(),
+				...error ? { error } : {}
+			});
+		}
+	}
+	/** Write the parent messages of this thread's routed children. */
+	async function saveParents(threadId) {
+		const runIds = new Set([...children.values()].filter((note) => note.threadId === threadId).map((note) => note.parentRunId));
+		for (const runId of runIds) await saveParent(threadId, runId);
+	}
+	return {
+		async start(input) {
+			await stores.runs?.createOrResume({
+				runId: input.runId,
+				threadId: input.threadId,
+				startedAt: Date.now()
+			});
+			if (input.resume?.length) answered.set(input.runId, [...input.resume]);
+			const incoming = convertMessagesToModelMessages([...input.messages]);
+			const stored = await loadMessages(input.threadId);
+			const merged = mergeStoredMessages(stored, incoming);
+			await stores.messages.saveThread(input.threadId, keepSubagentRunIds(stored, merged));
+		},
+		async chunk(input) {
+			const chunk = input.chunk;
+			if (chunk.type === "SUBAGENT_STARTED") {
+				await startChild(input, chunk);
+				return;
+			}
+			if (chunk.type === "SUBAGENT_FINISHED" || chunk.type === "SUBAGENT_ERROR") {
+				await settleChild(chunk);
+				await saveParents(input.threadId);
+				return;
+			}
+			const subagentRunId = readSubagentRunId(chunk);
+			if (!subagentRunId) return;
+			const notes = lineage(subagentRunId);
+			if (notes.length === 0) return;
+			for (const note of notes) note.processor.processChunk(chunk);
+			const now = Date.now();
+			const note = notes[0];
+			if (note && now - note.savedAt >= intervalMs) await saveChild(subagentRunId);
+			if (chunk.type === "TEXT_MESSAGE_CONTENT" && now - (parentSavedAt.get(input.runId) ?? 0) >= intervalMs) {
+				parentSavedAt.set(input.runId, now);
+				await saveParents(input.threadId);
+			}
+		},
+		async suspend(input) {
+			await commitAnswers(input.runId);
+			await saveParents(input.threadId);
+			for (const [subagentRunId] of notesOf(input.runId)) await saveChild(subagentRunId);
+			for (const interrupt of input.interrupts) await stores.interrupts?.create({
+				interruptId: interrupt.id,
+				runId: input.runId,
+				threadId: input.threadId,
+				requestedAt: Date.now(),
+				payload: { ...interrupt }
+			});
+			await stores.runs?.update(input.runId, { status: "interrupted" });
+			forget(input.runId);
+		},
+		async finish(input) {
+			await commitAnswers(input.runId);
+			await saveParents(input.threadId);
+			await settleOpenChildren(input.runId, "completed");
+			await stores.runs?.update(input.runId, {
+				status: "completed",
+				finishedAt: Date.now()
+			});
+			forget(input.runId);
+		},
+		async abort(input) {
+			const aborted = input.error instanceof Error && input.error.name === "AbortError";
+			const message = input.error instanceof Error ? input.error.message : "Run failed";
+			await settleOpenChildren(input.runId, aborted ? "aborted" : "failed", aborted ? void 0 : { message });
+			await saveParents(input.threadId);
+			await stores.runs?.update(input.runId, {
+				status: aborted ? "aborted" : "failed",
+				finishedAt: Date.now(),
+				...!aborted ? { error: { message } } : {}
+			});
+			answered.delete(input.runId);
+			forget(input.runId);
+		}
+	};
+}
+//#endregion
+export { createSubagentRunRecorder, storedSubagentInfo };
+
+//# sourceMappingURL=subagent-runs.js.map