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

package/src/ai/api.ts

@@ -0,0 +1,535 @@
+// The AI module's core data & API layer: threads, messages and runs in Convex.
+// Public functions guard themselves (permission, module enabled, role view,
+// human session, ownership) in the same transaction as the change. Internal
+// functions are called only by the runner (convex/aiRunner.ts).
+import { internalMutationGeneric, internalQueryGeneric, makeFunctionReference, mutationGeneric, queryGeneric } from "convex/server"
+import { v } from "convex/values"
+import { decide, requireHuman, toActorRef, type ActorRef, type UserActor } from "../core/access.js"
+import { recordAudit } from "../core/audit.js"
+import type { SystemContext } from "../core/context.js"
+import { SystemError } from "../core/errors.js"
+import { authorizeJob } from "../core/jobs.js"
+import { toConvexError, type ConvexSystem, type DbCtx } from "../convex/functions.js"
+import {
+  AI_AUDIT,
+  type AgentView,
+  type AiAgentDefinition,
+  type AiMessageId,
+  type AiOptions,
+  type AiRunId,
+  type AiThreadId,
+  type MessagePart,
+  type MessageStatus,
+  type MessageView,
+  type RunContext,
+  type RunStatus,
+  type ThreadStatus,
+  type ThreadView,
+  type ToolCallState,
+  type ToolExecutionResult,
+  toolCallState,
+} from "./contract.js"
+import { AiPermissions } from "./manifest.js"
+import { executeAiTool } from "./tools.js"
+
+export const AI_MESSAGE_MAX = 8000
+export const AI_TITLE_MAX = 120
+const AUTO_TITLE_LENGTH = 60
+const PAGE_DEFAULT = 30
+const PAGE_MAX = 100
+
+// --- Rows & loosely typed db (the app schema contains `aiTables`) ---------------------
+
+type ErrorInfo = { code: string; message: string }
+type MessageErrorInfo = ErrorInfo & { operationId?: string }
+
+interface ThreadDoc {
+  _id: AiThreadId
+  _creationTime: number
+  ownerId: string
+  title: string
+  agentId: string
+  status: ThreadStatus
+  archived: boolean
+  createdAt: number
+  updatedAt: number
+}
+
+interface MessageDoc {
+  _id: AiMessageId
+  _creationTime: number
+  threadId: AiThreadId
+  role: "user" | "assistant"
+  parts: MessagePart[]
+  status: MessageStatus
+  error?: MessageErrorInfo
+  runId?: AiRunId
+  createdAt: number
+}
+
+interface RunDoc {
+  _id: AiRunId
+  _creationTime: number
+  threadId: AiThreadId
+  messageId: AiMessageId
+  actor: ActorRef
+  agentId: string
+  model: string
+  status: RunStatus
+  stopRequested: boolean
+  operationId: string
+  error?: ErrorInfo
+  createdAt: number
+  updatedAt: number
+}
+
+type Docs = { aiThreads: ThreadDoc; aiMessages: MessageDoc; aiRuns: RunDoc }
+type Table = keyof Docs
+type IndexQ = { eq(field: string, value: unknown): IndexQ }
+interface Ordered<D> {
+  take(n: number): Promise<D[]>
+  first(): Promise<D | null>
+  collect(): Promise<D[]>
+  paginate(o: { cursor: string | null; numItems: number }): Promise<{ page: D[]; continueCursor: string; isDone: boolean }>
+}
+interface Query<D> extends Ordered<D> {
+  order(o: "asc" | "desc"): Ordered<D>
+}
+interface Db {
+  query<T extends Table>(t: T): { withIndex(i: string, f: (q: IndexQ) => unknown): Query<Docs[T]> }
+  get<T extends Table>(t: T, id: string): Promise<Docs[T] | null>
+  insert<T extends Table>(t: T, doc: Omit<Docs[T], "_id" | "_creationTime">): Promise<Docs[T]["_id"]>
+  patch<T extends Table>(t: T, id: string, doc: Partial<Omit<Docs[T], "_id" | "_creationTime">>): Promise<void>
+}
+type Scheduler = { runAfter(ms: number, ref: unknown, args: Record<string, unknown>): Promise<unknown> }
+const db = (ctx: { db: unknown }) => ctx.db as Db
+
+// --- Views -------------------------------------------------------------------------------
+
+const threadView = (t: ThreadDoc): ThreadView => ({ id: t._id, title: t.title, agentId: t.agentId, status: t.status, createdAt: t.createdAt, updatedAt: t.updatedAt })
+
+const messageView = (m: MessageDoc): MessageView => ({
+  id: m._id,
+  role: m.role,
+  parts: m.parts,
+  status: m.status,
+  error: m.error ? { code: m.error.code, message: m.error.message, ...(m.error.operationId ? { operationId: m.error.operationId } : {}) } : null,
+  createdAt: m.createdAt,
+})
+
+const agentView = (a: AiAgentDefinition, tools: AiAgentDefinition["tools"]): AgentView => ({
+  id: a.id,
+  name: a.name,
+  description: a.description,
+  tools: tools.map((t) => ({ id: t.id, description: t.description, requiresApproval: t.requiresApproval ?? false })),
+})
+
+// --- Helpers -----------------------------------------------------------------------------
+
+type FailCode = "NOT_FOUND" | "CONFLICT" | "VALIDATION" | "FORBIDDEN"
+
+function fail(code: FailCode, reason: string, operationId: string): never {
+  throw toConvexError(new SystemError(code, undefined, { reason, operationId }), operationId)
+}
+
+const actorArgs = { apiKey: v.optional(v.string()), operationId: v.optional(v.string()) }
+const ACTIVE_RUN: ReadonlySet<RunStatus> = new Set(["queued", "running", "waiting-approval"])
+const finishStatus = v.union(v.literal("done"), v.literal("error"), v.literal("stopped"), v.literal("waiting-approval"))
+const errorInfo = v.object({ code: v.string(), message: v.string() })
+
+/** First line-ish of the first message, whitespace collapsed. */
+const autoTitle = (text: string) => {
+  const flat = text.replace(/\s+/g, " ").trim()
+  return flat.length <= AUTO_TITLE_LENGTH ? flat : `${flat.slice(0, AUTO_TITLE_LENGTH - 1).trimEnd()}…`
+}
+
+/**
+ * The AI module's Convex functions, bound to the app's system:
+ *   // convex/ai.ts
+ *   export const { listAgents, listThreads, …, _startRun, … } = defineAi(system, aiOptions).functions
+ * Names: AI_PUBLIC_FUNCTIONS + AI_INTERNAL_FUNCTIONS in contract.ts.
+ */
+export function defineAi(system: ConvexSystem, options: AiOptions) {
+  if (!options.agents.length) throw new Error("defineAi: at least one agent is required")
+  const agents = new Map(options.agents.map((a) => [a.id, a]))
+  const runnerRef = makeFunctionReference<"action">(`${options.runnerModule ?? "aiRunner"}:runAgent`)
+
+  /** Permission, module, role view, then human-only. */
+  async function guard(ctx: DbCtx, a: { apiKey?: string | undefined; operationId?: string | undefined }): Promise<{ sys: SystemContext; actor: UserActor }> {
+    const { sys, actor } = await system.requirePermission(ctx, AiPermissions.use, { apiKey: a.apiKey, operationId: a.operationId })
+    try {
+      return { sys, actor: requireHuman(sys, actor) }
+    } catch (e) {
+      throw toConvexError(e, sys.operationId)
+    }
+  }
+
+  /** A thread the caller owns. Missing and foreign threads look the same. */
+  async function ownThread(ctx: { db: unknown }, sys: SystemContext, actor: UserActor, threadId: string): Promise<ThreadDoc> {
+    const thread = await db(ctx).get("aiThreads", threadId)
+    if (!thread || thread.ownerId !== actor.userId) fail("NOT_FOUND", "thread_not_found", sys.operationId)
+    return thread!
+  }
+
+  function schedule(ctx: { scheduler: unknown }, runId: AiRunId) {
+    return (ctx.scheduler as Scheduler).runAfter(0, runnerRef, { runId })
+  }
+
+  /** Closes a run: run, its assistant message and the thread. */
+  async function finish(ctx: { db: unknown }, run: RunDoc, status: "done" | "error" | "stopped" | "waiting-approval", error?: ErrorInfo) {
+    const now = Date.now()
+    await db(ctx).patch("aiRuns", run._id, { status, updatedAt: now, ...(error ? { error } : {}) })
+    const message = await db(ctx).get("aiMessages", run.messageId)
+    if (message) {
+      // Waiting for approval: the message is complete for now; its parts hold the pending call.
+      const msgStatus: MessageStatus = status === "waiting-approval" ? "done" : status
+      const patch: Partial<MessageDoc> = { status: msgStatus }
+      // The message carries the run's operationId so the UI can show it next to the error.
+      if (error) patch.error = { code: error.code, message: error.message, operationId: run.operationId }
+      if (status === "stopped") {
+        // Nobody can approve a stopped run's calls any more.
+        patch.parts = message.parts.map((p) => (p.type === "tool-call" && p.state === "awaiting-approval" ? { ...p, state: "rejected", error: "stopped" } : p))
+      }
+      await db(ctx).patch("aiMessages", message._id, patch)
+    }
+    await db(ctx).patch("aiThreads", run.threadId, { status: status === "waiting-approval" ? "waiting-approval" : "idle", updatedAt: now })
+  }
+
+  /** Puts a run back in the queue and schedules the runner. */
+  async function resume(ctx: { db: unknown; scheduler: unknown }, run: RunDoc) {
+    const now = Date.now()
+    await db(ctx).patch("aiRuns", run._id, { status: "queued", updatedAt: now })
+    await db(ctx).patch("aiMessages", run.messageId, { status: "streaming" })
+    await db(ctx).patch("aiThreads", run.threadId, { status: "running", updatedAt: now })
+    await schedule(ctx, run._id)
+  }
+
+  async function bindRun(ctx: DbCtx, run: RunDoc) {
+    return (await system.context(ctx, { operationId: run.operationId })).sys
+  }
+
+  async function updateMessageParts(ctx: { db: unknown }, messageId: string, fn: (parts: MessagePart[]) => MessagePart[] | null) {
+    const message = await db(ctx).get("aiMessages", messageId)
+    if (!message) throw toConvexError(new SystemError("NOT_FOUND", undefined, { reason: "message_not_found" }))
+    const parts = fn(message.parts)
+    if (parts) await db(ctx).patch("aiMessages", messageId, { parts })
+  }
+
+  const functions = {
+    // --- Public ---------------------------------------------------------------------------
+
+    listAgents: queryGeneric({
+      args: { ...actorArgs },
+      handler: async (ctx, a): Promise<AgentView[]> => {
+        const { sys, actor } = await guard(ctx, a)
+        const out: AgentView[] = []
+        for (const agent of options.agents) {
+          const tools = []
+          for (const tool of agent.tools) if ((await decide(sys, actor, tool.permission)).allowed) tools.push(tool)
+          out.push(agentView(agent, tools))
+        }
+        return out
+      },
+    }),
+
+    listThreads: queryGeneric({
+      args: { ...actorArgs, cursor: v.optional(v.union(v.string(), v.null())), limit: v.optional(v.number()) },
+      handler: async (ctx, a): Promise<{ items: ThreadView[]; cursor: string | null; done: boolean }> => {
+        const { actor } = await guard(ctx, a)
+        const numItems = Math.min(Math.max(1, Math.floor(a.limit ?? PAGE_DEFAULT)), PAGE_MAX)
+        const res = await db(ctx)
+          .query("aiThreads")
+          .withIndex("by_owner", (q) => q.eq("ownerId", actor.userId).eq("archived", false))
+          .order("desc")
+          .paginate({ cursor: a.cursor ?? null, numItems })
+        return { items: res.page.map(threadView), cursor: res.isDone ? null : res.continueCursor, done: res.isDone }
+      },
+    }),
+
+    getThread: queryGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads") },
+      handler: async (ctx, a): Promise<ThreadView> => {
+        const { sys, actor } = await guard(ctx, a)
+        return threadView(await ownThread(ctx, sys, actor, a.threadId))
+      },
+    }),
+
+    listMessages: queryGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads") },
+      handler: async (ctx, a): Promise<MessageView[]> => {
+        const { sys, actor } = await guard(ctx, a)
+        await ownThread(ctx, sys, actor, a.threadId)
+        const rows = await db(ctx)
+          .query("aiMessages")
+          .withIndex("by_thread", (q) => q.eq("threadId", a.threadId))
+          .order("asc")
+          .collect()
+        return rows.map(messageView)
+      },
+    }),
+
+    createThread: mutationGeneric({
+      args: { ...actorArgs, agentId: v.optional(v.string()), title: v.optional(v.string()) },
+      handler: async (ctx, a): Promise<{ threadId: AiThreadId }> => {
+        const { sys, actor } = await guard(ctx, a)
+        const agentId = a.agentId ?? options.agents[0]!.id
+        if (!agents.has(agentId)) fail("VALIDATION", "unknown_agent", sys.operationId)
+        const title = (a.title ?? "").trim()
+        if (title.length > AI_TITLE_MAX) fail("VALIDATION", "title_too_long", sys.operationId)
+        const now = Date.now()
+        const threadId = await db(ctx).insert("aiThreads", { ownerId: actor.userId, title, agentId, status: "idle", archived: false, createdAt: now, updatedAt: now })
+        await recordAudit(sys, actor, { action: AI_AUDIT.threadCreate, targetType: "aiThread", targetId: threadId, changes: { agentId } })
+        return { threadId }
+      },
+    }),
+
+    sendMessage: mutationGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads"), text: v.string() },
+      handler: async (ctx, a): Promise<{ messageId: AiMessageId; runId: AiRunId }> => {
+        const { sys, actor } = await guard(ctx, a)
+        const thread = await ownThread(ctx, sys, actor, a.threadId)
+        const text = a.text.trim()
+        if (!text) fail("VALIDATION", "empty_message", sys.operationId)
+        if (text.length > AI_MESSAGE_MAX) fail("VALIDATION", "message_too_long", sys.operationId)
+        if (thread.status !== "idle") fail("CONFLICT", "thread_busy", sys.operationId)
+        const agent = agents.get(thread.agentId)
+        if (!agent) fail("VALIDATION", "unknown_agent", sys.operationId)
+
+        const now = Date.now()
+        const messageId = await db(ctx).insert("aiMessages", { threadId: thread._id, role: "user", parts: [{ type: "text", text }], status: "done", createdAt: now })
+        const assistantId = await db(ctx).insert("aiMessages", { threadId: thread._id, role: "assistant", parts: [], status: "streaming", createdAt: now + 1 })
+        const runId = await db(ctx).insert("aiRuns", {
+          threadId: thread._id,
+          messageId: assistantId,
+          actor: toActorRef(actor),
+          agentId: agent!.id,
+          model: agent!.model ?? process.env.AI_MODEL ?? options.defaultModel,
+          status: "queued",
+          stopRequested: false,
+          operationId: sys.operationId,
+          createdAt: now,
+          updatedAt: now,
+        })
+        await db(ctx).patch("aiMessages", assistantId, { runId })
+        await db(ctx).patch("aiThreads", thread._id, { status: "running", updatedAt: now, ...(thread.title ? {} : { title: autoTitle(text) }) })
+        await schedule(ctx, runId)
+        await recordAudit(sys, actor, { action: AI_AUDIT.messageSend, targetType: "aiThread", targetId: thread._id, changes: { messageId, runId, length: text.length } })
+        return { messageId, runId }
+      },
+    }),
+
+    stopRun: mutationGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads") },
+      handler: async (ctx, a): Promise<{ stopped: boolean }> => {
+        const { sys, actor } = await guard(ctx, a)
+        const thread = await ownThread(ctx, sys, actor, a.threadId)
+        const run = await db(ctx)
+          .query("aiRuns")
+          .withIndex("by_thread", (q) => q.eq("threadId", thread._id))
+          .order("desc")
+          .first()
+        if (!run || !ACTIVE_RUN.has(run.status)) return { stopped: false }
+        await db(ctx).patch("aiRuns", run._id, { stopRequested: true, updatedAt: Date.now() })
+        // Nothing is executing a queued or approval-waiting run: close it now.
+        // A running one is closed by the runner when it sees `stopRequested`.
+        if (run.status !== "running") await finish(ctx, run, "stopped")
+        await recordAudit(sys, actor, { action: AI_AUDIT.runStop, targetType: "aiRun", targetId: run._id, changes: { threadId: thread._id, status: run.status } })
+        return { stopped: true }
+      },
+    }),
+
+    respondToToolCall: mutationGeneric({
+      args: { ...actorArgs, messageId: v.id("aiMessages"), toolCallId: v.string(), approve: v.boolean() },
+      handler: async (ctx, a): Promise<{ runId: AiRunId }> => {
+        const { sys, actor } = await guard(ctx, a)
+        const message = await db(ctx).get("aiMessages", a.messageId)
+        if (!message) fail("NOT_FOUND", "message_not_found", sys.operationId)
+        await ownThread(ctx, sys, actor, message!.threadId)
+        const run = message!.runId ? await db(ctx).get("aiRuns", message!.runId) : null
+        if (!run) fail("NOT_FOUND", "run_not_found", sys.operationId)
+        const part = message!.parts.find((p) => p.type === "tool-call" && p.toolCallId === a.toolCallId)
+        if (part?.type !== "tool-call") fail("NOT_FOUND", "tool_call_not_found", sys.operationId)
+        if (part!.state !== "awaiting-approval" || run!.stopRequested) fail("CONFLICT", "tool_call_not_awaiting_approval", sys.operationId)
+
+        const state: ToolCallState = a.approve ? "approved" : "rejected"
+        const parts = message!.parts.map((p) => (p.type === "tool-call" && p.toolCallId === a.toolCallId ? { ...p, state } : p))
+        await db(ctx).patch("aiMessages", message!._id, { parts })
+        await recordAudit(sys, actor, {
+          action: a.approve ? AI_AUDIT.toolApprove : AI_AUDIT.toolReject,
+          targetType: "aiToolCall",
+          targetId: a.toolCallId,
+          changes: { runId: run!._id, toolName: (part as { toolName: string }).toolName },
+        })
+        const pending = parts.some((p) => p.type === "tool-call" && p.state === "awaiting-approval")
+        // Resume only once the runner has parked the run; if it is still
+        // finishing, `_finishRun("waiting-approval")` resumes it instead.
+        if (!pending && run!.status === "waiting-approval") await resume(ctx, run!)
+        return { runId: run!._id }
+      },
+    }),
+
+    renameThread: mutationGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads"), title: v.string() },
+      handler: async (ctx, a): Promise<null> => {
+        const { sys, actor } = await guard(ctx, a)
+        const thread = await ownThread(ctx, sys, actor, a.threadId)
+        const title = a.title.trim()
+        if (!title || title.length > AI_TITLE_MAX) fail("VALIDATION", "invalid_title", sys.operationId)
+        await db(ctx).patch("aiThreads", thread._id, { title, updatedAt: Date.now() })
+        return null
+      },
+    }),
+
+    archiveThread: mutationGeneric({
+      args: { ...actorArgs, threadId: v.id("aiThreads") },
+      handler: async (ctx, a): Promise<null> => {
+        const { sys, actor } = await guard(ctx, a)
+        const thread = await ownThread(ctx, sys, actor, a.threadId)
+        await db(ctx).patch("aiThreads", thread._id, { archived: true, updatedAt: Date.now() })
+        return null
+      },
+    }),
+
+    // --- Internal (runner only) -------------------------------------------------------------
+
+    _startRun: internalMutationGeneric({
+      args: { runId: v.id("aiRuns") },
+      handler: async (ctx, a): Promise<RunContext | null> => {
+        const run = await db(ctx).get("aiRuns", a.runId)
+        if (!run) return null
+        if (run.stopRequested) {
+          if (ACTIVE_RUN.has(run.status)) await finish(ctx, run, "stopped")
+          return null
+        }
+        // Only a queued run starts: a duplicate schedule is a no-op.
+        if (run.status !== "queued") return null
+        const sys = await bindRun(ctx, run)
+        const agent = agents.get(run.agentId)
+        if (!agent) {
+          await finish(ctx, run, "error", { code: "VALIDATION", message: "unknown_agent" })
+          return null
+        }
+        // The actor may have lost the chat itself since the message was sent.
+        if (!(await authorizeJob(sys, run.actor, AiPermissions.use))) {
+          await finish(ctx, run, "error", { code: "FORBIDDEN", message: "chat_not_allowed" })
+          return null
+        }
+        const allowedToolIds: string[] = []
+        for (const tool of agent.tools) if (await authorizeJob(sys, run.actor, tool.permission)) allowedToolIds.push(tool.id)
+        const now = Date.now()
+        await db(ctx).patch("aiRuns", run._id, { status: "running", updatedAt: now })
+        await db(ctx).patch("aiThreads", run.threadId, { status: "running", updatedAt: now })
+        const history = await db(ctx)
+          .query("aiMessages")
+          .withIndex("by_thread", (q) => q.eq("threadId", run.threadId))
+          .order("asc")
+          .collect()
+        return {
+          runId: run._id,
+          threadId: run.threadId,
+          messageId: run.messageId,
+          agentId: run.agentId,
+          model: run.model,
+          actor: run.actor,
+          operationId: run.operationId,
+          history: history.map(messageView),
+          allowedToolIds,
+        }
+      },
+    }),
+
+    _appendText: internalMutationGeneric({
+      args: { messageId: v.id("aiMessages"), text: v.string() },
+      handler: async (ctx, a): Promise<null> => {
+        if (!a.text) return null
+        await updateMessageParts(ctx, a.messageId, (parts) => {
+          const last = parts.at(-1)
+          if (last?.type === "text") return [...parts.slice(0, -1), { type: "text", text: last.text + a.text }]
+          return [...parts, { type: "text", text: a.text }]
+        })
+        return null
+      },
+    }),
+
+    _addToolCall: internalMutationGeneric({
+      args: { messageId: v.id("aiMessages"), toolCallId: v.string(), toolName: v.string(), args: v.any(), state: toolCallState },
+      handler: async (ctx, a): Promise<null> => {
+        await updateMessageParts(ctx, a.messageId, (parts) => {
+          // Idempotent: a retried runner step must not duplicate the call.
+          if (parts.some((p) => p.type === "tool-call" && p.toolCallId === a.toolCallId)) return null
+          return [...parts, { type: "tool-call", toolCallId: a.toolCallId, toolName: a.toolName, args: a.args, state: a.state }]
+        })
+        return null
+      },
+    }),
+
+    _setToolCallState: internalMutationGeneric({
+      args: { messageId: v.id("aiMessages"), toolCallId: v.string(), state: toolCallState, result: v.optional(v.any()), error: v.optional(v.string()) },
+      handler: async (ctx, a): Promise<null> => {
+        await updateMessageParts(ctx, a.messageId, (parts) => {
+          if (!parts.some((p) => p.type === "tool-call" && p.toolCallId === a.toolCallId)) {
+            throw toConvexError(new SystemError("NOT_FOUND", undefined, { reason: "tool_call_not_found" }))
+          }
+          return parts.map((p) => {
+            if (p.type !== "tool-call" || p.toolCallId !== a.toolCallId) return p
+            const next = { ...p, state: a.state }
+            if (a.result !== undefined) next.result = a.result
+            if (a.error !== undefined) next.error = a.error
+            return next
+          })
+        })
+        return null
+      },
+    }),
+
+    _executeTool: internalMutationGeneric({
+      args: { runId: v.id("aiRuns"), toolCallId: v.string() },
+      handler: async (ctx, a): Promise<ToolExecutionResult> => {
+        const run = await db(ctx).get("aiRuns", a.runId)
+        if (!run) return { ok: false, code: "NOT_FOUND", message: "run_not_found" }
+        const message = await db(ctx).get("aiMessages", run.messageId)
+        const part = message?.parts.find((p) => p.type === "tool-call" && p.toolCallId === a.toolCallId)
+        if (part?.type !== "tool-call") return { ok: false, code: "NOT_FOUND", message: "tool_call_not_found" }
+        const tool = agents.get(run.agentId)?.tools.find((t) => t.id === part.toolName)
+        if (!tool) return { ok: false, code: "VALIDATION", message: "unknown_tool" }
+        // Defence in depth: an approval-gated tool never runs before the user approved it.
+        if (tool.requiresApproval && part.state !== "approved" && part.state !== "running") return { ok: false, code: "FORBIDDEN", message: "approval_required" }
+        const sys = await bindRun(ctx, run)
+        return executeAiTool({ db: ctx.db, sys, actorRef: run.actor, tool, args: part.args, toolCallId: a.toolCallId })
+      },
+    }),
+
+    _finishRun: internalMutationGeneric({
+      args: { runId: v.id("aiRuns"), status: finishStatus, error: v.optional(errorInfo) },
+      handler: async (ctx, a): Promise<null> => {
+        const run = await db(ctx).get("aiRuns", a.runId)
+        if (!run) return null
+        // Stop wins over whatever the runner reports, except an error.
+        const status = run.stopRequested && a.status !== "error" ? "stopped" : a.status
+        if (status === "waiting-approval") {
+          const message = await db(ctx).get("aiMessages", run.messageId)
+          const pending = message?.parts.some((p) => p.type === "tool-call" && p.state === "awaiting-approval") ?? false
+          // The user already answered every call while the runner was finishing: go on.
+          if (!pending) {
+            await resume(ctx, run)
+            return null
+          }
+        }
+        await finish(ctx, run, status, a.error)
+        return null
+      },
+    }),
+
+    _isStopRequested: internalQueryGeneric({
+      args: { runId: v.id("aiRuns") },
+      handler: async (ctx, a): Promise<boolean> => {
+        const run = await db(ctx).get("aiRuns", a.runId)
+        return !run || run.stopRequested
+      },
+    }),
+  }
+
+  return { functions }
+}
+
+export type AiSystem = ReturnType<typeof defineAi>

