@tanstack/ai-persistence 0.6.4 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-persistence",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Composable state persistence for TanStack AI messages, runs, interrupts, metadata, and locks.",
   "author": "",
   "license": "MIT",
@@ -43,7 +43,7 @@
   },
   "peerDependencies": {
     "vitest": "^4.1.10",
-    "@tanstack/ai": "^0.58.0"
+    "@tanstack/ai": "^0.59.0"
   },
   "peerDependenciesMeta": {
     "vitest": {
@@ -53,7 +53,7 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "0.58.0"
+    "@tanstack/ai": "0.59.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/ai-persistence/build-cloudflare-adapter/SKILL.md

@@ -97,21 +97,27 @@ The invariants are the whole game, whichever route you take:
 | `runs`       | `update` on an unknown id is a silent no-op — never throws, never inserts                                                                                                                          |
 | `runs`       | `findActiveRun` (required) returns the latest `'running'` run for the thread, else null                                                                                                            |
 | `runs`       | `listByThread` (optional) returns every run for the thread `ORDER BY started_at ASC`                                                                                                               |
+| `runs`       | `listByParentRun` (optional) returns child runs for one `parent_run_id`, `ORDER BY started_at ASC`. `reconstructChat` uses it to put subagent cards back                                           |
 | `runs`       | `listReclaimable` (optional) returns runs where `status = 'running' AND detached_since IS NOT NULL AND detached_since <= now - ttlMs` (inclusive cutoff); it is a query, not automatic reclamation |
 | `interrupts` | `create` is insert-if-absent; never clobber a resolved interrupt back to pending                                                                                                                   |
 | `interrupts` | every `list*` ends `ORDER BY requested_at ASC`                                                                                                                                                     |
 | `metadata`   | reject nullish `set` with a clear `TypeError`; tell callers to use `delete`                                                                                                                        |
 
-On `runs`, `findActiveRun` is required; `listByThread` and `listReclaimable` are
-optional, so implement those two only if the app needs them. `withPersistence`
-calls **none** of the three — the consumers are `reconstruct.ts`
-(`findActiveRun`, for rejoin-by-thread) and `@tanstack/ai-sandbox`'s `reapDetachedRuns`
-(`listReclaimable`, without which the store cannot be reaped); nothing in the
-framework calls `listByThread`. Consumers of the two OPTIONAL methods
-feature-detect with `store.method?.(...)` and degrade to "not supported" when one
-is absent. The conformance testkit does not: either of those you leave out must
-be listed in `skipMethods` or the suite fails, so declare them and it reports the
-omission as a skip.
+On `runs`, `findActiveRun` is required. `listByThread`, `listByParentRun`, and
+`listReclaimable` are optional, so implement those only if the app needs them.
+`withPersistence` calls `createOrResume`, `update`, and `get`. `reconstruct.ts` calls
+`findActiveRun` for rejoin-by-thread and `listByParentRun` to put subagent
+cards back. `@tanstack/ai-sandbox`'s `reapDetachedRuns` calls `listReclaimable`.
+`reconstruct.ts` also calls `listByThread` to find the parent runs of children
+that a tool call started. Consumers of the optional methods
+feature-detect with `store.method?.(...)` and degrade when one is absent. The
+conformance testkit does not: each optional method you leave out must be listed
+in `skipMethods` or the suite fails. `listByParentRun` is the exception. When it
+is absent, the subagent checks skip on their own.
+
+`createOrResume` copies `parentRunId`, `subagentRunId`, and `name` on the first
+insert. A later call for the same `runId` leaves them unchanged. If the caller
+omits a field, omit it on the mapped record.
 
 `RunRecord.error` is a structured `RunError` (`{ message: string, code?: string }`),
 so the table gets two columns rather than one JSON blob: `error` for the
@@ -159,10 +165,14 @@ CREATE TABLE IF NOT EXISTS chat_runs (
   sandbox_key text,
   detached_since integer,
   cancel_requested integer,
-  driver_epoch integer
+  driver_epoch integer,
+  parent_run_id text,
+  subagent_run_id text,
+  name text
 );
 CREATE INDEX IF NOT EXISTS chat_runs_thread_status ON chat_runs (thread_id, status);
 CREATE INDEX IF NOT EXISTS chat_runs_thread_started ON chat_runs (thread_id, started_at);
+CREATE INDEX IF NOT EXISTS chat_runs_parent_started ON chat_runs (parent_run_id, started_at);
 -- Powers listReclaimable: status = 'running' AND detached_since <= cutoff.
 CREATE INDEX IF NOT EXISTS chat_runs_status_detached ON chat_runs (status, detached_since);
 CREATE TABLE IF NOT EXISTS chat_interrupts (
@@ -189,6 +199,20 @@ Apply with `wrangler d1 migrations apply <database-name>` (`--local` first, then
 `drizzle-kit generate` instead of hand-writing it — the SQL and the Drizzle
 table definitions must agree, so let one of them own the other.
 
+An existing `chat_runs` table does not get the three subagent columns from
+`CREATE TABLE IF NOT EXISTS`, and the `chat_runs_parent_started` index then
+fails. To add subagent support to an existing database, apply a separate
+migration first:
+
+```sql
+ALTER TABLE chat_runs ADD COLUMN parent_run_id text;
+ALTER TABLE chat_runs ADD COLUMN subagent_run_id text;
+ALTER TABLE chat_runs ADD COLUMN name text;
+CREATE INDEX IF NOT EXISTS chat_runs_parent_started ON chat_runs (parent_run_id, started_at);
+```
+
+A store without subagent support can skip the columns and the index.
+
 ## 6. Wire it into the chat route
 
 ```ts ignore
@@ -290,11 +314,12 @@ once you add the R2-backed set from
 **ai-persistence/build-cloudflare-artifact-store**). `skip` never accepts
 `'locks'`, which is not a store.
 
-If your recipe leaves an optional `runs` method
-(`listByThread`/`listReclaimable`) unimplemented, declare it
-with `skipMethods`, e.g. `{ skipMethods: ['runs.listByThread'] }`. An
-omitted method that is not declared fails the suite instead of silently
-passing.
+If your recipe leaves `listByThread` or `listReclaimable` unimplemented,
+declare it with `skipMethods`, for example
+`{ skipMethods: ['runs.listByThread'] }`. An omitted method that is not declared
+fails the suite instead of silently passing. Subagent support is optional: when
+`listByParentRun` is absent, the subagent checks skip on their own and need no
+entry.
 
 The lock store needs its **own** tests, because nothing in the conformance suite
 touches it. Cover at minimum: two concurrent `withLock` calls on the same key

package/skills/ai-persistence/build-custom-adapter/SKILL.md

@@ -43,12 +43,12 @@ complete worked `node:sqlite` walkthrough is
 Four logical records. Whatever the engine, keep these keys — the store methods
 look records up by exactly these:
 
-| Record    | Key                | Fields                                                                                                                                    |
-| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| thread    | `threadId`         | `messages` (array, full transcript)                                                                                                       |
-| run       | `runId`            | `threadId`, `status`, `startedAt`, `finishedAt?`, `error?`, `usage?`, `sandboxKey?`, `detachedSince?`, `cancelRequested?`, `driverEpoch?` |
-| interrupt | `interruptId`      | `runId`, `threadId`, `status`, `requestedAt`, `resolvedAt?`, `payload`, `response?`                                                       |
-| metadata  | `(namespace, key)` | `value`                                                                                                                                   |
+| Record    | Key                | Fields                                                                                                                                                                               |
+| --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| thread    | `threadId`         | `messages` (array, full transcript)                                                                                                                                                  |
+| run       | `runId`            | `threadId`, `status`, `startedAt`, `finishedAt?`, `error?`, `usage?`, `parentRunId?`, `subagentRunId?`, `name?`, `sandboxKey?`, `detachedSince?`, `cancelRequested?`, `driverEpoch?` |
+| interrupt | `interruptId`      | `runId`, `threadId`, `status`, `requestedAt`, `resolvedAt?`, `payload`, `response?`                                                                                                  |
+| metadata  | `(namespace, key)` | `value`                                                                                                                                                                              |
 
 - Timestamps are **epoch milliseconds** (`number`) in records. Store them
   however the engine prefers and convert in the mapper.
@@ -57,8 +57,8 @@ look records up by exactly these:
   conformance suite checks it.
 - Index `runs(threadId, status)`, `runs(threadId, startedAt)`, and
   `interrupts(threadId, requestedAt)` for the listing paths. If the backend
-  implements `listReclaimable`, also index `runs(status, detachedSince)`; that
-  is the query it runs.
+  implements `listReclaimable`, also index `runs(status, detachedSince)`. If it
+  implements `listByParentRun`, also index `runs(parentRunId, startedAt)`.
 - `run.error` is a structured `RunError` (`{ message: string, code?: string }`),
   not a bare string. `message` is the provider's prose; `code` is the stable,
   machine-branchable classification an operator filters and groups by. In a
@@ -105,8 +105,12 @@ history. They are engine-independent:
    automatic reclamation: `reapDetachedRuns` from `@tanstack/ai-sandbox` is the
    sweep that consumes it, and the application schedules that sweep. A store
    without this method cannot be reaped. `runs.findActiveRun` is required;
-   `runs.listByThread` / `runs.listReclaimable` are optional: implement only
-   what the app needs and leave the rest off the object.
+   `runs.listByThread`, `runs.listByParentRun`, and `runs.listReclaimable` are
+   optional: implement only what the app needs and leave the rest off the object.
+   `listByParentRun` returns the child runs for one `parentRunId`, oldest
+   `startedAt` first. `reconstructChat` uses that list to put subagent cards
+   back. `createOrResume` copies `parentRunId`, `subagentRunId`, and `name` on
+   the first insert and leaves them unchanged on resume.
 
 Row mappers omit absent optionals
 (`...(row.sandbox_key != null ? { sandboxKey: row.sandbox_key } : {})`) so
@@ -165,21 +169,44 @@ function createRunStore(db: Pool): RunStore {
   return {
     get,
     // Idempotent: an existing runId is returned untouched.
-    async createOrResume({ runId, threadId, startedAt, status }) {
+    async createOrResume(input) {
+      const { runId, threadId, startedAt, status } = input
       const existing = await get(runId)
       if (existing) return existing
 
       await db.query(
-        `INSERT INTO chat_runs (run_id, thread_id, status, started_at)
-         VALUES ($1, $2, $3, $4)
+        `INSERT INTO chat_runs (
+           run_id, thread_id, status, started_at,
+           parent_run_id, subagent_run_id, name
+         ) VALUES ($1, $2, $3, $4, $5, $6, $7)
          ON CONFLICT (run_id) DO NOTHING`,
-        [runId, threadId, status ?? 'running', startedAt],
+        [
+          runId,
+          threadId,
+          status ?? 'running',
+          startedAt,
+          input.parentRunId ?? null,
+          input.subagentRunId ?? null,
+          input.name ?? null,
+        ],
       )
       // Re-read: a concurrent createOrResume may have won the race, and that
       // row is the authoritative one.
       const stored = await get(runId)
       return (
-        stored ?? { runId, threadId, status: status ?? 'running', startedAt }
+        stored ?? {
+          runId,
+          threadId,
+          status: status ?? 'running',
+          startedAt,
+          ...(input.parentRunId !== undefined
+            ? { parentRunId: input.parentRunId }
+            : {}),
+          ...(input.subagentRunId !== undefined
+            ? { subagentRunId: input.subagentRunId }
+            : {}),
+          ...(input.name !== undefined ? { name: input.name } : {}),
+        }
       )
     },
     // ... update (no-op on unknown id; sandboxKey/detachedSince/
@@ -191,8 +218,9 @@ function createRunStore(db: Pool): RunStore {
     // error = patch.error.message and error_code = patch.error.code ?? null,
     // together in the same call),
     // findActiveRun (latest 'running', required), listByThread (ascending
-    // by startedAt, optional), listReclaimable (status = 'running' AND
-    // detachedSince <= now - ttlMs, inclusive cutoff, optional)
+    // by startedAt, optional), listByParentRun (children of parentRunId,
+    // ascending by startedAt, optional), listReclaimable (status = 'running'
+    // AND detachedSince <= now - ttlMs, inclusive cutoff, optional)
   }
 }
 
@@ -321,8 +349,9 @@ seven stores, so declare every intentional omission — a chat adapter skips the
 generation half above, and adds e.g. `'metadata'` if it drops that too. `skip`
 never accepts `'locks'`, which is not a store.
 
-If your recipe leaves an optional `runs` method (`listByThread`/
-`listReclaimable`) unimplemented, declare it separately with `skipMethods`, e.g.
+If your recipe leaves `listByThread` or `listReclaimable` unimplemented,
+declare it separately with `skipMethods`, for example
 `{ skipMethods: ['runs.listByThread'] }`. An omitted method that is not declared
-fails the suite instead of silently passing. `findActiveRun` is **not** in that
+fails the suite instead of silently passing. Subagent support is optional: when
+`listByParentRun` is absent, the subagent checks skip on their own. `findActiveRun` is **not** in that
 set — it is required, so there is nothing to declare.

package/skills/ai-persistence/build-drizzle-adapter/SKILL.md

@@ -80,12 +80,17 @@ export const chatRuns = sqliteTable(
     detachedSince: integer('detached_since'),
     cancelRequested: integer('cancel_requested', { mode: 'boolean' }),
     driverEpoch: integer('driver_epoch'),
+    parentRunId: text('parent_run_id'),
+    subagentRunId: text('subagent_run_id'),
+    name: text('name'),
   },
   (table) => [
     // Powers listReclaimable: status = 'running' AND detachedSince <= cutoff.
     index('chat_runs_status_detached').on(table.status, table.detachedSince),
     // Powers listByThread and findActiveRun.
     index('chat_runs_thread_started').on(table.threadId, table.startedAt),
+    // Powers listByParentRun: children of one parent, oldest startedAt first.
+    index('chat_runs_parent_started').on(table.parentRunId, table.startedAt),
   ],
 )
 
