@tanstack/ai-persistence@1.0.0

Major Changes

• #1840 f1b3f65 - TanStack AI 1.0.0. This release removes every API that was deprecated in 0.x. Read the upgrade guide before you upgrade: https://tanstack.com/ai/latest/docs/migration/v1
  • Removed all @deprecated exports, options, fields, and type aliases. Each one has a replacement that already shipped in 0.x.
  • Removed addToolApprovalResponse() from ChatClient and every chat hook. Resolve the bound tool-approval interrupt with resolveInterrupt instead. The devtools event tools:approval:responded is also removed.
  • Removed the old wire formats: the CUSTOM approval-requested and tool-input-available events, the [DONE] SSE line, the data copy of forwardedProps, pre-binding interrupt descriptors and their approval_required and client_tool_input reasons, and the STEP events that adapters sent next to REASONING_* events. Use a 1.0 client with a 1.0 server.
  • Removed the toolName alias from TOOL_CALL_START chunks. Read toolCallName instead.
  • threadId is now required on useChat and every other chat hook, ChatClient, the generation hooks and clients, chat(), summarize(), the generation functions, codeModeWithSnippets(), selectRelevantSnippets(), CompactionContext, and SummarizeInput. TanStack AI no longer makes a thread id for you. Pass a stable id for each conversation. createChatHook factory options no longer take threadId: pass it on each hook call. Octane generation hooks take threadId instead of id. @tanstack/ai-sandbox removes resolveDurableThreadId and DurableThreadIdRequiredError.
  • The published @tanstack/ai-octane/ui types are now strict. UI.Messages, UI.Message, UI.Part, and UI.Interrupts type their render children. ToolProps types part.input and part.output for the named tool. toolsComponents and interruptsComponents are required when the chat options declare tools or named interrupts. Code that relied on the old loose types can fail to compile.
  • A connection adapter's connect() and send() need the run context (with threadId) as their fourth argument. ChatClient and the generation clients pass it.
  • @tanstack/ai-sandbox: createToolBridgeCore(), startHostToolBridge(), a ToolBridgeProvisioner, and executeHostTool() take a required threadId. Bridged tools get it in their context.
  • @tanstack/ai-sandbox: the harness tool bridge and executeHostTool() refuse a tool with needsApproval. Before, the tool ran with no approval. Remove needsApproval, or run the tool with an HTTP adapter.
  • stream() and rpcStream() pass the AG-UI RunAgentInput for the run as the fourth factory argument, the same body the HTTP adapters send. Read it on the server with chatParamsFromRequestBody() or generationParamsFromBody(), so threadId, runId, and interrupt resume reach a server function. RunAgentInput is exported from @tanstack/ai/client.
  • A generation fetcher gets threadId and runId in its second argument, next to signal and headers. Pass them to the server generation call.
  • generationParamsFromBody() and generationParamsFromRequest() read the generation input from forwardedProps. A server that reads body.data gets undefined. Read body.forwardedProps instead. They also require threadId and runId and return them as strings, the same as chatParamsFromRequestBody() and the AG-UI RunAgentInput. A body that holds only the input is rejected.
  • Removed the readers for data saved in old 0.x formats (old Cloudflare run-log records, a bare UIMessage[] from client persistence, artifact records without blobKey).
  • Removed provider models that are shut down.
  • @tanstack/ai-react-ui, @tanstack/ai-solid-ui, and @tanstack/ai-vue-ui get no 1.0 release. Import from @tanstack/ai-react/ui, @tanstack/ai-solid/ui, or @tanstack/ai-vue/ui.

Minor Changes

