@tanstack/ai-persistence 0.0.0

package/dist/esm/reconstruct.js

@@ -0,0 +1,75 @@
+import { validateReconstructChatStores } from "./types.js";
+import { modelMessagesToUIMessages } from "@tanstack/ai";
+//#region src/reconstruct.ts
+/**
+* Build the JSON `Response` a server-authoritative client hydrates from on load
+* (see the client-persistence guide). Reads the thread id from the request query
+* (`?threadId=` by default) and returns `{ messages, activeRun, interrupts }`
+* ({@link ReconstructedChat}):
+*
+* - `messages` — the stored transcript as UI messages.
+* - `activeRun` — `{ runId }` if a run is still generating for the thread (so the
+*   client tails it via the durability stream), else `null`. Resolved via the
+*   required `stores.runs.findActiveRun`; `null` when the `runs` store is absent.
+* - `interrupts` — `{ runId, pending }` if the thread has pending human-in-the-loop
+*   interrupts (a paused approval / wait) and the run they paused, else `null`, so
+*   a reload re-prompts the decision from the server. Resolved via the optional
+*   `stores.interrupts.listPending`; `null` when that store is absent.
+*
+* Requires `stores.messages`. Returns an empty transcript with no active run
+* and no interrupts when the thread id is missing or the thread is unknown, so
+* the caller never has to special-case a first load.
+*
+* This helper does **not** enforce tenancy by itself. Pass
+* {@link ReconstructChatOptions.authorize} (or wrap the call in your own
+* session gate) before exposing it on a public route.
+*
+* ```ts
+* export async function GET(request: Request) {
+*   return reconstructChat(persistence, request, {
+*     authorize: async (threadId, req) => {
+*       const userId = await getSessionUserId(req)
+*       return userId != null && (await userOwnsThread(userId, threadId))
+*     },
+*   })
+* }
+* ```
+*/
+async function reconstructChat(persistence, request, options) {
+	validateReconstructChatStores(persistence);
+	const messageStore = persistence.stores.messages;
+	if (!messageStore) throw new Error("reconstructChat requires stores.messages.");
+	const param = options?.param ?? "threadId";
+	const threadId = new URL(request.url).searchParams.get(param) ?? "";
+	if (threadId && options?.authorize) {
+		const decision = await options.authorize(threadId, request);
+		if (decision instanceof Response) return decision;
+		if (!decision) return new Response(JSON.stringify({ error: "Forbidden" }), {
+			status: 403,
+			headers: {
+				"content-type": "application/json",
+				"cache-control": "no-store"
+			}
+		});
+	}
+	const active = threadId ? await persistence.stores.runs?.findActiveRun(threadId) : null;
+	const stored = threadId ? await messageStore.loadThread(threadId) : [];
+	const pending = threadId ? await persistence.stores.interrupts?.listPending(threadId) ?? [] : [];
+	const firstPending = pending[0];
+	const body = {
+		messages: modelMessagesToUIMessages(stored),
+		activeRun: active ? { runId: active.runId } : null,
+		interrupts: firstPending ? {
+			runId: firstPending.runId,
+			pending: pending.map((record) => record.payload)
+		} : null
+	};
+	return new Response(JSON.stringify(body), { headers: {
+		"content-type": "application/json",
+		"cache-control": "no-store"
+	} });
+}
+//#endregion
+export { reconstructChat };
+
+//# sourceMappingURL=reconstruct.js.map

