@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/ai/index.ts

@@ -1,3 +1,5 @@
+export { CODE_SOURCE_TOOLS, type CodeSourceToolName } from "./code-source-contracts";
+export { CodeResourceId, CODE_RUNTIME_TOOL_NAMES, CodeRuntimeInput, parseCodeToolInput } from "./browser-code-contracts";
 export { assistantAiSettingsState, listAssistantAiModels } from "./assistant-models";
 export { type AiApprovalPreferenceRoutes, type AiApprovalPreferenceView, createAiApprovalPreferenceRoutes } from "./approval-routes";
 export {
@@ -19,6 +21,7 @@ export {
   type AiChatTaskView,
   AiConversationIdSchema,
   ChatTaskIdSchema,
+  ChatTaskGrantsSchema,
   ChatTaskOccurrenceIdSchema,
   ChatTaskScheduleInputSchema,
   chatTaskCreateFingerprint,
@@ -72,6 +75,9 @@ export {
   type AiFileStat,
   guessAiMediaType,
   listAiConversationFiles,
+  readAiConversationFile,
+  createAiConversationArtifact,
+  writeAiConversationFile,
   normalizeAiFilePath,
 } from "./files-store";
 export {
@@ -214,7 +220,7 @@ export {
   selectAiModelProfile,
   toPublicAiSettingsState,
 } from "./settings";
-export { AI_SHORT_ID_PATTERN, createAiShortId } from "./short-id";
+export { AI_SHORT_ID_PATTERN, createAiShortId, withAiShortIdForDb } from "./short-id";
 export {
   AI_SKILL_DESCRIPTION_MAX_CHARS,
   AI_SKILL_EXTRA_FRONTMATTER_MAX_CHARS,
@@ -237,7 +243,7 @@ export {
   validateAiSkillName,
   validateAiSkillReferences,
 } from "./skill-format";
-export { seedCloudAiSkills } from "./skill-seeds";
+export { seedCloudAiSkills } from "./skills";
 export {
   type AiLoadedSkillSnapshot,
   type AiSkill,
@@ -335,3 +341,21 @@ export {
   type CloudAiViewImageOutput,
   CloudAiViewImageOutputSchema,
 } from "./vision-tool";
+
+export {
+  createAiTranscriptionProvider,
+  resolveAiAudioModel,
+  runAiTranscription,
+  type AiResolvedAudioModel,
+  type RunAiTranscriptionInput,
+} from "./transcription";
+
+export { createCloudAiTranscribeAudioTool, CloudAiTranscribeAudioInputSchema, CloudAiTranscribeAudioOutputSchema } from "./audio-tool";
+
+export { getAiChatQuotas } from "./chat-quotas";
+
+export { AiFileLocation, AiFileReference } from "./file-reference-contracts";
+export { aiFileContentVersion, AiFileWriteError, AiFileVersionConflict } from "./file-content-version";
+
+// Framework-owned managed execution host transport.
+export { createCodeCapabilityTransport, CODE_CAPABILITY_TOKEN_HEADER } from "./code-capability-transport";

package/src/ai/inference-calls.ts

@@ -0,0 +1,198 @@
+import { hasBillableAiPricing } from "../shared/ai-costs";
+import { sql, type SQL } from "bun";
+import type { AccessSubject } from "../server/services/access";
+import { aiCostDecimal, aiCostUnits, aiDecimalUnits, aiBudgetUnits } from "../shared/ai-costs";
+import type { AiModelProfile } from "./types";
+import { aiQuotas, AiQuotaError, quotaWindow } from "./quotas";
+
+export class AiBackgroundCostError extends Error {
+  readonly code = "ai_background_cost_stop";
+  constructor() {
+    super("Background AI is paused by the cost safety limit. An administrator must review Usage rules.");
+  }
+}
+
+/** Admission can fail without latching the instance-wide emergency stop. */
+export class AiBackgroundAdmissionError extends Error {
+  readonly code: string;
+  constructor(readonly retryable: boolean) {
+    super(
+      retryable
+        ? "Background AI budget is reserved by running calls. Try again after they finish."
+        : "This call cannot fit in the remaining background AI budget.",
+    );
+    this.code = retryable ? "ai_background_budget_reserved" : "ai_background_budget_insufficient";
+  }
+}
+
+export type AiCallContext = {
+  kind: "chat" | "background";
+  task: string;
+  subject?: AccessSubject | null;
+  userId?: string;
+  conversationId?: string;
+  turnId?: string;
+  workflowRunId?: string;
+  stepKey?: string;
+  traceId?: string;
+  appId?: string;
+};
+
+export async function backgroundCostState(db: SQL = sql) {
+  const [row] = await db<
+    { used: number; reserved: number; usedExact: string; reservedExact: string; unknown: number; stoppedAt: Date | null; unit: string }[]
+  >`
+    SELECT COALESCE(sum(cost),0)::text AS "usedExact",
+      COALESCE(sum(reserved) FILTER(WHERE finished_at IS NULL AND lease_expires_at>now()),0)::text AS "reservedExact",
+      COALESCE(sum(cost),0)::float8 AS used,
+      COALESCE(sum(reserved) FILTER(WHERE finished_at IS NULL AND lease_expires_at>now()),0)::float8 AS reserved,
+      count(*) FILTER(WHERE (COALESCE((pricing->>'inputPerMillion')::numeric,0)>0 OR COALESCE((pricing->>'outputPerMillion')::numeric,0)>0) AND cost IS NULL AND (finished_at IS NOT NULL OR lease_expires_at<=now()))::int AS unknown,
+      (SELECT background_stopped_at FROM ai.cost_config WHERE singleton) AS "stoppedAt",
+      (SELECT unit FROM ai.cost_config WHERE singleton) AS unit
+    FROM ai.inference_calls WHERE kind='background' AND started_at>=now()-interval '24 hours'`;
+  return row!;
+}
+
+/** Called under the configuration lock; persist transitions before notification delivery. */
+async function checkBackgroundBudget(db: SQL) {
+  const config = await aiQuotas.config(db);
+  const state = await backgroundCostState(db);
+  if (!config.background?.enabled) return state;
+  const [flags] = await db<{ background_warned: boolean }[]>`SELECT background_warned FROM ai.cost_config WHERE singleton`;
+  const warning = config.background.warnAt !== null && aiDecimalUnits(state.usedExact) >= aiBudgetUnits(config.background.warnAt);
+  const stop = aiDecimalUnits(state.usedExact) >= aiBudgetUnits(config.background.stopAt) || state.unknown > 0;
+  for (const kind of [...(warning && !flags!.background_warned ? ["warning"] : []), ...(stop && !state.stoppedAt ? ["stop"] : [])])
+    await db`INSERT INTO ai.cost_alerts(id,kind,cost,unit) VALUES(${crypto.randomUUID()}::uuid,${kind},${state.usedExact}::numeric,${config.unit ?? "EUR"})`;
+  await db`UPDATE ai.cost_config SET background_warned=${warning},
+    background_stopped_at=CASE WHEN ${stop} THEN COALESCE(background_stopped_at,clock_timestamp()) ELSE background_stopped_at END WHERE singleton`;
+  return backgroundCostState(db);
+}
+
+/** Admission and reservation share the settings lock across all worker processes. */
+export async function beginAiCall(
+  profile: AiModelProfile,
+  context: AiCallContext,
+  inputTokens: number,
+  requestedOutput?: number,
+  outputBound?: number,
+) {
+  const result = await sql.begin(async (db) => {
+    await db`SELECT singleton FROM ai.cost_config WHERE singleton FOR UPDATE`;
+    const config = await aiQuotas.config(db);
+    let remaining: bigint | undefined;
+    let backgroundHeadroom: bigint | undefined;
+    if (hasBillableAiPricing(profile.pricing) && context.kind === "background" && config.background?.enabled) {
+      const state = await checkBackgroundBudget(db);
+      if (state.stoppedAt || aiDecimalUnits(state.usedExact) >= aiBudgetUnits(config.background.stopAt) || state.unknown) {
+        await db`UPDATE ai.cost_config SET background_stopped_at=COALESCE(background_stopped_at,clock_timestamp()) WHERE singleton`;
+        return { error: new AiBackgroundCostError() };
+      }
+      backgroundHeadroom = aiBudgetUnits(config.background.stopAt) - aiDecimalUnits(state.usedExact);
+      remaining = backgroundHeadroom - aiDecimalUnits(state.reservedExact);
+    }
+    if (hasBillableAiPricing(profile.pricing) && context.kind === "chat" && context.subject && config.enabled) {
+      const now = new Date();
+      const snapshot = await aiQuotas.snapshot(context.subject, profile.id, now, db);
+      for (const balance of snapshot.balances) {
+        if (balance.bypassed || balance.limit === null) continue;
+        if (balance.unknown)
+          return {
+            error: new AiQuotaError(
+              "quota_usage_unknown",
+              "Chat costs could not be measured. Reset the allowance or wait for the next window.",
+            ),
+          };
+        const rule = config.rules.find((rule) => rule.scope === balance.scope)!;
+        const window = quotaWindow(rule.anchor, rule.hours, now);
+        const user = context.subject.type === "user" ? context.subject.userId : null;
+        const service = context.subject.type === "service_account" ? context.subject.serviceAccountId : null;
+        const [pending] = await db<{ committed: string }[]>`
+          SELECT (COALESCE(sum(cost),0)+COALESCE(sum(reserved) FILTER(WHERE finished_at IS NULL AND lease_expires_at>now()),0))::text AS committed FROM ai.inference_calls c
+          WHERE kind='chat'
+            AND user_id IS NOT DISTINCT FROM ${user}::uuid AND service_account_id IS NOT DISTINCT FROM ${service}::uuid
+            AND (${balance.scope}='*' OR model_profile_id=${balance.scope}) AND started_at>=${window.from} AND started_at<${window.until}
+            AND started_at>COALESCE((SELECT max(created_at) FROM ai.cost_resets r
+              WHERE r.user_id IS NOT DISTINCT FROM ${user}::uuid AND r.service_account_id IS NOT DISTINCT FROM ${service}::uuid AND r.scope=${balance.scope}),'-infinity'::timestamptz)`;
+        const available = aiBudgetUnits(balance.limit) - aiDecimalUnits(pending?.committed ?? "0");
+        remaining = remaining === undefined || available < remaining ? available : remaining;
+      }
+    }
+    let maxOutputTokens = requestedOutput;
+    let reserved = "0";
+    if (profile.pricing && remaining !== undefined) {
+      const inputCost = aiCostUnits(profile.pricing, inputTokens, 0);
+      const outputPrice = aiCostUnits(profile.pricing, 0, 1);
+      const affordable = outputPrice > 0n ? Number((remaining - inputCost) / outputPrice) : Infinity;
+      if (inputCost > remaining || affordable < 1)
+        return {
+          error:
+            context.kind === "background"
+              ? new AiBackgroundAdmissionError(backgroundHeadroom !== undefined && inputCost + outputPrice <= backgroundHeadroom)
+              : new AiQuotaError("quota_exhausted", "Chat cost limit reached."),
+        };
+      const reserveOutput = Math.min(requestedOutput ?? outputBound ?? affordable, affordable);
+      // Preserve adapter defaults unless an explicit maximum or budget requires a cap.
+      if (requestedOutput !== undefined || reserveOutput < (outputBound ?? Infinity)) maxOutputTokens = reserveOutput;
+      reserved = aiCostDecimal(aiCostUnits(profile.pricing, inputTokens, Number.isFinite(reserveOutput) ? reserveOutput : 0));
+    }
+    const workflow = context.workflowRunId
+      ? (
+          await db<{ id: string; name: string; app: string; revision: number }[]>`
+      SELECT w.id,w.name,r.app_id AS app,v.revision FROM workflows.run r
+      JOIN workflows.workflow w ON w.id=r.workflow_id JOIN workflows.version v ON v.id=r.workflow_version_id
+      WHERE r.id=${context.workflowRunId}::uuid`
+        )[0]
+      : undefined;
+    const id = crypto.randomUUID();
+    const userId = context.subject?.type === "user" ? context.subject.userId : context.userId;
+    const serviceId = context.subject?.type === "service_account" ? context.subject.serviceAccountId : null;
+    await db`INSERT INTO ai.inference_calls(id,user_id,service_account_id,model_profile_id,provider_model,kind,task,
+      turn_id,turn_attempt,conversation_id,workflow_run_id,step_key,trace_id,app_id,workflow_id,workflow_name,workflow_version,pricing,reserved,lease_expires_at)
+      VALUES(${id}::uuid,CASE WHEN ${serviceId}::uuid IS NULL THEN COALESCE(${userId ?? null}::uuid,(SELECT created_by_user_id FROM ai.conversations WHERE id=${context.conversationId ?? null}::uuid)) ELSE NULL END,
+        ${serviceId}::uuid,${profile.id},${profile.model},${context.kind},${context.task},${context.turnId ?? null}::uuid,
+        (SELECT attempt FROM ai.turns WHERE id=${context.turnId ?? null}::uuid),${context.conversationId ?? null}::uuid,
+        ${context.workflowRunId ?? null}::uuid,${context.stepKey ?? null},${context.traceId ?? null},COALESCE(${workflow?.app ?? context.appId ?? null},(SELECT launched_by_app_id FROM ai.conversations WHERE id=${context.conversationId ?? null}::uuid),'core'),${workflow?.id ?? null}::uuid,${workflow?.name ?? null},${workflow?.revision ?? null},
+        (${profile.pricing ? JSON.stringify(profile.pricing) : null}::text)::jsonb,${reserved}::numeric,now()+interval '2 minutes')`;
+    return { id, maxOutputTokens };
+  });
+  if (result.error) throw result.error;
+  return { id: result.id!, maxOutputTokens: result.maxOutputTokens };
+}
+
+export async function finishAiCall(
+  id: string,
+  usage: { input: number; output: number; estimated?: boolean } | undefined,
+  status: "ok" | "failed",
+) {
+  await sql.begin(async (db) => {
+    await db`SELECT singleton FROM ai.cost_config WHERE singleton FOR UPDATE`;
+    const [call] = await db<
+      { pricing: AiModelProfile["pricing"]; kind: string }[]
+    >`SELECT pricing,kind FROM ai.inference_calls WHERE id=${id}::uuid AND finished_at IS NULL FOR UPDATE`;
+    if (!call) return;
+    const cost =
+      call.pricing?.inputPerMillion === 0 && call.pricing.outputPerMillion === 0
+        ? "0"
+        : call.pricing && usage
+          ? aiCostDecimal(aiCostUnits(call.pricing, usage.input, usage.output))
+          : null;
+    await db`UPDATE ai.inference_calls SET input=${usage?.input ?? null},output=${usage?.output ?? null},estimated=${usage?.estimated ?? false},
+      cost=${cost}::numeric,reserved=0,finished_at=clock_timestamp(),status=${status},error_code=${status === "failed" ? "ai_provider_call_failed" : null} WHERE id=${id}::uuid`;
+    if (call.kind === "background") await checkBackgroundBudget(db);
+  });
+}
+
+export async function releaseBackgroundCostStop(actorId: string) {
+  return sql.begin(async (db) => {
+    await db`SELECT singleton FROM ai.cost_config WHERE singleton FOR UPDATE`;
+    const config = await aiQuotas.config(db);
+    const state = await backgroundCostState(db);
+    if (config.background?.enabled && (aiDecimalUnits(state.usedExact) >= aiBudgetUnits(config.background.stopAt) || state.unknown))
+      throw new AiBackgroundCostError();
+    if (!state.stoppedAt) return state;
+    await db`UPDATE ai.cost_config SET background_stopped_at=NULL,background_warned=false,revision=revision+1 WHERE singleton`;
+    const next = await aiQuotas.config(db);
+    await db`INSERT INTO ai.cost_changes(revision,actor_id,config) VALUES(${next.revision},${actorId}::uuid,(${JSON.stringify({ ...next, action: "release-background-stop" })}::text)::jsonb)`;
+    return backgroundCostState(db);
+  });
+}

package/src/ai/live-events.ts

@@ -7,6 +7,7 @@ export const AI_INVALIDATION_DOMAINS = [
   "conversation-sources",
   "conversation-files",
   "conversation-tasks",
+  "conversation-dictations",
   "project-list",
   "project-detail",
   "project-context",
@@ -129,7 +130,10 @@ const AiConversationSchema = z
     keywords: z.array(z.string()),
     pinnedAt: z.string().nullable(),
     archivedAt: z.string().nullable(),
-    runStatus: z.enum(["idle", "queued", "running", "needs_attention", "failed"]),
+    done: z.boolean().nullable(),
+    isDone: z.boolean(),
+    lastUsedAt: z.string(),
+    runStatus: z.enum(["idle", "queued", "running", "needs_attention", "waiting_for_browser", "failed"]),
     runError: z.string().nullable(),
     unreadCompletion: z.boolean(),
     projectId: z.string().nullable(),

package/src/ai/memory-learning.ts

@@ -1,3 +1,4 @@
+import { AiBackgroundAdmissionError, AiBackgroundCostError } from "./inference-calls";
 import { sql } from "bun";
 import { createHash } from "node:crypto";
 import { z } from "zod";
@@ -217,13 +218,7 @@ export const buildMemoryLearningTranscript = (messages: AiStoredMessage[]): stri
   messages
     .flatMap((stored) => {
       const message = stored.message;
-      if (
-        stored.kind !== "message" ||
-        message.role !== "user" ||
-        stored.meta?.agentMessage ||
-        stored.meta?.scheduledTask
-      )
-        return [];
+      if (stored.kind !== "message" || message.role !== "user" || stored.meta?.agentMessage || stored.meta?.scheduledTask) return [];
       return message.content.flatMap((part) => {
         if (typeof part === "string") return part.trim() ? [part.trim()] : [];
         if (part.type !== "text") return [];
@@ -305,7 +300,15 @@ const estimatedTokens = (systemPrompt: string, taskInput: string): number =>
 
 const workflowEvidenceKey = (pattern: AiMemoryWorkflowPattern): string =>
   createHash("sha256")
-    .update(JSON.stringify([pattern.userId, pattern.capabilityId, pattern.resourceRef.type, pattern.resourceRef.id, ...[...pattern.turnIds].sort()]))
+    .update(
+      JSON.stringify([
+        pattern.userId,
+        pattern.capabilityId,
+        pattern.resourceRef.type,
+        pattern.resourceRef.id,
+        ...[...pattern.turnIds].sort(),
+      ]),
+    )
     .digest("hex");
 
 const toProposal = (change: z.infer<typeof AiMemoryLearningChangeSchema>): AiBackgroundMemoryProposal => ({
@@ -329,7 +332,8 @@ const applyChanges = async (
       !evidence.actions.some(
         (action) => action.resourceRef.type === change.resourceRef?.type && action.resourceRef.id === change.resourceRef.id,
       )
-    ) continue;
+    )
+      continue;
     const results = await aiMemories.applyBackgroundProposal({
       userId: evidence.candidate.userId,
       sourceConversationId: evidence.candidate.conversationId,
@@ -376,9 +380,7 @@ const workflowPatternInput = async (
   return {
     source: evidence[0] ?? null,
     mutableMemoryIds: new Set(
-      selected.memories
-        .filter((memory) => memory.source === "background" && memory.priority === "normal")
-        .map((memory) => memory.shortId),
+      selected.memories.filter((memory) => memory.source === "background" && memory.priority === "normal").map((memory) => memory.shortId),
     ),
     input: [
       `CAPABILITY: ${pattern.capabilityId}`,
@@ -395,7 +397,8 @@ const workflowPatternInput = async (
 const usageNumbers = (usage: RunAiStructuredResult<z.ZodType>["usage"], reserved: number) => {
   const inputTokens = usage?.input;
   const outputTokens = usage?.output;
-  const total = usage?.total ?? (inputTokens !== undefined || outputTokens !== undefined ? (inputTokens ?? 0) + (outputTokens ?? 0) : undefined);
+  const total =
+    usage?.total ?? (inputTokens !== undefined || outputTokens !== undefined ? (inputTokens ?? 0) + (outputTokens ?? 0) : undefined);
   return { inputTokens, outputTokens, accountedTokens: total ?? reserved };
 };
 
@@ -414,8 +417,7 @@ export const learnAiMemoriesFromPrivateChats = async (
   }
 
   const configuredBudget =
-    input.deps?.monthlyTokenBudget ??
-    Number(await coreSettings.get<number>(AI_MEMORY_LEARNING_MONTHLY_TOKEN_BUDGET_SETTING_KEY));
+    input.deps?.monthlyTokenBudget ?? Number(await coreSettings.get<number>(AI_MEMORY_LEARNING_MONTHLY_TOKEN_BUDGET_SETTING_KEY));
   const monthlyTokenBudget =
     Number.isFinite(configuredBudget) && configuredBudget > 0
       ? Math.floor(configuredBudget)
@@ -432,9 +434,7 @@ export const learnAiMemoriesFromPrivateChats = async (
   let defaultLocale: Promise<string> | undefined;
   const resolveLearningLocale = (locale?: string | null): Promise<string> => {
     if (locale) return Promise.resolve(normalizeLocale(locale));
-    defaultLocale ??= (input.deps?.readDefaultLocale ?? (() => coreSettings.get<string>("app.locale")))().then(
-      normalizeLocale,
-    );
+    defaultLocale ??= (input.deps?.readDefaultLocale ?? (() => coreSettings.get<string>("app.locale")))().then(normalizeLocale);
     return defaultLocale;
   };
 
@@ -514,6 +514,18 @@ export const learnAiMemoriesFromPrivateChats = async (
       if (status === "skipped") summary.skipped += 1;
       processedCandidates += 1;
     } catch (error) {
+      if (error instanceof AiBackgroundCostError || error instanceof AiBackgroundAdmissionError) {
+        summary.skipped += 1;
+        if (runId)
+          await aiMemoryLearningRuns.finish({
+            runId,
+            status: "skipped",
+            durationMs: Date.now() - startedAt,
+            changes: [],
+            accountedTokens: 0,
+          });
+        return summary;
+      }
       summary.failed += 1;
       processedCandidates += 1;
       await markFailed(candidate).catch(() => undefined);
@@ -564,7 +576,11 @@ export const learnAiMemoriesFromPrivateChats = async (
       if (!runId) continue;
       const result = await structured({
         task: "memory-learn-workflow",
-        attribution: { userId: pattern.userId, conversationId: context.source.candidate.conversationId, turnId: context.source.candidate.turnId },
+        attribution: {
+          userId: pattern.userId,
+          conversationId: context.source.candidate.conversationId,
+          turnId: context.source.candidate.turnId,
+        },
         appId: "ai",
         systemPrompt: workflowPrompt,
         input: context.input,
@@ -578,15 +594,19 @@ export const learnAiMemoriesFromPrivateChats = async (
       if (result.output.workflow && (await learningEnabled(pattern.userId))) {
         const memoryIds = result.output.workflow.memoryIds;
         const action = memoryIds.length > 1 ? "merge" : memoryIds.length === 1 ? "replace" : "add";
-        changes = await applyChanges(context.source, [
-          {
-            action,
-            kind: "workflow",
-            content: result.output.workflow.content,
-            memoryIds,
-            resourceRef: pattern.resourceRef,
-          },
-        ], context.mutableMemoryIds);
+        changes = await applyChanges(
+          context.source,
+          [
+            {
+              action,
+              kind: "workflow",
+              content: result.output.workflow.content,
+              memoryIds,
+              resourceRef: pattern.resourceRef,
+            },
+          ],
+          context.mutableMemoryIds,
+        );
       }
       await markAiWorkflowPatternReviewed(pattern);
       await aiMemoryLearningRuns.finish({
@@ -600,6 +620,18 @@ export const learnAiMemoriesFromPrivateChats = async (
       summary.updated += changes.filter((change) => change.action === "updated" || change.action === "merged").length;
       if (changes.length === 0) summary.skipped += 1;
     } catch (error) {
+      if (error instanceof AiBackgroundCostError || error instanceof AiBackgroundAdmissionError) {
+        summary.skipped += 1;
+        if (runId)
+          await aiMemoryLearningRuns.finish({
+            runId,
+            status: "skipped",
+            durationMs: Date.now() - startedAt,
+            changes: [],
+            accountedTokens: 0,
+          });
+        return summary;
+      }
       summary.failed += 1;
       if (runId) {
         await aiMemoryLearningRuns

package/src/ai/message-queue.ts

@@ -0,0 +1,167 @@
+import { editAiDraftText } from "./draft-content";
+import { aiQuotas, AiQuotaError } from "./quotas";
+import { aiChatAccessSubject, isAssistantChatTurn } from "./assistant-models";
+import { aiInputToUserMessage, aiTurnInputToContent } from "./http";
+import { canonicalizeAiConversationAttachments } from "./file-context";
+import { aiResourceMarker } from "./resource-markers";
+import { sql } from "bun";
+import type { AiConversationService, AiDraftContentPart } from "./types";
+import { aiConversations } from "./store";
+import { logger } from "../services/logging";
+import { AI_FILES_MAX_CONVERSATION_BYTES_DEFAULT } from "./files-store";
+
+const log = logger("ai:message-queue");
+export const AI_MESSAGE_QUEUE_LIMIT = 32;
+export class AiMessageQueueConflict extends Error {}
+
+type Submission = Parameters<AiConversationService["submitChatTurn"]>[0];
+
+export const migrateAiMessageQueue = async () => {
+  await sql`CREATE TABLE IF NOT EXISTS ai.queued_messages (
+    id uuid PRIMARY KEY, conversation_id uuid NOT NULL REFERENCES ai.conversations(id) ON DELETE CASCADE,
+    position bigint GENERATED ALWAYS AS IDENTITY, submission jsonb NOT NULL, content jsonb NOT NULL,
+    status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','failed','submitted','cancelled')),
+    error text, created_at timestamptz NOT NULL DEFAULT now()
+  )`.simple();
+  await sql`ALTER TABLE ai.queued_messages ADD COLUMN IF NOT EXISTS quota_checked_at TIMESTAMPTZ`.simple();
+  await sql`CREATE INDEX IF NOT EXISTS ai_queued_messages_pending ON ai.queued_messages(conversation_id, position) WHERE status IN ('pending','failed')`.simple();
+  await sql`CREATE TABLE IF NOT EXISTS ai.queued_message_files (
+    message_id uuid NOT NULL REFERENCES ai.queued_messages(id) ON DELETE CASCADE,
+    path text NOT NULL, bytes bytea NOT NULL, media_type text NOT NULL, size bigint NOT NULL,
+    origin text NOT NULL, dictation_recorded_at timestamptz, updated_at timestamptz NOT NULL, version bigint NOT NULL,
+    PRIMARY KEY(message_id, path)
+  )`.simple();
+  await sql`DROP TRIGGER IF EXISTS ai_live_queued_messages_changed ON ai.queued_messages`.simple();
+  await sql`CREATE TRIGGER ai_live_queued_messages_changed AFTER INSERT OR DELETE ON ai.queued_messages
+    FOR EACH ROW EXECUTE FUNCTION ai.live_conversation_child_changed('conversation-detail,conversation-list')`.simple();
+  await sql`DROP TRIGGER IF EXISTS ai_live_queued_messages_updated ON ai.queued_messages`.simple();
+  await sql`CREATE TRIGGER ai_live_queued_messages_updated AFTER UPDATE ON ai.queued_messages
+    FOR EACH ROW WHEN (OLD.status IS DISTINCT FROM NEW.status OR OLD.error IS DISTINCT FROM NEW.error OR OLD.content IS DISTINCT FROM NEW.content)
+    EXECUTE FUNCTION ai.live_conversation_child_changed('conversation-detail,conversation-list')`.simple();
+};
+
+export const listQueuedMessages = async (conversationId: string) => {
+  const rows = await sql<{ id: string; content: AiDraftContentPart[]; error: string | null }[]>`
+    SELECT id, content, error FROM ai.queued_messages
+    WHERE conversation_id = ${conversationId}::uuid AND status IN ('pending','failed') ORDER BY position`;
+  return rows.map((row) => ({ id: row.id, content: row.content, failed: Boolean(row.error) }));
+};
+
+export const queuedMessageAccepted = async (conversationId: string, id: string) => {
+  const [row] = await sql`SELECT id FROM ai.queued_messages WHERE id=${id}::uuid AND conversation_id=${conversationId}::uuid`;
+  return Boolean(row);
+};
+
+export const enqueueChatMessage = async (id: string, input: Submission, content: AiDraftContentPart[]) =>
+  sql.begin(async (tx) => {
+    const [conversation] = await tx<{ draft_revision: number; project_id: string | null }[]>`
+    SELECT draft_revision, project_id FROM ai.conversations WHERE id = ${input.conversationId}::uuid AND archived_at IS NULL FOR UPDATE`;
+    if (!conversation) throw new AiMessageQueueConflict("Conversation not found.");
+    const [existing] =
+      await tx`SELECT id FROM ai.queued_messages WHERE id = ${id}::uuid AND conversation_id = ${input.conversationId}::uuid`;
+    if (existing) return;
+    if (Number(conversation.draft_revision) !== input.expectedDraftRevision)
+      throw new AiMessageQueueConflict("Conversation draft changed before the message was queued.");
+    if (conversation.project_id !== input.expectedProjectId)
+      throw new AiMessageQueueConflict("Conversation Project changed before the message was queued.");
+    const [count] = await tx<
+      { count: number }[]
+    >`SELECT count(*)::int AS count FROM ai.queued_messages WHERE conversation_id = ${input.conversationId}::uuid AND status IN ('pending','failed')`;
+    if (count!.count >= AI_MESSAGE_QUEUE_LIMIT) throw new AiMessageQueueConflict("The message queue is full (32 messages).");
+    const [size] = await tx<
+      { size: number }[]
+    >`SELECT COALESCE(sum(f.size),0)::float8 AS size FROM ai.queued_message_files f JOIN ai.queued_messages q ON q.id = f.message_id WHERE q.conversation_id = ${input.conversationId}::uuid`;
+    if (
+      Number(size!.size) + (input.runConfig.files?.attached ?? []).reduce((sum, file) => sum + file.size, 0) >
+      AI_FILES_MAX_CONVERSATION_BYTES_DEFAULT
+    )
+      throw new AiMessageQueueConflict("Queued attachments exceed the conversation file budget.");
+    const { expectedDraftRevision, ...submission } = input;
+    await tx`INSERT INTO ai.queued_messages(id, conversation_id, submission, content) VALUES (${id}::uuid, ${input.conversationId}::uuid, (${JSON.stringify(submission)}::text)::jsonb, (${JSON.stringify(content)}::text)::jsonb)`;
+    for (const file of input.runConfig.files?.attached ?? []) {
+      const copied =
+        await tx`INSERT INTO ai.queued_message_files(message_id,path,bytes,media_type,size,origin,dictation_recorded_at,updated_at,version)
+      SELECT ${id}::uuid,path,bytes,media_type,size,origin,dictation_recorded_at,updated_at,version FROM ai.files
+      WHERE conversation_id = ${input.conversationId}::uuid AND path = ${file.path} AND version = ${file.version ?? -1} RETURNING path`;
+      if (!copied.length) throw new AiMessageQueueConflict("An attached file changed before the message was queued.");
+    }
+    await tx`UPDATE ai.conversations SET draft_content = '[]'::jsonb, draft_revision = draft_revision + 1, draft_updated_at = now(), last_used_at = now(), done = CASE WHEN done IS TRUE THEN NULL ELSE done END WHERE id = ${input.conversationId}::uuid`;
+  });
+
+/** Cancellation and retry share the conversation lock with promotion. */
+export const updateQueuedMessage = async (conversationId: string, id: string, action: "cancel" | "retry") =>
+  sql.begin(async (tx) => {
+    await tx`SELECT id FROM ai.conversations WHERE id = ${conversationId}::uuid FOR UPDATE`;
+    const changed = await tx`UPDATE ai.queued_messages SET status = ${action === "cancel" ? "cancelled" : "pending"}, error = NULL
+    WHERE id = ${id}::uuid AND conversation_id = ${conversationId}::uuid AND status IN ('pending','failed') RETURNING id`;
+    if (action === "cancel" && changed.length) {
+      await tx`DELETE FROM ai.queued_message_files WHERE message_id = ${id}::uuid`;
+      await tx`UPDATE ai.queued_messages SET submission = '{}'::jsonb, content = '[]'::jsonb WHERE id = ${id}::uuid`;
+    }
+    return Boolean(changed.length);
+  });
+
+/** Edit only queued text; immutable attachments and the independent composer draft stay intact. */
+export const editQueuedMessage = async (conversationId: string, id: string, text: string) =>
+  sql.begin(async (tx) => {
+    await tx`SELECT id FROM ai.conversations WHERE id = ${conversationId}::uuid FOR UPDATE`;
+    const [row] = await tx<{ submission: Submission; content: AiDraftContentPart[] }[]>`SELECT submission, content FROM ai.queued_messages
+    WHERE id = ${id}::uuid AND conversation_id = ${conversationId}::uuid AND status IN ('pending','failed') FOR UPDATE`;
+    if (!row) return false;
+    const content = editAiDraftText(row.content, text);
+    const parts = content.map((part) =>
+      part.type === "text"
+        ? part
+        : part.type === "project-file" ? { type: "text" as const, text: `Project file: ${part.path}` }
+        : part.type === "file"
+          ? { type: "attachment" as const, path: part.path, mediaType: part.mediaType, size: part.size }
+          : { type: "text" as const, text: aiResourceMarker({ ref: part.ref, title: part.title, icon: part.icon, href: part.href }) },
+    );
+    const { message } = aiInputToUserMessage(aiTurnInputToContent({ content: parts }));
+    const userMessage = canonicalizeAiConversationAttachments(message, row.submission.runConfig.files);
+    if (userMessage.role !== "user") throw new Error("Queued message must be a user message.");
+    const submission = { ...row.submission, userMessage, runConfig: { ...row.submission.runConfig, input: userMessage.content, selectedSkillIds: [...new Set(content.flatMap(part => part.type === "resource" && part.ref.type === "core.ai.skill" ? [part.ref.id] : []))] } };
+    await tx`UPDATE ai.queued_messages SET submission = (${JSON.stringify(submission)}::text)::jsonb,
+    content = (${JSON.stringify(content)}::text)::jsonb WHERE id = ${id}::uuid`;
+    return true;
+  });
+
+/** Existing turn creation owns execution and recovery; the DB lock owns FIFO and deduplication. */
+export const drainQueuedMessages = async (
+  enqueue: (job: { conversationId: string; turnId: string }) => Promise<unknown>,
+  conversationId?: string,
+) => {
+  const rows = await sql<{ id: string; conversation_id: string; submission: Submission }[]>`
+    SELECT q.id, q.conversation_id, q.submission FROM ai.queued_messages q
+    JOIN ai.conversations c ON c.id = q.conversation_id
+    WHERE (q.status = 'pending' OR (q.status = 'failed' AND q.error IN ('quota_exhausted','quota_usage_unknown'))) AND c.archived_at IS NULL AND c.created_by_user_id IS NOT NULL
+      AND (${conversationId ?? null}::uuid IS NULL OR q.conversation_id = ${conversationId ?? null}::uuid)
+      AND NOT EXISTS (SELECT 1 FROM ai.queued_messages earlier WHERE earlier.conversation_id = q.conversation_id AND earlier.position < q.position AND earlier.status IN ('pending','failed'))
+      AND NOT EXISTS (SELECT 1 FROM ai.turns t WHERE t.conversation_id = q.conversation_id AND NOT COALESCE(t.run_config ? 'background', false) AND t.status IN ('queued','running','waiting_for_action'))
+    ORDER BY q.quota_checked_at NULLS FIRST, q.position LIMIT ${AI_MESSAGE_QUEUE_LIMIT}`;
+  for (const row of rows) {
+    try {
+      const quotaSubject = aiChatAccessSubject(row.submission.runConfig.actor);
+      if (isAssistantChatTurn(row.submission.runConfig) && quotaSubject)
+        await aiQuotas.assertAllowed(quotaSubject, row.submission.modelProfileId);
+      await sql`UPDATE ai.queued_messages SET status='pending', error=NULL WHERE id=${row.id}::uuid AND status='failed' AND error IN ('quota_exhausted','quota_usage_unknown')`;
+      const result = await aiConversations.submitChatTurn({ ...row.submission, queuedMessageId: row.id });
+      await enqueue({ conversationId: row.conversation_id, turnId: result.turn.id });
+    } catch (error) {
+      if (error instanceof AiQuotaError) {
+        await sql`UPDATE ai.queued_messages SET status='failed', error=${error.code}, quota_checked_at=clock_timestamp() WHERE id=${row.id}::uuid AND status IN ('pending','failed')`;
+        continue;
+      }
+      // Another dispatcher may have consumed it or a new foreground turn may have won.
+      const reason = error instanceof Error ? error.message : String(error);
+      if (reason === "Queued message is no longer ready." || reason.includes("idx_ai_turns_one_active_per_conversation")) continue;
+      await sql`UPDATE ai.queued_messages SET status = 'failed', error = 'dispatch_failed' WHERE id = ${row.id}::uuid AND status = 'pending'`;
+      log.error("Queued message dispatch failed", {
+        conversationId: row.conversation_id,
+        messageId: row.id,
+        code: "queue_dispatch_failed",
+        errorType: error instanceof Error ? error.name : "unknown",
+      });
+    }
+  }
+};