@k2b/cloud 0.29.1 → 0.31.0

package/src/access/PermissionEditor.tsx

@@ -20,8 +20,11 @@ import { serviceAccountKindDisplay } from "./service-account-kind";
 export type GrantableLevel = Exclude<PermissionLevel, "none">;
 
 /** Either a bare level (uses the default View / Edit / Manage label and
- *  icon) or an object with per-context overrides. */
-export type AllowedLevel = GrantableLevel | { level: GrantableLevel; label?: string; icon?: string };
+ *  icon) or an object with per-context overrides. A `scope` offers the level
+ *  on a narrower part of the resource that the application defines, such as
+ *  Mail's assigned conversations; it reaches the callbacks and matches the
+ *  entry's `scope`. `description` explains an option in the level menu. */
+export type AllowedLevel = GrantableLevel | { level: GrantableLevel; scope?: string; label?: string; icon?: string; description?: string };
 
 type PermissionEditorProps = {
   /** Initial access entries — caller stays the source of truth for
@@ -41,10 +44,11 @@ type PermissionEditorProps = {
     principal: Principal,
     permission: GrantableLevel,
     display?: { displayName: string; serviceAccountKind?: ServiceAccountKind },
+    scope?: string,
   ) => Promise<AccessEntry>;
 
-  /** Update an existing entry's permission level. */
-  updateAccess: (accessId: string, permission: GrantableLevel) => Promise<void>;
+  /** Update an existing entry's permission level and, for a scoped level, its scope. */
+  updateAccess: (accessId: string, permission: GrantableLevel, scope?: string) => Promise<void>;
 
   /** Revoke an existing entry. Any entry can be revoked except the last
    *  manager: once exactly one entry manages the resource (`admin` for a
@@ -95,10 +99,16 @@ const defaultLabels = (t: ReturnType<typeof accessMessages.resolve>["t"]): Recor
 
 type ResolvedLevel = {
   level: GrantableLevel;
+  scope: string | undefined;
+  /** Unique per option: the level, prefixed by its scope. */
+  key: string;
   label: string;
   icon: string;
+  description: string | undefined;
 };
 
+const levelKey = (level: PermissionLevel, scope: string | undefined): string => (scope ? `${scope}:${level}` : level);
+
 /** Resolve the AllowedLevel union into a flat shape the renderer can
  *  loop over. Falls back to the default View / Edit / Manage list when
  *  no override is given. */
@@ -111,8 +121,11 @@ const resolveAllowedLevels = (allowed: AllowedLevel[] | undefined, t: ReturnType
     const def = defaults[level];
     return {
       level,
+      scope: override?.scope,
+      key: levelKey(level, override?.scope),
       label: override?.label ?? def.label,
       icon: override?.icon ?? def.icon,
+      description: override?.description,
     };
   });
 };
@@ -122,10 +135,11 @@ const resolveAllowedLevels = (allowed: AllowedLevel[] | undefined, t: ReturnType
  *  the platform defaults. Tolerates "none" / unknown legacy values. */
 const resolveEntryDisplay = (
   permission: PermissionLevel,
+  scope: string | undefined,
   allowed: ResolvedLevel[],
   t: ReturnType<typeof accessMessages.resolve>["t"],
 ): { label: string; icon: string } => {
-  const fromAllowed = allowed.find((a) => a.level === permission);
+  const fromAllowed = allowed.find((a) => a.key === levelKey(permission, scope));
   if (fromAllowed) return fromAllowed;
   const defaults = defaultLabels(t);
   return defaults[permission] ?? defaults.none;
@@ -186,22 +200,24 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     mutation: async (data: {
       principal: Principal;
       permission: GrantableLevel;
+      scope: string | undefined;
       display: { displayName: string; serviceAccountKind?: ServiceAccountKind };
-    }) => props.grantAccess(data.principal, data.permission, data.display),
+    }) => props.grantAccess(data.principal, data.permission, data.display, data.scope),
     onSuccess: (newEntry) => {
       setEntries(entries.length, { ...newEntry });
     },
     onError: (err) => prompts.error(err.message),
   });
 