• #1755 39c1c79 - Add opt-in session stores. The chat and generation middleware work as before without them.

  • log (LogStore): an append-only log for each session tree, with 15 methods, each with one object argument. Records: append, read, and subscribe. Ownership: acquireOwnership, renewOwnership, releaseOwnership, pinToWorkers, markHostAlive, and listLogsWithoutOwner. A pin (pinToWorkers) counts only while its host is alive: acquireOwnership and listLogsWithoutOwner ignore the affinity of a host with no live heartbeat({ hostId, ttlMs }), so the logs of a host that stopped go to other hosts. A host that is alive keeps its pins, also on the logs that it released. The input lane: offerInput and listOfferedInputs, consumed in the same write with append({ consumes }). The owner or the first offer names the harness of a log for listLogsWithoutOwner: a later offer does not change it. Snapshots and lifecycle: getSnapshot, putSnapshot, truncate, and deleteLog. acquireOwnership returns expired: true when it takes the log from another owner whose ownership expired with no release. Each fenced write carries the epoch from acquireOwnership, and a write with an old epoch rejects with OwnershipLostError. A writer that never calls acquireOwnership appends with NO_OWNER_EPOCH. pinToWorkers, putSnapshot, and truncate need the owner, so they refuse NO_OWNER_EPOCH. After deleteLog, every fenced write fails until the next acquireOwnership, and offerInput returns the new OfferResult 'deleted' and stores nothing, so a late write or input cannot bring a deleted log back. append rejects with LogConflictError when another writer took the position, and read rejects with LogTruncatedError before the truncation point. memoryLogStore() is the reference store. memoryLogStore({ state }) with one memoryLogState() lets two store instances share one log. The conformance kit needs twin, a second store set with a new log store instance on the same backend, for the log cases across instances.
  • sessions (SessionIndexStore): one index entry per tenant and thread. The key is { tenantId?, threadId } (SessionIndexKey), so one thread id in two tenants is two entries. An entry has members (SessionMember, with the role owner, member, viewer, or operator). The owner is the member with the role owner. The store has get(key), getVersioned(key), upsert(entry), upsertIf({ entry, revision }) for compare-and-set writes, list, and delete(key), a hard delete. list reads one tenant, filters by member, parent thread, title search, harness name, and exact metadata values, and pages with a cursor.

  defineLogStore and defineSessionIndexStore type an adapter. memoryPersistence() now also has log and sessions. runPersistenceConformance runs the cases of each session store when the store is present, so an existing backend needs no skip entry.

  With stores.sessions, withPersistence writes one index entry for each subagent child (subagent:<runId>), in the tenant of its tenantId option. The entry has the parent thread, the tool call, and the harness name of the parent entry. It has no members: access to a child goes through its top-level thread.

  loadChildTranscript(messages, subagentRunId, threadId) reads the stored messages of a child agent run for a UI. It returns undefined for a child of another thread.

