@tanstack/ai 0.19.1 → 0.20.1

package/dist/esm/utilities/chat-params.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  context: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: parsed.context,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools(\n  serverTools: ReadonlyArray<Tool>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool> = [...serverTools]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAIA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MASvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,EAAA,CACjB;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKa;AACb,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAsB,CAAC,GAAG,WAAW;AAC3C,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGT;AAAA,EACX;AACA,SAAO;AACT;"}
+{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  context: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: parsed.context,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools(\n  serverTools: ReadonlyArray<Tool>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool> = [...serverTools]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAIA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MASvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,EAAA,CACjB;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKa;AACb,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAsB,CAAC,GAAG,WAAW;AAC3C,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGT;AAAA,EACX;AACA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.19.1",
+  "version": "0.20.1",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@ag-ui/core": "^0.0.52",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.3.4"
+    "@tanstack/ai-event-client": "0.3.6"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/src/activities/chat/adapter.ts

@@ -55,6 +55,10 @@ export interface StructuredOutputResult<T = unknown> {
  * - TMessageMetadata: Metadata types for content parts (already resolved)
  * - TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`
  * - TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)
+ * - TSystemPromptMetadata: Provider-typed metadata accepted on each
+ *   `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to
+ *   `never` — adapters without per-prompt metadata reject the `metadata`
+ *   field at the call site.
  */
 export interface TextAdapter<
   TModel extends string,
@@ -63,6 +67,7 @@ export interface TextAdapter<
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
   TToolCallMetadata = unknown,
+  TSystemPromptMetadata = never,
 > {
   /** Discriminator for adapter kind */
   readonly kind: 'text'
@@ -80,6 +85,7 @@ export interface TextAdapter<
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
     toolCallMetadata: TToolCallMetadata
+    systemPromptMetadata: TSystemPromptMetadata
   }
 
   /**
@@ -123,7 +129,7 @@ export interface TextAdapter<
  * A TextAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any>
+export type AnyTextAdapter = TextAdapter<any, any, any, any, any, any, any>
 
 /**
  * Abstract base class for text adapters.
@@ -138,13 +144,15 @@ export abstract class BaseTextAdapter<
   TMessageMetadataByModality extends DefaultMessageMetadataByModality,
   TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>,
   TToolCallMetadata = unknown,
+  TSystemPromptMetadata = never,
 > implements TextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
   TMessageMetadataByModality,
   TToolCapabilities,
-  TToolCallMetadata
+  TToolCallMetadata,
+  TSystemPromptMetadata
 > {
   readonly kind = 'text' as const
   abstract readonly name: string
@@ -157,6 +165,7 @@ export abstract class BaseTextAdapter<
     messageMetadataByModality: TMessageMetadataByModality
     toolCapabilities: TToolCapabilities
     toolCallMetadata: TToolCallMetadata
+    systemPromptMetadata: TSystemPromptMetadata
   }
 
   protected config: TextAdapterConfig

package/src/activities/chat/index.ts

@@ -56,6 +56,7 @@ import type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
 } from './middleware/types'
+import type { SystemPrompt } from '../../system-prompts'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { ProviderTool } from '../../tools/provider-tool'
@@ -94,16 +95,28 @@ export interface TextActivityOptions<
    *
    * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages).
    */
-  messages?: Array<
-    | UIMessage
-    | ModelMessage
-    | ConstrainedModelMessage<{
-        inputModalities: TAdapter['~types']['inputModalities']
-        messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
-      }>
-  >
-  /** System prompts to prepend to the conversation */
-  systemPrompts?: TextOptions['systemPrompts']
+  messages?:
+    | Array<
+        | UIMessage
+        | ModelMessage
+        | ConstrainedModelMessage<{
+            inputModalities: TAdapter['~types']['inputModalities']
+            messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
+          }>
+      >
+    | undefined
+  /**
+   * System prompts to prepend to the conversation.
+   *
+   * Accepts plain strings or `{ content, metadata }` objects. The `metadata`
+   * field is typed by the adapter — Anthropic narrows it to
+   * `AnthropicSystemPromptMetadata` (with `cache_control` for prompt
+   * caching), providers without per-prompt metadata reject the field
+   * entirely.
+   */
+  systemPrompts?:
+    | Array<SystemPrompt<TAdapter['~types']['systemPromptMetadata']>>
+    | undefined
   /**
    * Tools for function calling (auto-executed when called).
    *
@@ -114,10 +127,12 @@ export interface TextActivityOptions<
    *    `supports.tools` list. Passing an unsupported tool produces a
    *    compile-time error on the array element.
    */
-  tools?: Array<
-    | (Tool & { readonly '~toolKind'?: never })
-    | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
-  >
+  tools?:
+    | Array<
+        | (Tool & { readonly '~toolKind'?: never })
+        | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
+      >
+    | undefined
   /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
   temperature?: TextOptions['temperature']
   /** Nucleus sampling parameter. The model considers tokens with topP probability mass. */
@@ -275,7 +290,7 @@ interface TextEngineConfig<
   TParams extends TextOptions<any, any> = TextOptions<any>,
 > {
   adapter: TAdapter
-  systemPrompts?: Array<string>
+  systemPrompts?: Array<SystemPrompt>
   params: TParams
   middleware?: Array<ChatMiddleware>
   context?: unknown
@@ -290,7 +305,7 @@ class TextEngine<
 > {
   private readonly adapter: TAdapter
   private params: TParams
-  private systemPrompts: Array<string>
+  private systemPrompts: Array<SystemPrompt>
   private tools: Array<Tool>
   private readonly loopStrategy: AgentLoopStrategy
   private toolCallManager: ToolCallManager
@@ -312,7 +327,7 @@ class TextEngine<
     []
   private currentThinkingContent = ''
   private currentThinkingSignature = ''
-  private eventOptions?: Record<string, unknown>
+  private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
   private earlyTermination = false
@@ -323,16 +338,16 @@ class TextEngine<
   private readonly initialClientToolResults: Map<string, any>
 
   // AG-UI protocol IDs
-  private threadId: string
-  private runIdOverride?: string
-  private parentRunIdOverride?: string
+  private readonly threadId: string
+  private readonly runIdOverride?: string
+  private readonly parentRunIdOverride?: string
 
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner
   private readonly middlewareCtx: ChatMiddlewareContext
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
-  private middlewareAbortController?: AbortController
+  private readonly middlewareAbortController?: AbortController
   private terminalHookCalled = false
 
   private readonly logger: InternalLogger
@@ -391,8 +406,11 @@ class TextEngine<
     // handleStreamChunk processes raw chunks BEFORE middleware, so internal
     // state management sees extended fields (finishReason, delta, toolCallName, etc.).
     // The strip middleware ensures the yielded public stream is AG-UI spec-compliant.
-    const allMiddleware = [
-      devtoolsMiddleware(),
+    // `devtoolsMiddleware()` returns a structurally compatible
+    // `DevtoolsChatMiddleware` (defined in `@tanstack/ai-event-client` to
+    // avoid a circular dep). Cast it to `ChatMiddleware` for the runner.
+    const allMiddleware: Array<ChatMiddleware> = [
+      devtoolsMiddleware() as ChatMiddleware,
       ...(config.middleware || []),
       stripToSpecMiddleware(),
     ]
@@ -692,6 +710,7 @@ class TextEngine<
   }
 
   private handleStreamChunk(chunk: StreamChunk): void {
+    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events.
     switch (chunk.type) {
       // AG-UI Events
       case 'TEXT_MESSAGE_CONTENT':
@@ -990,11 +1009,10 @@ class TextEngine<
       return true
     })
 
-    if (undiscoveredLazyResults.length > 0) {
-      const finishEvt = this.finishedEvent!
+    if (undiscoveredLazyResults.length > 0 && this.finishedEvent) {
       for (const chunk of this.buildToolResultChunks(
         undiscoveredLazyResults,
-        finishEvt,
+        this.finishedEvent,
       )) {
         yield* this.pipeThroughMiddleware(chunk)
       }
@@ -1691,8 +1709,9 @@ async function* runStreamingText(
 function runNonStreamingText(
   options: TextActivityOptions<AnyTextAdapter, undefined, false>,
 ): Promise<string> {
-  // Run the streaming text and collect all text using streamToText
+  // Run the streaming text and collect all text using streamToText.
   const stream = runStreamingText(
+    // eslint-disable-next-line no-restricted-syntax -- generic-stream remap: caller is non-streaming (false), but runStreamingText is invoked internally to collect text; concrete `false`→`true` literals don't structurally overlap.
     options as unknown as TextActivityOptions<AnyTextAdapter, undefined, true>,
   )
 

package/src/activities/chat/messages.ts

@@ -463,12 +463,13 @@ export function modelMessagesToUIMessages(
     if (msg.role === 'tool') {
       // Tool result - merge into the last assistant message if possible
       if (
+        msg.toolCallId !== undefined &&
         currentAssistantMessage &&
         currentAssistantMessage.role === 'assistant'
       ) {
         currentAssistantMessage.parts.push({
           type: 'tool-result',
-          toolCallId: msg.toolCallId!,
+          toolCallId: msg.toolCallId,
           content: getTextContent(msg.content),
           state: 'complete',
         })

package/src/activities/chat/middleware/types.ts

@@ -1,4 +1,5 @@
 import type { ModelMessage, StreamChunk, Tool, ToolCall } from '../../../types'
+import type { SystemPrompt } from '../../../system-prompts'
 
 // ===========================
 // Middleware Context
@@ -74,13 +75,13 @@ export interface ChatMiddlewareContext {
   // --- Config-derived info (may update per-iteration via onConfig) ---
 
   /** System prompts configured for this chat */
-  systemPrompts: Array<string>
+  systemPrompts: Array<SystemPrompt>
   /** Names of configured tools, if any */
   toolNames?: Array<string>
   /** Flattened generation options (temperature, topP, maxTokens, metadata) */
-  options?: Record<string, unknown>
+  options?: Record<string, unknown> | undefined
   /** Provider-specific model options */
-  modelOptions?: Record<string, unknown>
+  modelOptions?: Record<string, unknown> | undefined
 
   // --- Computed info ---
 
@@ -115,13 +116,13 @@ export interface ChatMiddlewareContext {
  */
 export interface ChatMiddlewareConfig {
   messages: Array<ModelMessage>
-  systemPrompts: Array<string>
+  systemPrompts: Array<SystemPrompt>
   tools: Array<Tool>
   temperature?: number
   topP?: number
   maxTokens?: number
-  metadata?: Record<string, unknown>
-  modelOptions?: Record<string, unknown>
+  metadata?: Record<string, unknown> | undefined
+  modelOptions?: Record<string, unknown> | undefined
 }
 
 // ===========================
@@ -256,11 +257,13 @@ export interface FinishInfo {
   /** Final accumulated text content */
   content: string
   /** Final usage totals, if available */
-  usage?: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
+  usage?:
+    | {
+        promptTokens: number
+        completionTokens: number
+        totalTokens: number
+      }
+    | undefined
 }
 
 /**

package/src/activities/chat/stream/processor.ts

@@ -133,25 +133,25 @@ export interface StreamProcessorOptions {
  * @see docs/chat-architecture.md#adapter-contract — What this class expects from adapters
  */
 export class StreamProcessor {
-  private chunkStrategy: ChunkStrategy
-  private events: StreamProcessorEvents
-  private jsonParser: { parse: (jsonString: string) => any }
+  private readonly chunkStrategy: ChunkStrategy
+  private readonly events: StreamProcessorEvents
+  private readonly jsonParser: { parse: (jsonString: string) => any }
   private recordingEnabled: boolean
 
   // Message state
   private messages: Array<UIMessage> = []
 
   // Per-message stream state
-  private messageStates: Map<string, MessageStreamState> = new Map()
-  private activeMessageIds: Set<string> = new Set()
-  private toolCallToMessage: Map<string, string> = new Map()
+  private readonly messageStates: Map<string, MessageStreamState> = new Map()
+  private readonly activeMessageIds: Set<string> = new Set()
+  private readonly toolCallToMessage: Map<string, string> = new Map()
   private pendingManualMessageId: string | null = null
   private pendingThinkingStepId: string | null = null
 
-  private structuredMessageIds: Set<string> = new Set()
+  private readonly structuredMessageIds: Set<string> = new Set()
 
   // Run tracking (for concurrent run safety)
-  private activeRuns = new Set<string>()
+  private readonly activeRuns = new Set<string>()
 
   // Shared stream state
   private finishReason: string | null = null
@@ -480,6 +480,7 @@ export class StreamProcessor {
     // Cast needed: @ag-ui/core Zod passthrough types add `& { [k: string]: unknown }`
     // which prevents TypeScript from narrowing the `type` discriminant in switch.
     const c = chunk as StreamChunk & { type: string }
+    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType enum members vs string-literal case labels; default branch handles untraced events.
     switch (c.type) {
       // AG-UI Events
       case 'TEXT_MESSAGE_START':
@@ -645,10 +646,9 @@ export class StreamProcessor {
    * Used as fallback for events that don't include a messageId.
    */
   private getActiveAssistantMessageId(): string | null {
-    // Set iteration is insertion-order; convert to array and search from the end
-    const ids = Array.from(this.activeMessageIds)
-    for (let i = ids.length - 1; i >= 0; i--) {
-      const id = ids[i]!
+    // Set iteration is insertion-order; reverse-iterate to search from the end
+    const ids = Array.from(this.activeMessageIds).reverse()
+    for (const id of ids) {
       const state = this.messageStates.get(id)
       if (state && state.role === 'assistant') {
         return id
@@ -679,8 +679,8 @@ export class StreamProcessor {
     // Try active assistant message
     const activeId = this.getActiveAssistantMessageId()
     if (activeId) {
-      const state = this.getMessageState(activeId)!
-      return { messageId: activeId, state }
+      const state = this.getMessageState(activeId)
+      if (state) return { messageId: activeId, state }
     }
 
     // Check if a message with preferredId already exists (reconnect/resume case).
@@ -781,10 +781,10 @@ export class StreamProcessor {
     const existingMsg = this.messages.find((m) => m.id === messageId)
     if (existingMsg) {
       this.activeMessageIds.add(messageId)
-      if (!this.messageStates.has(messageId)) {
+      const existingState = this.messageStates.get(messageId)
+      if (!existingState) {
         this.createMessageState(messageId, uiRole)
       } else {
-        const existingState = this.messageStates.get(messageId)!
         // If tool calls happened since last text, this TEXT_MESSAGE_START
         // signals a new text segment — reset segment accumulation
         if (existingState.hasToolCallsSinceTextStart) {
@@ -845,7 +845,7 @@ export class StreamProcessor {
   ): void {
     this.resetStreamState()
     // AG-UI Message[] is compatible with UIMessage[] at runtime
-    this.messages = [...chunk.messages] as unknown as Array<UIMessage>
+    this.messages = [...chunk.messages] as Array<UIMessage>
     this.emitMessagesChange()
   }
 
@@ -1365,7 +1365,7 @@ export class StreamProcessor {
       state.currentThinkingStepId = stepId
     }
 
-    const previous = state.thinkingSteps.get(stepId)!
+    const previous = state.thinkingSteps.get(stepId) ?? ''
     let nextThinking = previous
 
     // Prefer delta over content
@@ -1900,7 +1900,7 @@ export function createReplayStream(
   recording: ChunkRecording,
 ): AsyncIterable<StreamChunk> {
   return {
-    // eslint-disable-next-line @typescript-eslint/require-await
+    // eslint-disable-next-line @typescript-eslint/require-await -- async generator required by AsyncIterable contract; body has no await
     async *[Symbol.asyncIterator]() {
       for (const { chunk } of recording.chunks) {
         yield chunk

package/src/activities/chat/stream/strategies.ts

@@ -20,7 +20,7 @@ export class ImmediateStrategy implements ChunkStrategy {
  * Useful for natural text flow in UI
  */
 export class PunctuationStrategy implements ChunkStrategy {
-  private punctuation = /[.,!?;:\n]/
+  private readonly punctuation = /[.,!?;:\n]/
 
   shouldEmit(chunk: string, _accumulated: string): boolean {
     return this.punctuation.test(chunk)
@@ -34,7 +34,7 @@ export class PunctuationStrategy implements ChunkStrategy {
 export class BatchStrategy implements ChunkStrategy {
   private chunkCount = 0
 
-  constructor(private batchSize: number = 5) {}
+  constructor(private readonly batchSize: number = 5) {}
 
   shouldEmit(_chunk: string, _accumulated: string): boolean {
     this.chunkCount++
@@ -66,7 +66,7 @@ export class WordBoundaryStrategy implements ChunkStrategy {
  * Emits if ANY strategy says to emit
  */
 export class CompositeStrategy implements ChunkStrategy {
-  constructor(private strategies: Array<ChunkStrategy>) {}
+  constructor(private readonly strategies: Array<ChunkStrategy>) {}
 
   shouldEmit(chunk: string, accumulated: string): boolean {
     return this.strategies.some((s) => s.shouldEmit(chunk, accumulated))