@tanstack/ai 0.42.0 → 0.43.1

package/src/client.ts

@@ -1,3 +1,194 @@
+import type {
+  AudioGenerationOptions,
+  ImageGenerationOptions,
+  TTSOptions,
+  TranscriptionOptions,
+  VideoGenerationOptions,
+} from './types'
+
+export type GenerationKind =
+  | 'image'
+  | 'audio'
+  | 'tts'
+  | 'video'
+  | 'transcription'
+
+type GenerationInputByKind = {
+  image: Omit<ImageGenerationOptions, 'logger' | 'model'>
+  audio: Omit<AudioGenerationOptions, 'logger' | 'model'>
+  tts: Omit<TTSOptions, 'logger' | 'model'>
+  video: Omit<VideoGenerationOptions, 'logger' | 'model'>
+  transcription: Omit<TranscriptionOptions, 'logger' | 'model'>
+}
+
+export interface GenerationParams<TKind extends GenerationKind> {
+  input: GenerationInputByKind[TKind]
+  forwardedProps: Record<string, unknown>
+  threadId?: string
+  runId?: string
+}
+
+const generationKinds = [
+  'image',
+  'audio',
+  'tts',
+  'video',
+  'transcription',
+] as const satisfies ReadonlyArray<GenerationKind>
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwnKey(value: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function isGenerationEnvelope(body: unknown): body is Record<string, unknown> {
+  return (
+    isRecord(body) &&
+    (hasOwnKey(body, 'data') || hasOwnKey(body, 'forwardedProps'))
+  )
+}
+
+function assertGenerationKind(kind: unknown): asserts kind is GenerationKind {
+  if (!generationKinds.includes(kind as GenerationKind)) {
+    throw new Error(
+      `Unsupported generation kind: ${String(
+        kind,
+      )}. Expected one of ${generationKinds.join(', ')}.`,
+    )
+  }
+}
+
+function assertInputForKind(
+  kind: GenerationKind,
+  input: unknown,
+): asserts input is GenerationInputByKind[GenerationKind] {
+  if (!isRecord(input)) {
+    throw new Error(`Generation ${kind} input must be an object.`)
+  }
+
+  const requiredKey =
+    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
+
+  if (!hasOwnKey(input, requiredKey)) {
+    throw new Error(`Generation ${kind} input must include ${requiredKey}.`)
+  }
+}
+
+function isInputForKind(kind: GenerationKind, input: unknown): boolean {
+  if (!isRecord(input)) return false
+
+  const requiredKey =
+    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
+
+  return hasOwnKey(input, requiredKey)
+}
+
+function forwardedPropsFromEnvelope(
+  envelope: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!hasOwnKey(envelope, 'forwardedProps')) {
+    return {}
+  }
+
+  if (!isRecord(envelope.forwardedProps)) {
+    throw new Error('Generation envelope forwardedProps must be an object.')
+  }
+
+  return envelope.forwardedProps
+}
+
+function optionalStringField(
+  envelope: Record<string, unknown>,
+  key: 'threadId' | 'runId',
+): string | undefined {
+  if (!hasOwnKey(envelope, key)) {
+    return undefined
+  }
+
+  const value = envelope[key]
+  if (typeof value !== 'string') {
+    throw new Error(`Generation envelope ${key} must be a string.`)
+  }
+
+  return value
+}
+
+function generationIdentityFields(envelope: Record<string, unknown>): {
+  threadId?: string
+  runId?: string
+} {
+  const identity: {
+    threadId?: string
+    runId?: string
+  } = {}
+  const threadId = optionalStringField(envelope, 'threadId')
+  const runId = optionalStringField(envelope, 'runId')
+
+  if (threadId !== undefined) identity.threadId = threadId
+  if (runId !== undefined) identity.runId = runId
+
+  return identity
+}
+
+export function generationParamsFromBody<TKind extends GenerationKind>(
+  kind: TKind,
+  body: unknown,
+): GenerationParams<TKind> {
+  assertGenerationKind(kind)
+
+  if (isInputForKind(kind, body)) {
+    assertInputForKind(kind, body)
+    return {
+      input: body as GenerationInputByKind[TKind],
+      forwardedProps: {},
+    }
+  }
+
+  if (!isGenerationEnvelope(body)) {
+    assertInputForKind(kind, body)
+    return {
+      input: body as GenerationInputByKind[TKind],
+      forwardedProps: {},
+    }
+  }
+
+  if (!hasOwnKey(body, 'data')) {
+    throw new Error(`Generation ${kind} envelope must include data.`)
+  }
+
+  const input = body.data
+  assertInputForKind(kind, input)
+
+  const forwardedProps = forwardedPropsFromEnvelope(body)
+
+  return {
+    input: input as GenerationInputByKind[TKind],
+    forwardedProps,
+    ...generationIdentityFields(body),
+  }
+}
+
+export async function generationParamsFromRequest<TKind extends GenerationKind>(
+  kind: TKind,
+  request: Request,
+): Promise<GenerationParams<TKind>> {
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch (error) {
+    throw new Error('Invalid JSON request body.', { cause: error })
+  }
+
+  if (!isRecord(body)) {
+    throw new Error('Generation request body must be a JSON object.')
+  }
+
+  return generationParamsFromBody(kind, body)
+}
+
 export enum EventType {
   TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
   TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
@@ -41,15 +232,35 @@ export {
   type InferToolInput,
   type InferToolName,
   type InferToolOutput,
+  type ApprovalCapabilityOf,
+  type ApprovalSchemaConfig,
+  type ApprovalSchemaOf,
+  type InputSchemaOf,
+  type OutputSchemaOf,
+  type NoSchema,
   type ToolDefinition,
   type ToolDefinitionConfig,
   type ToolDefinitionInstance,
 } from './activities/chat/tools/tool-definition'
 
+export {
+  hashSchemaInput,
+  normalizeApprovalSchema,
+  type NormalizedApprovalSchema,
+  type NormalizedSchemaInput,
+} from './activities/chat/tools/approval-schema'
+
+export {
+  canonicalInterruptJson,
+  cloneAndDeepFreezeJson,
+  digestInterruptJson,
+} from './interrupt-serialization'
+
 export {
   convertSchemaToJsonSchema,
   isStandardSchema,
   parseWithStandardSchema,
+  validateWithStandardSchema,
 } from './activities/chat/tools/schema-converter'
 
 export {
@@ -103,8 +314,14 @@ export type {
   MediaPromptPart,
   MessagePart,
   ModelMessage,
+  PersistedArtifactActivity,
+  PersistedArtifactRef,
+  PersistedArtifactRole,
+  Interrupt,
+  RunAgentResumeItem,
   RunErrorEvent,
   RunFinishedEvent,
+  RunFinishedOutcome,
   SchemaInput,
   StreamChunk,
   StructuredOutputPart,
@@ -119,6 +336,33 @@ export type {
   InferSchemaType,
 } from './types'
 
+// Enumerated, not `export *` — see the matching note in `index.ts`. The
+// interrupt protocol surface is a commitment, so it is published field by
+// field.
+export {
+  INTERRUPT_BINDING_VERSION,
+  canonicalizeInterruptResolutions,
+} from './interrupts'
+export type {
+  BatchInterruptError,
+  BatchInterruptErrorCode,
+  InterruptBinding,
+  InterruptCorrelation,
+  InterruptSubmissionError,
+  ItemInterruptError,
+  ItemInterruptErrorCode,
+  ToolApprovalResolution,
+  UnopenedInterruptBinding,
+} from './interrupts'
+
+export {
+  INTERRUPT_BINDING_METADATA_KEY,
+  readInterruptBinding,
+  readUnopenedInterruptBinding,
+  withInterruptBinding,
+  withoutInterruptBinding,
+} from './interrupt-resume'
+
 export type {
   AudioVisualization,
   RealtimeAdapter,

package/src/custom-events.ts

@@ -0,0 +1,107 @@
+/**
+ * Catalog of well-known AG-UI `CUSTOM` event names used by the sandbox/agent
+ * layers, plus their payload shapes.
+ *
+ * The persisted run log is the AG-UI `StreamChunk` stream itself — there is no
+ * separate `RunEvent` type. Agent activity that has no first-class AG-UI event
+ * (process output, file diffs, ports, approvals, artifacts, sandbox lifecycle)
+ * rides on `CUSTOM` events carrying one of these names. Centralizing the names +
+ * payloads here keeps emitters (harness adapters, sandbox) and consumers
+ * (persistence projections, devtools, diff/terminal panels) in agreement without
+ * inventing a parallel event union.
+ */
+import { EventType } from './types'
+import type { CustomEvent, StreamChunk } from './types'
+
+/** Well-known CUSTOM event names. */
+export const CUSTOM_EVENT = {
+  FILE_CHANGED: 'file.changed',
+  PROCESS_STDOUT: 'process.stdout',
+  PROCESS_STDERR: 'process.stderr',
+  PORT_OPENED: 'port.opened',
+  APPROVAL_REQUESTED: 'approval.requested',
+  APPROVAL_RESOLVED: 'approval.resolved',
+  ARTIFACT_CREATED: 'artifact.created',
+  SANDBOX_CREATED: 'sandbox.created',
+  SANDBOX_RESUMED: 'sandbox.resumed',
+} as const
+
+/** Union of the well-known CUSTOM event name literals. */
+export type WellKnownCustomEventName =
+  (typeof CUSTOM_EVENT)[keyof typeof CUSTOM_EVENT]
+
+// ---- Payload shapes ----
+
+export interface FileChangedPayload {
+  type: 'create' | 'change' | 'delete'
+  /** Absolute path inside the sandbox (under the workspace root). */
+  path: string
+  /** Unified diff, when the harness can produce one. */
+  diff?: string
+  timestamp: number
+}
+
+export interface ProcessOutputPayload {
+  /** Stable id for the spawned process whose output this is. */
+  processId: string
+  /** A chunk of stdout/stderr text. */
+  chunk: string
+}
+
+export interface PortOpenedPayload {
+  port: number
+  /** Externally reachable URL, when the provider exposes one. */
+  url?: string
+}
+
+export interface ApprovalRequestedPayload {
+  approvalId: string
+  title: string
+  /** Free-form detail describing the action awaiting approval. */
+  [key: string]: unknown
+}
+
+export interface ApprovalResolvedPayload {
+  approvalId: string
+  granted: boolean
+}
+
+export interface ArtifactCreatedPayload {
+  artifactId: string
+  name: string
+  mimeType: string
+  size: number
+}
+
+export interface SandboxLifecyclePayload {
+  sandboxId: string
+  provider: string
+}
+
+/** Maps each well-known name to its payload type. */
+export interface CustomEventPayloads {
+  [CUSTOM_EVENT.FILE_CHANGED]: FileChangedPayload
+  [CUSTOM_EVENT.PROCESS_STDOUT]: ProcessOutputPayload
+  [CUSTOM_EVENT.PROCESS_STDERR]: ProcessOutputPayload
+  [CUSTOM_EVENT.PORT_OPENED]: PortOpenedPayload
+  [CUSTOM_EVENT.APPROVAL_REQUESTED]: ApprovalRequestedPayload
+  [CUSTOM_EVENT.APPROVAL_RESOLVED]: ApprovalResolvedPayload
+  [CUSTOM_EVENT.ARTIFACT_CREATED]: ArtifactCreatedPayload
+  [CUSTOM_EVENT.SANDBOX_CREATED]: SandboxLifecyclePayload
+  [CUSTOM_EVENT.SANDBOX_RESUMED]: SandboxLifecyclePayload
+}
+
+/** A CUSTOM event narrowed to a specific well-known name and its payload. */
+export type WellKnownCustomEvent<TName extends WellKnownCustomEventName> =
+  CustomEvent & { name: TName; value: CustomEventPayloads[TName] }
+
+/**
+ * Type guard: is `chunk` a CUSTOM event with the given well-known `name`?
+ * Narrows the payload type when true, so consumers read `chunk.value` typed.
+ */
+export function isCustomEvent<TName extends WellKnownCustomEventName>(
+  chunk: StreamChunk,
+  name: TName,
+): chunk is WellKnownCustomEvent<TName> {
+  return chunk.type === EventType.CUSTOM && chunk.name === name
+}

package/src/delivery-detach.ts

@@ -0,0 +1,72 @@
+/**
+ * The one-way channel from a chat run to the durable DELIVERY sink that is
+ * persisting it.
+ *
+ * The sink (`durableStreamSource` in `./stream-to-response.ts`) has to answer one
+ * question on the abort path: was this disconnect a DETACH — the agent keeps
+ * running and a later attach will continue the log — or the end of the run? Only
+ * the run's own middleware can answer it (`withSandbox`'s `onAbort` resolves both
+ * out-of-band cancel bands and `detachOnDisconnect`), and the sink cannot reach
+ * the middleware capability bus: it lives one layer up, in the transport, and is
+ * handed nothing but the stream and a durability adapter.
+ *
+ * So the fact travels on the STREAM ITSELF, keyed by the exact object `chat()`
+ * returned. That is the seam an application cannot forget to wire: passing the
+ * stream to `toServerSentEventsResponse(stream, { durability })` is already
+ * mandatory, and it is the same object both sides hold. The alternative — a
+ * `detachable` flag on the response options — has to be re-wired correctly at
+ * every durable call site, and a forgotten one silently terminalizes a healthy
+ * detached run's log, which is the exact defect this channel exists to fix.
+ *
+ * The value is a THUNK, not a boolean: the verdict is only known during the run's
+ * teardown, long after the response object was built.
+ */
+
+/**
+ * Per-stream detach predicates. Keyed weakly by the stream object, so a stream
+ * that is dropped without ever being consumed takes its entry with it.
+ */
+const detachSignals = new WeakMap<object, () => boolean>()
+
+/**
+ * Publish `stream`'s detach predicate. Called by `chat()` on the object it hands
+ * back, once per stream.
+ *
+ * Wired on BOTH streaming paths — `runStreamingText` and
+ * `runStreamingStructuredOutput` — since either can be handed to a durable
+ * transport helper. The non-streaming paths (`stream: false`, and the
+ * `Promise<T>` structured-output variant) resolve a value rather than yielding a
+ * stream, so there is no delivery sink to inform and nothing to publish.
+ *
+ * @internal
+ */
+export function publishRunDetachedSignal(
+  stream: object,
+  wasDetached: () => boolean,
+): void {
+  detachSignals.set(stream, wasDetached)
+}
+
+/**
+ * Whether the run behind `stream` declared its abort a detach.
+ *
+ * `false` for anything that never published a predicate — a hand-rolled
+ * iterable, a `chat()` from an older build, a non-object source — so an unknown
+ * stream keeps the terminalize-and-close behavior rather than being spared it.
+ *
+ * A throwing predicate is also `false`, for the same reason: this is consulted on
+ * a teardown path where the only safe default is to terminalize. Leaving a log
+ * open because a probe threw would park every tailer forever.
+ *
+ * @internal
+ */
+export function wasRunDetached(stream: unknown): boolean {
+  if (typeof stream !== 'object' || stream === null) return false
+  const signal = detachSignals.get(stream)
+  if (signal === undefined) return false
+  try {
+    return signal()
+  } catch {
+    return false
+  }
+}

package/src/delivery-disconnect.ts

@@ -0,0 +1,84 @@
+/**
+ * The one-way channel from the durable DELIVERY sink back to the chat run: "your
+ * viewer is gone, but you are not."
+ *
+ * This is the MIRROR of `./delivery-detach.ts`. That module answers a question the
+ * sink asks the run (was this abort a detach?); this one delivers a fact the sink
+ * learns first and the run cannot observe at all — the response body was
+ * cancelled. Both are keyed weakly by the exact stream object `chat()` returned,
+ * for the same reason: passing that object to
+ * `toServerSentEventsResponse(stream, { durability })` is already mandatory, so it
+ * is the one seam an application cannot forget to wire.
+ *
+ * WHY THE RUN CANNOT JUST WATCH AN ABORT SIGNAL. Before this channel existed, the
+ * only way a disconnect reached a run's middleware was for the application to
+ * mirror `request.signal` into `chat()`'s `abortController` — which ABORTS THE RUN.
+ * For a durable run that is precisely wrong, and wrong in the most expensive
+ * direction: `chat()` returns at its `isCancelled()` check immediately after
+ * middleware setup, so the harness adapter's `chatStream` is never called and the
+ * agent in the freshly-created sandbox is NEVER LAUNCHED. The user re-attaches to
+ * an empty log belonging to a run that did nothing, and no takeover can recover it
+ * because there is no journal to replay. The application was forced to choose
+ * between "the middleware learns about the disconnect" and "the run survives it".
+ *
+ * So the disconnect travels as a NOTIFICATION rather than a cancellation. The run
+ * hands it to whatever subscribed through `RunDisconnectCapability` — bookkeeping
+ * only, no teardown — and keeps producing into its still-open durable log, which
+ * is exactly what a re-attaching client tails to catch up.
+ *
+ * DISPATCHED FROM THE TRANSPORT, NOT FROM THE RUN'S UNWINDING. That is what makes
+ * it prompt. A run suspended inside a minutes-wide `setup` (cloning a repo into a
+ * sandbox) cannot dispatch anything from its own `finally`, because the `finally`
+ * is reached only once the generator unwinds — which is what made `detachedSince`
+ * land three minutes late instead of immediately.
+ */
+
+/**
+ * Per-stream disconnect handlers. Keyed weakly by the stream object, so a stream
+ * dropped without ever being consumed takes its entry with it.
+ */
+const disconnectHandlers = new WeakMap<object, () => void>()
+
+/**
+ * Publish `stream`'s disconnect handler. Called by `chat()` on the object it hands
+ * back, once per stream.
+ *
+ * Wired on BOTH streaming paths — `runStreamingText` and
+ * `runStreamingStructuredOutput` — since either can be handed to a durable
+ * transport helper, matching `publishRunDetachedSignal`.
+ *
+ * @internal
+ */
+export function publishRunDisconnectHandler(
+  stream: object,
+  onDisconnect: () => void,
+): void {
+  disconnectHandlers.set(stream, onDisconnect)
+}
+
+/**
+ * Tell the run behind `stream` that its delivery socket closed.
+ *
+ * A NO-OP for anything that never published a handler — a hand-rolled iterable, a
+ * `chat()` from an older build, a non-object source — so an unknown stream simply
+ * keeps today's behavior.
+ *
+ * NEVER THROWS and never returns a promise to await. This is called from
+ * `ReadableStream.cancel()`, whose rejection would surface as an unhandled error
+ * on a path where the consumer has already gone away; and the handler's own work
+ * is tracked by the run (which awaits it before finishing), not by this call. A
+ * throwing handler is swallowed for the same reason `wasRunDetached` swallows: the
+ * disconnect path has no second channel to report on.
+ *
+ * @internal
+ */
+export function notifyRunDisconnected(stream: unknown): void {
+  if (typeof stream !== 'object' || stream === null) return
+  const handler = disconnectHandlers.get(stream)
+  if (handler === undefined) return
+  try {
+    handler()
+  } catch {
+    // Intentionally empty: see above.
+  }
+}