• #1883 39abb7e - Core support for the harness: subagent binding options, the onGuardToolCall hook, server-side BYOK keys, harness tool runs, checked streamed outputSchema results, and resume fixes.

  Add the harness asks from the fifth findings list.

  • chat({ outputSchema, stream: true }) now checks the full result against a Standard Schema. A failure ends with RUN_ERROR structured-output-validation-failed, with the model text in metadata.tanstack.rawText.
  • session.send(prompt, { outputSchema }) gives the turn a typed structured value. It is per send only, and the HTTP handler does not take it.
  • A server tool reads run capabilities with context.get(capability) and context.getOptional(capability), for example the sandbox under withSandbox.
  • Readers keep the full history after a durable compaction. session.transcript(), GET transcript, and the chat hydration show every message. The model still gets the compacted context.
  • createHarnessHost({ acceptInput }) sees each input after the access check and before the log keeps it. It can change the input or refuse it.
  • A plugin adapter() pick with override: true wins over the stored thread model.
  • onModelError can return { retry: true, adapter } to retry on another model. ModelErrorContext has adapter and model.
  • Middleware reads ctx.context.run.source and label to tell a turn call from a plugin, router, or transfer call.
  • host.sessions.archive() and unarchive(). Lists hide archived threads unless you pass withArchived: true.
  • host.sessions.eraseUser({ harness, threadId, userId, replies }) replaces one person's messages with [removed], deletes their media, and cuts the log before a new snapshot. The new erase access action guards it.
  • HarnessRecord is exported, for a typed LogStore wrapper.
  • Coding-tool file calls pass their abort signal through WorkspaceBackend to the sandbox.
  • withCompaction limits (maxTokens, contextWindow, background.atTokens) can be a function of { model }.

  Run a harness tool with no model turn, add host records from a client, and add a per-run system preamble.

  • session.runTool({ name, args?, meta?, inputId?, user? }) runs one harness tool with no model
    turn, for example from a schedule or a webhook. The call goes through the
    same middleware, input check, and permissions() rules as a model call, and
    the call and its result join the transcript. A tool that asks for approval
    stops the turn with an interrupt. While interrupts wait, the call is refused
    with pending_interrupts. meta is echoed as a tanstack.injection custom
    event. args is typed from the input schema of a harness tool.
  • expose.tools lists the harness tools a client may run with a
    { op: 'tool', name, args?, meta? } input, or with the new
    client.runTool({ name, args?, meta?, inputId? }). The list is typed from the harness
    tools, and defineHarness throws for a name that is not in tools. Any
    other tool is refused with not_exposed. The capabilities document marks
    each tool with exposed.
  • expose.records lists the host record types a client may add with an
    { op: 'append', records } input, or with the new client.appendRecords({ records }).
    A record of another type, or with a thread field, is refused with
    not_exposed. The session log keeps the records.
  • createHarnessMcpServer adds a tool_<name> tool for each tool in
    expose.tools, and an append tool when expose.records has types. A tool
    input with its own threadId field throws when the server is created,
    because MCP uses threadId to pick the thread.
  • session.send(message, { systemPreamble }) prepends per-run, server-only
    system prompts ahead of the harness's own system prompts (for example
    host-provided memory). A client input cannot set them.
  • A tool call in a harness turn gets threadId and runId in its execution
    context. ToolExecutionContext in @tanstack/ai has the two new optional
    fields for a host to set.

  A host can add fields to the ctx an agent's run gets.

  • subagents.binding.extend(ctx) returns the fields to add. A child's ctx.chat({ subagents }) passes it down, so the fields reach nested children too.
  • SubagentContextExtension is an empty interface that SubagentRunContext includes. A package augments it to type its fields, for example ctx.harness from @tanstack/ai-harness. Make each field optional, because a run that a plain chat() starts has no host.

  Add interrupts to SubagentBinding.

  • A host sets binding.interrupts to give interrupt definitions to every ctx.chat call of an agent run. Then the host middleware in chatMiddleware can stop the child with these interrupts.
  • The own interrupts of the call win. When a host definition has the same id as one of the call, the host definition is not added.
  • A child's ctx.chat({ subagents }) passes the definitions on to its own children.
  • A plain chat() call does not get them.

  Add lastChatMiddleware to SubagentBinding. It runs after the own middleware of each ctx.chat call of an agent run, so it sees the final model context and tool results. A child's ctx.chat({ subagents }) passes it on, after the child's own.

  Add validateJsonSchema(schema, value). It checks a value against a JSON Schema with @cfworker/json-schema, as a tool input is checked, but with no repair. The result has the Standard Schema shape: { value } or { issues }. The root also exports the StandardSchemaV1 and StandardJSONSchemaV1 types.

  An agent run that throws the shape of MCPInputRequiredError (name, kind, request) stops the child as suspended, as a tool does, and the parent run stops with its interrupt. The interrupt has a generic binding and no tool call. Its id is the interruptId of the thrown value, else mcp_input_<subagentRunId>, and its message is the error message. The resume runs the child again, and ctx.resume has the answer.

  Add SubagentBinding.debug, the debug option for the model calls of child agents that set no debug of their own.

  Add the onGuardToolCall middleware hook for checks that must always run, such as permissions.

  • It runs for every tool call, after all onBeforeToolCall hooks and after the inputSchema check. hookCtx.args holds the final checked arguments that the tool gets.
  • The guard of every middleware runs, in order, until one returns a decision. An earlier onBeforeToolCall decision does not skip it.
  • Return { type: 'skip', result } to deny the call. The tool does not run, and the model gets result, the same as an onBeforeToolCall skip. Return { type: 'abort', reason } to abort the run.
  • It runs before a server tool runs and before a client tool goes to the client. A guard cannot change the arguments.
  • The new GuardToolCallDecision type is exported.

  BYOK keys can now live on the server. @tanstack/ai/byok exports the CredentialStore contract, the Credential and CredentialScope types, and defineCredentialStore. A CredentialScope has tenantId and userId. Its threadId is optional, and a store ignores it. @tanstack/ai/byok/server adds:

  • storedProviderKeys(store, scope): provider keys from the api_key credentials of a user, then of the tenant, then the provider's env names. Pass keys.adapter(...) to chat() and keys.get to subagents.keys.
  • readCredential(store, scope, id): one credential, the user's own first, then the tenant's. A user with no tenant reads only their own.
  • tenantScopeOf(scope): the tenant scope of a user scope, or undefined when the scope has no user or no tenant.
  • memoryCredentialStore(): a store in memory, for development and tests.
  • envKeyEntry(provider): the first provider.env name that is set, with its value.
  • readCredentialEntry(store, scope, id): reads a credential like readCredential. It also tells you which scope had the credential (the user or the tenant), and gives its revision when the store has getVersioned.

  CredentialStore has two optional methods for compare-and-set writes, getVersioned and setIf, with the same shape as the pair on MetadataStore. A store without them still works. memoryCredentialStore has both.

  Keep the store in your own database or in a secrets manager, and encrypt the secrets at rest. An oauth credential can keep the OAuth client it was issued to. list never returns secret values.

  scrubSecrets from @tanstack/ai/byok now also removes the JSON-escaped and URL-encoded forms of each secret. It skips a secret that is shorter than 6 characters, so a short value does not remove common words.

  Credential has a new type, secret_answer ({ value, expiresAt }). The harness keeps a secret answer to a question there for a short time and deletes it once read. Leave this type out of a list of connected accounts. memoryCredentialStore().list returns its expiresAt.

  Approved edits to tool arguments stay raw until the final input check.

  • @tanstack/ai: a resume no longer rejects approved editedArgs that do not fit the tool's inputSchema. The edit goes through onBeforeToolCall and the final input check, like the model's arguments. If it still does not fit, the approval is used, the tool does not run, and the model gets the input error as the tool result. The transcript keeps the approved edit as it was sent, but only when the call passed the check.
  • @tanstack/ai-persistence: withPersistence binds the client-tool phase of an approved tool call to its approval. After a restart, the client result resumes with the approval that came before it, and a stale or missing approval fails the resume.

  A nested subagent that waits on an interrupt now continues after the resume under withPersistence. Before, it ran again from its prompt. Core rebuilds the card of the nested child from the store and takes only its id from the client card. LoadChild takes an optional parentSubagentRunId, and returns interruptIds and parentToolCallId.

  chat() asks the middleware onShouldContinue after it runs the pending tool calls of a resume, before the next model call. A middleware that returns false there ends the run with no more model calls. The loop strategy is not asked at that point.

  WebSocketLike has an optional bufferedAmount. A server can read it to stop sending to a slow socket. A socket without it works as before.

