@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/ai/settings.ts

@@ -1,3 +1,4 @@
+import { AiModelPricingSchema } from "../shared/ai-costs";
 import { z } from "zod";
 import { coreSettings } from "../services";
 import { getAiCredential, listAiCredentialProfileIds } from "./credentials";
@@ -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,11 +14,11 @@ export const withAiShortId = async <T>(
     try {
       return await insert(allocate());
     } catch (error) {
+      const uniqueViolation = typeof error === "object" && error !== null && (("code" in error && error.code === "23505") || ("errno" in error && error.errno === "23505"));
       const collision =
         typeof error === "object" &&
         error !== null &&
-        "code" in error &&
-        error.code === "23505" &&
+        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,47 @@
+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))
+  `;
+  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 * word_similarity(${query}, skill.name) + 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_DATA_ANALYSIS_SKILL } from "./data-analysis-skill";
+import { ASSISTANT_CODE_MODE_SKILL } from "./code-mode-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,75 @@ 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. Interactive browser and Code Mode are not
+   available in background runs; explain an unsupported requirement rather than
+   promising it will work unattended.
+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 +426,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: 4,
     key: "grids:cloud-grids",
     name: "cloud-grids",
     description:
@@ -366,6 +439,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 +447,14 @@ const BUILTIN_CLOUD_AI_SKILLS: Array<Parameters<typeof aiSkills.seedOnce>[0]> =
     instructions: CLOUD_ASSISTANT_INSTRUCTIONS,
   },
   {
+    version: 1,
+    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 +462,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 +470,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 +479,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 +487,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 +496,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 +505,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 };
 };

package/src/ai/skill-tool.ts

@@ -2,11 +2,22 @@ import { z } from "zod";
 import type { AccessSubject } from "../server";
 import { AI_SKILL_FILE_MOUNT } from "./file-mount";
 import { AI_SHORT_ID_PATTERN } from "./short-id";
-import { searchAiSkillCatalog } from "./skill-catalog";
 import { AI_SKILL_NAME_MAX_CHARS, AI_SKILL_NAME_PATTERN } from "./skill-format";
 import { aiSkills } from "./skills";
 import { defineAiTool } from "./tools";
 
+/** Explicit selections use the same permission check and turn snapshot as load_skill. */
+export async function loadSelectedAiSkills(ids: readonly string[], turnId: string, subject: AccessSubject | null, allowed: boolean) {
+  const loaded = [];
+  for (const id of new Set(ids)) {
+    if (!subject || !allowed) throw new Error("The selected Skill requires a model and tool scope that allow Skills.");
+    const skill = await aiSkills.loadForTurn(turnId, { id }, subject);
+    if (!skill) throw new Error(`Selected Skill ${id} is unavailable or access was revoked.`);
+    loaded.push({ name: skill.name, revision: skill.revision, instructions: skill.instructions, files: skill.files.map(file => file.path) });
+  }
+  return loaded;
+}
+
 export const CloudAiLoadSkillInputSchema = z
   .object({
     name: z
@@ -58,7 +69,7 @@ export const createCloudAiLoadSkillTool = (subject: AccessSubject) =>
   });
 
 export const CloudAiSearchSkillsInputSchema = z.object({
-  query: z.string().trim().min(1).max(200).describe("Short English terms describing the workflow or domain to find."),
+  query: z.string().trim().min(1).max(200).describe("Words from the Skill name or description; minor typos are tolerated."),
   limit: z.number().int().min(1).max(20).default(10),
 });
 
@@ -71,11 +82,11 @@ export const createCloudAiSearchSkillsTool = (subject: AccessSubject) =>
   defineAiTool({
     name: "search_skills",
     description:
-      "Search enabled Assistant Skills omitted from the bounded system-prompt catalog. Use short English domain or workflow terms, then load_skill with an exact returned name.",
+      "Search enabled Assistant Skills omitted from the bounded system-prompt catalog. Search names and descriptions with short domain or workflow terms; minor typos are tolerated. Then load_skill with an exact returned name.",
     inputSchema: CloudAiSearchSkillsInputSchema,
     outputSchema: CloudAiSearchSkillsOutputSchema,
     approval: "never",
   }).server(async (input) => {
-    const skills = (await aiSkills.list(subject)).filter((skill) => skill.enabled);
-    return searchAiSkillCatalog(skills, input.query, input.limit);
+    const result = await aiSkills.search(subject, input.query, input.limit);
+    return { skills: result.skills.map(({ name, description }) => ({ name, description })), more: result.more };
   });

package/src/ai/skills-routes.ts

@@ -1,6 +1,7 @@
+import { aiProjects } from "./projects";
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
-import { PrincipalSchema } from "../contracts/shared";
+import { AuthenticatedPrincipalSchema } from "../contracts/shared";
 import { type AuthContext, auth, err, fail, ok, rateLimit, respond, v } from "../server";
 import {
   AI_SKILL_DESCRIPTION_MAX_CHARS,
@@ -38,7 +39,7 @@ const SkillFieldsSchema = z.object({
 });
 
 const UpdateSkillSchema = SkillFieldsSchema.extend({ expectedRevision: z.number().int().positive() });
-const SkillAccessSchema = z.object({ principal: PrincipalSchema, permission: z.enum(["read", "write", "admin"]) });
+const SkillAccessSchema = z.object({ principal: AuthenticatedPrincipalSchema, permission: z.enum(["read", "write", "admin"]) });
 const SkillAccessUpdateSchema = z.object({ permission: z.enum(["read", "write", "admin"]) });
 const SkillEnabledSchema = z.object({ enabled: z.boolean() });
 
@@ -56,8 +57,35 @@ type AiSkillsRouteDependencies = {
 const buildAiSkillsRoutes = (dependencies: AiSkillsRouteDependencies = {}) =>
   new Hono<AuthContext>()
     .use(dependencies.limit ?? rateLimit())
-    .use("*", dependencies.authenticate ?? auth.requireRole("*"))
-    .get("/", async (c) => respond(c, ok({ skills: (await aiSkills.list(c.get("accessSubject") ?? null)).map(publicSummary) })))
+    .use("*", dependencies.authenticate ?? auth.requireRole("authenticated"))
+    .get("/", v("query", z.object({ q: z.string().trim().max(200).optional() })), async (c) => {
+      const subject = c.get("accessSubject") ?? null;
+      const { q } = c.req.valid("query");
+      const skills = q === undefined ? await aiSkills.list(subject) : (await aiSkills.search(subject, q)).skills;
+      return respond(c, ok({ skills: skills.map(publicSummary) }));
+    })
+    .get("/project-links/:projectId", v("query", z.object({ q: z.string().max(200).default(""), page: z.coerce.number().int().min(1).max(100000).default(1), available: z.enum(["true","false"]).default("false") })), async c => {
+      const subject = c.get("accessSubject") ?? null, query = c.req.valid("query");
+      const project = await aiProjects.getByShortId(c.req.param("projectId")!, subject, query.available === "true" ? "admin" : "read");
+      const result = project ? await aiSkills.projectSkills(project.id, subject, { query:query.q, page:query.page, available:query.available === "true" }) : null;
+      return result ? respond(c, ok({ ...result, items:result.items.map(publicSummary) })) : respond(c, fail(err.notFound("Project")));
+    })
+    .get("/:skillId/projects", async c => {
+      const subject = c.get("accessSubject") ?? null;
+      const skill = await aiSkills.getByShortId(c.req.param("skillId")!, subject, "admin");
+      const projects = skill ? await aiSkills.linkedProjects(skill.id, subject) : null;
+      return projects ? respond(c, ok({ projects:projects.map(project => ({ id:project.shortId, name:project.name })) })) : respond(c, fail(err.notFound("Skill")));
+    })
+    .put("/:skillId/projects/:projectId", v("json", z.object({ linked:z.boolean() }).strict()), async c => {
+      const subject = c.get("accessSubject") ?? null;
+      const [skill,project] = await Promise.all([
+        aiSkills.getByShortId(c.req.param("skillId")!,subject,"admin"),
+        aiProjects.getByShortId(c.req.param("projectId")!,subject,"admin"),
+      ]);
+      const linked = c.req.valid("json").linked;
+      return skill && project && await aiSkills.linkProject(skill.id,project.id,linked,subject)
+        ? respond(c,ok({linked})) : respond(c,fail(err.notFound("Skill or Project")));
+    })
     .get("/templates/:name", dependencies.authenticate ?? auth.requireRole("authenticated"), (c) => {
       if (!c.get("accessSubject")) return respond(c, fail(err.forbidden("Skill templates require an authenticated access subject.")));
       const template = getBuiltinAiSkillTemplate(c.req.param("name"));