@k2b/cloud 0.6.0 → 0.8.0

package/src/ai/runtime.ts

@@ -6,12 +6,16 @@ import { lazySync } from "../_internal/process-sync";
 import type { RequestActor } from "../server";
 import { logger } from "../services/logging";
 import { superviseRuntimeTask } from "../services/runtime-lifecycle";
-
+import { coreSettings } from "../services/settings/api";
 import { type AiToolApprovalContext, aiTurnAllowsRememberedApprovals, rememberAiToolApproval } from "./approvals";
 import { aiChatAccessSubject, selectAssistantAiModelId } from "./assistant-models";
+import { startAiDictationRuntime } from "./dictation-runtime";
 import { AiTurnExecutor } from "./executor";
 import { canonicalizeAiConversationAttachments, snapshotAiConversationFiles } from "./file-context";
 import { startAiInvalidationRuntime, stopAiInvalidationRuntime } from "./live-outbox";
+import { drainQueuedMessages } from "./message-queue";
+import { aiQuotas } from "./quotas";
+import { parseAiResourceMarker } from "./resource-markers";
 import { isAiVisionModelConfigured } from "./settings";
 import { aiConversations } from "./store";
 import { publishAiTurnAbort, publishAiWireEvent } from "./stream";
@@ -44,7 +48,7 @@ const AI_TURN_LEASE_MS = 45_000;
 const AI_TURN_HEARTBEAT_MS = 3_000;
 const AI_TURN_WORKER_CONCURRENCY = 8;
 const AI_TURN_MAX_ATTEMPTS = 5;
-const AI_TURN_RUN_BUDGET_MS = 10 * 60_000;
+
 const AI_SWEEP_INTERVAL_MS = 15_000;
 
 // ---------------------------------------------------------------------------