Patch Changes

• #1847 d3b4cd4 - Report the conformance cases of an omitted generationRuns, artifacts, or blobs store as skipped. These cases reported a pass when the store was declared in skip.

• #1755 39c1c79 - Fix recovery, cancel, steer, and provider bugs, and fill small harness gaps.

  • Recovery: a resolve that another host recovers runs its continuation. Before, it settled completed with no answer.
  • Approvals: a tool that a middleware adds in onConfig can now be approved. chat() checks a durable resume after the whole onConfig chain.
  • Cancel: a cancelled turn keeps the text it streamed, and ends with TEXT_MESSAGE_END and RUN_FINISHED (outcome: cancelled). A turn that times out ends with RUN_ERROR (code: 'timeout').
  • Steer: a steer from another sender gets a queued receipt with its own operation. host.events() shows idle after a turn that a steer joined.
  • The duplicate-input check no longer depends on the key order of the stored input.
  • TurnInfo has model, attempt, and sender. The log keeps the sender's name. harness.input.accepted carries the message. The chat hydration has pendingWaits. ObservedSession.settled() reads a settlement with no open session. Another host's snapshot().plugins shows the saved plugin state.
  • New options: subagents.background: false, media.urlTtlMs, conversationSummarizer({ middleware }), and the beforeWrite workspace hook, which can refuse a write.
  • Plugin model calls (ctx.model.chat) run the harness middleware.
  • Exports: SHUTDOWN_REASON, BUDGET_REASON, and RUN_CANCEL_REASON from @tanstack/ai-harness, HARNESS_EVENTS from @tanstack/ai-harness/client, and ChatHydrateOptions and ChatHydrationResult from @tanstack/ai-client.
  • Compaction drops a background summary that another model prepared.
  • Sandbox file calls take an optional { signal }.
  • Anthropic: outputSchema moves keywords that Anthropic rejects into description, usage reports 1-hour cache writes as cacheWrite1hTokens again, and reasoning on a model with no reasoning entry warns once.
  • OpenAI Responses: a message whose model call sent a reasoning item is marked with metadata.tanstack.reasoningItem. A replay of that message without its reasoning item no longer sends its msg_ and fc_ ids.
  • Cloudflare: a data: line with no choices no longer throws, and the SSE fix-up accepts data: with no space, CRLF line ends, and any case in the content type.
  • Structured output: a schema failure carries rawText, and a parse failure has the code structured-output-parse-failed.
  • ChatClient.addToolResult answers the interrupt when the tool's schemas differ, so the result is sent.
  • The persistence conformance suite no longer fails a correct store on a slow runner.