@@ -135,7 +140,8 @@ behind.
 `boolean()` for `cancelRequested`, and `varchar(..., { length: 255 })` for the
 primary-key columns. The store bodies below are identical across all three,
 only `onConflictDoUpdate` becomes `onDuplicateKeyUpdate` on MySQL, and the
-`(status, detachedSince)` / `(threadId, startedAt)` indexes carry over as is.
+`(status, detachedSince)`, `(threadId, startedAt)`, and
+`(parentRunId, startedAt)` indexes carry over as is.
 
 ## 3. Write `src/lib/chat-persistence.ts`
 
@@ -190,6 +196,9 @@ function mapRun(row: typeof chatRuns.$inferSelect): RunRecord {
       ? { cancelRequested: row.cancelRequested }
       : {}),
     ...(row.driverEpoch != null ? { driverEpoch: row.driverEpoch } : {}),
+    ...(row.parentRunId != null ? { parentRunId: row.parentRunId } : {}),
+    ...(row.subagentRunId != null ? { subagentRunId: row.subagentRunId } : {}),
+    ...(row.name != null ? { name: row.name } : {}),
   }
 }
 
@@ -247,20 +256,45 @@ function createRunStore(db: Db): RunStore {
     get,
     // Idempotent: an existing runId is returned untouched so resume and
     // double-submit are safe.
-    async createOrResume({ runId, threadId, startedAt, status }) {
+    async createOrResume(input) {
+      const { runId, threadId, startedAt, status } = input
       const existing = await get(runId)
       if (existing) return existing
 
       await db
         .insert(chatRuns)
-        .values({ runId, threadId, status: status ?? 'running', startedAt })
+        .values({
+          runId,
+          threadId,
+          status: status ?? 'running',
+          startedAt,
+          ...(input.parentRunId !== undefined
+            ? { parentRunId: input.parentRunId }
+            : {}),
+          ...(input.subagentRunId !== undefined
+            ? { subagentRunId: input.subagentRunId }
+            : {}),
+          ...(input.name !== undefined ? { name: input.name } : {}),
+        })
         .onConflictDoNothing({ target: chatRuns.runId })
 
       // Re-read rather than trusting the insert: a concurrent createOrResume
       // may have won the race, and that row is the authoritative one.
       const stored = await get(runId)
       return (
-        stored ?? { runId, threadId, status: status ?? 'running', startedAt }
+        stored ?? {
+          runId,
+          threadId,
+          status: status ?? 'running',
+          startedAt,
+          ...(input.parentRunId !== undefined
+            ? { parentRunId: input.parentRunId }
+            : {}),
+          ...(input.subagentRunId !== undefined
+            ? { subagentRunId: input.subagentRunId }
+            : {}),
+          ...(input.name !== undefined ? { name: input.name } : {}),
+        }
       )
     },
     // Patching an unknown runId is a no-op: never throws, never inserts.
@@ -314,6 +348,16 @@ function createRunStore(db: Db): RunStore {
         .orderBy(asc(chatRuns.startedAt))
       return rows.map(mapRun)
     },
+    // Optional. Child runs for one parent, oldest startedAt first.
+    // reconstructChat uses this list to put subagent cards back.
+    async listByParentRun(parentRunId) {
+      const rows = await db
+        .select()
+        .from(chatRuns)
+        .where(eq(chatRuns.parentRunId, parentRunId))
+        .orderBy(asc(chatRuns.startedAt))
+      return rows.map(mapRun)
+    },
     // Optional; still-running runs detached at or before the cutoff. Uses the
     // (status, detachedSince) index. The cutoff is inclusive.
     async listReclaimable({ now, ttlMs }) {
@@ -531,11 +575,12 @@ seven stores, so a chat adapter declares the generation half it omits; drop the
 `skip` once you add those tables. `skip` never accepts `'locks'`, which is not a
 store.
 
-If your recipe leaves an optional `runs` method
-(`listByThread`/`listReclaimable`) unimplemented, declare it
-with `skipMethods`, e.g. `{ skipMethods: ['runs.listByThread'] }`. An
-omitted method that is not declared fails the suite instead of silently
-passing.
+If your recipe leaves `listByThread` or `listReclaimable` unimplemented,
+declare it with `skipMethods`, for example
+`{ skipMethods: ['runs.listByThread'] }`. An omitted method that is not declared
+fails the suite instead of silently passing. Subagent support is optional: when
+`listByParentRun` is absent, the subagent checks skip on their own and need no
+entry.
 
 ## Only if you are publishing this as a package
 

package/skills/ai-persistence/build-prisma-adapter/SKILL.md

@@ -67,9 +67,14 @@ model ChatRun {
   detachedSince   BigInt? @map("detached_since")
   cancelRequested Boolean? @map("cancel_requested")
   driverEpoch     Int?     @map("driver_epoch")
+  parentRunId     String?  @map("parent_run_id")
+  subagentRunId   String?  @map("subagent_run_id")
+  name            String?
 
   @@index([threadId, status])
   @@index([threadId, startedAt])
+  // Powers listByParentRun: children of one parent, oldest startedAt first.
+  @@index([parentRunId, startedAt])
   // Powers listReclaimable: status = 'running' AND detachedSince <= cutoff.
   @@index([status, detachedSince])
   @@map("chat_runs")
@@ -204,6 +209,9 @@ function mapRun(row: ChatRun): RunRecord {
       ? { cancelRequested: row.cancelRequested }
       : {}),
     ...(row.driverEpoch != null ? { driverEpoch: row.driverEpoch } : {}),
+    ...(row.parentRunId != null ? { parentRunId: row.parentRunId } : {}),
+    ...(row.subagentRunId != null ? { subagentRunId: row.subagentRunId } : {}),
+    ...(row.name != null ? { name: row.name } : {}),
   }
 }
 
@@ -250,7 +258,8 @@ function createRunStore(db: PrismaClient): RunStore {
     },
     // An empty `update` is Prisma's ON CONFLICT DO NOTHING: an existing runId
     // comes back untouched, so resume and double-submit are safe.
-    async createOrResume({ runId, threadId, startedAt, status }) {
+    async createOrResume(input) {
+      const { runId, threadId, startedAt, status } = input
       const row = await db.chatRun.upsert({
         where: { runId },
         create: {
@@ -258,6 +267,13 @@ function createRunStore(db: PrismaClient): RunStore {
           threadId,
           status: status ?? 'running',
           startedAt: BigInt(startedAt),
+          ...(input.parentRunId !== undefined
+            ? { parentRunId: input.parentRunId }
+            : {}),
+          ...(input.subagentRunId !== undefined
+            ? { subagentRunId: input.subagentRunId }
+            : {}),
+          ...(input.name !== undefined ? { name: input.name } : {}),
         },
         update: {},
       })
@@ -314,6 +330,15 @@ function createRunStore(db: PrismaClient): RunStore {
       })
       return rows.map(mapRun)
     },
+    // Optional. Child runs for one parent, oldest startedAt first.
+    // reconstructChat uses this list to put subagent cards back.
+    async listByParentRun(parentRunId) {
+      const rows = await db.chatRun.findMany({
+        where: { parentRunId },
+        orderBy: { startedAt: 'asc' },
+      })
+      return rows.map(mapRun)
+    },
     // Optional; still-running runs detached at or before the cutoff. Uses
     // the (status, detachedSince) index. The cutoff is inclusive.
     async listReclaimable({ now, ttlMs }) {
@@ -489,11 +514,12 @@ provided; the suite also covers the three generation stores, so declare those as
 skipped until you add them. `skip` never accepts `'locks'`, which is not a
 store.
 
-If your recipe leaves an optional `runs` method
-(`listByThread`/`listReclaimable`) unimplemented, declare it
-with `skipMethods`, e.g. `{ skipMethods: ['runs.listByThread'] }`. An
-omitted method that is not declared fails the suite instead of silently
-passing.
+If your recipe leaves `listByThread` or `listReclaimable` unimplemented,
+declare it with `skipMethods`, for example
+`{ skipMethods: ['runs.listByThread'] }`. An omitted method that is not declared
+fails the suite instead of silently passing. Subagent support is optional: when
+`listByParentRun` is absent, the subagent checks skip on their own and need no
+entry.
 
 ## Only if you are publishing this as a package
 

package/skills/ai-persistence/stores/SKILL.md

@@ -113,28 +113,30 @@ package name.
 resolve.
 
 Four methods are required (`createOrResume` / `update` / `get` /
-`findActiveRun`). Two are optional: implement only the ones your backend needs,
+`findActiveRun`). Three are optional: implement only the ones your backend needs,
 and leave the rest off the object entirely (not `undefined`, just absent). A
 four-method `RunStore` is a fully valid backend.
 
-`withPersistence` itself calls **none** of the three non-`createOrResume`/`update`
-query methods, so leaving both optional ones off costs nothing in the middleware.
-Their consumers are elsewhere, and each absence disables exactly one feature:
+`withPersistence` calls `createOrResume` and `update`. The query methods have
+other consumers. Each missing optional method disables one feature:
 
-| method            | consumer                                                  | absent ⇒                                                                 |
-| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `findActiveRun`   | `reconstruct.ts` (`stores.runs?.findActiveRun(threadId)`) | required — cannot be absent; stubbing it to `null` silently kills rejoin |
-| `listReclaimable` | `reapDetachedRuns` in `@tanstack/ai-sandbox`              | the store cannot be reaped at all                                        |
-| `listByThread`    | application code — nothing in the framework calls it      | nothing framework-side breaks                                            |
+| method            | consumer                                                  | absent means                                               |
+| ----------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
+| `findActiveRun`   | `reconstruct.ts` (`stores.runs?.findActiveRun(threadId)`) | required. A `null` stub hides a live run                   |
+| `listReclaimable` | `reapDetachedRuns` in `@tanstack/ai-sandbox`              | the store cannot be reaped at all                          |
+| `listByThread`    | `reconstructChat`, when the transcript has tool calls     | the cards of children that a tool call started stay absent |
+| `listByParentRun` | `reconstructChat`                                         | a reload shows the saved text, and the cards stay absent   |
 
-Consumers of the two OPTIONAL methods feature-detect with `store.method?.(...)`
+Consumers of the optional methods feature-detect with `store.method?.(...)`
 and degrade rather than throwing. `findActiveRun` is required, so nothing
 feature-detects it.
 
 The conformance testkit does not feature-detect. An optional method that is
 missing and not declared in `skipMethods` fails the suite, so an omission is
 always a choice you made on purpose rather than a check that quietly did not
-run. Declare yours and the suite reports them as skipped with a reason:
+run. The one exception is `listByParentRun`: subagent support is optional, so
+those checks skip on their own. Declare yours and the suite reports them as
+skipped with a reason:
 
 ```ts
 import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
@@ -155,6 +157,9 @@ interface RunStore {
   createOrResume: (
     input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
       status?: RunStatus
+      parentRunId?: string
+      subagentRunId?: string
+      name?: string
     },
   ) => Promise<RunRecord>
   update: (
@@ -178,6 +183,7 @@ interface RunStore {
 
   // Optional
   listByThread?: (threadId: string) => Promise<Array<RunRecord>>
+  listByParentRun?: (parentRunId: string) => Promise<Array<RunRecord>>
   listReclaimable?: (opts: {
     now: number
     ttlMs: number
@@ -280,15 +286,20 @@ store through `update`/`get` — but `cancelRequested` must round-trip
 faithfully (previous section) for the durable path to work at all.
 
 - **`createOrResume`** (required): if `runId` exists, return it **unchanged**,
-  including its stored `usage`, and ignore the passed `threadId` / `startedAt` /
-  `status`. Resuming a run does not reset `startedAt` or overwrite its current
-  status. Idempotent retries and double-submit depend on this. `status` defaults
-  to `'running'` on first creation.
+  including its stored `usage`, and ignore the passed `threadId`, `startedAt`,
+  `status`, `parentRunId`, `subagentRunId`, and `name`. Resuming a run does not
+  reset `startedAt` or overwrite its current status. Idempotent retries and
+  double-submit depend on this. `status` defaults to `'running'` on first
+  creation. The three link fields are copied only on the first insert.
 - **`update`** (required): missing `runId` is a **no-op** (do not throw, do not
   insert).
 - **`get`** (required): current record, or `null` when unknown.
 - **`listByThread`** (optional): every run for `threadId`, ascending by
-  `startedAt`. Only needed to render a thread's past agent activity.
+  `startedAt`. `reconstructChat` calls it to find the parent runs of children
+  that a tool call started.
+- **`listByParentRun`** (optional): child runs for `parentRunId`, ascending by
+  `startedAt`. `reconstructChat` uses this list to put subagent cards back.
+  Omit the method and a reload shows the saved text. The cards stay absent.
 - **`listReclaimable`** (optional): runs where `status === 'running'` AND
   `detachedSince` is set AND `detachedSince <= now - ttlMs`. The cutoff is
   inclusive: a run detached exactly at the cutoff qualifies. This is a query, not
@@ -308,9 +319,15 @@ faithfully (previous section) for the durable path to work at all.
   one release cycle and cost precisely that, which is why it is required now.
 
 Capability tiers belong at the STORE level (omit `runs` entirely and declare
-`ChatTranscriptStores`), not the method level — never ship a `RunStore` with a
-stubbed method. The two list queries above are the only method-level options,
-and each must be declared via `skipMethods` when absent.
+`ChatTranscriptStores`), not the method level. Never ship a `RunStore` with a
+stubbed method. The list queries above are the only method-level options,
+and each must be declared via `skipMethods` when absent, except
+`listByParentRun`: without it the subagent checks skip on their own.
+
+A subagent child run also stores `parentRunId`, `subagentRunId`, and `name`.
+`createOrResume` writes them on the first insert. A later call for the same
+`runId` leaves them unchanged. If the caller omits a field, omit it on the
+record. Do not store `''` for a missing field.
 
 ### `InterruptStore`
 
@@ -468,17 +485,17 @@ in `skip` fails loudly.
 pass `'locks'`** — it is not a state store and the suite does not cover it.
 
 **`skipMethods` (declare-or-fail for optional `RunStore` methods).** A backend
-that omits an OPTIONAL `RunStore` method (`listByThread`, `listReclaimable` —
-`findActiveRun` is required and cannot be declared away) must declare it in
-`skipMethods` as `'runs.<method>'`, e.g.
-`skipMethods: ['runs.listByThread', 'runs.listReclaimable']`. An omitted
-method that is NOT declared throws with an actionable message instead of
-silently reporting a pass; a declared one is reported as a SKIPPED vitest
-case, never as a pass. A case that did not run must never be
+that omits `listByThread` or `listReclaimable` must declare it. `findActiveRun`
+is required. Declare the omission as `'runs.<method>'`, for example
+`skipMethods: ['runs.listByThread', 'runs.listReclaimable']`. Subagent support is
+optional: when `listByParentRun` is absent, the subagent checks (the link fields
+and the child listing) skip on their own and need no entry.
+An omitted method that is NOT declared throws with an actionable message
+instead of silently reporting a pass. A declared one is reported as a SKIPPED
+vitest case, never as a pass. A case that did not run must never be
 indistinguishable from one that did. See
-`examples/ts-react-chat/src/lib/sqlite-persistence.test.ts` for a worked
-example: it declares `skipMethods: ['runs.listByThread']` only, keeping both
-`findActiveRun` and `listReclaimable` under test.
+`examples/ts-react-chat/src/lib/sqlite-persistence.test.ts`. It implements every
+run method, so it declares no `skipMethods`.
 
 Reference implementation: `memoryPersistence()` in `@tanstack/ai-persistence`.
 

package/src/memory.ts

@@ -60,6 +60,9 @@ class MemoryRunStore implements RunStore {
     threadId: string
     status?: RunRecord['status']
     startedAt: number
+    parentRunId?: string
+    subagentRunId?: string
+    name?: string
   }): Promise<RunRecord> {
     const existing = this.runs.get(input.runId)
     if (existing) return Promise.resolve(existing)
@@ -68,6 +71,13 @@ class MemoryRunStore implements RunStore {
       threadId: input.threadId,
       status: input.status ?? 'running',
       startedAt: input.startedAt,
+      ...(input.parentRunId !== undefined
+        ? { parentRunId: input.parentRunId }
+        : {}),
+      ...(input.subagentRunId !== undefined
+        ? { subagentRunId: input.subagentRunId }
+        : {}),
+      ...(input.name !== undefined ? { name: input.name } : {}),
     }
     this.runs.set(record.runId, record)
     return Promise.resolve(record)
@@ -107,6 +117,12 @@ class MemoryRunStore implements RunStore {
       .sort((a, b) => a.startedAt - b.startedAt)
     return Promise.resolve(matching)
   }
+  listByParentRun(parentRunId: string): Promise<Array<RunRecord>> {
+    const matching = [...this.runs.values()]
+      .filter((run) => run.parentRunId === parentRunId)
+      .sort((a, b) => a.startedAt - b.startedAt)
+    return Promise.resolve(matching)
+  }
   listReclaimable(opts: {
     now: number
     ttlMs: number