package/src/ai/card.ts

@@ -0,0 +1,91 @@
+// `@digimuza/system-core/ai/card`: the browser side of `ai.show_card`. No
+// dependencies, safe for client bundles. See display.ts for the security model:
+// render ONLY in <iframe sandbox="allow-scripts" srcDoc={cardDocument(...)}>.
+
+export const AI_CARD_HTML_MAX = 60_000
+export const AI_CARD_TITLE_MAX = 120
+/** `postMessage` type the card's resize script sends to the parent. */
+export const AI_CARD_RESIZE_MESSAGE = "ai-card:height"
+
+/** Theme passed into the card: CSS custom properties (name without `--`) → value. */
+export type CardTheme = Record<string, string>
+
+/** Theme variables a card may use (the app copies their computed values). */
+export const AI_CARD_THEME_VARS = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "muted",
+  "muted-foreground",
+  "border",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "radius",
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+] as const
+
+/**
+ * The CSP of every card: inline styles and scripts only, images from data: only,
+ * no network (connect/fetch/fonts/frames/forms), no base-uri tricks.
+ */
+export const AI_CARD_CSP = [
+  "default-src 'none'",
+  "style-src 'unsafe-inline'",
+  "script-src 'unsafe-inline'",
+  "img-src data:",
+  "font-src 'none'",
+  "connect-src 'none'",
+  "media-src 'none'",
+  "frame-src 'none'",
+  "form-action 'none'",
+  "base-uri 'none'",
+].join("; ")
+
+const safeCssValue = (v: string) => v.replace(/[<>{};\\]/g, "")
+const safeVarName = (k: string) => /^[a-z][a-z0-9-]*$/.test(k)
+
+/**
+ * The full `srcdoc` for a card iframe: CSP meta first, theme variables, base
+ * styles, the model's HTML, and a resize script that posts the content height
+ * to the parent (`{ type: AI_CARD_RESIZE_MESSAGE, id, height }`).
+ * Render it ONLY in `<iframe sandbox="allow-scripts" srcDoc={...}>`.
+ */
+export function cardDocument(options: { html: string; id: string; theme?: CardTheme; dark?: boolean; fontFamily?: string }): string {
+  const vars = Object.entries(options.theme ?? {})
+    .filter(([k]) => safeVarName(k))
+    .map(([k, v]) => `--${k}:${safeCssValue(v)};`)
+    .join("")
+  const font = safeCssValue(options.fontFamily ?? 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif')
+  const id = JSON.stringify(String(options.id).replace(/[^A-Za-z0-9_-]/g, "").slice(0, 100))
+  return `<!doctype html><html${options.dark ? ' class="dark"' : ""}><head><meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${AI_CARD_CSP}">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+:root{${vars}color-scheme:${options.dark ? "dark" : "light"};}
+*,*::before,*::after{box-sizing:border-box;}
+html,body{margin:0;padding:0;background:transparent;color:var(--foreground);font-family:${font};font-size:14px;line-height:1.5;-webkit-font-smoothing:antialiased;}
+body{padding:16px;overflow-wrap:anywhere;}
+h1,h2,h3,h4{margin:0 0 .5em;line-height:1.25;font-weight:600;text-wrap:balance;}
+h1{font-size:1.25rem;}h2{font-size:1.125rem;}h3{font-size:1rem;}
+p{margin:0 0 .75em;}p:last-child{margin-bottom:0;}
+table{width:100%;border-collapse:collapse;font-variant-numeric:tabular-nums;}
+th,td{padding:6px 8px;border-bottom:1px solid var(--border);text-align:left;}
+th{color:var(--muted-foreground);font-weight:500;font-size:.85em;}
+a{color:var(--primary);pointer-events:none;}
+svg{max-width:100%;height:auto;}
+img{max-width:100%;}
+</style></head><body>${options.html}
+<script>(function(){var id=${id};var last=0;function send(){var h=Math.ceil(document.documentElement.getBoundingClientRect().height);if(h!==last){last=h;parent.postMessage({type:${JSON.stringify(AI_CARD_RESIZE_MESSAGE)},id:id,height:h},"*");}}
+new ResizeObserver(send).observe(document.documentElement);window.addEventListener("load",send);send();})();</script>
+</body></html>`
+}