• #1875 f6a27bc - withPersistence now saves activity rows when a run is stopped or fails, so reconstructChat restores them after a reload. A plain disconnect on a detachable or interrupted run still writes nothing.

• #1805 7a0a48b - Middleware can read ctx.callMetadata, the metadata.tanstack of the current model call. Each assistant message of the call gets a copy of it.

  With snapshotStreaming, withPersistence now stores ctx.callMetadata on snapshot rows, so a stopped or failed row has the same metadata as a finished one. A stopped or failed row no longer stores other chunk metadata, such as the durability batch hint of ctx.emitCustomEvent(name, value, { batch: true }).

• #1806 468063c - Fix withPersistence failing to resume an interrupt of a subagent tool call with Tool <name> is unavailable for interrupt <id>. The parent run now leaves interrupts its child answers to the child, using the new ctx.childResumeIds on the middleware context, and still commits them once the run succeeds.

  With withPersistence, the resume of a child is server-authoritative:

  • The stored interrupt records decide which interrupts a child owns. A resume whose subagent cards claim other interrupts fails with InterruptResumeValidationError.
  • The child resumes from its stored messages, not from the card the client sent back. LoadChild results get an optional pending field for this. A middleware that provides loadChild must set pending for a waiting child, or the agent tool does not resume it.

• #1755 39c1c79 - Keep the answer of a routed agent in its own message when the turn resumes after an interrupt and a finished tool call (for example a handoff) comes before that answer. Before, the stored answer moved onto the message of the tool call.

• #1755 39c1c79 - withPersistence lets a subagent that a tool call started check the answers to its own interrupts. The parent run does not check them against its own tools and batch, so a child client tool, and two children that wait at once, resume.

• Updated dependencies [fcbd199, 39c1c79, 959f43e, 39c1c79, fa2a291, f7e7cce, 7a0a48b, 468063c, fe83aa0, 781a3a8, 39abb7e, f1b3f65]:

  • @tanstack/ai@1.0.0
  • @tanstack/ai-utils@1.0.0