@digimuza/system-core 0.2.0-rc.2 → 0.3.0-rc.1

package/src/ai/contract.ts

@@ -0,0 +1,245 @@
+// Shared contract of the AI module (DIG-71). Every part of `@digimuza/system-core/ai`
+// builds on these shapes: tables, views, function names, the tool and agent API.
+// No Mastra or AI SDK imports here: this file is safe in Convex's default runtime
+// and in the browser (types only).
+import { defineTable } from "convex/server"
+import { v, type GenericId, type Infer } from "convex/values"
+import type { z } from "zod"
+import type { Actor, ActorRef } from "../core/access.js"
+import type { SystemContext } from "../core/context.js"
+
+// --- Validators & tables -------------------------------------------------------------
+
+export const actorRefValidator = v.union(v.object({ kind: v.literal("user"), userId: v.string() }), v.object({ kind: v.literal("agent"), apiKeyId: v.string() }))
+
+export const toolCallState = v.union(
+  v.literal("awaiting-approval"), // requiresApproval tool, waiting for the user
+  v.literal("approved"), // user approved; the runner executes it next
+  v.literal("rejected"), // user rejected; the model is told so
+  v.literal("running"),
+  v.literal("done"),
+  v.literal("error"),
+)
+
+export const messagePart = v.union(
+  v.object({ type: v.literal("text"), text: v.string() }),
+  v.object({
+    type: v.literal("tool-call"),
+    toolCallId: v.string(),
+    toolName: v.string(),
+    args: v.any(),
+    state: toolCallState,
+    result: v.optional(v.any()),
+    /** Stable system-core error code (FORBIDDEN, VALIDATION, …) or a short message. */
+    error: v.optional(v.string()),
+  }),
+)
+
+export const threadStatus = v.union(v.literal("idle"), v.literal("running"), v.literal("waiting-approval"))
+export const messageStatus = v.union(v.literal("streaming"), v.literal("done"), v.literal("error"), v.literal("stopped"))
+export const runStatus = v.union(v.literal("queued"), v.literal("running"), v.literal("waiting-approval"), v.literal("done"), v.literal("error"), v.literal("stopped"))
+
+/** Spread into the app schema next to `systemTables`. */
+export const aiTables = {
+  aiThreads: defineTable({
+    /** system-core user key of the owner. Only the owner can see a thread. */
+    ownerId: v.string(),
+    title: v.string(),
+    agentId: v.string(),
+    status: threadStatus,
+    archived: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  }).index("by_owner", ["ownerId", "archived", "updatedAt"]),
+
+  aiMessages: defineTable({
+    threadId: v.id("aiThreads"),
+    role: v.union(v.literal("user"), v.literal("assistant")),
+    parts: v.array(messagePart),
+    status: messageStatus,
+    /** `operationId` is the run's, so support can find the logs of a failed answer. */
+    error: v.optional(v.object({ code: v.string(), message: v.string(), operationId: v.optional(v.string()) })),
+    runId: v.optional(v.id("aiRuns")),
+    createdAt: v.number(),
+  }).index("by_thread", ["threadId", "createdAt"]),
+
+  aiRuns: defineTable({
+    threadId: v.id("aiThreads"),
+    /** The assistant message this run writes into. */
+    messageId: v.id("aiMessages"),
+    /** Who the run acts for; re-authorized on every tool call (system-core authorizeJob). */
+    actor: actorRefValidator,
+    agentId: v.string(),
+    model: v.string(),
+    status: runStatus,
+    stopRequested: v.boolean(),
+    operationId: v.string(),
+    error: v.optional(v.object({ code: v.string(), message: v.string() })),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_thread", ["threadId", "createdAt"])
+    .index("by_message", ["messageId"]),
+}
+
+export type MessagePart = Infer<typeof messagePart>
+export type ToolCallState = Infer<typeof toolCallState>
+export type ThreadStatus = Infer<typeof threadStatus>
+export type MessageStatus = Infer<typeof messageStatus>
+export type RunStatus = Infer<typeof runStatus>
+export type AiThreadId = GenericId<"aiThreads">
+export type AiMessageId = GenericId<"aiMessages">
+export type AiRunId = GenericId<"aiRuns">
+
+// --- Views returned by public functions ----------------------------------------------
+
+export interface ThreadView {
+  id: AiThreadId
+  title: string
+  agentId: string
+  status: ThreadStatus
+  createdAt: number
+  updatedAt: number
+}
+
+export interface MessageView {
+  id: AiMessageId
+  role: "user" | "assistant"
+  parts: MessagePart[]
+  status: MessageStatus
+  /** Set when the answer failed; `operationId` is the run's (show it so support can trace it). */
+  error: { code: string; message: string; operationId?: string } | null
+  createdAt: number
+}
+
+export interface AgentToolView {
+  id: string
+  description: string
+  requiresApproval: boolean
+}
+
+export interface AgentView {
+  id: string
+  name: string
+  description: string
+  /** Only the tools the caller holds the permission for right now. */
+  tools: AgentToolView[]
+}
+
+// --- Tools ----------------------------------------------------------------------------
+
+/** What a tool handler gets. It runs inside an internal mutation, as the run's actor. */
+export interface AiToolContext {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any
+  sys: SystemContext
+  /** Re-authorized for `permission` right before the handler runs. */
+  actor: Actor
+}
+
+export interface AiTool<I extends z.ZodType = z.ZodType, O = unknown> {
+  /** Stable, `module.verb_object` style, e.g. `finance.list_invoices`. Shown to the model. */
+  id: string
+  /** For the model: what it does and when to use it. */
+  description: string
+  /** Zod schema of the arguments (also sent to the model as JSON schema). */
+  input: I
+  /** system-core permission required to run it, e.g. `finance:invoice:read`. */
+  permission: string
+  /** Writes or anything risky: the user approves each call first. */
+  requiresApproval?: boolean
+  /**
+   * Must be JSON-serializable. Throw SystemError for expected failures.
+   *
+   * Validate everything before the first write: a failed handler does not roll
+   * back. `executeAiTool` returns the failure instead of throwing (so the
+   * `ai.tool.run` audit survives), therefore writes made before the throw are
+   * committed with the surrounding mutation.
+   */
+  handler(ctx: AiToolContext, input: z.infer<I>): Promise<O>
+}
+
+// --- Agents ---------------------------------------------------------------------------
+
+export interface AiAgentDefinition {
+  /** Stable id, e.g. `assistant`. */
+  id: string
+  name: string
+  description: string
+  /** System prompt. */
+  instructions: string
+  /** Model id for this agent; falls back to `defaultModel`. OpenAI only in v1. */
+  model?: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools: readonly AiTool<any, any>[]
+}
+
+export interface AiOptions {
+  agents: readonly AiAgentDefinition[]
+  /** Default OpenAI model id when an agent has none (env AI_MODEL wins if set). */
+  defaultModel: string
+  /**
+   * Convex module paths (relative to convex/) where the app exports the AI
+   * functions and the Node runner. Defaults: "ai" and "aiRunner".
+   */
+  functionsModule?: string
+  runnerModule?: string
+}
+
+// --- Function names (the app re-exports these) ---------------------------------------
+
+/** Public functions in `functionsModule` (default convex/ai.ts). */
+export const AI_PUBLIC_FUNCTIONS = [
+  "listAgents", // () → AgentView[]
+  "listThreads", // ({ cursor?, limit? }) → { items: ThreadView[], cursor, done }
+  "getThread", // ({ threadId }) → ThreadView (NOT_FOUND unless owner)
+  "listMessages", // ({ threadId }) → MessageView[] (live, ascending)
+  "createThread", // ({ agentId?, title? }) → { threadId }
+  "sendMessage", // ({ threadId, text }) → { messageId, runId }; schedules the runner
+  "stopRun", // ({ threadId }) → { stopped }
+  "respondToToolCall", // ({ messageId, toolCallId, approve }) → { runId }; resumes the run
+  "renameThread", // ({ threadId, title })
+  "archiveThread", // ({ threadId })
+] as const
+
+/** Internal functions in `functionsModule`, called by the runner. */
+export const AI_INTERNAL_FUNCTIONS = [
+  "_startRun", // ({ runId }) → RunContext | null (null: stopped or gone)
+  "_appendText", // ({ messageId, text }) append to the last text part (or start one)
+  "_addToolCall", // ({ messageId, toolCallId, toolName, args, state })
+  "_executeTool", // ({ runId, toolCallId }) → ToolExecutionResult; authorizes and runs the handler
+  "_setToolCallState", // ({ messageId, toolCallId, state, result?, error? })
+  "_finishRun", // ({ runId, status, error? }) sets run, message and thread status
+  "_isStopRequested", // ({ runId }) → boolean
+] as const
+
+/** Node runner in `runnerModule` (default convex/aiRunner.ts, "use node"). */
+export const AI_RUNNER_FUNCTION = "runAgent" // internalAction ({ runId }) → void
+
+/** What `_startRun` gives the runner. */
+export interface RunContext {
+  runId: AiRunId
+  threadId: AiThreadId
+  messageId: AiMessageId
+  agentId: string
+  model: string
+  actor: ActorRef
+  operationId: string
+  /** Full history in order, including this run's assistant message so far. */
+  history: MessageView[]
+  /** Tool ids of the agent the actor may use right now (permission held). */
+  allowedToolIds: string[]
+}
+
+export type ToolExecutionResult = { ok: true; result: unknown } | { ok: false; code: string; message: string }
+
+// --- Audit actions ------------------------------------------------------------------------
+
+export const AI_AUDIT = {
+  threadCreate: "ai.thread.create",
+  messageSend: "ai.message.send",
+  toolRun: "ai.tool.run",
+  toolApprove: "ai.tool.approve",
+  toolReject: "ai.tool.reject",
+  runStop: "ai.run.stop",
+} as const

package/src/ai/display.ts

@@ -0,0 +1,38 @@
+// Display tools of the AI module: the assistant shows the user a visual card
+// (summary, comparison, table, simple chart) made of HTML/CSS/inline SVG.
+//
+// The HTML is model output and therefore UNTRUSTED (prompt injection can reach
+// it through tool results). Apps must render it only with `cardDocument()` in an
+// <iframe sandbox="allow-scripts"> (never allow-same-origin): opaque origin, no
+// network, no navigation, no forms, no popups. Nothing leaves the frame except
+// the height message the frame's own resize script posts.
+import { z } from "zod"
+import { AiPermissions } from "./manifest.js"
+import { AI_CARD_HTML_MAX, AI_CARD_TITLE_MAX } from "./card.js"
+import { defineAiTool } from "./tools.js"
+
+export * from "./card.js"
+
+export const AI_SHOW_CARD = "ai.show_card"
+
+/** `ai.show_card`: no data access, no writes, so no approval; needs only `ai:chat:use`. */
+export const showCardTool = defineAiTool({
+  id: AI_SHOW_CARD,
+  description: [
+    "Show the user a visual card rendered from HTML, inside the chat.",
+    "Use it when a visual answer is clearly better than text: a summary with key figures, a comparison, a small table, a status overview, a simple bar chart (HTML/CSS or inline SVG).",
+    "Rules: a self-contained HTML fragment (no <html>/<head>), inline <style> allowed; no external resources (images, fonts, scripts, links to URLs are blocked); images only as inline SVG or data: URLs.",
+    "Style with the CSS variables provided: var(--background), var(--foreground), var(--muted), var(--muted-foreground), var(--card), var(--border), var(--primary), var(--primary-foreground), var(--destructive), var(--radius). They follow the app's light/dark theme; do not hardcode colours.",
+    "The chat already draws the card frame (border, background, padding, title): do NOT add an outer border, background, shadow or padding of your own; start with the content. Use var(--destructive) only for errors or overdue items, var(--primary) for the one figure that matters.",
+    "Only show data you got from tools or the user. Keep the card compact. Write a short sentence in the chat too.",
+  ].join(" "),
+  input: z.object({
+    title: z.string().trim().min(1).max(AI_CARD_TITLE_MAX).optional(),
+    html: z.string().min(1).max(AI_CARD_HTML_MAX),
+  }),
+  permission: AiPermissions.use,
+  handler: async (_ctx, input) => ({ shown: true, bytes: input.html.length }),
+})
+
+/** Tools for showing things to the user. Add to an agent: `tools: [...financeTools, ...displayTools]`. */
+export const displayTools = [showCardTool] as const

package/src/ai/index.ts

@@ -0,0 +1,9 @@
+// `@digimuza/system-core/ai`: reusable AI chat with permissioned tools.
+// Convex default runtime + browser types. The Mastra runner is in
+// `@digimuza/system-core/ai/runner` (Node only, "use node").
+export * from "./contract.js"
+export * from "./manifest.js"
+export { defineAiTool, defineAiAgent, executeAiTool } from "./tools.js"
+export { defineAi, type AiSystem } from "./api.js"
+export { AI_SHOW_CARD, showCardTool, displayTools } from "./display.js"
+export * from "./card.js"

package/src/ai/manifest.ts

@@ -0,0 +1,16 @@
+import { defineModule, type PermissionOf } from "../modules/index.js"
+
+/**
+ * The AI assistant module. Business module: registers disabled, a Super
+ * enables it. `ai:chat:use` lets a person chat; what the assistant may *do* is
+ * decided per tool by that tool's own permission (finance:invoice:read, …).
+ */
+export const ai = defineModule({
+  id: "ai",
+  kind: "business",
+  description: "AI asistentas su įrankiais",
+  permissions: [{ id: "ai:chat:use", name: "Naudoti asistentą", description: "Kalbėtis su AI asistentu ir matyti savo pokalbius" }],
+  initialSubroles: [{ id: "ai:user", name: "Asistento naudotojas", description: "Gali kalbėtis su AI asistentu", permissions: ["ai:chat:use"] }],
+})
+
+export const AiPermissions = { use: "ai:chat:use" } as const satisfies Record<string, PermissionOf<typeof ai>>

package/src/ai/runner.ts

@@ -0,0 +1,275 @@
+// Node-only Mastra runner of the AI module (DIG-71). Entry `@digimuza/system-core/ai/runner`.
+// All Mastra / AI SDK imports live here, never in contract/api/tools: the app file that
+// re-exports `runAgent` must start with "use node".
+import { createOpenAI } from "@ai-sdk/openai"
+import { Agent } from "@mastra/core/agent"
+import { noopLogger } from "@mastra/core/logger"
+import { createTool } from "@mastra/core/tools"
+import { internalActionGeneric, makeFunctionReference, type GenericActionCtx, type GenericDataModel } from "convex/server"
+import { v } from "convex/values"
+import { createLogger } from "../diagnostics/logging.js"
+import type { AiOptions, AiRunId, AiTool, MessagePart, MessageView, RunContext, RunStatus, ToolCallState, ToolExecutionResult } from "./contract.js"
+
+/** Max model steps (calls) per run turn; guards against tool loops. */
+export const AI_MAX_STEPS = 8
+/** Text deltas are written with `_appendText` at most this often … */
+export const AI_FLUSH_MS = 150
+/** … or as soon as this many characters are buffered. */
+export const AI_FLUSH_CHARS = 200
+
+// Any AI SDK language model Mastra accepts (V2/V3/V4 spec). Kept loose so the
+// option does not tie apps to one `@ai-sdk/provider` version.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AiLanguageModel = any
+
+export interface AiRunnerOptions extends AiOptions {
+  /** OpenAI API key; default `process.env.OPENAI_API_KEY`. Never logged or returned. */
+  openAiApiKey?: () => string | undefined
+  /**
+   * Base URL of an OpenAI-compatible API, e.g. a proxy like 9Router
+   * (`https://router.digimuza.ai/v1`). Default `process.env.OPENAI_BASE_URL`,
+   * else api.openai.com. Requests go to `<baseURL>/chat/completions`.
+   */
+  baseURL?: string
+  /** Custom fetch for the provider (tests, request middleware). Default: global fetch. */
+  fetch?: typeof globalThis.fetch
+  /**
+   * Test hook: builds the language model for a model id instead of OpenAI (e.g.
+   * `MockLanguageModelV4` from `ai/test`). When set, no API key is needed.
+   */
+  model?: (modelId: string) => AiLanguageModel
+}
+
+type ToolPart = Extract<MessagePart, { type: "tool-call" }>
+type ModelMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: Array<{ type: "text"; text: string } | { type: "tool-call"; toolCallId: string; toolName: string; input: unknown }> }
+  | { role: "tool"; content: Array<{ type: "tool-result"; toolCallId: string; toolName: string; output: { type: "json"; value: unknown } }> }
+
+class StopTurn extends Error {}
+
+const UNAVAILABLE = "UNAVAILABLE"
+const FAILED = { code: UNAVAILABLE, message: "The assistant failed. Try again." }
+
+/** OpenAI function names allow only `[a-zA-Z0-9_-]`; tool ids are `module.verb_object`. */
+export const modelToolName = (toolId: string) => toolId.replace(/[^a-zA-Z0-9_-]/g, "_")
+
+const toolOutput = (p: ToolPart): unknown =>
+  p.state === "done" ? { ok: true, result: p.result ?? null } : p.state === "rejected" ? { ok: false, error: "REJECTED", message: "rejected by user" } : { ok: false, error: p.error ?? UNAVAILABLE }
+
+/**
+ * History → model messages. User text → user messages; assistant parts in order as
+ * text + tool calls, each finished call (done/error/rejected) followed by its result.
+ * Calls without an outcome yet are left out (a call without a result is invalid).
+ */
+export function toModelMessages(history: readonly MessageView[]): ModelMessage[] {
+  const out: ModelMessage[] = []
+  for (const m of history) {
+    if (m.role === "user") {
+      const text = m.parts.flatMap((p) => (p.type === "text" ? [p.text] : [])).join("\n")
+      if (text.trim()) out.push({ role: "user", content: text })
+      continue
+    }
+    let assistant: Extract<ModelMessage, { role: "assistant" }>["content"] = []
+    let results: Extract<ModelMessage, { role: "tool" }>["content"] = []
+    const flush = () => {
+      if (assistant.length) out.push({ role: "assistant", content: assistant })
+      if (results.length) out.push({ role: "tool", content: results })
+      assistant = []
+      results = []
+    }
+    for (const p of m.parts) {
+      if (p.type === "text") {
+        if (!p.text) continue
+        if (results.length) flush()
+        assistant.push({ type: "text", text: p.text })
+      } else if (p.state === "done" || p.state === "error" || p.state === "rejected") {
+        const toolName = modelToolName(p.toolName)
+        assistant.push({ type: "tool-call", toolCallId: p.toolCallId, toolName, input: p.args ?? {} })
+        results.push({ type: "tool-result", toolCallId: p.toolCallId, toolName, output: { type: "json", value: toolOutput(p) } })
+      }
+    }
+    flush()
+  }
+  return out
+}
+
+/**
+ *   // convex/aiRunner.ts
+ *   "use node"
+ *   export const { runAgent } = defineAiRunner(aiOptions)
+ */
+export function defineAiRunner(options: AiRunnerOptions) {
+  const fnModule = options.functionsModule ?? "ai"
+  const mutation = (name: string) => makeFunctionReference<"mutation">(`${fnModule}:${name}`)
+  const query = (name: string) => makeFunctionReference<"query">(`${fnModule}:${name}`)
+  const fn = {
+    startRun: mutation("_startRun"),
+    appendText: mutation("_appendText"),
+    addToolCall: mutation("_addToolCall"),
+    executeTool: mutation("_executeTool"),
+    setToolCallState: mutation("_setToolCallState"),
+    finishRun: mutation("_finishRun"),
+    isStopRequested: query("_isStopRequested"),
+  }
+  const logger = createLogger({ moduleId: "ai.runner" })
+
+  async function run(ctx: GenericActionCtx<GenericDataModel>, runId: AiRunId): Promise<void> {
+    const rc = (await ctx.runMutation(fn.startRun, { runId })) as RunContext | null
+    if (!rc) return
+
+    let finished: RunStatus | null = null
+    const finish = async (status: RunStatus, error?: { code: string; message: string }) => {
+      if (finished) return
+      finished = status
+      await ctx.runMutation(fn.finishRun, error ? { runId, status, error } : { runId, status })
+    }
+
+    try {
+      const agentDef = options.agents.find((a) => a.id === rc.agentId)
+      if (!agentDef) return await finish("error", { code: UNAVAILABLE, message: "Unknown assistant" })
+
+      let modelFor = options.model
+      if (!modelFor) {
+        const apiKey = options.openAiApiKey?.() ?? process.env.OPENAI_API_KEY
+        if (!apiKey) return await finish("error", { code: UNAVAILABLE, message: "AI model is not configured" })
+        const baseURL = options.baseURL ?? (process.env.OPENAI_BASE_URL || undefined)
+        const openai = createOpenAI({ apiKey, ...(baseURL ? { baseURL } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) })
+        // Chat Completions, not the Responses API default: OpenAI-compatible
+        // proxies (9Router, LiteLLM, …) implement /v1/chat/completions. Model ids
+        // are plain strings (router names like `cx/gpt-5` are not in the SDK's union).
+        modelFor = (id: string) => openai.chat(id)
+      }
+
+      const messageId = rc.messageId
+      const executeTool = async (toolCallId: string): Promise<ToolExecutionResult> => {
+        let res: ToolExecutionResult
+        try {
+          res = (await ctx.runMutation(fn.executeTool, { runId, toolCallId })) as ToolExecutionResult
+        } catch (e) {
+          logger.warn("ai_tool_execute_failed", { errorName: e instanceof Error ? e.name : typeof e })
+          res = { ok: false, code: UNAVAILABLE, message: "Tool failed" }
+        }
+        await ctx.runMutation(
+          fn.setToolCallState,
+          res.ok ? { messageId, toolCallId, state: "done", result: res.result ?? null } : { messageId, toolCallId, state: "error", error: res.code },
+        )
+        return res
+      }
+
+      // 5. Resume: run the tools the user approved since the last turn.
+      const history = rc.history.map((m) => (m.id === messageId ? { ...m, parts: m.parts.map((p) => ({ ...p })) } : m))
+      const current = history.find((m) => m.id === messageId)
+      for (const p of current?.parts ?? []) {
+        if (p.type !== "tool-call" || p.state !== "approved") continue
+        await ctx.runMutation(fn.setToolCallState, { messageId, toolCallId: p.toolCallId, state: "running" })
+        const res = await executeTool(p.toolCallId)
+        Object.assign(p, res.ok ? { state: "done" as ToolCallState, result: res.result ?? null } : { state: "error" as ToolCallState, error: res.code })
+      }
+      // Still waiting on the user for another call: nothing to do until they answer.
+      if (current?.parts.some((p) => p.type === "tool-call" && p.state === "awaiting-approval")) return await finish("waiting-approval")
+
+      // 7. Text batching + stop checks.
+      const controller = new AbortController()
+      let buffer = ""
+      let lastFlush = Date.now()
+      let chain: Promise<void> = Promise.resolve()
+      const flush = (): Promise<void> =>
+        (chain = chain.then(async () => {
+          lastFlush = Date.now()
+          if (buffer && !finished) {
+            const text = buffer
+            buffer = ""
+            await ctx.runMutation(fn.appendText, { messageId, text })
+          }
+          if (!finished && (await ctx.runQuery(fn.isStopRequested, { runId }))) {
+            controller.abort()
+            await finish("stopped")
+          }
+        }))
+
+      // 4. Tools: only those the actor may use right now.
+      let awaitingApproval = false
+      const allowed = new Set(rc.allowedToolIds)
+      const tools: Record<string, ReturnType<typeof createTool>> = {}
+      for (const tool of agentDef.tools as readonly AiTool[]) {
+        if (!allowed.has(tool.id)) continue
+        const name = modelToolName(tool.id)
+        tools[name] = createTool({
+          id: name,
+          description: tool.description,
+          inputSchema: tool.input,
+          execute: async (input: unknown, toolCtx: { agent?: { toolCallId?: string } } | undefined) => {
+            const toolCallId = toolCtx?.agent?.toolCallId || `call_${crypto.randomUUID()}`
+            await flush()
+            if (finished) throw new StopTurn("stopped")
+            const args = input ?? {}
+            if (tool.requiresApproval) {
+              awaitingApproval = true
+              await ctx.runMutation(fn.addToolCall, { messageId, toolCallId, toolName: tool.id, args, state: "awaiting-approval" })
+              return { ok: false, status: "awaiting-approval", message: "The user must approve this action first. Stop and wait for their answer." }
+            }
+            await ctx.runMutation(fn.addToolCall, { messageId, toolCallId, toolName: tool.id, args, state: "running" })
+            const res = await executeTool(toolCallId)
+            return res.ok ? { ok: true, result: res.result ?? null } : { ok: false, error: res.code, message: res.message }
+          },
+        } as Parameters<typeof createTool>[0]) as ReturnType<typeof createTool>
+      }
+
+      const agent = new Agent({
+        id: agentDef.id,
+        name: agentDef.name,
+        instructions: agentDef.instructions,
+        model: modelFor(rc.model),
+        tools,
+      })
+      // Mastra logs stream errors with the full error object; upstream API errors carry the
+      // request body (prompts, tool results). Silence it; we log only the error name.
+      agent.__setLogger(noopLogger)
+
+      const messages = toModelMessages(history)
+      // An approval call ends the turn after its step (other calls of the same step still
+      // finish and are recorded); the step cap stops tool loops.
+      const stopWhen = [({ steps }: { steps: unknown[] }) => steps.length >= AI_MAX_STEPS, () => awaitingApproval]
+      try {
+        const output = await agent.stream(messages as never, {
+          maxSteps: AI_MAX_STEPS,
+          stopWhen: stopWhen as never,
+          abortSignal: controller.signal,
+        })
+        const reader = output.fullStream.getReader()
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done || finished) break
+          const chunk = value as { type: string; payload?: { text?: string; error?: unknown } }
+          if (chunk.type === "text-delta" && chunk.payload?.text) {
+            buffer += chunk.payload.text
+            if (buffer.length >= AI_FLUSH_CHARS || Date.now() - lastFlush >= AI_FLUSH_MS) await flush()
+          } else if (chunk.type === "error") {
+            throw chunk.payload?.error instanceof Error ? chunk.payload.error : new Error("stream error")
+          }
+          if (finished) break
+        }
+        if (finished) await reader.cancel().catch(() => {})
+      } catch (e) {
+        if (!finished) throw e
+      }
+      await flush()
+      await chain
+      // 8. End of turn.
+      await finish(awaitingApproval ? "waiting-approval" : "done")
+    } catch (e) {
+      logger.error("ai_run_failed", { errorName: e instanceof Error ? e.name : typeof e })
+      await finish("error", FAILED)
+    }
+  }
+
+  const runAgent = internalActionGeneric({
+    args: { runId: v.id("aiRuns") },
+    handler: async (ctx, { runId }) => {
+      await run(ctx, runId as AiRunId)
+    },
+  })
+
+  return { runAgent }
+}