-  const updateMut = mutation.create<{ accessId: string; permission: GrantableLevel }, { accessId: string; permission: GrantableLevel }>({
+  type LevelChange = { accessId: string; permission: GrantableLevel; scope: string | undefined };
+  const updateMut = mutation.create<LevelChange, LevelChange>({
     mutation: async (data) => {
-      await props.updateAccess(data.accessId, data.permission);
+      await props.updateAccess(data.accessId, data.permission, data.scope);
       return data;
     },
     onSuccess: (result) => {
       if (result) {
-        setEntries((entry) => entry.id === result.accessId, "permission", result.permission);
+        setEntries((entry) => entry.id === result.accessId, { permission: result.permission, scope: result.scope });
       }
     },
     onError: (err) => prompts.error(err.message),
@@ -226,7 +242,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   const busy = () => grantMut.loading() || updateMut.loading() || revokeMut.loading();
   // The service refuses to remove the last manager; the row says so up front.
   const lastManagerId = createMemo(() => {
-    const managers = (props.effectiveEntries?.(entries) ?? entries).filter(isManagerEntry);
+    // A grant on part of the resource never manages it.
+    const managers = (props.effectiveEntries?.(entries) ?? entries).filter((entry) => !entry.scope && isManagerEntry(entry));
     return managers.length === 1 ? managers[0]!.id : null;
   });
 
@@ -247,8 +264,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
                 lastManager={entry.id === lastManagerId()}
                 allowed={allowed(entry.principal)}
                 singlePicker={allowed(entry.principal).length === 1}
-                onUpdatePermission={(permission) => {
-                  if (!busy()) void updateMut.mutate({ accessId: entry.id, permission });
+                onUpdatePermission={(option) => {
+                  if (!busy()) void updateMut.mutate({ accessId: entry.id, permission: option.level, scope: option.scope });
                 }}
                 onRevoke={() => {
                   if (!busy()) void revokeMut.mutate(entry);
@@ -273,8 +290,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
           allowServiceAccounts={props.allowServiceAccounts}
           disabled={busy()}
           onSelect={(principal, display) => {
-            const permission = allowed(principal)[0]?.level;
-            if (permission && !busy()) grantMut.mutate({ principal, permission, display });
+            const first = allowed(principal)[0];
+            if (first && !busy()) grantMut.mutate({ principal, permission: first.level, scope: first.scope, display });
           }}
         />
       </Show>
@@ -298,17 +315,18 @@ function AccessEntryRow(props: {
   singlePicker: boolean;
   /** Present for group grants: who currently receives access through the group. */
   coverage?: GroupCoverage;
-  onUpdatePermission: (permission: GrantableLevel) => void;
+  onUpdatePermission: (option: ResolvedLevel) => void;
   onRevoke: () => void;
 }) {
   const locale = useLocale();
   const t = () => accessMessages.resolve([locale()]).t;
   const displayName = () => getEntryDisplayName(props.entry, t(), locale());
-  const display = () => resolveEntryDisplay(props.entry.permission, props.allowed, t());
-  const manageLabel = () => resolveEntryDisplay("admin", props.allowed, t()).label;
+  const entryKey = () => levelKey(props.entry.permission, props.entry.scope);
+  const display = () => resolveEntryDisplay(props.entry.permission, props.entry.scope, props.allowed, t());
+  const manageLabel = () => resolveEntryDisplay("admin", undefined, props.allowed, t()).label;
   const removeLabel = () => (props.lastManager ? t().lastManager({ level: manageLabel() }) : t().remove({ name: displayName() }));
   const isInteractive = () =>
-    props.canEdit && !props.disabled && !props.singlePicker && props.allowed.some((option) => option.level === props.entry.permission);
+    props.canEdit && !props.disabled && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
 
   const badgeClass =
     "flex min-h-7 items-center gap-1 rounded-full border border-transparent bg-[var(--ui-surface-muted)] px-2.5 py-1 text-xs text-secondary";
@@ -371,21 +389,22 @@ function AccessEntryRow(props: {
         <Show when={isInteractive()} fallback={<span class={`${badgeClass} cursor-default`}>{badgeContent}</span>}>
           <SelectChip
             aria-label={t().permissionFor({ name: displayName() })}
-            value={() => props.entry.permission as GrantableLevel}
+            value={entryKey}
             options={props.allowed.map((option) => {
-              const locked = props.lastManager && option.level !== "admin";
+              const locked = props.lastManager && (option.level !== "admin" || option.scope !== undefined);
               return {
-                value: option.level,
+                value: option.key,
                 label: option.label,
                 icon: `ti ${option.icon}`,
                 disabled: locked,
-                description: locked ? t().lastManagerOption({ level: manageLabel() }) : undefined,
+                description: locked ? t().lastManagerOption({ level: manageLabel() }) : option.description,
               };
             })}
             icon={`ti ${display().icon}`}
             position="bottom-left"
-            onValueChange={(permission) => {
-              if (permission !== props.entry.permission) props.onUpdatePermission(permission);
+            onValueChange={(key) => {
+              const option = props.allowed.find((candidate) => candidate.key === key);
+              if (option && key !== entryKey()) props.onUpdatePermission(option);
             }}
           />
         </Show>

package/src/ai/app-skill-store.ts

@@ -0,0 +1,298 @@
+import { type SQL, sql, type TransactionSQL } from "bun";
+import { z } from "zod";
+import { appAudienceRoles } from "../_internal/app-roles";
+import { APP_REGISTRY_TTL_MS } from "../_internal/registry";
+import type { AppRegistryEntry } from "../contracts/registry";
+import { logger } from "../services/logging";
+import { toPgTextArray } from "../services/postgres";
+import { type AppSkillDefinition, parseStoredAppSkill } from "./app-skills";
+import { withAiShortIdForDb } from "./short-id";
+import { AI_SKILL_CATALOG_MAX_CHARS, aiSkillCatalogChars } from "./skill-catalog";
+import { appSkillStatus, contentHash } from "./skill-content";
+import { serializeAiSkillMarkdown } from "./skill-format";
+import {
+  AiSkillInputError,
+  AiSkillRevisionConflictError,
+  createSkillAccess,
+  getRow,
+  listReferences,
+  replaceSkillContent,
+  rowContentHash,
+  type SkillRow,
+} from "./skills";
+
+const log = logger("ai:app-skills");
+type AppSkillRow = {
+  key: string;
+  app_id: string;
+  app_name: string;
+  name: string;
+  skill_id: string | null;
+  source: unknown;
+  source_hash: string | null;
+  applied_hash: string | null;
+  manifest_hash: string | null;
+  available: boolean;
+  required_roles: string[] | null;
+  conflict: "invalid" | "name_taken" | null;
+};
+
+const lock = (db: SQL) => db`SELECT pg_advisory_xact_lock(hashtext('cloud:ai:app-skills'))`;
+const nameTaken = (error: unknown): boolean =>
+  error !== null && typeof error === "object" && "constraint" in error && error.constraint === "idx_ai_skills_name";
+
+const install = async (source: AppSkillDefinition, db: SQL): Promise<SkillRow> => {
+  const [row] = await withAiShortIdForDb(
+    db,
+    "idx_ai_skills_short_id",
+    (attempt, shortId) => attempt<SkillRow[]>`
+    INSERT INTO ai.skills(short_id, name, description, instructions, extra_frontmatter)
+    VALUES (${shortId}, ${source.name}, ${source.description}, ${source.instructions},
+      (${JSON.stringify(source.extraFrontmatter)}::text)::jsonb) RETURNING *`,
+  );
+  if (!row) throw new Error("Failed to install app skill.");
+  for (const ref of source.references)
+    await db`INSERT INTO ai.skill_references(skill_id, path, content) VALUES (${row.id}::uuid, ${ref.path}, ${ref.content})`;
+  await createSkillAccess(row.id, { principal: { type: "authenticated" }, permission: "read" }, db);
+  return row;
+};
+const sourceJson = (source: AppSkillDefinition): string =>
+  JSON.stringify({
+    name: source.name,
+    description: source.description,
+    instructions: source.instructions,
+    extraFrontmatter: source.extraFrontmatter,
+    references: source.references,
+  });
+
+/**
+ * Brings one live app's Skills in line with its published catalog. Returns false while the advertised catalog is not
+ * stored yet, so the caller retries on a later registry change.
+ */
+const reconcileApp = async (app: AppRegistryEntry, tx: TransactionSQL): Promise<boolean> => {
+  if (!app.skills) {
+    await tx`UPDATE ai.app_skills SET available=false, updated_at=now() WHERE app_id=${app.id} AND available`;
+    return true;
+  }
+  const manifest = app.skills.manifestHash;
+  const [catalog] = await tx<
+    { skills: unknown }[]
+  >`SELECT skills FROM ai.app_skill_catalogs WHERE app_id=${app.id} AND manifest_hash=${manifest}`;
+  if (!catalog) return false; // Publication may still be in flight: keep the last known state.
+  const roles = appAudienceRoles(app.nav);
+  const roleArray = roles === undefined ? null : toPgTextArray([...roles]);
+  const [state] = await tx<{ current: boolean }[]>`SELECT
+    EXISTS(SELECT 1 FROM ai.app_skills WHERE app_id=${app.id}) AND
+    NOT EXISTS(SELECT 1 FROM ai.app_skills WHERE app_id=${app.id} AND (
+      manifest_hash IS DISTINCT FROM ${manifest} OR NOT available OR app_name IS DISTINCT FROM ${app.name}
+      OR required_roles IS DISTINCT FROM ${roleArray}::text[]
+    )) AS current`;
+  if (state?.current) return true;
+  const entries = z
+    .array(z.unknown())
+    .max(Math.floor((AI_SKILL_CATALOG_MAX_CHARS + 1) / "- a: b\n".length))
+    .parse(catalog.skills);
+  const names = new Set<string>();
+  let catalogChars = 0;
+  for (const [index, input] of entries.entries()) {
+    const name = input && typeof input === "object" && "name" in input && typeof input.name === "string" ? input.name : `invalid-${index}`;
+    const key = `app:${app.id}/${name}`;
+    let source: AppSkillDefinition;
+    try {
+      source = parseStoredAppSkill(input);
+      if (names.has(name)) throw new Error(`Skill "${name}" is duplicated.`);
+      catalogChars += aiSkillCatalogChars([source]) + (names.size ? 1 : 0);
+      if (catalogChars > AI_SKILL_CATALOG_MAX_CHARS) throw new Error("App skill catalog exceeds the Assistant catalog budget.");
+    } catch (error) {
+      names.add(name);
+      await tx`INSERT INTO ai.app_skills(key, app_id, app_name, name, manifest_hash, available, required_roles, conflict)
+        VALUES (${key}, ${app.id}, ${app.name}, ${name}, ${manifest}, true, ${roleArray}::text[], 'invalid')
+        ON CONFLICT(key) DO UPDATE SET app_name=EXCLUDED.app_name, manifest_hash=EXCLUDED.manifest_hash,
+          available=true, required_roles=EXCLUDED.required_roles, conflict='invalid', updated_at=now()`;
+      log.warn("Invalid app skill skipped", { appId: app.id, name, error: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    names.add(name);
+    const [managed] = await tx<AppSkillRow[]>`INSERT INTO ai.app_skills
+      (key, app_id, app_name, name, source, source_hash, manifest_hash, available, required_roles)
+      VALUES (${key}, ${app.id}, ${app.name}, ${name}, (${sourceJson(source)}::text)::jsonb,
+        ${source.hash}, ${manifest}, true, ${roleArray}::text[])
+      ON CONFLICT(key) DO UPDATE SET app_name=EXCLUDED.app_name, source=EXCLUDED.source, source_hash=EXCLUDED.source_hash,
+        manifest_hash=EXCLUDED.manifest_hash, available=true, required_roles=EXCLUDED.required_roles,
+        conflict=CASE WHEN ai.app_skills.skill_id IS NULL THEN ai.app_skills.conflict ELSE NULL END, updated_at=now()
+      RETURNING *`;
+    if (!managed) throw new Error("Failed to read app skill association.");
+    if (managed.skill_id) {
+      const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id=${managed.skill_id}::uuid FOR UPDATE`;
+      if (!row) continue; // A durable admin deletion, even when the app's manifest changes.
+      const hash = await rowContentHash(row, tx);
+      if (hash === source.hash) {
+        if (managed.applied_hash !== source.hash) await tx`UPDATE ai.app_skills SET applied_hash=${source.hash} WHERE key=${key}`;
+      } else if (hash === managed.applied_hash) {
+        try {
+          await tx.savepoint(async (attempt) => {
+            await replaceSkillContent(row, source, attempt);
+            await attempt`UPDATE ai.app_skills SET applied_hash=${source.hash} WHERE key=${key}`;
+          });
+        } catch (error) {
+          if (!nameTaken(error)) throw error;
+          await tx`UPDATE ai.app_skills SET conflict='name_taken' WHERE key=${key}`;
+        }
+      }
+      continue;
+    }
+    try {
+      await tx.savepoint(async (attempt) => {
+        const row = await install(source, attempt);
+        await attempt`UPDATE ai.app_skills SET skill_id=${row.id}::uuid, applied_hash=${source.hash}, conflict=NULL WHERE key=${key}`;
+      });
+    } catch (error) {
+      if (!nameTaken(error)) throw error;
+      await tx`UPDATE ai.app_skills SET conflict='name_taken' WHERE key=${key}`;
+    }
+  }
+  await tx`UPDATE ai.app_skills SET available=false, updated_at=now()
+    WHERE app_id=${app.id} AND available AND NOT(name=ANY(${toPgTextArray([...names])}::text[]))`;
+  return true;
+};
+
+/** Everything app Skills derive from the registry. While it is unchanged, reconciling again changes nothing. */
+export const appSkillsRegistryState = (apps: readonly AppRegistryEntry[]): string =>
+  JSON.stringify(apps.map((app) => [app.id, app.name, app.skills?.manifestHash ?? null, appAudienceRoles(app.nav) ?? null]).sort());
+
+/**
+ * Core's sync from the live registry into `ai.skills`. One app's broken catalog never blocks another app. Returns
+ * whether every advertised catalog was applied.
+ */
+export const reconcileAppSkills = async (apps: readonly AppRegistryEntry[], db: SQL = sql): Promise<boolean> => {
+  const liveIds = toPgTextArray(apps.map((app) => app.id));
+  await db.begin(async (tx) => {
+    await lock(tx);
+    await tx`UPDATE ai.app_skills SET available=false, updated_at=now()
+      WHERE available AND NOT (app_id=ANY(${liveIds}::text[]))`;
+    await tx`DELETE FROM ai.app_skill_catalogs WHERE last_seen_at < now() - ${APP_REGISTRY_TTL_MS * 2} * interval '1 millisecond'`;
+  });
+  let complete = true;
+  for (const app of apps) {
+    try {
+      const applied = await db.begin(async (tx) => {
+        await tx`SET LOCAL statement_timeout = '10s'`.simple();
+        await lock(tx);
+        return reconcileApp(app, tx);
+      });
+      if (!applied) complete = false;
+    } catch (error) {
+      complete = false;
+      log.error("App skill reconciliation failed", { appId: app.id, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return complete;
+};
+
+/** An app Skill Cloud does not offer because an administrator deleted it or it could not be installed. */
+export type AiAppSkillIssue = {
+  appId: string;
+  appName: string;
+  name: string;
+  state: "deleted" | "name_taken" | "invalid";
+  available: boolean;
+};
+
+export const appSkillIssues = async (): Promise<AiAppSkillIssue[]> => sql`SELECT app.app_id AS "appId", app.app_name AS "appName", app.name,
+  COALESCE(app.conflict, 'deleted') AS state, app.available
+  FROM ai.app_skills app LEFT JOIN ai.skills skill ON skill.id=app.skill_id
+  WHERE (app.skill_id IS NOT NULL AND skill.id IS NULL) OR app.conflict IS NOT NULL ORDER BY app.app_id, app.name LIMIT 500`;
+
+export const appSkillVersion = async (skillId: string) =>
+  sql.begin(async (tx) => {
+    // Source association before Skill, matching reconciliation/reset lock order.
+    const [app] = await tx<AppSkillRow[]>`SELECT * FROM ai.app_skills WHERE skill_id=${skillId}::uuid FOR SHARE`;
+    const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id=${skillId}::uuid FOR SHARE`;
+    if (!row) return null;
+    const fields = {
+      name: row.name,
+      description: row.description,
+      instructions: row.instructions,
+      extraFrontmatter: z.record(z.string(), z.unknown()).parse(row.extra_frontmatter),
+      references: await listReferences(skillId, tx),
+    };
+    const source = app?.source ? parseStoredAppSkill(app.source) : null;
+    return {
+      current: { markdown: serializeAiSkillMarkdown(fields), references: fields.references },
+      app: source ? { markdown: serializeAiSkillMarkdown(source), references: source.references } : null,
+      /** Pass back to reset, so a release published after the review is not applied unseen. */
+      appVersion: source ? source.hash : null,
+      status: app ? appSkillStatus(contentHash(fields), app.source_hash, app.applied_hash) : null,
+    };
+  });
+
+export const resetAppSkill = async (skillId: string, expectedRevision: number, expectedAppVersion: string): Promise<boolean> =>
+  sql.begin(async (tx) => {
+    await lock(tx);
+    const [app] = await tx<AppSkillRow[]>`SELECT * FROM ai.app_skills WHERE skill_id=${skillId}::uuid FOR UPDATE`;
+    const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id=${skillId}::uuid FOR UPDATE`;
+    if (!row) return false;
+    if (Number(row.revision) !== expectedRevision) throw new AiSkillRevisionConflictError();
+    if (!app?.source || !app.source_hash) throw new AiSkillInputError("No app source is available for this Skill.");
+    if (app.source_hash !== expectedAppVersion)
+      throw new AiSkillRevisionConflictError(
+        "The app shipped a different version since you compared it. Compare it again before resetting.",
+      );
+    const source = parseStoredAppSkill(app.source);
+    try {
+      await tx.savepoint((attempt) => replaceSkillContent(row, source, attempt));
+    } catch (error) {
+      if (nameTaken(error)) throw new AiSkillRevisionConflictError("A Skill with this name already exists.");
+      throw error;
+    }
+    await tx`UPDATE ai.app_skills SET applied_hash=${source.hash}, conflict=NULL, updated_at=now() WHERE key=${app.key}`;
+    return true;
+  });
+
+export const restoreAppSkill = async (appId: string, name: string): Promise<boolean> =>
+  sql.begin(async (tx) => {
+    await lock(tx);
+    const [app] = await tx<AppSkillRow[]>`SELECT * FROM ai.app_skills WHERE app_id=${appId} AND name=${name} FOR UPDATE`;
+    if (!app) return false;
+    if (!app.source) throw new AiSkillInputError("No app source is available for this Skill.");
+    if (app.skill_id && (await getRow(app.skill_id, tx))) throw new AiSkillRevisionConflictError("This app Skill is already installed.");
+    const source = parseStoredAppSkill(app.source);
+    let row: SkillRow;
+    try {
+      row = await tx.savepoint((attempt) => install(source, attempt));
+    } catch (error) {
+      if (nameTaken(error)) throw new AiSkillRevisionConflictError("A Skill with this name already exists.");
+      throw error;
+    }
+    await tx`UPDATE ai.app_skills SET skill_id=${row.id}::uuid, applied_hash=${source.hash}, conflict=NULL, updated_at=now() WHERE key=${app.key}`;
+    return true;
+  });
+
+/**
+ * Links the Skill that already holds an app Skill's name to that app Skill. Its content stays as an administrator
+ * customization until an administrator resets it; grants, short ID and personal settings stay unchanged.
+ */
+export const adoptAppSkill = async (appId: string, name: string): Promise<boolean> =>
+  sql.begin(async (tx) => {
+    await lock(tx);
+    const [app] = await tx<AppSkillRow[]>`SELECT * FROM ai.app_skills WHERE app_id=${appId} AND name=${name} FOR UPDATE`;
+    if (!app) return false;
+    if (!app.source_hash) throw new AiSkillInputError("No app source is available for this Skill.");
+    if (app.skill_id && (await getRow(app.skill_id, tx))) throw new AiSkillRevisionConflictError("This app Skill is already installed.");
+    const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE name=${name} FOR UPDATE`;
+    if (!row) throw new AiSkillInputError("No Skill uses this name. Install the app Skill instead.");
+    const [linked] = await tx`SELECT 1 FROM ai.app_skills WHERE skill_id=${row.id}::uuid`;
+    if (linked) throw new AiSkillRevisionConflictError("This Skill already belongs to another app Skill.");
+    await tx`UPDATE ai.app_skills SET skill_id=${row.id}::uuid, applied_hash=${app.source_hash}, conflict=NULL, updated_at=now()
+      WHERE key=${app.key}`;
+    return true;
+  });
+
+/** Platform-admin operations on app Skills. Callers enforce platform-admin authorization. */
+export const aiAppSkills = {
+  appSkillIssues,
+  appVersion: appSkillVersion,
+  reset: resetAppSkill,
+  restore: restoreAppSkill,
+  adopt: adoptAppSkill,
+};

package/src/ai/app-skills.ts

@@ -0,0 +1,105 @@
+import { type SQL, sql } from "bun";
+import { z } from "zod";
+import { logger } from "../services/logging";
+import { AI_SKILL_CATALOG_MAX_CHARS, aiSkillCatalogChars } from "./skill-catalog";
+import { type AiSkillContent, canonicalHash, contentHash, validateSkillContent } from "./skill-content";
+import { type AiSkillExtraFrontmatter, type AiSkillReferenceInput, parseAiSkillMarkdown } from "./skill-format";
+
+export type AppSkillDefinition = Readonly<{
+  name: string;
+  description: string;
+  instructions: string;
+  extraFrontmatter: AiSkillExtraFrontmatter;
+  references: readonly AiSkillReferenceInput[];
+  hash: string;
+}>;
+
+const freezeJson = (value: unknown): void => {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) freezeJson(child);
+    Object.freeze(value);
+  }
+};
+
+export const validateAppSkillContent = (input: AiSkillContent): AppSkillDefinition => {
+  try {
+    const fields = validateSkillContent(input);
+    fields.instructions = fields.instructions.replace(
+      /\]\((references\/[a-z0-9][a-z0-9._-]*\.md)\)/g,
+      (_, path: string) => `](/skills/${fields.name}/${path})`,
+    );
+    // Link expansion must respect the same instruction size limits.
+    const validated = validateSkillContent(fields);
+    const paths = new Set(validated.references.map((ref) => ref.path));
+    for (const match of validated.instructions.matchAll(/references\/[^\s\])`"'<>]+\.md/g)) {
+      const path = match[0];
+      const owner = validated.instructions.slice(0, match.index).match(/\/skills\/([a-z0-9-]+)\/$/)?.[1];
+      // A fully qualified link to another loaded Skill names that Skill's files, not this catalog entry's references.
+      if (owner && owner !== validated.name) continue;
+      if (!paths.has(path)) throw new Error(`Reference "${path}" is not declared.`);
+    }
+    const definition = { ...validated, hash: contentHash(validated) };
+    freezeJson(definition);
+    return definition;
+  } catch (error) {
+    throw new Error(`Skill "${input.name}": ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
+export const skill = (input: { markdown: string; references?: Readonly<Record<string, string>> }): AppSkillDefinition => {
+  const document = parseAiSkillMarkdown(input.markdown);
+  return validateAppSkillContent({
+    ...document,
+    references: Object.entries(input.references ?? {}).map(([path, content]) => ({ path, content })),
+  });
+};
+
+export const appSkillManifestHash = (skills: readonly AppSkillDefinition[]): string =>
+  canonicalHash(skills.map(({ name, hash }) => ({ name, hash })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)));
+
+export const validateAppSkillCatalog = (skills: readonly AppSkillDefinition[]): readonly AppSkillDefinition[] => {
+  const validated = skills.map(validateAppSkillContent);
+  if (new Set(validated.map((entry) => entry.name)).size !== validated.length) throw new Error("App skill names must be unique.");
+  if (aiSkillCatalogChars(validated) > AI_SKILL_CATALOG_MAX_CHARS)
+    throw new Error(
+      `App skills exceed the ${AI_SKILL_CATALOG_MAX_CHARS}-character always-visible Assistant catalog budget; this bounds the number of skills per app.`,
+    );
+  return Object.freeze(validated);
+};
+
+// Catalog JSON is untrusted even though application authors use skill() to produce it.
+const StoredSkillSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  instructions: z.string(),
+  extraFrontmatter: z.record(z.string(), z.unknown()),
+  references: z.array(z.object({ path: z.string(), content: z.string() })),
+});
+export const parseStoredAppSkill = (value: unknown): AppSkillDefinition => validateAppSkillContent(StoredSkillSchema.parse(value));
+
+export const registerAppSkills = async (
+  appId: string,
+  skills: readonly AppSkillDefinition[],
+  manifestHash: string,
+  db: SQL = sql,
+): Promise<void> => {
+  try {
+    await db.begin(async (tx) => {
+      await tx`SET LOCAL statement_timeout = '10s'`.simple();
+      const renewed = await tx`UPDATE ai.app_skill_catalogs SET last_seen_at = now()
+        WHERE app_id = ${appId} AND manifest_hash = ${manifestHash} RETURNING app_id`;
+      if (renewed.length) return;
+      await tx`INSERT INTO ai.app_skill_catalogs(app_id, manifest_hash, skills)
+        VALUES (${appId}, ${manifestHash}, (${JSON.stringify(skills)}::text)::jsonb)
+        ON CONFLICT (app_id, manifest_hash) DO UPDATE SET last_seen_at = now()`;
+    });
+  } catch (error) {
+    // Bun's PostgresError carries the SQLSTATE in `errno`; `code` names the driver error class.
+    const state = error && typeof error === "object" ? ("errno" in error ? error.errno : "code" in error ? error.code : null) : null;
+    if (["42P01", "3F000", "42703"].includes(String(state))) {
+      logger("ai:app-skills").warn("App skill schema is not available yet; next heartbeat will retry", { appId });
+      return;
+    }
+    throw error;
+  }
+};