@tanstack-ai-browser/apfel 0.1.0 → 0.2.0

package/src/adapter.ts

@@ -1,868 +1,106 @@
 /**
  * A TanStack AI text adapter for Apple's on-device Foundation Model, served
- * by apfel's OpenAI-compatible server on the user's Mac. No backend
- * involved: the browser streams straight from it. Hand it to `chat()`
- * like any hosted model's adapter: `chat()` runs tools and the agent loop,
- * and each `chatStream` call here is one completion from apfel, streamed
- * back as AG-UI events.
+ * by apfel. apfel speaks OpenAI's Chat Completions API, so this is TanStack's
+ * OpenAI-compatible adapter pointed at it: tool calls and structured output
+ * go to apfel as `tools` and `response_format`, image parts as `image_url`
+ * parts, and `modelOptions` as given. It adds `availability()` and
+ * `create()`, which ask apfel whether it serves the model.
  */
-import { buildBaseUsage, EventType, normalizeSystemPrompts } from "@tanstack/ai"
-import type {
-  AdapterYieldChunk,
-  ModelMessage,
-  TextOptions,
-  TokenUsage,
-  Tool
-} from "@tanstack/ai"
-import { BaseTextAdapter } from "@tanstack/ai/adapters"
-import type {
-  StructuredOutputOptions,
-  StructuredOutputResult
-} from "@tanstack/ai/adapters"
+import { openaiCompatibleText } from "@tanstack/ai-openai/compatible"
+import type { OpenAICompatibleChatAdapter } from "@tanstack/ai-openai/compatible"
 
-import {
-  JSON_TOOL_CALLS_MARKER,
-  createToolCallSplitter,
-  parseJsonToolCalls
-} from "./tool-calls.js"
-import { matchToolName, repairToolArguments } from "./tool-repair.js"
-import type { GuidedRequest } from "./tool-repair.js"
+import { APFEL_MODEL_META } from "./model-meta.js"
+import type { ApfelChatModel } from "./model-meta.js"
 
