iris-chatbot 0.2.4

package/template/src/app/api/chat/route.ts

@@ -0,0 +1,2445 @@
+import OpenAI from "openai";
+import Anthropic from "@anthropic-ai/sdk";
+import type {
+  ChatConnectionPayload,
+  ChatMessageInput,
+  MemoryContextPayload,
+  MemoryMusicAlias,
+  ChatRequest,
+  ChatStreamChunk,
+  LocalToolsSettings,
+} from "../../../lib/types";
+import { DEFAULT_LOCAL_TOOLS_SETTINGS } from "../../../lib/types";
+import { GEMINI_OPENAI_BASE_URL, supportsToolsByDefault } from "../../../lib/connections";
+import { createApprovalRequest } from "../../../lib/tooling/approvals";
+import {
+  createToolRegistry,
+  findToolByName,
+  serializeToolOutput,
+  toProviderToolSchemas,
+} from "../../../lib/tooling/registry";
+import { createAnthropicSession } from "../../../lib/tooling/providers/anthropic";
+import { streamOllamaChat } from "../../../lib/tooling/providers/ollama";
+import {
+  createOpenAISession,
+  extractCitationSourcesFromResponse,
+} from "../../../lib/tooling/providers/openai";
+import { createOpenAICompatibleSession } from "../../../lib/tooling/providers/openai_compatible";
+import type {
+  ProviderCitationSource,
+  ToolLoopMessage,
+  ToolProviderSession,
+} from "../../../lib/tooling/providers/types";
+import { requiresApprovalForRisk } from "../../../lib/tooling/safety";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const MAX_TOOL_STEPS = 48;
+const STREAM_CHUNK_SIZE = 8;
+const LOCAL_TOOL_SYSTEM_INSTRUCTIONS = [
+  "You can access the user's local computer through provided tools.",
+  "When the user asks for file, app, notes, music, web, calendar, or system actions, call tools directly.",
+  "Default to execution instead of clarification. Ask at most one question only when a truly required value is missing.",
+  "For iMessage/text requests, use messages_send; if contact matching is ambiguous, ask one concise clarification with candidate names.",
+  "For media requests, assume Apple Music unless the user specifies otherwise.",
+  "For note creation, write structured markdown with clear headings, bolded key labels, and tables when they improve clarity.",
+  "If the user requests multiple actions in one prompt, execute every requested action sequentially before your final response.",
+  "Do not stop after completing just one action when additional requested actions remain.",
+  "For multi-step requests, prefer a single workflow tool call when available.",
+  "When tools are enabled, never say you cannot access the user's device.",
+  "After tool results arrive, provide a brief final answer and stop.",
+  "Summarize tool activity in plain English and avoid raw JSON, stack traces, or script line numbers.",
+  "Respect tool errors and provide clear next steps.",
+].join(" ");
+
+const ACTION_VERB_PATTERN =
+  "create|make|write|play|set|add|remind|open|send|launch|start|pause|resume|focus";
+const SEQUENCE_MARKER_PATTERN = "first|second|third|fourth|fifth|next|then|finally|lastly";
+const TOOL_INTENT_EXPLICIT_PATTERN =
+  /\b(use|run|call)\s+(?:the\s+)?(?:local\s+)?tools?\b|\b(on my (?:mac|computer|device)|locally)\b/i;
+const TOOL_INTENT_LEADING_VERB_PATTERN =
+  /^(?:please\s+)?(?:(?:can|could|would)\s+you\s+)?(?:send|text|message|play|pause|resume|skip|next|previous|set|open|launch|focus|create|make|add|remind|search|find|list|move|copy|rename|delete|trash|append|write|read|start|stop)\b/i;
+const TOOL_INTENT_MESSAGING_PATTERN =
+  /\b(text|message|imessage|sms|mail|email)\b[\s\S]{0,80}\b(send|text|message|email|mail)\b|\b(send|text|message|email|mail)\b[\s\S]{0,80}\b(text|message|imessage|sms|mail|email)\b/i;
+const TOOL_INTENT_NOTES_PATTERN =
+  /\b(note|notes)\b[\s\S]{0,80}\b(create|make|write|append|add|find|search|open|update|jot)\b|\b(create|make|write|append|add|find|search|open|update|jot)\b[\s\S]{0,80}\b(note|notes)\b/i;
+const TOOL_INTENT_MUSIC_PATTERN =
+  /\b(music|song|track|album|playlist|apple music)\b[\s\S]{0,80}\b(play|pause|resume|skip|next|previous|volume|set|stop)\b|\b(play|pause|resume|skip|next|previous|volume|set|stop)\b[\s\S]{0,80}\b(music|song|track|album|playlist|apple music)\b/i;
+const TOOL_INTENT_SCHEDULE_PATTERN =
+  /\b(calendar|event|reminder|schedule)\b[\s\S]{0,80}\b(create|add|list|show|set|remind|schedule)\b|\b(create|add|list|show|set|remind|schedule)\b[\s\S]{0,80}\b(calendar|event|reminder|schedule)\b/i;
+const TOOL_INTENT_FILES_PATTERN =
+  /\b(file|folder|directory|path|document)\b[\s\S]{0,80}\b(list|find|search|move|copy|rename|delete|trash|create|make|mkdir|open)\b|\b(list|find|search|move|copy|rename|delete|trash|create|make|mkdir|open)\b[\s\S]{0,80}\b(file|folder|directory|path|document)\b/i;
+const TOOL_INTENT_APPS_PATTERN =
+  /\b(app|application|window|url|website|browser|system)\b[\s\S]{0,80}\b(open|launch|focus|quit|set|mute|unmute|browse)\b|\b(open|launch|focus|quit|set|mute|unmute|browse)\b[\s\S]{0,80}\b(app|application|window|url|website|browser|system)\b/i;
+const TOOL_INTENT_NUMBERS_PATTERN =
+  /\b(numbers|spreadsheet|cell)\b[\s\S]{0,80}\b(read|set|update|write)\b|\b(read|set|update|write)\b[\s\S]{0,80}\b(numbers|spreadsheet|cell)\b/i;
+const TOOL_INTENT_WORKFLOW_PATTERN = /\b(workflow|automation)\b[\s\S]{0,80}\b(run|start|execute|create)\b/i;
+
+function splitCompoundActionClauses(input: string): string[] {
+  const normalized = input.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return [];
+  }
+
+  const roughParts = normalized.split(
+    new RegExp(
+      `\\s*(?:,|;|\\n)+\\s*(?=(?:(?:${SEQUENCE_MARKER_PATTERN})\\b|${ACTION_VERB_PATTERN}\\b))|` +
+        `\\s+(?:and then|and also|as well as|after that|plus|then|also|next|finally|lastly)\\s+|` +
+        `\\s+and\\s+(?=(?:${ACTION_VERB_PATTERN})\\b)`,
+      "i",
+    ),
+  );
+
+  return roughParts
+    .map((part) =>
+      part
+        .trim()
+        .replace(new RegExp(`^(?:${SEQUENCE_MARKER_PATTERN})\\b[\\s,:-]*`, "i"), "")
+        .replace(/^(?:can you|could you|would you|please|hey|hi|yo)\s+/i, "")
+        .trim(),
+    )
+    .filter(Boolean);
+}
+
+function buildDetectedActionHint(messages: ChatMessageInput[]): string | null {
+  const lastUser = [...messages].reverse().find((message) => message.role === "user");
+  if (!lastUser?.content) {
+    return null;
+  }
+  const clauses = splitCompoundActionClauses(lastUser.content);
+  if (clauses.length < 2) {
+    return null;
+  }
+  const lines = clauses.map((clause, index) => `${index + 1}. ${clause}`);
+  return `Detected user actions:\n${lines.join("\n")}\nExecute each action in order and confirm each result.`;
+}
+
+function buildToolSystemPrompt(system: string | undefined, messages: ChatMessageInput[]): string {
+  const base = system?.trim();
+  const actionHint = buildDetectedActionHint(messages);
+  if (!base) {
+    return actionHint
+      ? `${LOCAL_TOOL_SYSTEM_INSTRUCTIONS}\n\n${actionHint}`
+      : LOCAL_TOOL_SYSTEM_INSTRUCTIONS;
+  }
+  return actionHint
+    ? `${base}\n\n${LOCAL_TOOL_SYSTEM_INSTRUCTIONS}\n\n${actionHint}`
+    : `${base}\n\n${LOCAL_TOOL_SYSTEM_INSTRUCTIONS}`;
+}
+
+function shouldRouteThroughToolOrchestrator(messages: ChatMessageInput[]): boolean {
+  const hasToolIntent = (input: string): boolean => {
+    const text = input.replace(/\s+/g, " ").trim();
+    if (!text) {
+      return false;
+    }
+
+    if (TOOL_INTENT_EXPLICIT_PATTERN.test(text)) {
+      return true;
+    }
+
+    if (TOOL_INTENT_LEADING_VERB_PATTERN.test(text)) {
+      return true;
+    }
+
+    return (
+      TOOL_INTENT_MESSAGING_PATTERN.test(text) ||
+      TOOL_INTENT_NOTES_PATTERN.test(text) ||
+      TOOL_INTENT_MUSIC_PATTERN.test(text) ||
+      TOOL_INTENT_SCHEDULE_PATTERN.test(text) ||
+      TOOL_INTENT_FILES_PATTERN.test(text) ||
+      TOOL_INTENT_APPS_PATTERN.test(text) ||
+      TOOL_INTENT_NUMBERS_PATTERN.test(text) ||
+      TOOL_INTENT_WORKFLOW_PATTERN.test(text)
+    );
+  };
+
+  const lastUserIndex = (() => {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      if (messages[index]?.role === "user") {
+        return index;
+      }
+    }
+    return -1;
+  })();
+  if (lastUserIndex < 0) {
+    return false;
+  }
+
+  const lastUserText = messages[lastUserIndex]?.content ?? "";
+  if (hasToolIntent(lastUserText)) {
+    return true;
+  }
+
+  const clauses = splitCompoundActionClauses(lastUserText);
+  if (clauses.length >= 2 && clauses.some((clause) => hasToolIntent(clause))) {
+    return true;
+  }
+
+  const compactLastUser = lastUserText.replace(/\s+/g, " ").trim();
+  const isLikelyClarification = compactLastUser.length > 0 && compactLastUser.length <= 48;
+  if (!isLikelyClarification) {
+    return false;
+  }
+
+  let priorToolIntentCount = 0;
+  for (let index = lastUserIndex - 1; index >= 0 && priorToolIntentCount < 3; index -= 1) {
+    if (messages[index]?.role !== "user") {
+      continue;
+    }
+    if (hasToolIntent(messages[index]?.content ?? "")) {
+      return true;
+    }
+    priorToolIntentCount += 1;
+  }
+
+  return false;
+}
+
+type RuntimeConnection = {
+  id: string;
+  name: string;
+  kind: "builtin" | "openai_compatible" | "ollama";
+  provider?: "openai" | "anthropic" | "google";
+  baseUrl?: string;
+  apiKey?: string;
+  headers?: Array<{ key: string; value: string }>;
+  supportsTools: boolean;
+};
+
+function headersArrayToRecord(headers: RuntimeConnection["headers"]): Record<string, string> | undefined {
+  if (!Array.isArray(headers) || headers.length === 0) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const header of headers) {
+    if (!header || typeof header.key !== "string") {
+      continue;
+    }
+    const key = header.key.trim();
+    if (!key) {
+      continue;
+    }
+    out[key] = typeof header.value === "string" ? header.value : "";
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function normalizeRuntimeConnection(connection: ChatConnectionPayload): RuntimeConnection {
+  const kind =
+    connection.kind === "builtin" || connection.kind === "openai_compatible" || connection.kind === "ollama"
+      ? connection.kind
+      : "openai_compatible";
+  const provider =
+    kind === "builtin" &&
+    (connection.provider === "openai" ||
+      connection.provider === "anthropic" ||
+      connection.provider === "google")
+      ? connection.provider
+      : undefined;
+  const baseUrl =
+    typeof connection.baseUrl === "string" && connection.baseUrl.trim()
+      ? connection.baseUrl.trim()
+      : kind === "builtin" && provider === "google"
+        ? GEMINI_OPENAI_BASE_URL
+        : kind === "ollama"
+          ? "http://localhost:11434"
+          : undefined;
+  const apiKey = typeof connection.apiKey === "string" && connection.apiKey.trim()
+    ? connection.apiKey.trim()
+    : undefined;
+  const supportsTools =
+    typeof connection.supportsTools === "boolean"
+      ? connection.supportsTools
+      : supportsToolsByDefault({ kind, provider });
+  return {
+    id: typeof connection.id === "string" && connection.id.trim() ? connection.id.trim() : "ad-hoc",
+    name:
+      typeof connection.name === "string" && connection.name.trim() ? connection.name.trim() : "Connection",
+    kind,
+    provider,
+    baseUrl,
+    apiKey,
+    headers: Array.isArray(connection.headers)
+      ? connection.headers.filter(
+          (header): header is { key: string; value: string } =>
+            Boolean(header) && typeof header.key === "string" && typeof header.value === "string",
+        )
+      : [],
+    supportsTools,
+  };
+}
+
+function resolveRuntimeConnection(body: ChatRequest): RuntimeConnection | null {
+  if (body.connection) {
+    return normalizeRuntimeConnection(body.connection);
+  }
+
+  if (body.provider) {
+    return normalizeRuntimeConnection({
+      id: `legacy-${body.provider}`,
+      name: body.provider,
+      kind: "builtin",
+      provider: body.provider,
+      apiKey: body.apiKey,
+      supportsTools: true,
+    });
+  }
+
+  return null;
+}
+
+function requiresApiKey(connection: RuntimeConnection): boolean {
+  if (connection.kind === "ollama") {
+    return false;
+  }
+  if (connection.kind === "openai_compatible") {
+    return false;
+  }
+  return connection.provider === "openai" || connection.provider === "anthropic" || connection.provider === "google";
+}
+
+function normalizeLocalTools(settings: LocalToolsSettings | undefined): LocalToolsSettings {
+  if (!settings) {
+    return { ...DEFAULT_LOCAL_TOOLS_SETTINGS };
+  }
+
+  const normalized: LocalToolsSettings = {
+    enabled: Boolean(settings.enabled),
+    approvalMode: settings.approvalMode ?? DEFAULT_LOCAL_TOOLS_SETTINGS.approvalMode,
+    safetyProfile: settings.safetyProfile ?? DEFAULT_LOCAL_TOOLS_SETTINGS.safetyProfile,
+    allowedRoots:
+      Array.isArray(settings.allowedRoots) && settings.allowedRoots.length > 0
+        ? settings.allowedRoots
+        : [...DEFAULT_LOCAL_TOOLS_SETTINGS.allowedRoots],
+    enableNotes:
+      typeof settings.enableNotes === "boolean"
+        ? settings.enableNotes
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableNotes,
+    enableApps:
+      typeof settings.enableApps === "boolean"
+        ? settings.enableApps
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableApps,
+    enableNumbers:
+      typeof settings.enableNumbers === "boolean"
+        ? settings.enableNumbers
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableNumbers,
+    enableWeb:
+      typeof settings.enableWeb === "boolean"
+        ? settings.enableWeb
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableWeb,
+    enableMusic:
+      typeof settings.enableMusic === "boolean"
+        ? settings.enableMusic
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableMusic,
+    enableCalendar:
+      typeof settings.enableCalendar === "boolean"
+        ? settings.enableCalendar
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableCalendar,
+    enableMail:
+      typeof settings.enableMail === "boolean"
+        ? settings.enableMail
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableMail,
+    enableWorkflow:
+      typeof settings.enableWorkflow === "boolean"
+        ? settings.enableWorkflow
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableWorkflow,
+    enableSystem:
+      typeof settings.enableSystem === "boolean"
+        ? settings.enableSystem
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.enableSystem,
+    webSearchBackend:
+      settings.webSearchBackend ?? DEFAULT_LOCAL_TOOLS_SETTINGS.webSearchBackend,
+    dryRun:
+      typeof settings.dryRun === "boolean"
+        ? settings.dryRun
+        : DEFAULT_LOCAL_TOOLS_SETTINGS.dryRun,
+  };
+
+  const looksLikeLegacyDefaults =
+    normalized.enabled === true &&
+    normalized.approvalMode === "always_confirm_writes" &&
+    normalized.safetyProfile === "balanced" &&
+    normalized.allowedRoots.length === DEFAULT_LOCAL_TOOLS_SETTINGS.allowedRoots.length &&
+    normalized.allowedRoots.every(
+      (value, index) => value === DEFAULT_LOCAL_TOOLS_SETTINGS.allowedRoots[index],
+    ) &&
+    normalized.enableNotes === true &&
+    normalized.enableApps === true &&
+    normalized.enableNumbers === false &&
+    normalized.enableWeb === false &&
+    normalized.enableMusic === true &&
+    normalized.enableCalendar === false &&
+    normalized.enableMail === false &&
+    normalized.enableWorkflow === true &&
+    normalized.enableSystem === true &&
+    normalized.webSearchBackend === "no_key" &&
+    normalized.dryRun === false;
+
+  if (looksLikeLegacyDefaults) {
+    normalized.approvalMode = "trusted_auto";
+  }
+
+  return normalized;
+}
+
+function createToolMessages(messages: ChatMessageInput[], system?: string): ToolLoopMessage[] {
+  const turns: ToolLoopMessage[] = [];
+  if (system?.trim()) {
+    turns.push({ role: "system", content: system.trim() });
+  }
+  for (const message of messages) {
+    turns.push({ role: message.role, content: message.content });
+  }
+  return turns;
+}
+
+function sanitizeChatMessages(messages: ChatMessageInput[]): ChatMessageInput[] {
+  const sanitized: ChatMessageInput[] = [];
+  for (const message of messages) {
+    if (!message) {
+      continue;
+    }
+    const role = message.role;
+    if (role !== "user" && role !== "assistant" && role !== "system") {
+      continue;
+    }
+    if (typeof message.content !== "string") {
+      continue;
+    }
+    const normalizedContent = message.content.replace(/\r\n/g, "\n");
+    if (!normalizedContent.trim()) {
+      continue;
+    }
+    sanitized.push({
+      role,
+      content: normalizedContent,
+    });
+  }
+  return sanitized;
+}
+
+function sanitizeMemoryContext(
+  memory: ChatRequest["memory"],
+): MemoryContextPayload | null {
+  if (!memory || typeof memory !== "object" || memory.enabled !== true) {
+    return null;
+  }
+
+  const aliases =
+    memory.aliases && typeof memory.aliases === "object"
+      ? memory.aliases
+      : { people: [], music: [] };
+
+  const people = Array.isArray(aliases.people)
+    ? aliases.people
+        .map((item) => {
+          const alias = typeof item?.alias === "string" ? item.alias.trim() : "";
+          const target = typeof item?.target === "string" ? item.target.trim() : "";
+          if (!alias || !target) {
+            return null;
+          }
+          return { alias, target };
+        })
+        .filter((item): item is { alias: string; target: string } => Boolean(item))
+        .slice(0, 16)
+    : [];
+
+  const music = Array.isArray(aliases.music)
+    ? aliases.music
+        .map((item) => {
+          const alias = typeof item?.alias === "string" ? item.alias.trim() : "";
+          const query = typeof item?.query === "string" ? item.query.trim() : "";
+          if (!alias || !query) {
+            return null;
+          }
+          const title =
+            typeof item?.title === "string" && item.title.trim()
+              ? item.title.trim()
+              : undefined;
+          const artist =
+            typeof item?.artist === "string" && item.artist.trim()
+              ? item.artist.trim()
+              : undefined;
+          return { alias, query, title, artist };
+        })
+        .filter(
+          (
+            item,
+          ): item is {
+            alias: string;
+            query: string;
+            title: string | undefined;
+            artist: string | undefined;
+          } => Boolean(item),
+        )
+        .slice(0, 16)
+    : [];
+
+  return {
+    enabled: true,
+    aliases: {
+      people,
+      music,
+    },
+  };
+}
+
+function chunkText(text: string, chunkSize = STREAM_CHUNK_SIZE): string[] {
+  if (!text) {
+    return [];
+  }
+  const chunks: string[] = [];
+  let buffer = "";
+  for (const char of text) {
+    buffer += char;
+    const atBoundary = char === "\n" || /[\s,.;:!?)]/.test(char);
+    if (buffer.length >= chunkSize && atBoundary) {
+      chunks.push(buffer);
+      buffer = "";
+    }
+  }
+  if (buffer) {
+    chunks.push(buffer);
+  }
+  return chunks;
+}
+
+function emitTokenText(
+  send: (chunk: ChatStreamChunk) => void,
+  text: string,
+  onChunk?: (chunkTextValue: string) => void,
+) {
+  for (const token of chunkText(text)) {
+    send({ type: "token", value: token });
+    onChunk?.(token);
+  }
+}
+
+function emitThinking(
+  send: (chunk: ChatStreamChunk) => void,
+  status: "started" | "update" | "done",
+  summary?: string,
+) {
+  send({
+    type: "thinking",
+    status,
+    summary,
+  });
+}
+
+function normalizeWebSourcesEnabled(value: boolean | undefined): boolean {
+  return value !== false;
+}
+
+function supportsWebSourcesViaOpenAI(connection: RuntimeConnection): boolean {
+  return connection.kind === "builtin" && connection.provider === "openai";
+}
+
+function mergeCitationSources(
+  target: Map<string, ProviderCitationSource>,
+  sources: ProviderCitationSource[] | undefined,
+) {
+  if (!sources?.length) {
+    return;
+  }
+  for (const source of sources) {
+    if (!source?.url) {
+      continue;
+    }
+    const existing = target.get(source.url);
+    if (!existing || (!existing.title && source.title)) {
+      target.set(source.url, source);
+    }
+  }
+}
+
+function sourceFromAnnotation(annotation: unknown): ProviderCitationSource | null {
+  if (!annotation || typeof annotation !== "object") {
+    return null;
+  }
+  const record = annotation as {
+    type?: unknown;
+    url?: unknown;
+    title?: unknown;
+    url_citation?: unknown;
+  };
+  if (record.type !== "url_citation") {
+    return null;
+  }
+
+  if (typeof record.url === "string" && record.url.trim()) {
+    return {
+      url: record.url.trim(),
+      title:
+        typeof record.title === "string" && record.title.trim()
+          ? record.title.trim()
+          : undefined,
+    };
+  }
+
+  if (record.url_citation && typeof record.url_citation === "object") {
+    const nested = record.url_citation as { url?: unknown; title?: unknown };
+    if (typeof nested.url === "string" && nested.url.trim()) {
+      return {
+        url: nested.url.trim(),
+        title:
+          typeof nested.title === "string" && nested.title.trim()
+            ? nested.title.trim()
+            : undefined,
+      };
+    }
+  }
+
+  return null;
+}
+
+function extractSourcesFromToolOutput(toolName: string, output: unknown): ProviderCitationSource[] {
+  if (!output || typeof output !== "object") {
+    return [];
+  }
+  const record = output as Record<string, unknown>;
+  const sources: ProviderCitationSource[] = [];
+
+  if (toolName === "web_search") {
+    const rawResults = record.results;
+    if (Array.isArray(rawResults)) {
+      for (const item of rawResults) {
+        if (!item || typeof item !== "object") {
+          continue;
+        }
+        const result = item as { url?: unknown; title?: unknown };
+        if (typeof result.url !== "string" || !result.url.trim()) {
+          continue;
+        }
+        sources.push({
+          url: result.url.trim(),
+          title:
+            typeof result.title === "string" && result.title.trim()
+              ? result.title.trim()
+              : undefined,
+        });
+      }
+    }
+  }
+
+  if (toolName === "web_open") {
+    const rawUrl = record.url;
+    if (typeof rawUrl === "string" && rawUrl.trim()) {
+      sources.push({
+        url: rawUrl.trim(),
+        title: "Opened page",
+      });
+    }
+  }
+
+  return sources;
+}
+
+function truncateMessage(message: string, maxLength = 500): string {
+  if (message.length <= maxLength) {
+    return message;
+  }
+  const remaining = message.length - maxLength;
+  return `${message.slice(0, maxLength)}… (+${remaining} chars truncated)`;
+}
+
+function stripTechnicalToolError(message: string): string {
+  return message
+    .trim()
+    .replace(/^\d+:\d+:\s*/i, "")
+    .replace(/^execution error:\s*/i, "")
+    .replace(/^error:\s*/i, "")
+    .replace(/\s+\(-\d+\)\s*$/, "")
+    .replace(/\s+/g, " ");
+}
+
+function humanizeToolErrorMessage(toolName: string, message: string): string {
+  const cleaned = stripTechnicalToolError(message);
+  const normalized = cleaned.toLowerCase().replace(/[\u2019]/g, "'");
+
+  if (toolName === "calendar_create_event" && normalized.includes("can't get date")) {
+    const requestedDateMatch = cleaned.match(/can't get date "([^"]+)"/i);
+    if (requestedDateMatch?.[1]) {
+      const parsed = new Date(requestedDateMatch[1]);
+      if (!Number.isNaN(parsed.getTime())) {
+        const formatted = parsed.toLocaleString("en-US", {
+          month: "short",
+          day: "numeric",
+          year: "numeric",
+          hour: "numeric",
+          minute: "2-digit",
+        });
+        return `Calendar could not understand the event time (${formatted}). Try a local format like "Feb 12 at 9:00 AM".`;
+      }
+    }
+    return 'Calendar could not understand the date/time. Try a local format like "Feb 12 at 9:00 AM".';
+  }
+
+  if (normalized.includes("missing required")) {
+    const fieldMatch = cleaned.match(/missing required (?:string|numeric) field:\s*([a-zA-Z0-9_]+)/i);
+    if (fieldMatch?.[1]) {
+      return `Missing required field "${fieldMatch[1]}".`;
+    }
+    return "Missing required information for this action.";
+  }
+
+  if (normalized.includes("tool input must be an object")) {
+    return "The request format was invalid. Please try again.";
+  }
+
+  if (normalized.includes("timed out") || normalized.includes("timeout")) {
+    return "The app did not respond in time.";
+  }
+
+  if (normalized.includes("no calendar is available")) {
+    return "No calendar is available in the Calendar app.";
+  }
+
+  return cleaned || "Unknown tool execution error.";
+}
+
+function formatToolErrorForUser(toolName: string, error: unknown, fallback: string): string {
+  if (!(error instanceof Error)) {
+    return fallback;
+  }
+  return truncateMessage(humanizeToolErrorMessage(toolName, error.message));
+}
+
+function summarizeApprovalReason(toolName: string, args: Record<string, unknown>): string {
+  if (toolName === "mail_send") {
+    const to = Array.isArray(args.to) ? args.to.length : 0;
+    return `Send email${to > 0 ? ` to ${to} recipient${to === 1 ? "" : "s"}` : ""}.`;
+  }
+  if (toolName === "messages_send") {
+    const to = Array.isArray(args.to) ? args.to.length : 0;
+    return `Send text message${to > 0 ? ` to ${to} recipient${to === 1 ? "" : "s"}` : ""}.`;
+  }
+  if (toolName === "music_set_volume" || toolName === "system_set_volume") {
+    const level = typeof args.level === "number" ? args.level : null;
+    return `Set volume${level !== null ? ` to ${level}%` : ""}.`;
+  }
+  if (toolName === "file_delete_to_trash") {
+    return "Move item to Trash.";
+  }
+  if (toolName === "workflow_run") {
+    return "Execute multi-step workflow with write/system/external operations.";
+  }
+  return `Approval required for ${toolName}.`;
+}
+
+function normalizeAliasText(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function resolveMusicAlias(query: string, aliases: MemoryMusicAlias[] | undefined): MemoryMusicAlias | null {
+  if (!Array.isArray(aliases) || aliases.length === 0) {
+    return null;
+  }
+
+  const normalizedQuery = normalizeAliasText(query);
+  if (!normalizedQuery) {
+    return null;
+  }
+
+  const scored = aliases
+    .map((alias) => {
+      const aliasText = typeof alias.alias === "string" ? alias.alias.trim() : "";
+      const targetQuery = typeof alias.query === "string" ? alias.query.trim() : "";
+      if (!aliasText || !targetQuery) {
+        return null;
+      }
+
+      const normalizedAlias = normalizeAliasText(aliasText);
+      if (!normalizedAlias) {
+        return null;
+      }
+
+      let score = 0;
+      if (normalizedAlias === normalizedQuery) {
+        score += 120;
+      } else if (
+        normalizedQuery.startsWith(`${normalizedAlias} `) ||
+        normalizedQuery.includes(` ${normalizedAlias}`)
+      ) {
+        score += 75;
+      }
+
+      const aliasTokens = normalizedAlias.split(" ").filter(Boolean);
+      if (aliasTokens.length > 0) {
+        const queryTokens = new Set(normalizedQuery.split(" ").filter(Boolean));
+        const overlap = aliasTokens.filter((token) => queryTokens.has(token)).length;
+        if (overlap === aliasTokens.length) {
+          score += 55;
+        } else if (overlap >= 2) {
+          score += 30;
+        }
+      }
+
+      return score > 0 ? { alias, score } : null;
+    })
+    .filter((item): item is { alias: MemoryMusicAlias; score: number } => Boolean(item))
+    .sort((left, right) => right.score - left.score);
+
+  if (scored.length === 0) {
+    return null;
+  }
+
+  const top = scored[0];
+  const runnerUp = scored[1];
+  const strongEnough = top.score >= 75;
+  const clearWinner = !runnerUp || top.score - runnerUp.score >= 20;
+  if (!strongEnough || !clearWinner) {
+    return null;
+  }
+  return top.alias;
+}
+
+function resolvePersonAlias(
+  input: string,
+  aliases: MemoryContextPayload["aliases"]["people"] | undefined,
+): string | null {
+  if (!Array.isArray(aliases) || aliases.length === 0) {
+    return null;
+  }
+
+  const normalizedInput = normalizeAliasText(input);
+  if (!normalizedInput) {
+    return null;
+  }
+
+  const scored = aliases
+    .map((alias) => {
+      const aliasText = typeof alias?.alias === "string" ? alias.alias.trim() : "";
+      const targetText = typeof alias?.target === "string" ? alias.target.trim() : "";
+      if (!aliasText || !targetText) {
+        return null;
+      }
+      const normalizedAlias = normalizeAliasText(aliasText);
+      if (!normalizedAlias) {
+        return null;
+      }
+
+      let score = 0;
+      if (normalizedAlias === normalizedInput) {
+        score += 120;
+      } else if (
+        normalizedInput.startsWith(`${normalizedAlias} `) ||
+        normalizedInput.includes(` ${normalizedAlias}`)
+      ) {
+        score += 75;
+      }
+
+      const aliasTokens = normalizedAlias.split(" ").filter(Boolean);
+      if (aliasTokens.length > 0) {
+        const inputTokens = new Set(normalizedInput.split(" ").filter(Boolean));
+        const overlap = aliasTokens.filter((token) => inputTokens.has(token)).length;
+        if (overlap === aliasTokens.length) {
+          score += 55;
+        } else if (overlap >= 2) {
+          score += 30;
+        }
+      }
+
+      return score > 0 ? { target: targetText, score } : null;
+    })
+    .filter((item): item is { target: string; score: number } => Boolean(item))
+    .sort((left, right) => right.score - left.score);
+
+  if (scored.length === 0) {
+    return null;
+  }
+  const top = scored[0];
+  const runnerUp = scored[1];
+  const strongEnough = top.score >= 75;
+  const clearWinner = !runnerUp || top.score - runnerUp.score >= 20;
+  if (!strongEnough || !clearWinner) {
+    return null;
+  }
+  return top.target;
+}
+
+function parseDirectMessageIntent(params: {
+  text: string;
+  peopleAliases?: MemoryContextPayload["aliases"]["people"];
+}): { to: string[]; body: string } | null {
+  const text = params.text.replace(/\s+/g, " ").trim();
+  if (!text) {
+    return null;
+  }
+
+  const separators = [
+    " that says ",
+    " saying ",
+    " with message ",
+    " saying that ",
+    " that ",
+    ": ",
+    " - ",
+  ];
+  const splitRecipientAndBody = (value: string): { recipient: string; body: string } | null => {
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (!compact) {
+      return null;
+    }
+    const lowered = compact.toLowerCase();
+    let bestIndex = -1;
+    let bestSeparator = "";
+    for (const separator of separators) {
+      const candidateIndex = lowered.indexOf(separator);
+      if (candidateIndex <= 0) {
+        continue;
+      }
+      if (bestIndex === -1 || candidateIndex < bestIndex) {
+        bestIndex = candidateIndex;
+        bestSeparator = separator;
+      }
+    }
+    if (bestIndex === -1) {
+      return null;
+    }
+    const recipient = compact.slice(0, bestIndex).trim();
+    const body = compact.slice(bestIndex + bestSeparator.length).trim();
+    if (!recipient || !body) {
+      return null;
+    }
+    return { recipient, body };
+  };
+
+  let recipientChunk = "";
+  let body = "";
+  const quotedSendMatch = text.match(/^\s*send\s+["'“”](.+?)["'“”]\s+to\s+(.+?)\s*$/i);
+  if (quotedSendMatch?.[1] && quotedSendMatch?.[2]) {
+    body = quotedSendMatch[1].trim();
+    recipientChunk = quotedSendMatch[2].trim();
+  }
+
+  if (!recipientChunk || !body) {
+    const sendToPrefix = text.match(/^\s*send\s+(?:a\s+)?(?:text(?:\s+message)?|message)\s+to\s+(.+)$/i);
+    if (sendToPrefix?.[1]) {
+      const split = splitRecipientAndBody(sendToPrefix[1]);
+      if (split) {
+        recipientChunk = split.recipient;
+        body = split.body;
+      }
+    }
+  }
+
+  if (!recipientChunk || !body) {
+    const directPrefix = text.match(/^\s*(?:text|message)\s+(.+)$/i);
+    if (directPrefix?.[1]) {
+      const split = splitRecipientAndBody(directPrefix[1]);
+      if (split) {
+        recipientChunk = split.recipient;
+        body = split.body;
+      }
+    }
+  }
+
+  if (!recipientChunk || !body) {
+    const sendTargetFirst = text.match(/^\s*send\s+(.+?)\s+(?:a\s+)?(?:text(?:\s+message)?|message)\s+(.+)$/i);
+    if (sendTargetFirst?.[1] && sendTargetFirst?.[2]) {
+      recipientChunk = sendTargetFirst[1].trim();
+      body = sendTargetFirst[2].trim();
+    }
+  }
+
+  if (!recipientChunk || !body) {
+    return null;
+  }
+
+  body = body
+    .replace(/^says?\s+/i, "")
+    .replace(/^saying\s+/i, "")
+    .trim()
+    .replace(/^['"]|['"]$/g, "")
+    .trim();
+  if (!body) {
+    return null;
+  }
+
+  const recipients = recipientChunk
+    .replace(/^to\s+/i, "")
+    .split(/\s*,\s*|\s+and\s+/i)
+    .map((value) => value.trim().replace(/[,:;]+$/g, "").replace(/^['"]|['"]$/g, ""))
+    .filter(Boolean)
+    .slice(0, 3);
+  if (recipients.length === 0) {
+    return null;
+  }
+
+  const normalizedRecipients = recipients.map((value) => {
+    const normalized = normalizeAliasText(value);
+    const blocked = normalized === "me" || normalized === "myself" || normalized === "us";
+    if (blocked) {
+      return "";
+    }
+    return resolvePersonAlias(value, params.peopleAliases) ?? value;
+  }).filter(Boolean);
+
+  if (normalizedRecipients.length === 0) {
+    return null;
+  }
+
+  return {
+    to: normalizedRecipients,
+    body,
+  };
+}
+
+function extractDirectMusicIntent(messages: ChatMessageInput[], aliases?: MemoryMusicAlias[]): {
+  query: string;
+  title: string | null;
+  artist: string | null;
+  volume: number | null;
+} | null {
+  const userMessages = messages.filter((message) => message.role === "user");
+  const lastUser = [...userMessages].reverse()[0];
+  if (!lastUser) {
+    return null;
+  }
+  const text = lastUser.content.trim();
+  if (!text) {
+    return null;
+  }
+
+  const parsePlayText = (value: string) => {
+    const playMatch = value.match(/play\s+(.+?)(?:\s+at\s+\d{1,3}\s*%|\s+volume|\s*$)/i);
+    if (!playMatch?.[1]) {
+      return null;
+    }
+    const raw = playMatch[1]
+      .replace(/\bvia apple music app\b/gi, "")
+      .replace(/\bon apple music\b/gi, "")
+      .trim();
+    if (!raw) {
+      return null;
+    }
+    const bySplit = raw.split(/\s+by\s+/i);
+    const hasExplicitArtist = bySplit.length > 1;
+    const title = hasExplicitArtist ? bySplit[0]?.trim() || null : null;
+    const artist = hasExplicitArtist ? bySplit.slice(1).join(" by ").trim() : null;
+    return {
+      query: raw,
+      title,
+      artist,
+    };
+  };
+
+  let parsed = parsePlayText(text);
+  if (!parsed) {
+    const notPlayingFollowup = /not playing|isn['’]?t playing|is not playing|not playing yet/i.test(text);
+    if (!notPlayingFollowup) {
+      return null;
+    }
+    const priorPlayable = [...userMessages].reverse().find((message) =>
+      /play\s+/i.test(message.content),
+    );
+    if (!priorPlayable) {
+      return null;
+    }
+    parsed = parsePlayText(priorPlayable.content);
+    if (!parsed) {
+      return null;
+    }
+  }
+
+  const query = parsed.query.trim();
+  if (!query) {
+    return null;
+  }
+  const resolvedAlias = resolveMusicAlias(query, aliases);
+
+  const volumeMatch = text.match(/(\d{1,3})\s*%/);
+  const volume = volumeMatch ? Math.max(0, Math.min(100, Number(volumeMatch[1]))) : null;
+  return {
+    query: resolvedAlias?.query?.trim() || query,
+    title: resolvedAlias?.title?.trim() || parsed.title,
+    artist: resolvedAlias?.artist?.trim() || parsed.artist,
+    volume: Number.isFinite(volume as number) ? volume : null,
+  };
+}
+
+function titleCase(input: string): string {
+  return input.replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function inferNoteTopic(messages: ChatMessageInput[]): { title: string; topic: string } | null {
+  const userMessages = messages.filter((message) => message.role === "user");
+  const lastUser = [...userMessages].reverse()[0];
+  if (!lastUser) {
+    return null;
+  }
+
+  const text = lastUser.content.trim();
+  const noteMatch = text.match(/\b(?:create|make|write)\b.*\bnote\b(?:\s+about|\s+on|\s+for|\s+titled)?\s+(.+)$/i);
+  if (!noteMatch?.[1]) {
+    return null;
+  }
+
+  const topic = noteMatch[1]
+    .replace(/[.?!]+$/g, "")
+    .replace(/^['"]|['"]$/g, "")
+    .trim();
+  if (!topic) {
+    return null;
+  }
+
+  return {
+    topic,
+    title: titleCase(topic),
+  };
+}
+
+function inferDetailedNoteFollowup(messages: ChatMessageInput[]): { title: string; topic: string } | null {
+  const userMessages = messages.filter((message) => message.role === "user");
+  const lastUser = [...userMessages].reverse()[0];
+  if (!lastUser) {
+    return null;
+  }
+
+  if (!/\b(more detail|detailed|in depth|in-depth|comprehensive|expand)\b/i.test(lastUser.content)) {
+    return null;
+  }
+
+  for (let index = userMessages.length - 2; index >= 0; index -= 1) {
+    const candidate = inferNoteTopic(userMessages.slice(0, index + 1));
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function shouldBypassDirectFastPathForCompoundRequest(input: string): boolean {
+  const text = input.toLowerCase().replace(/\s+/g, " ").trim();
+  if (!text) {
+    return false;
+  }
+  const clauses = splitCompoundActionClauses(text);
+  if (clauses.length < 2) {
+    return false;
+  }
+
+  const domainPatterns: RegExp[] = [
+    /\b(play|music|song|track|volume)\b/i,
+    /\b(note|notes|apple notes|write down|jot)\b/i,
+    /\b(remind|reminder|calendar|event|schedule)\b/i,
+    /\b(open|launch|focus app|application)\b/i,
+    /\b(email|mail|message|text)\b/i,
+    /\b(file|folder|directory|move|copy|delete|trash)\b/i,
+  ];
+  const matchedDomains = new Set<number>();
+  for (const clause of clauses) {
+    domainPatterns.forEach((pattern, index) => {
+      if (pattern.test(clause)) {
+        matchedDomains.add(index);
+      }
+    });
+  }
+  return matchedDomains.size >= 2;
+}
+
+function sanitizeReminderTitle(input: string): string {
+  return input
+    .replace(/^(?:at|for)\s+\d{1,2}(?::\d{2})?\s*(?:am|pm)\b/i, "")
+    .replace(/^\d{1,2}(?::\d{2})?\s*(?:am|pm)\b/i, "")
+    .replace(
+      new RegExp(
+        `\\s+(?:and|then|also|plus|next|finally|lastly|after that)\\s+(?=(?:${ACTION_VERB_PATTERN})\\b)[\\s\\S]*$`,
+        "i",
+      ),
+      "",
+    )
+    .replace(
+      new RegExp(`\\s*(?:,|;)\\s*(?=(?:${SEQUENCE_MARKER_PATTERN}|${ACTION_VERB_PATTERN})\\b)[\\s\\S]*$`, "i"),
+      "",
+    )
+    .replace(/\s+(?:at|for)\s+\d{1,2}(?::\d{2})?\s*(?:am|pm)\b(?:\s+(?:today|tomorrow))?$/i, "")
+    .replace(/\s+(?:for|at)\s+(?:today|tomorrow|next\s+\w+|this\s+\w+|upcoming\s+\w+)$/i, "")
+    .replace(/^(?:that|to|for|about|i have to)\s+/i, "")
+    .replace(/[.?!]+$/g, "")
+    .trim();
+}
+
+function buildDetailedNoteBody(topic: string): string {
+  const normalizedTopic = topic.trim();
+  const topicLower = normalizedTopic.toLowerCase();
+
+  if (/\bfood allerg(y|ies)\b/i.test(topicLower)) {
+    return [
+      "## Overview",
+      "**Food allergies** are immune-system reactions to specific foods. Reactions can range from mild symptoms to severe, life-threatening anaphylaxis, so prevention and a clear response plan matter.",
+      "",
+      "## Snapshot",
+      "| Area | Key Points |",
+      "| --- | --- |",
+      "| Definition | Immune response triggered by specific foods. |",
+      "| Highest Risk | Rapid-onset breathing trouble, throat swelling, fainting. |",
+      "| Priority | Strict avoidance + clear emergency action plan. |",
+      "",
+      "## Common Triggers",
+      "- Peanuts and tree nuts (almonds, cashews, walnuts, pistachios)",
+      "- Milk and egg",
+      "- Wheat and soy",
+      "- Fish and shellfish",
+      "- Sesame",
+      "",
+      "## Typical Symptoms",
+      "- Skin: itching, hives, flushing, swelling",
+      "- GI: nausea, vomiting, cramps, diarrhea",
+      "- Respiratory: cough, wheeze, throat tightness, trouble breathing",
+      "- Cardiovascular/neuro: dizziness, fainting, confusion",
+      "",
+      "## Red Flags (Emergency)",
+      "- Trouble breathing or swallowing",
+      "- Swelling of tongue/lips/throat",
+      "- Repeated vomiting after exposure",
+      "- Sudden dizziness or fainting",
+      "",
+      "## Action Plan",
+      "1. **Avoid** known trigger foods and cross-contact.",
+      "2. **Read labels** every time (ingredients can change).",
+      "3. **Carry prescribed emergency medication** (e.g., epinephrine) if indicated.",
+      "4. **Use emergency medication immediately** for severe symptoms.",
+      "5. **Call emergency services** after epinephrine use.",
+      "",
+      "## Daily Prevention Checklist",
+      "- Confirm safe meal options before eating out.",
+      "- Keep ingredient lists for frequently used products.",
+      "- Inform school/work/family about allergy and emergency steps.",
+      "- Keep meds accessible and not expired.",
+      "",
+      "## Medical Follow-up",
+      "- Confirm diagnosis with an allergist (history + testing).",
+      "- Review whether oral food challenge is appropriate.",
+      "- Recheck plan annually or after any serious reaction.",
+      "",
+      "## Notes",
+      "**This is an educational summary, not personal medical advice.** Use clinician guidance for diagnosis and treatment decisions.",
+    ].join("\n");
+  }
+
+  return [
+    "## Overview",
+    `This note captures a detailed, practical view of **${normalizedTopic}**.`,
+    "",
+    "## Snapshot",
+    "| Dimension | Summary |",
+    "| --- | --- |",
+    `| Objective | Define a concrete, measurable outcome for ${normalizedTopic}. |`,
+    "| Constraints | Account for time, ownership, and available resources. |",
+    "| Success Signal | Use evidence-based checkpoints and review cadence. |",
+    "",
+    "## Core Concepts",
+    `- **What ${normalizedTopic} is** and why it matters`,
+    `- **Main factors** that influence outcomes in ${normalizedTopic}`,
+    `- **Common misconceptions** that cause mistakes`,
+    "",
+    "## Practical Framework",
+    "1. **Clarify the objective** and success criteria.",
+    "2. **Identify constraints** (time, resources, stakeholders).",
+    "3. **Break work into small, testable steps.**",
+    "4. **Track results and adjust** based on evidence.",
+    "",
+    "## Risks and Failure Modes",
+    "- Ambiguous goals or undefined ownership",
+    "- Inconsistent execution over time",
+    "- Missing feedback loops and measurement",
+    "",
+    "## Implementation Checklist",
+    "- Define clear next actions for this week",
+    "- Set a simple review cadence",
+    "- Document decisions and assumptions",
+    "- Capture open questions for follow-up",
+    "",
+    "## Next Steps",
+    `If needed, expand this into a deeper version with examples, templates, and references tailored to **${normalizedTopic}**.`,
+  ].join("\n");
+}
+
+async function tryDirectAutomationFastPath(params: {
+  localTools: LocalToolsSettings;
+  messages: ChatMessageInput[];
+  memory?: MemoryContextPayload | null;
+  send: (chunk: ChatStreamChunk) => void;
+  signal?: AbortSignal;
+}): Promise<boolean> {
+  if (!params.localTools.enabled) {
+    return false;
+  }
+
+  const tools = createToolRegistry(params.localTools);
+  const lastUser = [...params.messages].reverse().find((message) => message.role === "user");
+  const lastUserText = lastUser?.content.trim() ?? "";
+  if (shouldBypassDirectFastPathForCompoundRequest(lastUserText)) {
+    return false;
+  }
+
+  const parseReminderIntent = (text: string): { title: string; due?: string } | null => {
+    if (!/\b(reminder|remind me)\b/i.test(text)) {
+      return null;
+    }
+    const weekdays = [
+      "sunday",
+      "monday",
+      "tuesday",
+      "wednesday",
+      "thursday",
+      "friday",
+      "saturday",
+    ] as const;
+    const weekdayIndex = Object.fromEntries(weekdays.map((day, index) => [day, index])) as Record<
+      (typeof weekdays)[number],
+      number
+    >;
+    const normalizedText = text.replace(/\bthis\s+upcoming\s+/gi, "upcoming ");
+    const timeMatch = normalizedText.match(/\b(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)\b/i);
+    const weekdayMatch = normalizedText.match(
+      /\b(?:(this|next|upcoming)\s+)?(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/i,
+    );
+    const hasTomorrow = /\btomorrow\b/i.test(normalizedText);
+    const hasToday = /\btoday\b/i.test(normalizedText);
+
+    const toIsoLocal = (value: Date) => {
+      const yyyy = value.getFullYear();
+      const mm = String(value.getMonth() + 1).padStart(2, "0");
+      const dd = String(value.getDate()).padStart(2, "0");
+      const hh = String(value.getHours()).padStart(2, "0");
+      const min = String(value.getMinutes()).padStart(2, "0");
+      return `${yyyy}-${mm}-${dd}T${hh}:${min}:00`;
+    };
+
+    const resolveDueBaseDate = () => {
+      const base = new Date();
+      if (hasTomorrow) {
+        base.setDate(base.getDate() + 1);
+        return base;
+      }
+      if (hasToday) {
+        return base;
+      }
+      if (!weekdayMatch?.[2]) {
+        return null;
+      }
+      const modifier = weekdayMatch[1]?.toLowerCase();
+      const targetDay = weekdayMatch[2].toLowerCase() as (typeof weekdays)[number];
+      const todayDay = base.getDay();
+      let delta = (weekdayIndex[targetDay] - todayDay + 7) % 7;
+
+      if (modifier === "next") {
+        if (delta === 0) {
+          delta = 7;
+        }
+      } else if (modifier === "this") {
+        if (delta === 0 && !timeMatch) {
+          delta = 0;
+        }
+      } else if (delta === 0) {
+        delta = 7;
+      }
+
+      base.setDate(base.getDate() + delta);
+      return base;
+    };
+
+    let due: string | undefined;
+    const dueBaseDate = resolveDueBaseDate();
+    if (timeMatch) {
+      const hoursRaw = Number(timeMatch[1]);
+      const minutesRaw = Number(timeMatch[2] ?? "0");
+      const meridiem = timeMatch[3].toLowerCase();
+      let hours24 = hoursRaw % 12;
+      if (meridiem === "pm") {
+        hours24 += 12;
+      }
+
+      if (dueBaseDate) {
+        dueBaseDate.setHours(hours24, minutesRaw, 0, 0);
+        due = toIsoLocal(dueBaseDate);
+      } else {
+        const base = new Date();
+        base.setHours(hours24, minutesRaw, 0, 0);
+        if (base.getTime() < Date.now() - 60_000) {
+          base.setDate(base.getDate() + 1);
+        }
+        due = toIsoLocal(base);
+      }
+    } else if (dueBaseDate) {
+      due = toIsoLocal(dueBaseDate);
+    }
+
+    const dateStopPattern =
+      "\\s+(?:at\\s+.+|today|tomorrow|this\\s+upcoming\\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|this\\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|next\\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|upcoming\\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|sunday|monday|tuesday|wednesday|thursday|friday|saturday|$)";
+    const aboutMatch = normalizedText.match(/\babout\s+(.+)$/i);
+    const reminderToMatch = normalizedText.match(
+      /\breminder\b(?:\s+for\s+[^,.;!?]+|\s+at\s+[^,.;!?]+)?\s+to\s+(.+)$/i,
+    );
+    const toMatch = normalizedText.match(
+      new RegExp(`\\bremind me(?:\\s+to)?\\s+(.+?)(?:${dateStopPattern})`, "i"),
+    );
+    const reminderDateThenTitleMatch = normalizedText.match(
+      /\breminder\b(?:\s+for\s+(?:this\s+upcoming|this|next|upcoming)?\s*(?:today|tomorrow|sunday|monday|tuesday|wednesday|thursday|friday|saturday))\s+(?:for|about)\s+(.+?)(?:\s+at\s+.+|$)/i,
+    );
+    const reminderForMatch = normalizedText.match(
+      new RegExp(
+        `\\breminder(?:\\s+that)?\\s+(.+?)(?:\\s+for\\s+\\d{1,2}(?::\\d{2})?\\s*(?:am|pm)|${dateStopPattern})`,
+        "i",
+      ),
+    );
+    const forAboutMatch = normalizedText.match(
+      /\breminder\b(?:\s+for\s+\d{1,2}(?::\d{2})?\s*(?:am|pm))?(?:\s+(?:tomorrow|today|this\s+upcoming\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|this\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|next\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)|upcoming\s+(?:sunday|monday|tuesday|wednesday|thursday|friday|saturday)))?\s+about\s+(.+)$/i,
+    );
+    const rawTitle =
+      aboutMatch?.[1]?.trim() ||
+      reminderToMatch?.[1]?.trim() ||
+      reminderDateThenTitleMatch?.[1]?.trim() ||
+      forAboutMatch?.[1]?.trim() ||
+      toMatch?.[1]?.trim() ||
+      reminderForMatch?.[1]?.trim() ||
+      "Reminder";
+    const title = sanitizeReminderTitle(
+      rawTitle
+      .replace(/^(that|i have to|to|for)\s+/i, "")
+      .trim(),
+    );
+
+    return { title: title || "Reminder", due };
+  };
+
+  // Fast path 1: reminders
+  const reminderIntent = parseReminderIntent(lastUserText);
+  if (params.localTools.enableCalendar && reminderIntent) {
+    const reminderTool = findToolByName(tools, "reminder_create");
+    if (reminderTool) {
+      if (requiresApprovalForRisk(reminderTool.risk, params.localTools.approvalMode)) {
+        return false;
+      }
+
+      const { title, due } = reminderIntent;
+      const dueDateOnly = due?.match(/^\d{4}-\d{2}-\d{2}/)?.[0] ?? due;
+
+      const callId = "fastpath_reminder_create";
+      params.send({
+        type: "tool_call",
+        callId,
+        name: reminderTool.name,
+        args: { title, due },
+      });
+      params.send({
+        type: "tool_progress",
+        callId,
+        name: reminderTool.name,
+        status: "started",
+        message: "Creating reminder.",
+      });
+      try {
+        const output = await reminderTool.execute(
+          { title, due },
+          { localTools: params.localTools, signal: params.signal },
+        );
+        params.send({
+          type: "tool_result",
+          callId,
+          name: reminderTool.name,
+          ok: true,
+          result: output,
+        });
+        params.send({
+          type: "token",
+          value: `**Done.** Created reminder "${title}"${dueDateOnly ? ` for ${dueDateOnly}` : ""}.`,
+        });
+      } catch (error) {
+        const message = formatToolErrorForUser(
+          reminderTool.name,
+          error,
+          "Could not create reminder.",
+        );
+        params.send({
+          type: "tool_result",
+          callId,
+          name: reminderTool.name,
+          ok: false,
+          result: { error: message },
+        });
+        params.send({
+          type: "token",
+          value:
+            `I couldn't confirm reminder creation: ${message}. ` +
+            "I did not auto-retry to avoid duplicate reminders.",
+        });
+      }
+      return true;
+    }
+  }
+
+  // Fast path 2: direct text/iMessage
+  const messageIntent = parseDirectMessageIntent({
+    text: lastUserText,
+    peopleAliases: params.memory?.enabled ? params.memory.aliases.people : [],
+  });
+  if (messageIntent) {
+    if (!params.localTools.enableMail) {
+      params.send({
+        type: "token",
+        value:
+          "Messaging tools are disabled. Enable **mail/messages tools** in Settings > Local Tools, then retry.",
+      });
+      return true;
+    }
+
+    const messageTool = findToolByName(tools, "messages_send");
+    if (messageTool) {
+      if (requiresApprovalForRisk(messageTool.risk, params.localTools.approvalMode)) {
+        return false;
+      }
+
+      const callId = "fastpath_messages_send";
+      const args = {
+        to: messageIntent.to,
+        body: messageIntent.body,
+      };
+      params.send({
+        type: "tool_call",
+        callId,
+        name: messageTool.name,
+        args,
+      });
+      params.send({
+        type: "tool_progress",
+        callId,
+        name: messageTool.name,
+        status: "started",
+        message: "Sending message.",
+      });
+
+      try {
+        const output = await messageTool.execute(args, {
+          localTools: params.localTools,
+          signal: params.signal,
+        });
+        params.send({
+          type: "tool_result",
+          callId,
+          name: messageTool.name,
+          ok: true,
+          result: output,
+        });
+
+        const outputRecord =
+          output && typeof output === "object"
+            ? (output as { recipients?: Array<{ name?: string | null; input?: string; handle?: string }> })
+            : null;
+        const recipientLabel =
+          outputRecord?.recipients?.map((recipient) => recipient.name || recipient.input || recipient.handle)
+            .filter(Boolean)
+            .join(", ") || messageIntent.to.join(", ");
+
+        params.send({
+          type: "token",
+          value: `**Done.** Sent message to ${recipientLabel}.`,
+        });
+      } catch (error) {
+        const message = formatToolErrorForUser(
+          messageTool.name,
+          error,
+          "Could not send message.",
+        );
+        params.send({
+          type: "tool_result",
+          callId,
+          name: messageTool.name,
+          ok: false,
+          result: { error: message },
+        });
+        params.send({
+          type: "token",
+          value: `I couldn't send that message: ${message}.`,
+        });
+      }
+      return true;
+    }
+  }
+
+  // Fast path 3: quick-note capture only (defer richer notes to model planning)
+  const noteFollowup = inferDetailedNoteFollowup(params.messages);
+  const noteIntent = noteFollowup ?? inferNoteTopic(params.messages);
+  const isQuickNoteRequest =
+    /\b(quick note|jot(?:\s+this|\s+that|\s+it|\s+down)?|capture (?:this|that|it) (?:as a )?note)\b/i.test(
+      lastUserText,
+    );
+  if (params.localTools.enableNotes && noteIntent && isQuickNoteRequest) {
+    const noteTool = findToolByName(tools, "notes_create_or_append");
+    if (noteTool) {
+      if (requiresApprovalForRisk(noteTool.risk, params.localTools.approvalMode)) {
+        return false;
+      }
+
+      const title = noteIntent.title;
+      const body = buildDetailedNoteBody(noteIntent.topic);
+
+      const callId = "fastpath_note_create";
+      params.send({
+        type: "tool_call",
+        callId,
+        name: noteTool.name,
+        args: { title, body, mode: "create" },
+      });
+      params.send({
+        type: "tool_progress",
+        callId,
+        name: noteTool.name,
+        status: "started",
+        message: noteFollowup ? "Updating note with more detail." : "Creating detailed note.",
+      });
+      try {
+        const output = await noteTool.execute(
+          { title, body, mode: "create" },
+          { localTools: params.localTools, signal: params.signal },
+        );
+        params.send({
+          type: "tool_result",
+          callId,
+          name: noteTool.name,
+          ok: true,
+          result: output,
+        });
+        params.send({
+          type: "token",
+          value: noteFollowup
+            ? `**Done.** Updated note "${title}" with more detail.`
+            : `**Done.** Created detailed note "${title}".`,
+        });
+      } catch (error) {
+        const message = formatToolErrorForUser(noteTool.name, error, "Could not create note.");
+        params.send({
+          type: "tool_result",
+          callId,
+          name: noteTool.name,
+          ok: false,
+          result: { error: message },
+        });
+        params.send({
+          type: "token",
+          value: `I couldn't create that note: ${message}.`,
+        });
+      }
+      return true;
+    }
+  }
+
+  if (!params.localTools.enableMusic) {
+    return false;
+  }
+
+  const intent = extractDirectMusicIntent(
+    params.messages,
+    params.memory?.enabled ? params.memory.aliases.music : [],
+  );
+  if (!intent) {
+    return false;
+  }
+
+  const playTool = findToolByName(tools, "music_play");
+  const volumeTool = findToolByName(
+    tools,
+    params.localTools.enableSystem ? "system_set_volume" : "music_set_volume",
+  );
+  if (!playTool) {
+    return false;
+  }
+  if (requiresApprovalForRisk(playTool.risk, params.localTools.approvalMode)) {
+    return false;
+  }
+  if (
+    intent.volume !== null &&
+    volumeTool &&
+    requiresApprovalForRisk(volumeTool.risk, params.localTools.approvalMode)
+  ) {
+    return false;
+  }
+
+  const playCallId = "fastpath_music_play";
+  params.send({
+    type: "tool_call",
+    callId: playCallId,
+    name: playTool.name,
+    args: {
+      query: intent.query,
+      title: intent.title,
+      artist: intent.artist,
+      source: "apple_music",
+    },
+  });
+  params.send({
+    type: "tool_progress",
+    callId: playCallId,
+    name: playTool.name,
+    status: "started",
+    message: "Starting playback.",
+  });
+  let playOutput: unknown;
+  try {
+    playOutput = await playTool.execute(
+      {
+        query: intent.query,
+        title: intent.title,
+        artist: intent.artist,
+        source: "apple_music",
+      },
+      { localTools: params.localTools, signal: params.signal },
+    );
+  } catch (error) {
+    const message = formatToolErrorForUser(playTool.name, error, "Could not start playback.");
+    params.send({
+      type: "tool_result",
+      callId: playCallId,
+      name: playTool.name,
+      ok: false,
+      result: { error: message },
+    });
+    params.send({
+      type: "token",
+      value: `I couldn't start Apple Music playback: ${message}.`,
+    });
+    return true;
+  }
+
+  const playResult =
+    playOutput && typeof playOutput === "object"
+      ? (playOutput as {
+          playing?: boolean;
+          matched?: boolean;
+          playlistName?: string | null;
+          title?: string | null;
+          artist?: string | null;
+          album?: string | null;
+          reason?: string | null;
+          matchedTitle?: string | null;
+          matchedArtist?: string | null;
+          catalogTitle?: string | null;
+          catalogArtist?: string | null;
+        })
+      : null;
+
+  if (!playResult || playResult.playing !== true) {
+    params.send({
+      type: "tool_result",
+      callId: playCallId,
+      name: playTool.name,
+      ok: false,
+      result: playOutput ?? { error: "Unable to start playback." },
+    });
+    const reason =
+      typeof playResult?.reason === "string" && playResult.reason.trim()
+        ? playResult.reason.trim()
+        : null;
+    params.send({
+      type: "token",
+      value:
+        reason
+          ? `I couldn't start that track automatically in Apple Music: ${reason}`
+          : "I couldn't start that track automatically in Apple Music. Please retry once with the exact song title and artist.",
+    });
+    return true;
+  }
+  params.send({
+    type: "tool_result",
+    callId: playCallId,
+    name: playTool.name,
+    ok: true,
+    result: playOutput,
+  });
+
+  const resolvedTitle =
+    typeof playResult.title === "string" && playResult.title.trim()
+      ? playResult.title.trim()
+      : intent.title || intent.query;
+  const resolvedArtist =
+    typeof playResult.artist === "string" && playResult.artist.trim()
+      ? playResult.artist.trim()
+      : intent.artist;
+  const resolvedPlaylistName =
+    typeof playResult.playlistName === "string" && playResult.playlistName.trim()
+      ? playResult.playlistName.trim()
+      : null;
+  const isSpecificSongRequest = Boolean(intent.title || intent.artist);
+  const hasNearbyMatch =
+    playResult.matched === false &&
+    isSpecificSongRequest &&
+    typeof playResult.reason === "string" &&
+    playResult.reason.trim().length > 0;
+
+  if (intent.volume !== null && volumeTool) {
+    const volumeCallId = "fastpath_set_volume";
+    params.send({
+      type: "tool_call",
+      callId: volumeCallId,
+      name: volumeTool.name,
+      args: { level: intent.volume },
+    });
+    params.send({
+      type: "tool_progress",
+      callId: volumeCallId,
+      name: volumeTool.name,
+      status: "started",
+      message: `Setting volume to ${intent.volume}%.`,
+    });
+    try {
+      const volumeOutput = await volumeTool.execute(
+        { level: intent.volume },
+        { localTools: params.localTools, signal: params.signal },
+      );
+      params.send({
+        type: "tool_result",
+        callId: volumeCallId,
+        name: volumeTool.name,
+        ok: true,
+        result: volumeOutput,
+      });
+    } catch (error) {
+      const message = formatToolErrorForUser(volumeTool.name, error, "Could not set volume.");
+      params.send({
+        type: "tool_result",
+        callId: volumeCallId,
+        name: volumeTool.name,
+        ok: false,
+        result: { error: message },
+      });
+      params.send({
+        type: "token",
+        value:
+          `Started playback for "${resolvedTitle}", but couldn't set volume: ${message}.`,
+      });
+      return true;
+    }
+  }
+
+  params.send({
+      type: "token",
+      value:
+        hasNearbyMatch
+          ? `Started nearby match "${resolvedTitle}"${resolvedArtist ? ` by ${resolvedArtist}` : ""}. ${playResult.reason}`
+          : resolvedPlaylistName && intent.volume !== null
+            ? `**Done.** Playing playlist "${resolvedPlaylistName}" in Apple Music and set volume to ${intent.volume}%.`
+            : resolvedPlaylistName
+              ? `**Done.** Playing playlist "${resolvedPlaylistName}" in Apple Music.`
+          : intent.volume !== null
+              ? `**Done.** Playing "${resolvedTitle}"${resolvedArtist ? ` by ${resolvedArtist}` : ""} in Apple Music and set volume to ${intent.volume}%.`
+              : `**Done.** Playing "${resolvedTitle}"${resolvedArtist ? ` by ${resolvedArtist}` : ""} in Apple Music.`,
+    });
+  return true;
+}
+
+async function streamPlainChat(params: {
+  connection: RuntimeConnection;
+  model: string;
+  system?: string;
+  messages: ChatMessageInput[];
+  enableWebSources: boolean;
+  send: (chunk: ChatStreamChunk) => void;
+  signal?: AbortSignal;
+}) {
+  if (params.connection.kind === "ollama") {
+    await streamOllamaChat({
+      baseUrl: params.connection.baseUrl ?? "http://localhost:11434",
+      model: params.model,
+      messages: params.messages,
+      signal: params.signal,
+      onToken: (value) => emitTokenText(params.send, value),
+    });
+    return;
+  }
+
+  if (params.connection.kind === "builtin" && params.connection.provider === "anthropic") {
+    if (!params.connection.apiKey) {
+      throw new Error("Missing Anthropic API key for this connection.");
+    }
+    const client = new Anthropic({ apiKey: params.connection.apiKey });
+    const response = await client.messages.stream({
+      model: params.model,
+      max_tokens: 1024,
+      system: params.system,
+      messages: params.messages.map((message) => ({
+        role: message.role === "assistant" ? "assistant" : "user",
+        content: message.content,
+      })),
+    });
+
+    for await (const event of response) {
+      if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+        emitTokenText(params.send, event.delta.text);
+      }
+    }
+    return;
+  }
+
+  const openAIBaseURL =
+    params.connection.kind === "openai_compatible"
+      ? params.connection.baseUrl
+      : params.connection.kind === "builtin" && params.connection.provider === "google"
+        ? params.connection.baseUrl ?? GEMINI_OPENAI_BASE_URL
+        : undefined;
+  const openAIHeaders = headersArrayToRecord(params.connection.headers);
+  const client = new OpenAI({
+    apiKey: params.connection.apiKey ?? "no-key-required",
+    baseURL: openAIBaseURL,
+    defaultHeaders: openAIHeaders,
+  });
+  const useWebSources =
+    params.enableWebSources && supportsWebSourcesViaOpenAI(params.connection);
+  const response = await client.responses.create(
+    {
+      model: params.model,
+      instructions: params.system,
+      input: params.messages.map((message) => ({
+        type: "message",
+        role: message.role,
+        content: message.content,
+      })),
+      tools: useWebSources ? [{ type: "web_search" }] : undefined,
+      tool_choice: useWebSources ? "auto" : undefined,
+      include: useWebSources ? ["web_search_call.action.sources"] : undefined,
+      stream: true,
+    },
+    { signal: params.signal },
+  );
+
+  const gatheredSources = new Map<string, ProviderCitationSource>();
+
+  for await (const event of response) {
+    const eventAny = event as {
+      type: string;
+      delta?: string;
+      error?: { message?: string };
+      response?: { output?: unknown };
+      annotation?: unknown;
+    };
+    if (eventAny.type === "response.output_text.delta") {
+      emitTokenText(params.send, eventAny.delta ?? "");
+      continue;
+    }
+    if (eventAny.type === "response.output_text.annotation.added") {
+      const source = sourceFromAnnotation(eventAny.annotation);
+      mergeCitationSources(gatheredSources, source ? [source] : undefined);
+      continue;
+    }
+    if (eventAny.type === "response.completed") {
+      mergeCitationSources(
+        gatheredSources,
+        extractCitationSourcesFromResponse(eventAny.response ?? {}),
+      );
+      continue;
+    }
+    if (eventAny.type === "response.error") {
+      params.send({
+        type: "error",
+        error: eventAny.error?.message || "OpenAI-compatible response error",
+      });
+    }
+  }
+
+  const sources = [...gatheredSources.values()];
+  if (sources.length > 0) {
+    params.send({
+      type: "sources",
+      items: sources,
+    });
+  }
+}
+
+function getToolSession(params: {
+  connection: RuntimeConnection;
+  model: string;
+  system?: string;
+  messages: ChatMessageInput[];
+  localTools: LocalToolsSettings;
+  enableWebSources: boolean;
+}): {
+  session: ToolProviderSession;
+  tools: ReturnType<typeof createToolRegistry>;
+} {
+  const tools = createToolRegistry(params.localTools);
+  const schemas = toProviderToolSchemas(tools);
+  const turns = createToolMessages(params.messages, params.system);
+
+  if (params.connection.kind === "builtin" && params.connection.provider === "anthropic") {
+    if (!params.connection.apiKey) {
+      throw new Error("Missing Anthropic API key for this connection.");
+    }
+    return {
+      tools,
+      session: createAnthropicSession({
+        model: params.model,
+        apiKey: params.connection.apiKey,
+        system: params.system,
+        messages: turns,
+        tools: schemas,
+      }),
+    };
+  }
+
+  if (params.connection.kind === "ollama") {
+    throw new Error("Ollama tool sessions are not supported in this build.");
+  }
+
+  const baseURL =
+    params.connection.kind === "openai_compatible"
+      ? params.connection.baseUrl
+      : params.connection.kind === "builtin" && params.connection.provider === "google"
+        ? params.connection.baseUrl ?? GEMINI_OPENAI_BASE_URL
+        : undefined;
+  const defaultHeaders = headersArrayToRecord(params.connection.headers);
+  if (params.connection.kind === "openai_compatible") {
+    if (!baseURL) {
+      throw new Error("OpenAI-compatible connection is missing baseUrl.");
+    }
+    return {
+      tools,
+      session: createOpenAICompatibleSession({
+        model: params.model,
+        apiKey: params.connection.apiKey ?? "no-key-required",
+        system: params.system,
+        messages: turns,
+        tools: schemas,
+        enableWebSources: params.enableWebSources,
+        baseURL,
+        defaultHeaders,
+      }),
+    };
+  }
+
+  return {
+    tools,
+    session: createOpenAISession({
+      model: params.model,
+      apiKey: params.connection.apiKey ?? "no-key-required",
+      system: params.system,
+      messages: turns,
+      tools: schemas,
+      enableWebSources: params.enableWebSources,
+      baseURL,
+      defaultHeaders,
+    }),
+  };
+}
+
+async function runToolOrchestrator(params: {
+  connection: RuntimeConnection;
+  model: string;
+  system?: string;
+  messages: ChatMessageInput[];
+  localTools: LocalToolsSettings;
+  enableWebSources: boolean;
+  send: (chunk: ChatStreamChunk) => void;
+  signal?: AbortSignal;
+}) {
+  const { tools, session } = getToolSession({
+    connection: params.connection,
+    model: params.model,
+    system: buildToolSystemPrompt(params.system, params.messages),
+    messages: params.messages,
+    localTools: params.localTools,
+    enableWebSources: params.enableWebSources,
+  });
+
+  if (tools.length === 0) {
+    params.send({
+      type: "tool_progress",
+      callId: "tooling",
+      name: "tooling",
+      status: "warning",
+      message: "Local tools are enabled but no tool categories are active in settings.",
+    });
+    return;
+  }
+
+  let emittedAssistantText = false;
+  let sawSuccessfulToolResult = false;
+  const gatheredSources = new Map<string, ProviderCitationSource>();
+  const emitSourcesIfPresent = () => {
+    const sources = [...gatheredSources.values()];
+    if (sources.length > 0) {
+      params.send({
+        type: "sources",
+        items: sources,
+      });
+    }
+  };
+  const emitThinkingUpdate = (summary: string) => {
+    emitThinking(params.send, "update", summary);
+  };
+
+  for (let stepIndex = 0; stepIndex < MAX_TOOL_STEPS; stepIndex += 1) {
+    if (params.signal?.aborted) {
+      throw new Error("Request aborted.");
+    }
+
+    emitThinkingUpdate(
+      stepIndex === 0
+        ? "Planning your request and choosing the next action."
+        : "Reviewing results and deciding the next step.",
+    );
+    const step = await session.step(params.signal);
+    mergeCitationSources(gatheredSources, step.sources);
+
+    const modelRefusalLikeText =
+      params.localTools.enabled &&
+      /\b(can(?:not|'t)|unable|don't have)\b[\s\S]{0,80}\b(control|access|create|set|play|open)\b[\s\S]{0,80}\b(device|here|from here)\b/i.test(
+        step.text,
+      );
+    const shouldEmitText = !modelRefusalLikeText;
+
+    if (shouldEmitText) {
+      emitTokenText(params.send, step.text, (token) => {
+        if (!emittedAssistantText && token.trim()) {
+          emittedAssistantText = true;
+        }
+      });
+    }
+
+    if (step.toolCalls.length === 0) {
+      if (modelRefusalLikeText && !sawSuccessfulToolResult) {
+        params.send({
+          type: "token",
+          value:
+            "I hit a local-tool planning issue on that request. Please repeat the action once and I will execute it directly.",
+        });
+        return;
+      }
+      if (sawSuccessfulToolResult && !emittedAssistantText) {
+        params.send({ type: "token", value: "**Done.** I completed that request." });
+      }
+      emitSourcesIfPresent();
+      return;
+    }
+
+    emitThinkingUpdate("Executing requested actions.");
+    for (const call of step.toolCalls) {
+      let callInput = call.input;
+      if (call.name === "reminder_create") {
+        const titleValue = call.input?.title;
+        if (typeof titleValue === "string" && titleValue.trim()) {
+          callInput = {
+            ...call.input,
+            title: sanitizeReminderTitle(titleValue) || "Reminder",
+          };
+        }
+      }
+
+      params.send({ type: "tool_call", callId: call.id, name: call.name, args: callInput });
+
+      const tool = findToolByName(tools, call.name);
+      if (!tool) {
+        const message = `Unknown tool requested by model: ${call.name}`;
+        params.send({
+          type: "tool_result",
+          callId: call.id,
+          name: call.name,
+          ok: false,
+          result: { error: message },
+        });
+        session.addToolResult({
+          callId: call.id,
+          name: call.name,
+          result: message,
+          isError: true,
+        });
+        continue;
+      }
+
+      if (requiresApprovalForRisk(tool.risk, params.localTools.approvalMode)) {
+        const approval = createApprovalRequest();
+        params.send({
+          type: "approval_requested",
+            approvalId: approval.approvalId,
+            callId: call.id,
+            name: call.name,
+            args: callInput,
+            reason: summarizeApprovalReason(call.name, callInput),
+          });
+
+        emitThinkingUpdate(`Waiting for approval to run ${call.name}.`);
+        const decision = await approval.promise;
+        params.send({
+          type: "approval_resolved",
+          approvalId: approval.approvalId,
+          callId: call.id,
+          decision,
+          message:
+            decision === "approve"
+              ? "Approved"
+              : decision === "timeout"
+                ? "Timed out"
+                : "Denied",
+        });
+
+        if (decision !== "approve") {
+          const message =
+            decision === "timeout"
+              ? "Tool call timed out waiting for approval."
+              : "Tool call denied by user.";
+          params.send({
+            type: "tool_result",
+            callId: call.id,
+            name: call.name,
+            ok: false,
+            result: { error: message },
+          });
+          session.addToolResult({
+            callId: call.id,
+            name: call.name,
+            result: message,
+            isError: true,
+          });
+          continue;
+        }
+      }
+
+      params.send({
+        type: "tool_progress",
+        callId: call.id,
+        name: call.name,
+        status: "started",
+        message: `Executing ${call.name}...`,
+      });
+
+      try {
+        const output = await tool.execute(callInput, {
+          localTools: params.localTools,
+          signal: params.signal,
+        });
+        if (callInput !== call.input && call.name === "reminder_create") {
+          const outputWithSanitizedTitle =
+            output && typeof output === "object"
+              ? { ...(output as Record<string, unknown>), title: (callInput.title as string) || "Reminder" }
+              : output;
+          params.send({
+            type: "tool_result",
+            callId: call.id,
+            name: call.name,
+            ok: true,
+            result: outputWithSanitizedTitle,
+          });
+          sawSuccessfulToolResult = true;
+          session.addToolResult({
+            callId: call.id,
+            name: call.name,
+            result: serializeToolOutput(outputWithSanitizedTitle),
+          });
+          continue;
+        }
+        params.send({
+          type: "tool_result",
+          callId: call.id,
+          name: call.name,
+          ok: true,
+          result: output,
+        });
+        sawSuccessfulToolResult = true;
+        mergeCitationSources(gatheredSources, extractSourcesFromToolOutput(call.name, output));
+        session.addToolResult({
+          callId: call.id,
+          name: call.name,
+          result: serializeToolOutput(output),
+        });
+        emitThinkingUpdate("Tool finished. Updating the response.");
+      } catch (error) {
+        const message = formatToolErrorForUser(
+          call.name,
+          error,
+          "Unknown tool execution error.",
+        );
+        params.send({
+          type: "tool_result",
+          callId: call.id,
+          name: call.name,
+          ok: false,
+          result: { error: message },
+        });
+        session.addToolResult({
+          callId: call.id,
+          name: call.name,
+          result: message,
+          isError: true,
+        });
+      }
+    }
+  }
+
+  if (sawSuccessfulToolResult && !emittedAssistantText) {
+    params.send({ type: "token", value: "**Done.** I completed that request." });
+    emitSourcesIfPresent();
+    return;
+  }
+  params.send({
+    type: "token",
+    value: "I hit an internal tool limit before finishing cleanly. I can continue from here with one more step.",
+  });
+  emitSourcesIfPresent();
+}
+
+export async function POST(request: Request) {
+  const body = (await request.json()) as ChatRequest;
+  const { model, messages, system } = body;
+  const connection = resolveRuntimeConnection(body);
+
+  if (!connection) {
+    return new Response(JSON.stringify({ error: "Missing connection." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  if (requiresApiKey(connection) && !connection.apiKey) {
+    return new Response(JSON.stringify({ error: "Missing API key for selected connection." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  if (typeof model !== "string" || !model.trim()) {
+    return new Response(JSON.stringify({ error: "Missing model." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  if (!Array.isArray(messages)) {
+    return new Response(JSON.stringify({ error: "Missing chat messages." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+  const sanitizedMessages = sanitizeChatMessages(messages);
+  if (sanitizedMessages.length === 0) {
+    return new Response(JSON.stringify({ error: "Missing non-empty chat messages." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const webSourcesEnabled = normalizeWebSourcesEnabled(body.enableWebSources);
+  const enableWebSourcesForConnection =
+    webSourcesEnabled && supportsWebSourcesViaOpenAI(connection);
+  const localToolsRequested = normalizeLocalTools(body.localTools);
+  const memoryContext = sanitizeMemoryContext(body.memory);
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      const send = (chunk: ChatStreamChunk) => {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+      };
+      const sendThinking = (
+        status: "started" | "update" | "done",
+        summary?: string,
+      ) => emitThinking(send, status, summary);
+
+      let sentDone = false;
+      const sendDone = () => {
+        if (sentDone) {
+          return;
+        }
+        send({ type: "done" });
+        sentDone = true;
+      };
+
+      try {
+        sendThinking("started", "Understanding your request.");
+        const toolsSupported = connection.supportsTools !== false;
+        const localTools = toolsSupported
+          ? localToolsRequested
+          : { ...localToolsRequested, enabled: false };
+
+        if (localToolsRequested.enabled && !toolsSupported) {
+          send({
+            type: "tool_progress",
+            callId: "tooling",
+            name: "tooling",
+            status: "warning",
+            message: `Local tools are disabled for "${connection.name}" (connection does not support tool calls). Continuing with plain chat.`,
+          });
+        }
+
+        if (localTools.enabled) {
+          const routeThroughTools = shouldRouteThroughToolOrchestrator(sanitizedMessages);
+          if (routeThroughTools) {
+            sendThinking("update", "Checking whether this can run through a direct action path.");
+            let fastHandled = false;
+            try {
+              fastHandled = await tryDirectAutomationFastPath({
+                localTools,
+                messages: sanitizedMessages,
+                memory: memoryContext,
+                send,
+                signal: request.signal,
+              });
+            } catch (error) {
+              const message =
+                error instanceof Error ? truncateMessage(error.message) : "Fast-path unavailable.";
+              send({
+                type: "tool_progress",
+                callId: "tooling",
+                name: "tooling",
+                status: "warning",
+                message: `Direct automation fast-path failed: ${message}. Continuing with tool orchestration.`,
+              });
+            }
+
+            if (fastHandled) {
+              sendThinking("done");
+              sendDone();
+              return;
+            }
+
+            sendThinking("update", "Planning tool actions and preparing the response.");
+            await runToolOrchestrator({
+              connection,
+              model,
+              system,
+              messages: sanitizedMessages,
+              localTools,
+              enableWebSources: enableWebSourcesForConnection,
+              send,
+              signal: request.signal,
+            });
+            sendThinking("done");
+            sendDone();
+            return;
+          }
+        }
+
+        sendThinking("update", "Generating response.");
+        await streamPlainChat({
+          connection,
+          model,
+          system,
+          messages: sanitizedMessages,
+          enableWebSources: enableWebSourcesForConnection,
+          send,
+          signal: request.signal,
+        });
+        sendThinking("done");
+      } catch (error) {
+        const message = error instanceof Error ? truncateMessage(error.message) : "Unexpected error";
+        send({ type: "error", error: message });
+        sendThinking("done");
+      } finally {
+        sendDone();
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}