@@ -65,7 +69,14 @@ const aiTurnQueue = lazySync((sync) => {
 
 // No idempotency key: the DB claim is the only gate, so re-enqueues (recovery,
 // continuation, stale-sweep) are always allowed and never silently swallowed.
-const enqueueAiTurn = (job: AiTurnJob): Promise<unknown> => aiTurnQueue().send({ data: job, orderingKey: job.conversationId });
+const enqueueAiTurn = (job: AiTurnJob): Promise<unknown> => aiTurnQueue().send({ data: job, orderingKey: job.turnId });
+
+/** Wake the durable queue promptly; the periodic sweep retries a failed wake-up. */
+export const wakeAiMessageQueue = (conversationId: string): void => {
+  void drainQueuedMessages(enqueueAiTurn, conversationId).catch(() =>
+    log.warn("AI message queue wake-up failed", { code: "queue_wakeup_failed", conversationId }),
+  );
+};
 
 /** Enqueue a turn created atomically by another durable AI workflow. */
 export const enqueueExistingAiTurn = (input: AiTurnJob): Promise<unknown> => enqueueAiTurn(input);
@@ -103,7 +114,7 @@ export type SubmitAiChatTurnInput = {
   retrySourceTurnId?: string;
 };
 
-export const submitAiChatTurn = async (input: SubmitAiChatTurnInput): Promise<{ turn: AiTurn; message: AiStoredMessage }> => {
+export const prepareAiChatTurn = async (input: SubmitAiChatTurnInput) => {
   if (input.clientToolIds?.length && input.toolSource?.kind !== "default") {
     throw new Error("Optional client tools require the default tool source.");
   }
@@ -128,8 +139,18 @@ export const submitAiChatTurn = async (input: SubmitAiChatTurnInput): Promise<{
     modelPolicy: input.modelPolicy,
     requestedModelId,
   });
+  const quotaSubject = aiChatAccessSubject(input.actor);
+  if (input.assistantChat && quotaSubject) await aiQuotas.assertAllowed(quotaSubject, resolved.profile.id);
   const runConfig: AiChatTurnRunConfig = {
     kind: "chat",
+    selectedSkillIds: [
+      ...new Set(
+        (userMessage.role === "user" ? userMessage.content : []).flatMap((part) => {
+          const marker = parseAiResourceMarker(typeof part === "string" ? part : part.type === "text" ? part.text : "");
+          return marker?.ref.type === "core.ai.skill" ? [marker.ref.id] : [];
+        }),
+      ),
+    ],
     ...(input.assistantChat ? { assistantChat: true } : {}),
     input: canonicalInput,
     chatId: input.chatId,
@@ -146,7 +167,7 @@ export const submitAiChatTurn = async (input: SubmitAiChatTurnInput): Promise<{
     toolApprovalContext: input.toolApprovalContext,
   };
 
-  const submitted = await aiConversations.submitChatTurn({
+  return {
     conversationId: input.conversationId,
     modelProfileId: resolved.profile.id,
     runConfig,
@@ -156,8 +177,11 @@ export const submitAiChatTurn = async (input: SubmitAiChatTurnInput): Promise<{
     expectedProjectId: input.expectedProjectId,
     resources: input.resources,
     retrySourceTurnId: input.retrySourceTurnId,
-  });
+  };
+};
 
+export const submitAiChatTurn = async (input: SubmitAiChatTurnInput): Promise<{ turn: AiTurn; message: AiStoredMessage }> => {
+  const submitted = await aiConversations.submitChatTurn(await prepareAiChatTurn(input));
   await enqueueAiTurn({ conversationId: input.conversationId, turnId: submitted.turn.id });
   return submitted;
 };
@@ -242,7 +266,8 @@ export const abortAiTurn = async (input: { conversationId: string; turnId: strin
 
   if (request.ownerless) {
     const finalized = await aiConversations.completeTurn({ ...input, status: "aborted", error: null });
-    if (finalized === "completed") {
+    const config = await aiConversations.getTurnRunConfig(input);
+    if (finalized === "completed" && !(config?.kind === "chat" && config.background)) {
       const attempt = active?.turn.id === input.turnId ? active.turn.attempt : 1;
       const seq = (active?.turn.id === input.turnId ? active.liveSeq : 0) + 1;
       await publishAiWireEvent({
@@ -343,9 +368,7 @@ export const submitAiTurnAction = async (input: {
         return { ok: false, status: 409, message: "AI action was already resolved with a different response." };
       }
     }
-    await aiToolAudit
-      .noteToolCompleted({ turnId: input.turnId, callId: input.callId, result: input.action.result, isError: false })
-      .catch(() => undefined);
+    await aiToolAudit.noteToolCompleted({ turnId: input.turnId, callId: input.callId, isError: false }).catch(() => undefined);
   }
 
   await enqueueAiTurn({ conversationId: input.conversationId, turnId: input.turnId });
@@ -362,6 +385,8 @@ const runClaimedTurn = async (
   leaseOwner: string,
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>,
 ): Promise<void> => {
+  const timeoutMinutes = await coreSettings.get<number>("ai.turn_timeout_minutes");
+  const runBudgetMs = Math.max(0, Number(timeoutMinutes ?? 30)) * 60_000;
   const claim =
     (await aiConversations.claimTurn({
       ...job,
@@ -369,7 +394,7 @@ const runClaimedTurn = async (
       leaseMs: AI_TURN_LEASE_MS,
       from: "queue",
       maxAttempts: AI_TURN_MAX_ATTEMPTS,
-      runBudgetMs: AI_TURN_RUN_BUDGET_MS,
+      runBudgetMs,
     })) ??
     (await aiConversations.claimTurn({
       ...job,
@@ -377,7 +402,7 @@ const runClaimedTurn = async (
       leaseMs: AI_TURN_LEASE_MS,
       from: "waiting",
       maxAttempts: AI_TURN_MAX_ATTEMPTS,
-      runBudgetMs: AI_TURN_RUN_BUDGET_MS,
+      runBudgetMs,
     }));
 
   if (!claim) return; // Already owned, done, cancelled, or attempt-capped.
@@ -392,12 +417,29 @@ const runClaimedTurn = async (
 };
 
 const processMessage = async (
-  message: QueueMessage<AiTurnJob>,
+  message: Pick<QueueMessage<AiTurnJob>, "messageId" | "data" | "heartbeat">,
   signal: AbortSignal,
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>,
 ): Promise<void> => {
   const leaseOwner = `${AI_WORKER_ID}:${message.messageId}:${crypto.randomUUID()}`;
-  const touch = setInterval(() => void message.heartbeat().catch(() => undefined), AI_TURN_HEARTBEAT_MS);
+  let heartbeatFailed = false;
+  const touch = setInterval(() => {
+    void message
+      .heartbeat()
+      .then(() => {
+        heartbeatFailed = false;
+      })
+      .catch(() => {
+        if (!heartbeatFailed && !signal.aborted) {
+          log.warn("AI queue heartbeat failed", {
+            code: "queue_heartbeat_failed",
+            conversationId: message.data.conversationId,
+            turnId: message.data.turnId,
+          });
+        }
+        heartbeatFailed = true;
+      });
+  }, AI_TURN_HEARTBEAT_MS);
   if (typeof touch === "object" && "unref" in touch) touch.unref();
   try {
     await runClaimedTurn(message.data, signal, leaseOwner, onTurnFinalized);
@@ -409,10 +451,13 @@ const processMessage = async (
     });
   } finally {
     clearInterval(touch);
+    if (!signal.aborted) wakeAiMessageQueue(message.data.conversationId);
   }
 };
 
 const publishSweepFinished = async (turn: AiTurnFinalizedAction & { error?: string }, status: "failed" | "aborted"): Promise<void> => {
+  const config = await aiConversations.getTurnRunConfig(turn);
+  if (config?.kind === "chat" && config.background) return;
   await publishAiWireEvent({
     v: 1,
     conversationId: turn.conversationId,
@@ -422,13 +467,23 @@ const publishSweepFinished = async (turn: AiTurnFinalizedAction & { error?: stri
     type: "turn_finished",
     status,
     error: status === "failed" ? (turn.error ?? "AI turn failed.") : null,
-  }).catch(() => undefined);
+  }).catch(() =>
+    log.warn("AI completion notification failed", {
+      code: "completion_publish_failed",
+      conversationId: turn.conversationId,
+      turnId: turn.turnId,
+    }),
+  );
 };
 
 export const sweepAiRuntime = async (onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>): Promise<void> => {
+  await aiQuotas.prune().catch(() => log.warn("Quota retention failed", { code: "quota_retention_failed" }));
+  await drainQueuedMessages(enqueueAiTurn);
   const sweep = await aiConversations.sweepTurns({ maxAttempts: AI_TURN_MAX_ATTEMPTS });
   await Promise.all([
-    ...sweep.requeued.map((job) => enqueueAiTurn(job).catch(() => undefined)),
+    ...sweep.requeued.map((job) =>
+      enqueueAiTurn(job).catch(() => log.warn("AI recovery enqueue failed", { code: "recovery_enqueue_failed", ...job })),
+    ),
     ...sweep.failed.map((turn) => publishSweepFinished(turn, "failed")),
     ...sweep.aborted.map((turn) => publishSweepFinished(turn, "aborted")),
   ]);
@@ -508,11 +563,13 @@ export const startAiRuntime = (
   const sweepTimer = setInterval(runSweep, AI_SWEEP_INTERVAL_MS);
   if (typeof sweepTimer === "object" && "unref" in sweepTimer) sweepTimer.unref();
 
+  const stopDictations = startAiDictationRuntime();
   const state: AiRuntimeState = {
     listeners,
     stop: () => {
       if (running !== state) return;
       controller.abort();
+      stopDictations();
       clearInterval(sweepTimer);
       listeners.clear();
       running = null;
@@ -541,4 +598,4 @@ const releaseAiRuntime = (listener: ((event: AiTurnFinalizedEvent) => Promise<vo
   };
 };
 
-export const __aiRuntimeTest = { actionMatchesResolvedEvent };
+export const __aiRuntimeTest = { actionMatchesResolvedEvent, processMessage, publishSweepFinished };

package/src/ai/settings.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { coreSettings } from "../services";
+import { AiModelPricingSchema } from "../shared/ai-costs";
 import { getAiCredential, listAiCredentialProfileIds } from "./credentials";
 import { AI_FIRECRAWL_API_KEY_SETTING_KEY } from "./firecrawl-tools";
 import { createAiProvider } from "./provider";
@@ -94,10 +95,22 @@ const ModelProfileSchema = z
     maxOutputTokens: z.number().int().positive().optional(),
     maxLoadedTools: z.number().int().optional(),
     maxToolRounds: z.number().int().optional(),
-    creditsPerInputToken: z.number().nonnegative().optional(),
-    creditsPerOutputToken: z.number().nonnegative().optional(),
+    pricing: AiModelPricingSchema.optional(),
   })
   .superRefine((profile, ctx) => {
+    if (profile.capabilities?.includes("transcription")) {
+      if (profile.pricing) ctx.addIssue({ code: "custom", path: ["pricing"], message: "Audio pricing is not supported." });
+      if (profile.capabilities.some((capability) => capability !== "transcription")) {
+        ctx.addIssue({ code: "custom", path: ["capabilities"], message: "Audio transcription cannot be combined with chat capabilities." });
+      }
+      if (profile.provider !== "openai" && profile.provider !== "openai-compatible") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["provider"],
+          message: "Audio transcription requires OpenAI or an OpenAI-compatible endpoint.",
+        });
+      }
+    }
     if (profile.provider === "openai-compatible" && !profile.baseURL) {
       ctx.addIssue({ code: "custom", path: ["baseURL"], message: "OpenAI-compatible profiles require a base URL." });
     }
@@ -177,6 +190,7 @@ export const validateAiSettingsConfiguration = (input: {
   defaultModelId: string;
   backgroundModelId: string;
   visionModelId?: string;
+  audioModelId?: string;
   workflowModelId: string;
   profiles: readonly AiModelProfile[];
   credentialProfileIds: readonly string[];
@@ -186,13 +200,14 @@ export const validateAiSettingsConfiguration = (input: {
   const errors: Record<string, string> = {};
   const enabledProfiles = input.profiles.filter((profile) => profile.enabled);
   const defaultProfile = input.profiles.find((profile) => profile.id === input.defaultModelId);
-  if (!input.defaultModelId || !defaultProfile?.enabled) {
+  if (!input.defaultModelId || !defaultProfile?.enabled || defaultProfile.capabilities.includes("transcription")) {
     errors["ai.default_model_id"] = "Choose an enabled model profile.";
   }
 
   if (input.backgroundModelId) {
     const backgroundProfile = input.profiles.find((profile) => profile.id === input.backgroundModelId);
-    if (!backgroundProfile?.enabled) errors["ai.background_model_id"] = "Choose an enabled model profile or use the platform default.";
+    if (!backgroundProfile?.enabled || backgroundProfile.capabilities.includes("transcription"))
+      errors["ai.background_model_id"] = "Choose an enabled chat model profile or use the platform default.";
   }
 
   if (input.visionModelId) {
@@ -204,7 +219,15 @@ export const validateAiSettingsConfiguration = (input: {
 
   if (input.workflowModelId) {
     const workflowProfile = input.profiles.find((profile) => profile.id === input.workflowModelId);
-    if (!workflowProfile?.enabled) errors["ai.workflow_model_id"] = "Choose an enabled model profile or use the background model.";
+    if (!workflowProfile?.enabled || workflowProfile.capabilities.includes("transcription"))
+      errors["ai.workflow_model_id"] = "Choose an enabled chat model profile or use the background model.";
+  }
+
+  if (input.audioModelId) {
+    const audioProfile = input.profiles.find((profile) => profile.id === input.audioModelId);
+    if (!audioProfile?.enabled || !audioProfile.capabilities.includes("transcription")) {
+      errors["ai.audio_model_id"] = "Choose an enabled audio transcription profile or disable audio transcription.";
+    }
   }
 
   const configured = new Set(input.credentialProfileIds);
@@ -301,7 +324,7 @@ export const resolveAiSettingsStateFromRaw = async (input: {
     };
   }
 
-  if (!defaultProfile.enabled) {
+  if (!defaultProfile.enabled || defaultProfile.capabilities.includes("transcription")) {
     return {
       ok: false,
       ...baseState,
@@ -309,7 +332,7 @@ export const resolveAiSettingsStateFromRaw = async (input: {
       profiles: parsed.profiles,
       error: {
         code: "default_model_disabled",
-        message: `Default AI model "${input.defaultModelId}" is disabled.`,
+        message: `Default AI model "${input.defaultModelId}" must be an enabled text model.`,
         fields: { "ai.default_model_id": "Choose an enabled model profile id." },
       },
     };
@@ -398,6 +421,7 @@ const hasAll = <T extends string>(values: readonly T[], required: readonly T[] |
 
 const matchesPolicy = (profile: AiModelProfile, policy: AiModelPolicy): boolean => {
   if (!profile.enabled) return false;
+  if (profile.capabilities.includes("transcription") !== Boolean(policy.requiredCapabilities?.includes("transcription"))) return false;
   if ("allowedModelIds" in policy && policy.allowedModelIds && !policy.allowedModelIds.includes(profile.id)) return false;
   if (policy.allowedDataBoundaries && !policy.allowedDataBoundaries.includes(profile.dataBoundary)) return false;
   return hasAll(profile.capabilities, policy.requiredCapabilities);
@@ -521,7 +545,11 @@ export const toPublicAiSettingsState = async (allowedDataBoundaries?: AiDataBoun
     firecrawlConfigured: state.firecrawlConfigured,
     models:
       state.ok && state.enabled
-        ? state.profiles.filter((profile) => profile.enabled && isUsableProfile(profile, configured)).map(profileToPublic)
+        ? state.profiles
+            .filter(
+              (profile) => matchesPolicy(profile, { kind: "selectable", allowedDataBoundaries }) && isUsableProfile(profile, configured),
+            )
+            .map(profileToPublic)
         : [],
   };
 };

package/src/ai/short-id.ts

@@ -14,13 +14,12 @@ export const withAiShortId = async <T>(
     try {
       return await insert(allocate());
     } catch (error) {
-      const collision =
+      const uniqueViolation =
         typeof error === "object" &&
         error !== null &&
-        "code" in error &&
-        error.code === "23505" &&
-        "constraint" in error &&
-        error.constraint === constraint;
+        (("code" in error && error.code === "23505") || ("errno" in error && error.errno === "23505"));
+      const collision =
+        typeof error === "object" && error !== null && uniqueViolation && "constraint" in error && error.constraint === constraint;
       if (!collision) throw error;
     }
   }

package/src/ai/skill-catalog.ts

@@ -60,14 +60,4 @@ export const selectAiSkillCatalog = (
   return { skills: selected, omitted: normalized.length - selected.length };
 };
 
-export const searchAiSkillCatalog = (
-  skills: readonly AiSkillCatalogEntry[],
-  query: string,
-  limit: number,
-): { skills: AiSkillCatalogEntry[]; more: boolean } => {
-  const normalized = skills.map((skill) => ({ name: skill.name, description: skill.description }));
-  const matches = ranked(normalized, query).filter((skill) => relevance(skill, query) > 0);
-  return { skills: matches.slice(0, limit), more: matches.length > limit };
-};
-
 export const aiSkillCatalogChars = (skills: readonly AiSkillCatalogEntry[]): number => skills.map(catalogLine).join("\n").length;

package/src/ai/skill-search.ts

@@ -0,0 +1,58 @@
+import { sql } from "bun";
+import { toPgTextArray } from "../services/postgres";
+
+const BM25_INDEX = "ai.skills_search_bm25_idx";
+let bm25Available: Promise<boolean> | undefined;
+
+/** BM25 only ranks candidates; native matching and access checks always apply. */
+export async function withAiSkillSearch<T>(query: string, run: (bm25: boolean) => Promise<T>): Promise<T> {
+  if (!query) return run(false);
+  bm25Available ??= sql<{ available: boolean }[]>`
+    SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_textsearch')
+      AND EXISTS (SELECT 1 FROM pg_class c JOIN pg_am am ON am.oid = c.relam
+        WHERE c.oid = to_regclass(${BM25_INDEX}) AND am.amname = 'bm25') AS available
+  `.then((rows) => rows[0]?.available ?? false);
+  const bm25 = await bm25Available;
+  try {
+    return await run(bm25);
+  } catch (error) {
+    const capabilityLost =
+      typeof error === "object" &&
+      error !== null &&
+      ["code", "errno"].some((key) => key in error && ["0A000", "42704", "42883", "55000"].includes(String(Reflect.get(error, key))));
+    if (!bm25 || !capabilityLost) throw error;
+    bm25Available = Promise.resolve(false);
+    return run(false);
+  }
+}
+
+export function aiSkillSearchSql(query: string, bm25: boolean) {
+  const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])];
+  // Match every term in either field. Short prefixes stay exact; longer terms
+  // tolerate typos without matching unrelated short words throughout the catalog.
+  const matches = !query
+    ? sql`TRUE`
+    : !terms.length
+      ? sql`FALSE`
+      : sql`
+    NOT EXISTS (SELECT 1 FROM unnest(${toPgTextArray(terms)}::text[]) AS term
+      WHERE strpos(lower(skill.name), term) = 0 AND strpos(lower(skill.description), term) = 0
+        AND (length(term) < 4 OR greatest(word_similarity(term, skill.name),
+          word_similarity(term, skill.description)) < 0.35))
+  `;
+  // Rank typos against whole words: a partial-word extent such as "invi…" in a
+  // description must not outscore the typo'd name "invoices" it was meant for.
+  const rank = !query
+    ? sql`0::real`
+    : sql`
+    CASE WHEN lower(skill.name) = ${query.toLowerCase()} THEN 100 ELSE 0 END
+    + CASE WHEN strpos(lower(skill.name), ${query.toLowerCase()}) > 0 THEN 10 ELSE 0 END
+    + 2 * strict_word_similarity(${query}, skill.name) + strict_word_similarity(${query}, skill.description)
+  `;
+  const textRank = !query
+    ? sql`0::real`
+    : bm25
+      ? sql`-(skill.search_text <@> to_bm25query(${query}, ${BM25_INDEX}))`
+      : sql`ts_rank_cd(to_tsvector('simple', skill.search_text), plainto_tsquery('simple', ${query}))`;
+  return { matches, rank, textRank };
+}

package/src/ai/skill-seeds.ts

@@ -1,6 +1,7 @@
-import { CLOUD_KIT_INSTRUCTIONS } from "./kit-skill";
+import { ASSISTANT_CODE_MODE_SKILL } from "./code-mode-skill";
+import { ASSISTANT_DATA_ANALYSIS_SKILL } from "./data-analysis-skill";
 import { CLOUD_GRIDS_INSTRUCTIONS, CLOUD_GRIDS_QUERY_REFERENCE } from "./grids-skill";
-import { aiSkills } from "./skills";
+import type { AiSkillTemplate } from "./skills";
 
 const SKILL_CREATOR_INSTRUCTIONS = `# Create and improve Skills
 
@@ -81,7 +82,15 @@ Pass the exact current revision to mutations and read again after a revision con
 
 Creating, changing, and deleting Skills are reviewed mutations. Prepare the concrete content the user requested, then use the Capability review instead of asking for an extra confirmation that duplicates it.
 
-Sharing, access changes, imports, and exports are not available through these capabilities. Say so plainly rather than inventing a tool or bypassing Cloud permissions.`;
+## Optional App-backed workflows
+
+A Skill can reference a reusable Studio App and its published actions instead of duplicating code. Load \`assistant-code-mode\` only when building, changing, or discovering such an App is useful. Apps may be stateless scripts, agent-only services with shared data, dashboards, or a combination. Many Skills need no code and many Apps need no Skill.
+
+When referring to an App, include its exact ID, action names, input/output meaning, and a concrete workflow example. Read the action schemas instead of guessing APIs. Skill access and App access are independent: warn when intended recipients can use only one; never grant access implicitly.
+
+For requested sharing, discover \`core.entities.search\` to resolve a recipient, then \`core.ai.skill.access.read\` and \`core.ai.skill.access.change\`. Read current grants and pass their exact accessRevision as expectedAccessRevision. Supply either a returned principal and permission (read/write/admin), or an existing accessId and permission (null revokes). Every mutation receives fresh review and preserves the last administrator. After a conflict, re-read and prepare a new review. For App permissions, read the Code Mode access reference; App Use/Manage is separate from Skill Read/Edit/Manage.
+
+Imports and exports are not available through these capabilities. Do not invent a tool or bypass Cloud permissions.`;
 
 const CLOUD_MAIL_INSTRUCTIONS = `# Work with Cloud Mail
 
@@ -196,7 +205,7 @@ Use these defaults unless the user asks otherwise or a more specific loaded Skil
 - Simple subtasks use \`spaces.task.checklist.list\`, \`spaces.task.checklist.create\`, \`spaces.task.checklist.update\` and \`spaces.task.checklist.delete\`. Keep each entry to a label and completion state; do not turn checklist entries into independent assigned tasks.
 - Use comments for discussion; read before replacing or deleting them. For tag replacement, preserve tags not included in the requested change.
 - Use \`spaces.item.reference.find\` to find existing items for a source resource. Link on creation through references rather than a redundant second mutation. For an existing item use \`spaces.item.reference.add\`; use \`spaces.item.link-candidate.search\` when a writable target is unknown.
-- Use \`spaces.event.create-once\` only in retryable durable workflows with their stable idempotency key. Normal interactive creation uses \`spaces.event.create\`. Never blindly retry an uncertain mutation.
+- Use \`spaces.event.create\` for interactive creation. Never blindly retry an uncertain mutation.
 
 ## Calendar mail and cross-app work
 
@@ -237,7 +246,7 @@ Use these defaults unless the user asks otherwise or a more specific loaded Skil
 
 - Conversations: \`core.ai.chats.search\`, \`core.ai.chat.read\`, \`core.ai.chat.search\`, \`core.ai.chat.resources\`, and \`core.ai.chats.resources\`.
 - Messaging: \`core.ai.chat.message\`.
-- Scheduled work: \`core.ai.tasks.list\`, \`core.ai.task.read\`, \`core.ai.task.create\`, \`core.ai.task.update\`, \`core.ai.task.pause\`, \`core.ai.task.resume\`, \`core.ai.task.run\`, and \`core.ai.task.delete\`.
+
 
 Load only the needed capabilities and reuse returned typed IDs unchanged.
 
@@ -246,9 +255,83 @@ Load only the needed capabilities and reuse returned typed IDs unchanged.
 - The runtime Chat ID identifies the current conversation. Use \`core.ai.chat.search\` for earlier content in it. For another conversation, use \`core.ai.chats.search\`, then \`core.ai.chat.read\` or \`core.ai.chat.search\` with the returned ID.
 - Use \`core.ai.chat.resources\` for resources from one known conversation and \`core.ai.chats.resources\` to search across conversations. Read a returned resource through its owning app rather than guessing its contents.
 - Before \`core.ai.chat.message\`, identify the exact target and message. Report queued or delivered status accurately and do not claim the target completed the requested work.
-- For reminders and recurring work, use \`core.ai.task.create\` with the exact runtime timezone. Ask one focused question when the schedule or intended conversation is materially ambiguous.
-- Use \`core.ai.tasks.list\` and \`core.ai.task.read\` before changing a task. Preserve its ID and use the focused update, pause, resume, run, or delete Action.
-- A scheduled run continues its conversation with the Project and permissions available at execution time; do not promise access that may later be unavailable.`;
+- For one-time reminders, recurring background work, or changing and repairing a scheduled task, load the \`scheduled-tasks\` Skill.`;
+
+const SCHEDULED_TASKS_INSTRUCTIONS = `# Schedule reminders and background work
+
+Use this Skill to create or manage a task that runs later, once or repeatedly.
+Use the current conversation unless the user names another owned chat. A simple
+reminder is a valid task: its result is a normal message in that chat.
+
+## Load the tools for the job
+
+- Create: \`core.ai.task.create\`.
+- Find and inspect: \`core.ai.tasks.list\`, then \`core.ai.task.read\`.
+- Change instructions, schedule or grants: \`core.ai.task.update\`.
+- Control an existing task: \`core.ai.task.pause\`, \`core.ai.task.resume\`,
+  \`core.ai.task.run\`, or \`core.ai.task.delete\`, as requested.
+- Diagnose an occurrence: \`core.ai.task.run.read\`, using the task and occurrence
+  IDs returned by task.read.
+
+Discover and load only the needed capabilities. Read their current input schemas;
+reuse returned IDs. Read an existing task before changing it. If the request may
+refer to an existing schedule, list tasks before creating a duplicate.
+
+## Prepare the task
+
+1. Resolve the user's timing with the exact runtime timezone (IANA). For a
+   one-time reminder or delayed job use kind once and localAt; for recurrence use
+   kind cron and cron. Resolve relative wording against the current runtime date
+   and time. Ask only if a missing time, timezone or target changes the outcome.
+2. Write a self-contained prompt with the intended result, verified resource IDs
+   and relevant context. Use normal language for results and problems, without a
+   fixed return schema. A reminder prompt says what to remind the user about;
+   it needs no app capabilities merely to post its result to this chat.
+3. For work across apps, load the relevant domain Skills and discover every
+   capability needed, including searches and reads before writes. Propose grants
+   for those capabilities. Choose fixedInput fields from their real schemas:
+   constrain a specific note when the task targets it; allow a whole notebook or
+   unrestricted inputs when that is the intended scope. Empty fixedInput allows
+   any inputs within current user access. Do not invent resource IDs or claim a
+   notebook constraint exists on an action that accepts only a note ID.
+4. Explain the scope through the normal create/update review. Grants authorize
+   this task's capability use, not new access to resources. Always-approval
+   capabilities cannot be granted. Code Mode can run unattended on the server:
+   load its Skill for calculations, chat-file processing, AI tasks and exports.
+   Code capability calls inherit this task's grants, including fixed inputs.
+   HTTP and RSQL use the same grants list: kind http with fixedInput fields
+   origin, url and/or method; kind database with resourceId, operation and/or
+   table. Empty fixedInput grants all supported targets/operations within current
+   access. Prefer a resourceId-only database grant when a task needs connect and
+   multiple operations; a fixed operation also requires a separate connect grant.
+   HTTP secrets must already be configured in the chat or app. Interactive dialogs,
+   secret entry and capability binary streams are unavailable in scheduled code.
+   Explain those requirements instead of promising unattended interaction.
+5. Create the task. Confirm its actual saved timing, timezone and destination only
+   after success. Queued or manually started does not mean completed.
+
+Examples: “Remind me tomorrow at 09:00 to call Anna” is one once task with no
+capability grants. “Every weekday summarize my mail, compare it with calendar X,
+and update note Y” is a recurring task with discovered read and write grants,
+using verified calendar and note IDs where the respective schemas allow them.
+
+## Changes, errors and missing rights
+
+Read the task and relevant failed run before proposing a repair. Distinguish
+missing task grants from lost resource access and ordinary execution errors.
+Update the same task's prompt, future schedule or grants; do not recreate it.
+Omitted grants remain unchanged; supplied grants replace the complete list.
+Expanded authority needs the normal user review and cannot restore lost resource
+access. Check writes already performed before retrying with task.run to avoid
+duplicates; use task.resume when the user wants future scheduled runs restored.
+
+Each run works independently from a snapshot of the chat history at its start.
+Available memories, Skills, Project context and chat files remain accessible
+under runtime rules; files are live, not frozen copies. The run returns its result
+or problem to the parent chat, reopening it and updating activity. The user can
+keep chatting meanwhile. Do not load this management Skill on every background
+run unless managing a schedule is itself needed; use the domain Skills for the
+actual work.`;
 
 const CLOUD_NOTEBOOKS_REFERENCE = `## Flexible data and automatic page lists
 
@@ -351,13 +434,11 @@ Mail attachment inputs require base64: encode the exact returned calendar string
 
 Do not fabricate organizer/attendee addresses, regenerate the returned calendar text, commit after a failed attachment, or retry an unknown mutation result without reconciliation.`;
 
-const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> = [
-  {
-    key: "kit:cloud-kit", name: "cloud-kit",
-    description: "Use for Cloud Kit: programming or improving browser mini apps, file converters, JavaScript tools, workbench UIs, CSV processing or exact money calculations in an existing Kit app. Read current Kit Help before choosing SDK methods.",
-    instructions: CLOUD_KIT_INSTRUCTIONS,
-  },
+const BUILTIN_CLOUD_AI_SKILLS: AiSkillTemplate[] = [
+  ASSISTANT_CODE_MODE_SKILL,
+  ASSISTANT_DATA_ANALYSIS_SKILL,
   {
+    version: 5,
     key: "grids:cloud-grids",
     name: "cloud-grids",
     description:
@@ -366,6 +447,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     references: [{ path: "references/query-tasks.md", content: CLOUD_GRIDS_QUERY_REFERENCE }],
   },
   {
+    version: 2,
     key: "assistant:cloud-assistant",
     name: "cloud-assistant",
     description:
@@ -373,6 +455,15 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     instructions: CLOUD_ASSISTANT_INSTRUCTIONS,
   },
   {
+    version: 2,
+    key: "assistant:scheduled-tasks",
+    name: "scheduled-tasks",
+    description:
+      "Create and manage one-time reminders, delayed jobs and recurring scheduled background tasks in Cloud Assistant. Use for requests such as remind me tomorrow, check in an hour, every morning, or changing, pausing, resuming and repairing a scheduled task, including missing permissions or failed runs.",
+    instructions: SCHEDULED_TASKS_INSTRUCTIONS,
+  },
+  {
+    version: 2,
     key: "core:skill-creator",
     name: "skill-creator",
     description:
@@ -380,6 +471,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     instructions: SKILL_CREATOR_INSTRUCTIONS,
   },
   {
+    version: 1,
     key: "mail:cloud-mail",
     name: "cloud-mail",
     description:
@@ -387,6 +479,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     instructions: CLOUD_MAIL_INSTRUCTIONS,
   },
   {
+    version: 1,
     key: "notebooks:cloud-notebooks",
     name: "cloud-notebooks",
     description:
@@ -395,6 +488,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     references: [{ path: "references/structured-pages.md", content: CLOUD_NOTEBOOKS_REFERENCE }],
   },
   {
+    version: 1,
     key: "contacts:cloud-contacts",
     name: "cloud-contacts",
     description:
@@ -402,6 +496,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     instructions: CLOUD_CONTACTS_INSTRUCTIONS,
   },
   {
+    version: 1,
     key: "spaces:cloud-spaces",
     name: "cloud-spaces",
     description:
@@ -410,6 +505,7 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     references: [{ path: "references/calendar-mail.md", content: CLOUD_SPACES_CALENDAR_REFERENCE }],
   },
   {
+    version: 1,
     key: "weather:cloud-weather",
     name: "cloud-weather",
     description:
@@ -418,13 +514,11 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
   },
 ];
 
+export const getBuiltinAiSkillTemplates = (): readonly AiSkillTemplate[] => BUILTIN_CLOUD_AI_SKILLS;
+
 export const getBuiltinAiSkillTemplate = (name: string) => {
   const seed = BUILTIN_CLOUD_AI_SKILLS.find((entry) => entry.name === name);
   if (!seed) return undefined;
-  const { key: _key, ...template } = seed;
-  return template;
-};
-
-export const seedCloudAiSkills = async (): Promise<void> => {
-  for (const seed of BUILTIN_CLOUD_AI_SKILLS) await aiSkills.seedOnce(seed);
+  const { key, ...template } = seed;
+  return { ...template, templateId: key };
 };