-/** Where apfel's server listens by default. */
-export const APFEL_BASE_URL = "http://127.0.0.1:11434/v1"
-
-/** The models apfel serves: Apple's on-device Foundation Model. */
-export const APFEL_TEXT_MODELS = ["apple-foundationmodel"] as const
-
-/** A model apfel serves. */
-export type ApfelTextModel = (typeof APFEL_TEXT_MODELS)[number] | (string & {})
-
-export type ApfelTextConfig = {
-  /** apfel's OpenAI-compatible API, up to `/v1`. `APFEL_BASE_URL` by default. */
+export type ApfelConfig = {
+  /** apfel's OpenAI-compatible API, up to `/v1`. `http://127.0.0.1:11434/v1` by default. */
   baseURL?: string
   /** Headers sent with every request, such as apfel's bearer token. */
   defaultHeaders?: Record<string, string>
 }
 
-/**
- * Timings of one model call, in milliseconds, in `RUN_FINISHED`'s
- * `usage.providerUsageDetails`. The adapter measures them as the stream
- * arrives; apfel itself reports token counts only.
- */
-export type ApfelProviderUsageDetails = {
-  /** From sending the request to the first generated text. */
-  firstTokenMs?: number
-  /** From the first generated text to the last. */
-  decodeMs?: number
-  /**
-   * Tokens generated after the first chunk, estimated: apfel streams a few
-   * tokens per chunk, and the first chunk's share of the characters stands
-   * in for its share of the tokens.
-   */
-  decodeTokens?: number
-  /**
-   * Time spent rewriting the tool calls' arguments under their schemas,
-   * after the reply ended (see the README's "Tool calls").
-   */
-  toolRepairMs?: number
-}
-
-/**
- * Request fields apfel takes for Apple's model. apfel rejects parameters
- * the model doesn't support (stop, penalties, n…) with HTTP 400.
- */
-export type ApfelModelOptions = {
-  temperature?: number
+/** Per-call `modelOptions`: the request fields apfel takes, with OpenAI's names, sent as given. */
+export type ApfelTextModelOptions = {
+  /** Most tokens to generate. */
   max_tokens?: number
+  temperature?: number
+  top_p?: number
   seed?: number
 }
 
-type ApfelReasoning = never
+/** The Prompt API's availability values; apfel's model is "available" or "unavailable". */
+export type Availability = "unavailable" | "downloadable" | "downloading" | "available"
 
-type MetadataByModality = {
-  text: unknown
-  image: unknown
-  audio: unknown
-  video: unknown
-  document: unknown
+/** TanStack's OpenAI-compatible adapter for apfel, with apfel's availability. */
+export type ApfelTextAdapter = OpenAICompatibleChatAdapter<ApfelModel, ApfelTextModelOptions> & {
+  /** Text and images for Apple's model; not known for another model. */
+  readonly inputModalities: ReadonlyArray<"text" | "image"> | undefined
+  /** "available" if apfel answers and serves the model, else "unavailable". */
+  availability(signal?: AbortSignal): Promise<Availability>
+  /** Resolves to this adapter if apfel serves the model, else rejects. Nothing loads. */
+  create(options?: { signal?: AbortSignal }): Promise<ApfelTextAdapter>
 }
 
-type OpenAIToolCall = {
-  id: string
-  type: "function"
-  function: { name: string; arguments: string }
-}
-
-type OpenAIMessage =
-  | { role: "system" | "user"; content: string }
-  | {
-      role: "assistant"
-      content: string | null
-      tool_calls?: Array<OpenAIToolCall>
-    }
-  | { role: "tool"; tool_call_id: string; content: string }
+const DEFAULT_BASE_URL = "http://127.0.0.1:11434/v1"
 
-type OpenAITool = {
-  type: "function"
-  function: { name: string; description: string; parameters: unknown }
-}
-
-type FinishReason = "stop" | "length" | "content_filter" | "tool_calls" | null
-
-type OpenAIUsage = {
-  prompt_tokens?: number
-  completion_tokens?: number
-  prompt_tokens_details?: { cached_tokens?: number }
-}
-
-type OpenAIChunk = {
-  choices?: Array<{
-    delta?: {
-      content?: string | null
-      reasoning_content?: string | null
-      tool_calls?: Array<{
-        index: number
-        id?: string
-        function?: { name?: string; arguments?: string }
-      }>
-    }
-    finish_reason?: FinishReason
-  }>
-  /** Sent in a last chunk of its own when asked for with include_usage. */
-  usage?: OpenAIUsage | null
-  error?: { message?: string }
-}
-
-type OpenAICompletion = {
-  choices?: Array<{
-    message?: { content?: string | null; refusal?: string | null }
-    finish_reason?: FinishReason
-  }>
-  usage?: OpenAIUsage | null
-}
+/** A model apfel serves: Apple's ("apple-foundationmodel", the default), or any other name. */
+export type ApfelModel = ApfelChatModel | (string & {})
 
 /**
- * A tool result for the model. A failed tool gives its error message, so the
- * model can see what went wrong and try again.
- */
-function toolResultText(m: ModelMessage) {
-  const text = contentText(m.content)
-  if (m.error) return `Error: ${m.error}`
-  return text && text !== "null" ? text : "The tool returned nothing."
-}
-
-function contentText(content: ModelMessage["content"]) {
-  if (typeof content === "string") return content
-  return (content ?? [])
-    .map((part) => (part.type === "text" ? part.content : ""))
-    .join("")
-}
-
-/**
- * The conversation in OpenAI's chat format. Tool calls and results from
- * earlier turns are left out; their answers stay. With them in the history,
- * Apple's model writes its next tool call as broken JSON text most of the
- * time (4 of 12 calls worked, against 12 of 12 without). The current turn's
- * calls and results are kept: the model answers from them.
- */
-function toOpenAIMessages(messages: Array<ModelMessage>): Array<OpenAIMessage> {
-  const out: Array<OpenAIMessage> = []
-  const currentTurn = messages.map((m) => m.role).lastIndexOf("user")
-  for (const [i, m] of messages.entries()) {
-    const earlierToolStep =
-      i < currentTurn &&
-      (m.role === "tool" || (m.role === "assistant" && m.toolCalls?.length))
-    const content = contentText(m.content)
-    if (earlierToolStep) {
-      if (m.role === "assistant" && content) {
-        out.push({ role: "assistant", content })
-      }
-    } else if (m.role === "tool") {
-      out.push({
-        role: "tool",
-        tool_call_id: m.toolCallId ?? "",
-        content: toolResultText(m)
-      })
-    } else if (m.role === "assistant" && m.toolCalls?.length) {
-      out.push({
-        role: "assistant",
-        content: content || null,
-        tool_calls: m.toolCalls.map((call) => ({
-          id: call.id,
-          type: "function",
-          function: call.function
-        }))
-      })
-    } else if (content) {
-      out.push({ role: m.role === "user" ? "user" : "assistant", content })
-    }
-  }
-  return out
-}
-
-/** Tools as OpenAI function tools; `inputSchema` is already JSON Schema. */
-function toOpenAITools(tools: Array<Tool> | undefined): Array<OpenAITool> {
-  return (tools ?? []).map((tool) => ({
-    type: "function",
-    function: {
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.inputSchema ?? {
-        type: "object",
-        properties: {},
-        required: []
-      }
-    }
-  }))
-}
-
-/**
- * `tool_choice` for the request. "auto" is apfel's default and is left out,
- * so a plain request is sent exactly as before.
+ * An adapter for a model apfel serves: Apple's on-device model by default.
+ *
+ * @example
+ * ```ts
+ * const adapter = apfelText()
+ * if ((await adapter.availability()) === "available") {
+ *   chat({ adapter, messages, tools })
+ * }
+ * ```
  */
-function toolChoice(choice: TextOptions["toolChoice"]) {
-  if (!choice || choice === "auto") return {}
-  if (typeof choice === "string") return { tool_choice: choice }
-  return {
-    tool_choice: { type: "function", function: { name: choice.name } }
-  }
-}
-
-/** The system prompts as one system message, if there are any. */
-function systemMessages(
-  prompts: TextOptions["systemPrompts"]
-): Array<OpenAIMessage> {
-  const system = normalizeSystemPrompts(prompts)
-    .map((p) => p.content)
-    .join("\n\n")
-  return system ? [{ role: "system", content: system }] : []
-}
-
-/** Yields the `data:` payloads of an SSE response body. */
-async function* sseData(body: ReadableStream<Uint8Array>) {
-  const reader = body.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ""
-  try {
-    for (;;) {
-      const { value, done } = await reader.read()
-      if (done) break
-      buffer += decoder.decode(value, { stream: true })
-      let newline: number
-      while ((newline = buffer.indexOf("\n")) >= 0) {
-        const line = buffer.slice(0, newline).trim()
-        buffer = buffer.slice(newline + 1)
-        if (line.startsWith("data:")) yield line.slice(5).trim()
-      }
-    }
-  } finally {
-    reader.releaseLock()
-  }
-}
-
-/** A tool call's JSON arguments, or undefined if they aren't a JSON object. */
-function parseArguments(json: string): Record<string, unknown> | undefined {
-  try {
-    const args = JSON.parse(json) as unknown
-    return args && typeof args === "object" && !Array.isArray(args)
-      ? (args as Record<string, unknown>)
-      : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/** The message of apfel's `{"error": {"message"}}` body, or the raw body. */
-async function errorBody(response: Response) {
-  const raw = await response.text().catch(() => "")
-  try {
-    const message = (JSON.parse(raw) as OpenAIChunk).error?.message
-    if (message) return message
-  } catch {
-    // Not JSON: the raw body says what it says.
-  }
-  return raw.slice(0, 200)
-}
-
-/** apfel's token counts as TanStack AI usage, with the call's timings. */
-function usageOf(
-  usage: OpenAIUsage | null | undefined,
-  details?: ApfelProviderUsageDetails
-): TokenUsage | undefined {
-  if (
-    usage?.prompt_tokens === undefined ||
-    usage.completion_tokens === undefined
-  ) {
-    return undefined
-  }
-  const result = buildBaseUsage<ApfelProviderUsageDetails>({
-    promptTokens: usage.prompt_tokens,
-    completionTokens: usage.completion_tokens,
-    totalTokens: usage.prompt_tokens + usage.completion_tokens
-  })
-  const cachedTokens = usage.prompt_tokens_details?.cached_tokens
-  if (cachedTokens) result.promptTokensDetails = { cachedTokens }
-  if (details && Object.keys(details).length > 0) {
-    result.providerUsageDetails = details
-  }
-  return result
-}
-
-const errorText = (error: unknown) =>
-  error instanceof Error ? error.message : String(error)
-
-const unreachable = (baseURL: string) => `Couldn't reach apfel at ${baseURL}.`
-
-let ids = 0
-const nextId = (prefix: string) =>
-  `${prefix}_${Date.now().toString(36)}_${(ids++).toString(36)}`
-
-type StreamedCall = { name: string; arguments: string }
-
-export class ApfelTextAdapter<TModel extends string> extends BaseTextAdapter<
-  TModel,
-  ApfelModelOptions,
-  readonly ["text"],
-  MetadataByModality,
-  ReadonlyArray<string>,
-  unknown,
-  never,
-  ApfelReasoning
-> {
-  override readonly kind = "text" as const
-  readonly name = "apfel" as const
-  override readonly provider = "apfel" as const
-  override readonly api = "openai-completions" as const
-  override readonly inputModalities = ["text"] as const
-  private readonly baseURL: string
-  private readonly headers: Record<string, string>
-
-  constructor(config: ApfelTextConfig, model: TModel) {
-    super({}, model)
-    this.baseURL = (config.baseURL ?? APFEL_BASE_URL).replace(/\/+$/, "")
-    this.headers = {
-      ...config.defaultHeaders,
-      "Content-Type": "application/json"
-    }
-  }
-
-  async *chatStream(
-    options: TextOptions<ApfelModelOptions>
-  ): AsyncIterable<AdapterYieldChunk> {
-    const runId = options.runId ?? nextId("run")
-    const threadId = options.threadId
-    const messageId = nextId("msg")
-    const reasoningId = nextId("reasoning")
-    const model = this.model
-    const { logger } = options
-    const signal =
-      options.abortController?.signal ??
-      (options.request as RequestInit | undefined)?.signal ??
-      undefined
-    const timestamp = () => Date.now()
-    const runError = (message: string): AdapterYieldChunk => ({
-      type: EventType.RUN_ERROR,
-      model,
-      timestamp: timestamp(),
-      message,
-      error: { message }
-    })
-
-    yield {
-      type: EventType.RUN_STARTED,
-      runId,
-      threadId,
-      model,
-      timestamp: timestamp(),
-      ...(options.parentRunId && { parentRunId: options.parentRunId })
-    }
-
-    const tools = toOpenAITools(options.tools)
-    const toolNames = new Set(tools.map((tool) => tool.function.name))
-    const send = options.wrapFetch ? options.wrapFetch(fetch) : fetch
-    const url = `${this.baseURL}/chat/completions`
-    logger.request(
-      `activity=chat provider=apfel model=${model} messages=${options.messages.length} tools=${tools.length} stream=true`,
-      { provider: "apfel", model }
-    )
-    const sentAt = performance.now()
-    let response: Response
-    try {
-      response = await send(url, {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify({
-          ...options.modelOptions,
-          model,
-          stream: true,
-          // Token counts, for the stats.
-          stream_options: { include_usage: true },
-          messages: [
-            ...systemMessages(options.systemPrompts),
-            ...toOpenAIMessages(options.messages)
-          ],
-          ...(tools.length > 0 && {
-            tools,
-            ...toolChoice(options.toolChoice)
-          })
-        }),
-        signal
-      })
-    } catch (error) {
-      if (signal?.aborted) return
-      logger.errors("apfel.chatStream fetch failed", {
-        error,
-        source: "apfel.chatStream"
-      })
-      yield runError(unreachable(this.baseURL))
-      return
-    }
-    if (!response.ok || !response.body) {
-      yield runError(
-        `apfel returned HTTP ${response.status}: ${await errorBody(response)}`
-      )
-      return
-    }
-
-    // Reasoning (apfel sends none for Apple's model today) streams as
-    // reasoning events, then the answer as text up to any tool call the
-    // model wrote as text, which is held back and parsed at the end.
-    let reasoning: "none" | "open" | "closed" = "none"
-    let textStarted = false
-    let text = ""
-    const events: Array<AdapterYieldChunk> = []
-    const endReasoning = () => {
-      if (reasoning !== "open") return
-      reasoning = "closed"
-      events.push(
-        {
-          type: EventType.REASONING_MESSAGE_END,
-          messageId: reasoningId,
-          model,
-          timestamp: timestamp()
-        },
-        {
-          type: EventType.REASONING_END,
-          messageId: reasoningId,
-          model,
-          timestamp: timestamp()
-        }
-      )
-    }
-    const addReasoning = (delta: string) => {
-      if (reasoning === "none") {
-        events.push(
-          {
-            type: EventType.REASONING_START,
-            messageId: reasoningId,
-            model,
-            timestamp: timestamp()
-          },
-          {
-            type: EventType.REASONING_MESSAGE_START,
-            messageId: reasoningId,
-            role: "reasoning",
-            model,
-            timestamp: timestamp()
-          }
-        )
-      }
-      reasoning = "open"
-      events.push({
-        type: EventType.REASONING_MESSAGE_CONTENT,
-        messageId: reasoningId,
-        delta,
-        model,
-        timestamp: timestamp()
-      })
-    }
-    const addText = (delta: string) => {
-      if (!delta) return
-      endReasoning()
-      if (!textStarted) {
-        textStarted = true
-        events.push({
-          type: EventType.TEXT_MESSAGE_START,
-          messageId,
-          role: "assistant",
-          model,
-          timestamp: timestamp()
-        })
-      }
-      text += delta
-      events.push({
-        type: EventType.TEXT_MESSAGE_CONTENT,
-        messageId,
-        delta,
-        content: text,
-        model,
-        timestamp: timestamp()
-      })
-    }
-    const endText = () => {
-      if (!textStarted) return
-      textStarted = false
-      events.push({
-        type: EventType.TEXT_MESSAGE_END,
-        messageId,
-        model,
-        timestamp: timestamp()
-      })
-    }
-
-    // When apfel doesn't recognize a tool call, it passes it on as text;
-    // that part is held back and read once the reply ends.
-    const splitter = createToolCallSplitter(JSON_TOOL_CALLS_MARKER)
-    // Tool calls stream in pieces, by index.
-    const streamed: Array<StreamedCall> = []
-    // apfel streams a few tokens per chunk: the first chunk's share of the
-    // characters stands in for its share of the tokens.
-    const timing = { first: 0, last: 0, firstChars: 0, chars: 0 }
-    let usage: OpenAIChunk["usage"]
-    let finishReason: FinishReason = null
+export function apfelText(config?: ApfelConfig): ApfelTextAdapter
+export function apfelText(model: ApfelModel, config?: ApfelConfig): ApfelTextAdapter
+export function apfelText(modelOrConfig?: ApfelModel | ApfelConfig, maybeConfig: ApfelConfig = {}): ApfelTextAdapter {
+  const model = typeof modelOrConfig === "string" ? modelOrConfig : "apple-foundationmodel"
+  const config = typeof modelOrConfig === "string" ? maybeConfig : (modelOrConfig ?? {})
+  const baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, "")
+  const headers = config.defaultHeaders
+  const adapter = openaiCompatibleText(model, {
+    name: "apfel",
+    baseURL,
+    // apfel takes any key unless it was started with a token (see defaultHeaders).
+    apiKey: "apfel",
+    api: "chat-completions",
+    ...(headers && { defaultHeaders: headers }),
+    // apfel runs on the user's own machine: there's no secret key to expose.
+    dangerouslyAllowBrowser: true
+  }) as OpenAICompatibleChatAdapter<ApfelModel, ApfelTextModelOptions>
+
+  const availability = async (signal?: AbortSignal): Promise<Availability> => {
     try {
-      for await (const data of sseData(response.body)) {
-        if (data === "[DONE]") break
-        const chunk = JSON.parse(data) as OpenAIChunk
-        logger.provider("provider=apfel", { chunk })
-        if (chunk.error) {
-          throw new Error(chunk.error.message ?? "apfel sent an error.")
-        }
-        usage = chunk.usage ?? usage
-        const choice = chunk.choices?.[0]
-        const delta = choice?.delta
-        const chars =
-          (delta?.content?.length ?? 0) +
-          (delta?.reasoning_content?.length ?? 0) +
-          (delta?.tool_calls ?? []).reduce(
-            (n, piece) =>
-              n +
-              (piece.function?.name?.length ?? 0) +
-              (piece.function?.arguments?.length ?? 0),
-            0
-          )
-        if (chars > 0) {
-          timing.last = performance.now()
-          if (!timing.first) {
-            timing.first = timing.last
-            timing.firstChars = chars
-          }
-          timing.chars += chars
-        }
-        if (delta?.reasoning_content) addReasoning(delta.reasoning_content)
-        if (delta?.content) addText(splitter.push(delta.content))
-        for (const piece of delta?.tool_calls ?? []) {
-          // apfel numbers its calls call_1, call_2… in every response; the
-          // adapter gives them ids of its own that are unique in the thread.
-          const call = (streamed[piece.index] ??= { name: "", arguments: "" })
-          call.name += piece.function?.name ?? ""
-          call.arguments += piece.function?.arguments ?? ""
-        }
-        if (choice?.finish_reason) finishReason = choice.finish_reason
-        yield* events.splice(0)
-      }
-    } catch (error) {
-      if (signal?.aborted) return
-      logger.errors("apfel.chatStream stream failed", {
-        error,
-        source: "apfel.chatStream"
-      })
-      endReasoning()
-      endText()
-      yield* events.splice(0)
-      yield runError(`apfel's stream failed: ${errorText(error)}`)
-      return
-    }
-
-    const outputTokens = usage?.completion_tokens
-    const details: ApfelProviderUsageDetails = timing.first
-      ? {
-          firstTokenMs: timing.first - sentAt,
-          decodeMs: timing.last - timing.first,
-          ...(outputTokens !== undefined && {
-            decodeTokens:
-              (outputTokens * (timing.chars - timing.firstChars)) /
-              timing.chars
-          })
-        }
-      : {}
-
-    endReasoning()
-    const { text: rest, markup } = splitter.flush()
-    const fromText =
-      markup && streamed.length === 0
-        ? parseJsonToolCalls(markup, toolNames)
-        : []
-    // Text that wasn't a readable tool call is shown after all.
-    addText(`${rest}${fromText.length > 0 ? "" : (markup ?? "")}`)
-    yield* events.splice(0)
-
-    // Calls to tools that don't exist are passed on too: `chat()` answers
-    // them with an "Unknown tool" error, so the model can answer with what
-    // it has instead of stopping there.
-    const calls = [
-      ...streamed.filter((call) => call?.name),
-      ...fromText.map((call) => ({
-        name: call.name,
-        arguments: JSON.stringify(call.args)
-      }))
-    ].map((call) => ({
-      ...call,
-      name: matchToolName(call.name, toolNames) ?? call.name
-    }))
-    let repairMs = 0
-    for (const [index, call] of calls.entries()) {
-      const toolCallId = nextId("tool")
-      yield {
-        type: EventType.TOOL_CALL_START,
-        toolCallId,
-        toolCallName: call.name,
-        parentMessageId: messageId,
-        index,
-        model,
-        timestamp: timestamp()
-      }
-      const tool = options.tools?.find((t) => t.name === call.name)
-      const repairStart = performance.now()
-      const repaired = tool
-        ? await this.repairArguments(
-            tool,
-            call.arguments,
-            options,
-            send,
-            signal
-          )
-        : undefined
-      repairMs += performance.now() - repairStart
-      if (signal?.aborted) return
-      const args = repaired ? JSON.stringify(repaired) : call.arguments || "{}"
-      const input = repaired ?? parseArguments(args)
-      yield {
-        type: EventType.TOOL_CALL_ARGS,
-        toolCallId,
-        delta: args,
-        args,
-        model,
-        timestamp: timestamp()
-      }
-      yield {
-        type: EventType.TOOL_CALL_END,
-        toolCallId,
-        toolCallName: call.name,
-        args,
-        // Arguments that aren't JSON are left out; `chat()` reports them.
-        ...(input && { input }),
-        model,
-        timestamp: timestamp()
-      }
-    }
-    endText()
-    yield* events.splice(0)
-
-    if (repairMs > 0) details.toolRepairMs = repairMs
-    const finishUsage = usageOf(usage, details)
-    yield {
-      type: EventType.RUN_FINISHED,
-      runId,
-      threadId,
-      model,
-      timestamp: timestamp(),
-      finishReason:
-        calls.length > 0
-          ? "tool_calls"
-          : finishReason === "tool_calls" || finishReason === null
-            ? "stop"
-            : finishReason,
-      ...(finishUsage && { usage: finishUsage })
-    }
-  }
-
-  /**
-   * A tool call's arguments, written again under the tool's schema with
-   * guided generation. Undefined if the tool takes no arguments or a request
-   * failed: the model's own arguments are used then.
-   */
-  private async repairArguments(
-    tool: Tool,
-    draft: string,
-    options: TextOptions<ApfelModelOptions>,
-    send: typeof fetch,
-    signal: AbortSignal | undefined
-  ) {
-    const system = normalizeSystemPrompts(options.systemPrompts)
-      .map((p) => p.content)
-      .join("\n\n")
-    const messages = toOpenAIMessages(options.messages)
-    const complete = async ({ instructions, schema, name }: GuidedRequest) => {
-      options.logger.request(
-        `activity=tool-repair provider=apfel model=${this.model} tool=${tool.name} step=${name}`,
-        { provider: "apfel", model: this.model }
-      )
-      const response = await send(`${this.baseURL}/chat/completions`, {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify({
-          ...options.modelOptions,
-          model: this.model,
-          // apfel takes one system message, and the conversation must end
-          // with the user or a tool result: the instructions go first.
-          messages: [
-            {
-              role: "system",
-              content: system
-                ? `${instructions}\n\nThe assistant's instructions, for context:\n${system}`
-                : instructions
-            },
-            ...messages
-          ],
-          response_format: {
-            type: "json_schema",
-            json_schema: { name, schema }
-          }
-        }),
-        signal
+      const timeout = AbortSignal.timeout(10_000)
+      const response = await fetch(`${baseURL}/models`, {
+        ...(headers && { headers }),
+        signal: signal ? AbortSignal.any([signal, timeout]) : timeout
       })
-      if (!response.ok) {
-        throw new Error(
-          `apfel returned HTTP ${response.status}: ${await errorBody(response)}`
-        )
-      }
-      const completion = (await response.json()) as OpenAICompletion
-      const text = (completion.choices?.[0]?.message?.content ?? "").trim()
-      return JSON.parse(
-        text.replace(/^```(?:json)?\s*|\s*```$/g, "")
-      ) as unknown
-    }
-    try {
-      return await repairToolArguments(tool, complete, draft)
-    } catch (error) {
-      if (!signal?.aborted) {
-        options.logger.errors("apfel tool-call repair failed", {
-          error,
-          source: "apfel.repairArguments"
-        })
-      }
-      return undefined
+      const list = (await response.json()) as { data?: Array<{ id?: string }> }
+      return response.ok && list.data?.some((m) => m.id === model) ? "available" : "unavailable"
+    } catch {
+      return "unavailable"
     }
   }
 
-  /**
-   * A JSON answer for `chat({ outputSchema })`, from apfel's JSON mode:
-   * `response_format: json_schema` constrains Apple's model to the schema
-   * (guided generation). `chat()` validates the result.
-   */
-  async structuredOutput(
-    options: StructuredOutputOptions<ApfelModelOptions>
-  ): Promise<StructuredOutputResult<unknown>> {
-    const { chatOptions, outputSchema } = options
-    const model = this.model
-    const send = chatOptions.wrapFetch ? chatOptions.wrapFetch(fetch) : fetch
-    chatOptions.logger.request(
-      `activity=chat provider=apfel model=${model} messages=${chatOptions.messages.length} tools=0 stream=false`,
-      { provider: "apfel", model }
-    )
-    let response: Response
-    try {
-      response = await send(`${this.baseURL}/chat/completions`, {
-        method: "POST",
-        headers: this.headers,
-        body: JSON.stringify({
-          ...chatOptions.modelOptions,
-          model,
-          messages: [
-            ...systemMessages(chatOptions.systemPrompts),
-            ...toOpenAIMessages(chatOptions.messages)
-          ],
-          response_format: {
-            type: "json_schema",
-            json_schema: { name: "output", schema: outputSchema }
-          }
-        }),
-        signal:
-          chatOptions.abortController?.signal ??
-          (chatOptions.request as RequestInit | undefined)?.signal ??
-          undefined
-      })
-    } catch (error) {
-      chatOptions.logger.errors("apfel.structuredOutput fetch failed", {
-        error,
-        source: "apfel.structuredOutput"
-      })
-      if (chatOptions.abortController?.signal.aborted) throw error
-      throw new Error(unreachable(this.baseURL))
-    }
-    if (!response.ok) {
-      throw new Error(
-        `apfel returned HTTP ${response.status}: ${await errorBody(response)}`
-      )
-    }
-    const completion = (await response.json()) as OpenAICompletion
-    const choice = completion.choices?.[0]
-    if (choice?.finish_reason === "length") {
-      throw new Error(
-        "apfel's answer was cut off at the token limit before its JSON ended; raise modelOptions.max_tokens."
-      )
-    }
-    const rawText = (
-      choice?.message?.content ??
-      choice?.message?.refusal ??
-      ""
-    ).trim()
-    const json = rawText.replace(/^```(?:json)?\s*|\s*```$/g, "")
-    const usage = usageOf(completion.usage)
-    try {
-      return {
-        data: JSON.parse(json) as unknown,
-        rawText,
-        model,
-        ...(usage && { usage })
+  const apfel: ApfelTextAdapter = Object.assign(adapter, {
+    inputModalities: Object.hasOwn(APFEL_MODEL_META, model) ? APFEL_MODEL_META[model as ApfelChatModel].supports.input : undefined,
+    availability,
+    async create({ signal }: { signal?: AbortSignal } = {}) {
+      signal?.throwIfAborted()
+      const answer = await availability(signal)
+      signal?.throwIfAborted()
+      if (answer !== "available") {
+        throw new Error(`apfel at ${baseURL} didn't answer, or doesn't serve ${model}. Start it with \`apfel --serve --cors\`.`)
       }
-    } catch {
-      throw new Error(
-        `The model's answer isn't JSON: ${rawText.slice(0, 200)}${rawText.length > 200 ? "…" : ""}`
-      )
+      return apfel
     }
-  }
-}
-
-/**
- * A TanStack AI text adapter for Apple's on-device Foundation Model, served
- * by apfel.
- *
- * @example
- * ```ts
- * chat({
- *   adapter: apfelText("apple-foundationmodel", { baseURL: APFEL_BASE_URL }),
- *   messages,
- *   threadId
- * })
- * ```
- */
-export function apfelText<TModel extends ApfelTextModel>(
-  model: TModel,
-  config: ApfelTextConfig = {}
-): ApfelTextAdapter<TModel> {
-  return new ApfelTextAdapter(config, model)
-}
-
-/**
- * Whether apfel is running and serves the model: true if `GET /v1/models`
- * lists it within 10 seconds.
- */
-export async function isApfelAvailable(
-  model: ApfelTextModel,
-  config: ApfelTextConfig = {}
-) {
-  const baseURL = (config.baseURL ?? APFEL_BASE_URL).replace(/\/+$/, "")
-  try {
-    const response = await fetch(`${baseURL}/models`, {
-      headers: { ...config.defaultHeaders },
-      signal: AbortSignal.timeout(10_000)
-    })
-    if (!response.ok) return false
-    const list = (await response.json()) as { data?: Array<{ id?: string }> }
-    return list.data?.some((m) => m.id === model) ?? false
-  } catch {
-    return false
-  }
+  })
+  return apfel
 }