package/dist/esm/reconstruct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconstruct.js","names":[],"sources":["../../src/reconstruct.ts"],"sourcesContent":["import { modelMessagesToUIMessages } from '@tanstack/ai'\nimport type { UIMessage } from '@tanstack/ai'\nimport { validateReconstructChatStores } from './types'\nimport type { AIPersistence, ChatTranscriptStores } from './types'\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 */\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}\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 * 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 param = options?.param ?? 'threadId'\n  const threadId = new URL(request.url).searchParams.get(param) ?? ''\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 = threadId ? await messageStore.loadThread(threadId) : []\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 body: ReconstructedChat = {\n    messages: modelMessagesToUIMessages(stored),\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  }\n  return new Response(JSON.stringify(body), {\n    headers: {\n      'content-type': 'application/json',\n      'cache-control': 'no-store',\n    },\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoFA,eAAsB,gBACpB,aACA,SACA,SACmB;CACnB,8BAA8B,WAAW;CACzC,MAAM,eAAe,YAAY,OAAO;CACxC,IAAI,CAAC,cAEH,MAAM,IAAI,MAAM,2CAA2C;CAG7D,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,WAAW,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC,aAAa,IAAI,KAAK,KAAK;CAEjE,IAAI,YAAY,SAAS,WAAW;EAClC,MAAM,WAAW,MAAM,QAAQ,UAAU,UAAU,OAAO;EAC1D,IAAI,oBAAoB,UACtB,OAAO;EAET,IAAI,CAAC,UACH,OAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,YAAY,CAAC,GAAG;GAC1D,QAAQ;GACR,SAAS;IACP,gBAAgB;IAChB,iBAAiB;GACnB;EACF,CAAC;CAEL;CAQA,MAAM,SAAS,WACX,MAAM,YAAY,OAAO,MAAM,cAAc,QAAQ,IACrD;CACJ,MAAM,SAAS,WAAW,MAAM,aAAa,WAAW,QAAQ,IAAI,CAAC;CAIrE,MAAM,UAAU,WACV,MAAM,YAAY,OAAO,YAAY,YAAY,QAAQ,KAAM,CAAC,IAClE,CAAC;CACL,MAAM,eAAe,QAAQ;CAC7B,MAAM,OAA0B;EAC9B,UAAU,0BAA0B,MAAM;EAC1C,WAAW,SAAS,EAAE,OAAO,OAAO,MAAM,IAAI;EAC9C,YAAY,eACR;GACE,OAAO,aAAa;GACpB,SAAS,QAAQ,KAAK,WAAW,OAAO,OAAO;EACjD,IACA;CACN;CACA,OAAO,IAAI,SAAS,KAAK,UAAU,IAAI,GAAG,EACxC,SAAS;EACP,gBAAgB;EAChB,iBAAiB;CACnB,EACF,CAAC;AACH"}

package/dist/esm/retrieve.d.ts

@@ -0,0 +1,40 @@
+import { AIPersistence, ArtifactRecord, BlobGetOptions, BlobObject } from './types.js';
+/**
+ * The DEFAULT blob-store key a generation artifact's bytes are stored under,
+ * used when `withGenerationPersistence` is given no `storageKey` mapper.
+ *
+ * Reads go through {@link resolveArtifactBlobKey} instead: a record written with
+ * a custom `storageKey` carries its real key in `blobKey`, and recomputing the
+ * default would look in the wrong place.
+ *
+ * @internal
+ */
+export declare function artifactBlobKey(ref: Pick<ArtifactRecord, 'runId' | 'artifactId'>): string;
+/**
+ * The blob-store key to read an artifact's bytes from: the key recorded when it
+ * was written, falling back to the default convention for records written
+ * before `blobKey` existed.
+ *
+ * The fallback is what makes `blobKey` a non-breaking addition — and why the
+ * default convention can never be changed retroactively without one.
+ */
+export declare function resolveArtifactBlobKey(record: ArtifactRecord): string;
+/**
+ * Look up a persisted generation artifact's metadata by id. Returns `null` when
+ * the persistence has no `artifacts` store or no record matches — so a serve
+ * handler can map that straight to a 404.
+ */
+export declare function retrieveArtifact(persistence: AIPersistence, artifactId: string): Promise<ArtifactRecord | null>;
+/**
+ * Look up a persisted generation artifact's stored bytes. Pass an `artifactId`
+ * (resolved to its record first) or an already-loaded {@link ArtifactRecord}
+ * (no second metadata lookup). Returns `null` when the artifact, its record, or
+ * its blob is missing, or the stores are not configured.
+ *
+ * Pass `options.range` to read one slice — how a serve route answers a `Range`
+ * request with `206` + `Content-Range` instead of the whole file, which is what
+ * `<video>` seeking is built on. Resolve the range against `record.size` and
+ * reply `416` yourself when it does not fit; the store is handed satisfiable
+ * ranges only. The returned object's `range` reports the slice actually served.
+ */
+export declare function retrieveBlob(persistence: AIPersistence, artifact: string | ArtifactRecord, options?: BlobGetOptions): Promise<BlobObject | null>;

package/dist/esm/retrieve.js

@@ -0,0 +1,54 @@
+//#region src/retrieve.ts
+/**
+* The DEFAULT blob-store key a generation artifact's bytes are stored under,
+* used when `withGenerationPersistence` is given no `storageKey` mapper.
+*
+* Reads go through {@link resolveArtifactBlobKey} instead: a record written with
+* a custom `storageKey` carries its real key in `blobKey`, and recomputing the
+* default would look in the wrong place.
+*
+* @internal
+*/
+function artifactBlobKey(ref) {
+	return `artifacts/${ref.runId}/${ref.artifactId}`;
+}
+/**
+* The blob-store key to read an artifact's bytes from: the key recorded when it
+* was written, falling back to the default convention for records written
+* before `blobKey` existed.
+*
+* The fallback is what makes `blobKey` a non-breaking addition — and why the
+* default convention can never be changed retroactively without one.
+*/
+function resolveArtifactBlobKey(record) {
+	return record.blobKey ?? artifactBlobKey(record);
+}
+/**
+* Look up a persisted generation artifact's metadata by id. Returns `null` when
+* the persistence has no `artifacts` store or no record matches — so a serve
+* handler can map that straight to a 404.
+*/
+async function retrieveArtifact(persistence, artifactId) {
+	return await persistence.stores.artifacts?.get(artifactId) ?? null;
+}
+/**
+* Look up a persisted generation artifact's stored bytes. Pass an `artifactId`
+* (resolved to its record first) or an already-loaded {@link ArtifactRecord}
+* (no second metadata lookup). Returns `null` when the artifact, its record, or
+* its blob is missing, or the stores are not configured.
+*
+* Pass `options.range` to read one slice — how a serve route answers a `Range`
+* request with `206` + `Content-Range` instead of the whole file, which is what
+* `<video>` seeking is built on. Resolve the range against `record.size` and
+* reply `416` yourself when it does not fit; the store is handed satisfiable
+* ranges only. The returned object's `range` reports the slice actually served.
+*/
+async function retrieveBlob(persistence, artifact, options) {
+	const record = typeof artifact === "string" ? await retrieveArtifact(persistence, artifact) : artifact;
+	if (!record) return null;
+	return await persistence.stores.blobs?.get(resolveArtifactBlobKey(record), options) ?? null;
+}
+//#endregion
+export { artifactBlobKey, resolveArtifactBlobKey, retrieveArtifact, retrieveBlob };
+
+//# sourceMappingURL=retrieve.js.map

package/dist/esm/retrieve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.js","names":[],"sources":["../../src/retrieve.ts"],"sourcesContent":["import type {\n  AIPersistence,\n  ArtifactRecord,\n  BlobGetOptions,\n  BlobObject,\n} from './types'\n\n/**\n * The DEFAULT blob-store key a generation artifact's bytes are stored under,\n * used when `withGenerationPersistence` is given no `storageKey` mapper.\n *\n * Reads go through {@link resolveArtifactBlobKey} instead: a record written with\n * a custom `storageKey` carries its real key in `blobKey`, and recomputing the\n * default would look in the wrong place.\n *\n * @internal\n */\nexport function artifactBlobKey(\n  ref: Pick<ArtifactRecord, 'runId' | 'artifactId'>,\n): string {\n  return `artifacts/${ref.runId}/${ref.artifactId}`\n}\n\n/**\n * The blob-store key to read an artifact's bytes from: the key recorded when it\n * was written, falling back to the default convention for records written\n * before `blobKey` existed.\n *\n * The fallback is what makes `blobKey` a non-breaking addition — and why the\n * default convention can never be changed retroactively without one.\n */\nexport function resolveArtifactBlobKey(record: ArtifactRecord): string {\n  return record.blobKey ?? artifactBlobKey(record)\n}\n\n/**\n * Look up a persisted generation artifact's metadata by id. Returns `null` when\n * the persistence has no `artifacts` store or no record matches — so a serve\n * handler can map that straight to a 404.\n */\nexport async function retrieveArtifact(\n  persistence: AIPersistence,\n  artifactId: string,\n): Promise<ArtifactRecord | null> {\n  const record = await persistence.stores.artifacts?.get(artifactId)\n  return record ?? null\n}\n\n/**\n * Look up a persisted generation artifact's stored bytes. Pass an `artifactId`\n * (resolved to its record first) or an already-loaded {@link ArtifactRecord}\n * (no second metadata lookup). Returns `null` when the artifact, its record, or\n * its blob is missing, or the stores are not configured.\n *\n * Pass `options.range` to read one slice — how a serve route answers a `Range`\n * request with `206` + `Content-Range` instead of the whole file, which is what\n * `<video>` seeking is built on. Resolve the range against `record.size` and\n * reply `416` yourself when it does not fit; the store is handed satisfiable\n * ranges only. The returned object's `range` reports the slice actually served.\n */\nexport async function retrieveBlob(\n  persistence: AIPersistence,\n  artifact: string | ArtifactRecord,\n  options?: BlobGetOptions,\n): Promise<BlobObject | null> {\n  const record =\n    typeof artifact === 'string'\n      ? await retrieveArtifact(persistence, artifact)\n      : artifact\n  if (!record) return null\n\n  const blob = await persistence.stores.blobs?.get(\n    resolveArtifactBlobKey(record),\n    options,\n  )\n  return blob ?? null\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAgB,gBACd,KACQ;CACR,OAAO,aAAa,IAAI,MAAM,GAAG,IAAI;AACvC;;;;;;;;;AAUA,SAAgB,uBAAuB,QAAgC;CACrE,OAAO,OAAO,WAAW,gBAAgB,MAAM;AACjD;;;;;;AAOA,eAAsB,iBACpB,aACA,YACgC;CAEhC,OAAO,MADc,YAAY,OAAO,WAAW,IAAI,UAAU,KAChD;AACnB;;;;;;;;;;;;;AAcA,eAAsB,aACpB,aACA,UACA,SAC4B;CAC5B,MAAM,SACJ,OAAO,aAAa,WAChB,MAAM,iBAAiB,aAAa,QAAQ,IAC5C;CACN,IAAI,CAAC,QAAQ,OAAO;CAMpB,OAAO,MAJY,YAAY,OAAO,OAAO,IAC3C,uBAAuB,MAAM,GAC7B,OACF,KACe;AACjB"}

package/dist/esm/testkit/conformance.d.ts

@@ -0,0 +1,33 @@
+import { AIPersistence, AIPersistenceStores } from '../types.js';
+type MakePersistence = () => Promise<AIPersistence> | AIPersistence;
+/**
+ * Methods that are optional on the `RunStore` contract.
+ *
+ * `findActiveRun` is deliberately NOT here: it is REQUIRED, per the evolution
+ * policy in `../types.ts`. It was optional for one release cycle and silently
+ * disabled reconnect on every backend that had not caught up.
+ */
+type OptionalRunStoreMethod = 'listByThread' | 'listReclaimable';
+/** Dotted `store.method` key a backend passes to declare an omitted method. */
+export type PersistenceConformanceMethodKey = `runs.${OptionalRunStoreMethod}`;
+export interface PersistenceConformanceOptions {
+    /**
+     * Store keys this backend intentionally does not provide. Any store that is
+     * absent from the persistence and NOT listed here fails the suite, so a
+     * dropped/misconfigured store can never pass silently.
+     */
+    skip?: Array<keyof AIPersistenceStores>;
+    /**
+     * OPTIONAL store methods this backend intentionally does not implement, as
+     * `'runs.listByThread'` and friends. A method that is absent and NOT listed
+     * here fails the suite; a listed one is reported as a skipped case.
+     */
+    skipMethods?: Array<PersistenceConformanceMethodKey>;
+}
+/**
+ * Register a Vitest suite that validates `makePersistence()` against the full
+ * `AIPersistence` contract — every store it provides, and none it declares
+ * skipped.
+ */
+export declare function runPersistenceConformance(name: string, makePersistence: MakePersistence, options?: PersistenceConformanceOptions): void;
+export {};