@k2b/cloud 0.31.0 → 0.33.0

package/src/ai/routes.ts

@@ -2,9 +2,9 @@ import { type Context, Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { z } from "zod";
 import { listCapabilities } from "../_internal/registry";
+import { APPROVAL_CLIENT_HEADER } from "../contracts/approvals";
 import {
   type AccessSubject,
-  type ApiErrorResponse,
   type AuthContext,
   auth,
   err,
@@ -23,13 +23,13 @@ import { ImageMetadataError } from "../services/image-metadata";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
 import { readThemeFromCookieHeader } from "../shared/theme";
-import type { AiToolApprovalContext } from "./approvals";
 import { assistantAiSettingsState, listAssistantAiModels, resolveAssistantAudioModel, selectAssistantAiModelId } from "./assistant-models";
 import { AI_AUDIO_MAX_BYTES } from "./audio-format";
 import { buildAiCapabilityCatalog } from "./capabilities";
 import { aiChatMessages } from "./chat/messages";
 import { getAiChatQuotas } from "./chat-quotas";
-import { createConfiguredDefaultCloudAiTools } from "./default-tools";
+import { AI_CLIENT_TOOL_ACTION_MAX_BYTES, aiClientToolOutputSchemas } from "./client-tool-results";
+import { createCloudAiLocalBashTool, createCloudAiLocalTools, createConfiguredDefaultCloudAiTools } from "./default-tools";
 import { enqueueAiDictation } from "./dictation-runtime";
 import { AiDictationConflict, AiDictationListSchema, AiDictationStartSchema, aiDictations } from "./dictations";
 import { aiProjectFilePathFromMount } from "./file-mount";
@@ -49,6 +49,7 @@ import {
   toAiActionFailureResponse,
   toAiErrorResponse,
 } from "./http";
+import { AI_LOCAL_TOOL_NAMES, AiLocalClientSchema } from "./local-tool-contracts";
 import { aiMaintenanceJobs } from "./maintenance";
 import { AI_MEMORY_CONTENT_MAX_CHARS, aiMemories } from "./memories";
 import { aiMemoryLearningRuns } from "./memory-learning-runs";
@@ -61,10 +62,10 @@ import {
   queuedMessageAccepted,
   updateQueuedMessage,
 } from "./message-queue";
-import { personalAiModelPolicy } from "./personal-agent";
 import { aiActorUser, aiPrefsUserId, aiUserPrefs } from "./prefs";
 import { aiProjects } from "./projects";
 import { projectPublicAiStoredMessages, publicAiStoredMessages } from "./public-projection";
+import { type AiChatRequestContext, resolveAiChatRequestContext as resolveContext } from "./request-context";
 import { aiResourceMarker } from "./resource-markers";
 import { isConversationResourceCursor } from "./resource-refs";
 import {
@@ -86,32 +87,7 @@ import { aiConversations } from "./store";
 import { createAiConversationStreamResponse, loadAiStreamState } from "./stream";
 import { composeAiSystemPrompt } from "./system-prompt";
 import { aiToolPromptHints } from "./tools";
-import type { AiConversation, AiModelPolicy, AiTurn } from "./types";
-
-/** Everything a resolved, authorized request needs to run against the shared runtime. */
-type AiChatRequestContext = {
-  actor: RequestActor;
-  ownerUserId: string;
-  modelPolicy: AiModelPolicy;
-  toolApprovalContext: AiToolApprovalContext;
-  /** A person in a signed-in browser session, not `cld`, an API key, or another delegated credential. */
-  signedInSession: boolean;
-};
-
-const actorUser = (actor: RequestActor) => (actor.kind === "user" ? actor.user : actor.delegatedUser);
-
-const resolveContext = async (c: Context<AuthContext>): Promise<AiChatRequestContext | ApiErrorResponse> => {
-  const actor = c.get("actor");
-  const user = actorUser(actor);
-  if (!user) return respond(c, fail(err.forbidden("AI conversations require a user-backed actor.")));
-  return {
-    actor,
-    ownerUserId: user.id,
-    modelPolicy: personalAiModelPolicy,
-    toolApprovalContext: { actorUserId: user.id },
-    signedInSession: actor.kind === "user" && !actor.delegation && c.get("credentialKind") === "session",
-  };
-};
+import type { AiConversation, AiTurn } from "./types";
 
 const retryInstruction = (mode: "retry" | "details" | "concise"): string | null => {
   if (mode === "details") return "Answer the user's request again with more detail and specificity.";
@@ -330,7 +306,11 @@ export const aiRoutes = (() => {
       .use(rateLimit())
       .use("*", auth.requireRole("authenticated"))
       .get("/status", async (c) => {
-        return respond(c, ok(await assistantAiSettingsState(c.get("accessSubject"))));
+        const [status, enabled] = await Promise.all([
+          assistantAiSettingsState(c.get("accessSubject")),
+          coreSettings.get<boolean>("ai.openai_api_enabled"),
+        ]);
+        return respond(c, ok({ ...status, openaiApi: { enabled } }));
       })
       .get("/quotas", async (c) => {
         c.header("Cache-Control", "no-store");
@@ -406,6 +386,21 @@ export const aiRoutes = (() => {
         const user = aiActorUser(ctx.actor);
         if (!user) return respond(c, fail(err.forbidden("AI preferences require a user context.")));
 
+        const clientKind = c.req.query("clientKind");
+        const parsedClient =
+          clientKind === undefined
+            ? undefined
+            : AiLocalClientSchema.safeParse({
+                kind: clientKind,
+                name: c.req.query("clientName"),
+                cwd: c.req.query("cwd"),
+                os: c.req.query("os"),
+                shell: c.req.query("shell"),
+                localTools: c.req.query("localTools"),
+              });
+        if (parsedClient && !parsedClient.success)
+          return respond(c, fail(err.badInput(`Invalid local client: ${parsedClient.error.issues[0]?.message}`)));
+        const client = parsedClient?.success ? parsedClient.data : undefined;
         const prefs = await aiUserPrefs.get(user.id);
         const memoryEnabled = Boolean(prefs?.memoryEnabled);
         const memory = memoryEnabled ? await aiMemories.selectHot(user.id, "") : null;
@@ -421,13 +416,18 @@ export const aiRoutes = (() => {
         }
         const toolsSupported = Boolean(previewProfile?.capabilities.includes("tools"));
         const availableSkills = toolsSupported ? (await aiSkills.list(c.get("accessSubject"))).filter((skill) => skill.enabled) : [];
-        const skillCatalog = selectAiSkillCatalog(availableSkills, previewProfile?.contextWindow ?? 0, "");
+        const skillCatalog = selectAiSkillCatalog(
+          availableSkills.filter((skill) => !skill.manualOnly).map(({ name, description }) => ({ name, description })),
+          previewProfile?.contextWindow ?? 0,
+          "",
+        );
         const tools = toolsSupported
           ? [
               ...(await createConfiguredDefaultCloudAiTools({
                 accessSubject: c.get("accessSubject"),
                 allowedDataBoundaries: ctx.modelPolicy.allowedDataBoundaries,
               })),
+              ...(client?.localTools === "ask" ? [createCloudAiLocalBashTool(), ...createCloudAiLocalTools()] : []),
               ...(memoryEnabled ? [createCloudAiMemoryTool()] : []),
               ...(availableSkills.length ? [createCloudAiLoadSkillTool(c.get("accessSubject"))] : []),
               ...(skillCatalog.omitted > 0 ? [createCloudAiSearchSkillsTool(c.get("accessSubject"))] : []),
@@ -438,6 +438,9 @@ export const aiRoutes = (() => {
         const promptLocale = getLocale(c);
         const prompt = composeAiSystemPrompt({
           globalInstructions: state.globalInstructions,
+          localClient: client
+            ? { client, cloudUrl: (await coreSettings.get<string>("app.url")) || "", instructions: state.localClientInstructions }
+            : undefined,
           user,
           memoryEnabled,
           memoryToolEnabled,
@@ -450,7 +453,7 @@ export const aiRoutes = (() => {
           memory: memory?.text,
           timeZone,
           locale: promptLocale,
-          skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator"),
+          skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator" && !skill.manualOnly),
         });
         return respond(c, ok({ prompt, renderedAt: new Date().toISOString() }));
       })
@@ -907,6 +910,8 @@ export const aiRoutes = (() => {
             modelPolicy: ctx.modelPolicy,
             project: project ?? undefined,
             clientToolIds: body.clientToolIds,
+            client: body.client,
+            localContext: body.localContext,
             toolSource: { kind: "default" as const, appTools: true },
             toolApprovalContext: ctx.toolApprovalContext,
             expectedDraftRevision: body.draftRevision,
@@ -1022,7 +1027,20 @@ export const aiRoutes = (() => {
             truncateFromSeq: target.seq,
             fileSnapshot: originalRunConfig?.kind !== "compact" ? originalRunConfig?.files : undefined,
             retrySourceTurnId: target.loopId ?? undefined,
-            clientToolIds: originalRunConfig?.kind !== "compact" ? originalRunConfig?.clientToolIds : undefined,
+            // Local context and tools belong to the retrying client, not the original workspace.
+            clientToolIds:
+              body.clientToolIds ??
+              (originalRunConfig?.kind !== "compact"
+                ? originalRunConfig?.clientToolIds?.filter((id) => id !== "local_bash" && !AI_LOCAL_TOOL_NAMES.some((name) => name === id))
+                : undefined),
+            client: body.client,
+            localContext: body.client
+              ? {
+                  instructions: body.localContext?.instructions ?? [],
+                  skills: body.localContext?.skills ?? [],
+                  selectedSkills: originalRunConfig?.kind !== "compact" ? (originalRunConfig?.localContext?.selectedSkills ?? []) : [],
+                }
+              : undefined,
           });
           rememberLastUsedModel(ctx.actor, result.turn.modelProfileId);
           return respond(
@@ -1114,29 +1132,49 @@ export const aiRoutes = (() => {
         await abortAiTurn({ conversationId: conversation.id, turnId: turn.id });
         return respond(c, ok({ ok: true }));
       })
-      .post("/conversations/:conversationId/turns/:turnId/actions/:callId", v("json", AiTurnActionSchema), async (c) => {
-        const ctx = await resolveContext(c);
-        if (ctx instanceof Response) return ctx;
-        const conversation = await loadConversation(c, ctx);
-        if (!conversation) return notFound(c);
-        const turn = await loadTurn(conversation, c.req.param("turnId"));
-        const callId = c.req.param("callId");
-        if (!turn || !callId) return notFound(c);
-        const result = await submitAiTurnAction({
-          conversationId: conversation.id,
-          turnId: turn.id,
-          callId,
-          action: c.req.valid("json"),
-          decidedBy: {
-            userId: ctx.ownerUserId,
-            via: approvalDecisionChannel({ credentialKind: c.get("credentialKind"), actor: ctx.actor }),
-          },
-          toolApprovalContext: ctx.toolApprovalContext,
-          signedInSession: ctx.signedInSession,
-        });
-        if (!result.ok) return toAiActionFailureResponse(c, result);
-        return respond(c, ok({ ok: true }));
-      })
+      .post(
+        "/conversations/:conversationId/turns/:turnId/actions/:callId",
+        bodyLimit({ maxSize: AI_CLIENT_TOOL_ACTION_MAX_BYTES }),
+        v("json", AiTurnActionSchema),
+        async (c) => {
+          const ctx = await resolveContext(c);
+          if (ctx instanceof Response) return ctx;
+          const conversation = await loadConversation(c, ctx);
+          if (!conversation) return notFound(c);
+          const turn = await loadTurn(conversation, c.req.param("turnId"));
+          const callId = c.req.param("callId");
+          if (!turn || !callId) return notFound(c);
+          const action = c.req.valid("json");
+          if (action.type === "tool_result") {
+            const pending = await aiConversations.getPendingTurnAction({ conversationId: conversation.id, turnId: turn.id, callId });
+            const schema = pending?.kind === "client_tool" ? aiClientToolOutputSchemas.get(pending.name) : undefined;
+            if (schema) {
+              const parsed = schema.safeParse(action.result);
+              if (!parsed.success)
+                return respond(c, fail(err.badInput(`Invalid ${pending?.name} result: ${parsed.error.issues[0]?.message}`)));
+              action.result = parsed.data;
+            }
+          }
+          const result = await submitAiTurnAction({
+            conversationId: conversation.id,
+            turnId: turn.id,
+            callId,
+            action,
+            decidedBy: {
+              userId: ctx.ownerUserId,
+              via: approvalDecisionChannel({
+                credentialKind: c.get("credentialKind"),
+                actor: ctx.actor,
+                client: c.req.header(APPROVAL_CLIENT_HEADER),
+              }),
+            },
+            toolApprovalContext: ctx.toolApprovalContext,
+            signedInSession: ctx.signedInSession,
+          });
+          if (!result.ok) return toAiActionFailureResponse(c, result);
+          return respond(c, ok({ ok: true }));
+        },
+      )
       .get("/conversations/:conversationId/pending-actions/:turnId", async (c) => {
         const ctx = await resolveContext(c);
         if (ctx instanceof Response) return ctx;
@@ -1353,6 +1391,7 @@ export const aiRoutes = (() => {
           "Content-Type": stored.mediaType || "application/octet-stream",
           "Content-Disposition": `attachment; filename="${filename}"`,
           "Content-Length": String(stored.size),
+          "X-Cloud-Ai-File-Origin": stored.origin,
           "Cache-Control": "private, no-store",
         });
       })

package/src/ai/runtime.ts

@@ -11,8 +11,9 @@ import { coreSettings } from "../services/settings/api";
 import { AI_WEBSITE_APPROVAL_TOOL, type AiToolApprovalContext, aiTurnAllowsRememberedApprovals, rememberAiToolApproval } from "./approvals";
 import { aiChatAccessSubject, selectAssistantAiModelId } from "./assistant-models";
 import { startAiDictationRuntime } from "./dictation-runtime";
-import { AiTurnExecutor } from "./executor";
+import { AiTurnExecutor, type ExecutorConfig } from "./executor";
 import { canonicalizeAiConversationAttachments, snapshotAiConversationFiles } from "./file-context";
+import type { AiLocalClient, AiLocalContext } from "./local-tool-contracts";
 import { drainQueuedMessages } from "./message-queue";
 import { AI_TURN_LEASE_MS } from "./protocol";
 import { aiQuotas } from "./quotas";
@@ -105,6 +106,8 @@ export type SubmitAiChatTurnInput = {
   systemPrompt?: string;
   project?: AiChatTurnRunConfig["project"];
   clientToolIds?: AiClientToolId[];
+  client?: AiLocalClient;
+  localContext?: AiLocalContext;
   toolSource?: AiTurnToolSource;
   canInspectAttachedImages?: boolean;
   toolApprovalContext?: AiToolApprovalContext;
@@ -119,6 +122,7 @@ export type SubmitAiChatTurnInput = {
 };
 
 export const prepareAiChatTurn = async (input: SubmitAiChatTurnInput) => {
+  if (input.localContext && !input.client) throw new Error("Local context requires a local client.");
   if (input.clientToolIds?.length && input.toolSource?.kind !== "default") {
     throw new Error("Optional client tools require the default tool source.");
   }
@@ -170,6 +174,8 @@ export const prepareAiChatTurn = async (input: SubmitAiChatTurnInput) => {
     files,
     canInspectAttachedImages,
     clientToolIds: input.clientToolIds,
+    client: input.client,
+    localContext: input.localContext,
     toolSource: input.toolSource ?? { kind: "none" },
     toolApprovalContext: input.toolApprovalContext,
   };
@@ -324,11 +330,11 @@ export const submitAiTurnAction = async (input: {
   turnId: string;
   callId: string;
   action: AiTurnActionInput;
-  decidedBy: { userId: string; via: ApprovalDecisionChannel };
+  decidedBy: { userId: string; via: ApprovalDecisionChannel; deviceId?: string };
   toolApprovalContext?: AiToolApprovalContext;
   /** Whether a person decides in a signed-in browser session; only such a decision may remember a website. */
   signedInSession?: boolean;
-}): Promise<{ ok: true } | { ok: false; status: 400 | 404 | 409; message: string }> => {
+}): Promise<{ ok: true } | { ok: false; status: 400 | 403 | 404 | 409; message: string }> => {
   const pending = await aiConversations.getPendingTurnAction(input);
   if (!pending) return { ok: false, status: 404, message: "This request has expired — the assistant already moved on." };
   if (pending.status === "resolved") {
@@ -365,9 +371,11 @@ export const submitAiTurnAction = async (input: {
     if (pending.approvalId) {
       const decision = await approvals.decide(pending.approvalId, { approved: input.action.approved }, input.decidedBy);
       if (!decision.ok)
-        return decision.code === "ALREADY_DECIDED"
-          ? { ok: false, status: 409, message: "AI action was already resolved with a different response." }
-          : { ok: false, status: 404, message: "This request has expired — the assistant already moved on." };
+        return decision.code === "REJECT_ONLY"
+          ? { ok: false, status: 403, message: "Approve this request in Cloud. An editor can only reject it." }
+          : decision.code === "ALREADY_DECIDED"
+            ? { ok: false, status: 409, message: "AI action was already resolved with a different response." }
+            : { ok: false, status: 404, message: "This request has expired — the assistant already moved on." };
     }
     if (remember && input.toolApprovalContext) {
       const toolName = pending.rememberToolName ?? pending.name;
@@ -425,11 +433,14 @@ export const submitAiTurnAction = async (input: {
 // Worker + sweep lifecycle
 // ---------------------------------------------------------------------------
 
+type ApprovalRequestedListener = NonNullable<ExecutorConfig["onApprovalRequested"]>;
+
 const runClaimedTurn = async (
   job: AiTurnJob,
   signal: AbortSignal,
   leaseOwner: string,
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>,
+  onApprovalRequested?: ApprovalRequestedListener,
 ): Promise<void> => {
   const timeoutMinutes = await coreSettings.get<number>("ai.turn_timeout_minutes");
   const runBudgetMs = Math.max(0, Number(timeoutMinutes ?? 30)) * 60_000;
@@ -458,6 +469,7 @@ const runClaimedTurn = async (
     heartbeatMs: AI_TURN_HEARTBEAT_MS,
     enqueueContinuation: (input) => enqueueAiTurn(input).then(() => undefined),
     onTurnFinalized,
+    onApprovalRequested,
   });
   await executor.run({ conversationId: job.conversationId, turnId: job.turnId, claim, signal });
 };
@@ -466,6 +478,7 @@ const processMessage = async (
   message: Pick<QueueMessage<AiTurnJob>, "messageId" | "data" | "heartbeat">,
   signal: AbortSignal,
   onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>,
+  onApprovalRequested?: ApprovalRequestedListener,
 ): Promise<void> => {
   const leaseOwner = `${AI_WORKER_ID}:${message.messageId}:${crypto.randomUUID()}`;
   let heartbeatFailed = false;
@@ -488,7 +501,7 @@ const processMessage = async (
   }, AI_TURN_HEARTBEAT_MS);
   if (typeof touch === "object" && "unref" in touch) touch.unref();
   try {
-    await runClaimedTurn(message.data, signal, leaseOwner, onTurnFinalized);
+    await runClaimedTurn(message.data, signal, leaseOwner, onTurnFinalized, onApprovalRequested);
   } catch (error) {
     log.error("AI turn worker error", {
       conversationId: message.data.conversationId,
@@ -550,6 +563,7 @@ export const sweepAiRuntime = async (onTurnFinalized?: (event: AiTurnFinalizedEv
 
 type AiRuntimeState = {
   listeners: Set<(event: AiTurnFinalizedEvent) => Promise<void>>;
+  approvalListeners: Set<ApprovalRequestedListener>;
   stop: () => void;
 };
 
@@ -557,19 +571,29 @@ let running: AiRuntimeState | null = null;
 let refCount = 0;
 
 export const startAiRuntime = (
-  input: { concurrency?: number; onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void> } = {},
+  input: {
+    concurrency?: number;
+    onTurnFinalized?: (event: AiTurnFinalizedEvent) => Promise<void>;
+    onApprovalRequested?: ApprovalRequestedListener;
+  } = {},
 ): (() => void) => {
   const listener = input.onTurnFinalized ? (event: AiTurnFinalizedEvent) => input.onTurnFinalized!(event) : null;
+  const approvalListener: ApprovalRequestedListener | null = input.onApprovalRequested
+    ? (event) => input.onApprovalRequested!(event)
+    : null;
   if (running) {
     refCount += 1;
     if (listener) running.listeners.add(listener);
-    return releaseAiRuntime(listener);
+    if (approvalListener) running.approvalListeners.add(approvalListener);
+    return releaseAiRuntime(listener, approvalListener);
   }
 
   const concurrency = Math.min(Math.max(Math.floor(input.concurrency ?? AI_TURN_WORKER_CONCURRENCY), 1), 64);
   const controller = new AbortController();
   const listeners = new Set<(event: AiTurnFinalizedEvent) => Promise<void>>();
   if (listener) listeners.add(listener);
+  const approvalListeners = new Set<ApprovalRequestedListener>();
+  if (approvalListener) approvalListeners.add(approvalListener);
   refCount = 1;
   const dispatchTurnFinalized = async (event: AiTurnFinalizedEvent): Promise<void> => {
     const results = await Promise.allSettled([...listeners].map((notify) => notify(event)));
@@ -577,12 +601,18 @@ export const startAiRuntime = (
     if (errors.length > 0) throw new AggregateError(errors, `${errors.length} AI turn finalized listener(s) failed`);
   };
 
+  const dispatchApprovalRequested: ApprovalRequestedListener = async (event) => {
+    const results = await Promise.allSettled([...approvalListeners].map((notify) => notify(event)));
+    const errors = results.filter((result): result is PromiseRejectedResult => result.status === "rejected").map((result) => result.reason);
+    if (errors.length) throw new AggregateError(errors, `${errors.length} AI approval requested listener(s) failed`);
+  };
+
   void superviseRuntimeTask({
     name: "AI turn worker",
     signal: controller.signal,
     run: async (signal) => {
       const worker = await aiTurnQueue().process({ concurrency, signal }, (message) =>
-        processMessage(message, message.signal, dispatchTurnFinalized),
+        processMessage(message, message.signal, dispatchTurnFinalized, dispatchApprovalRequested),
       );
       try {
         await new Promise<void>((resolve) => {
@@ -612,22 +642,27 @@ export const startAiRuntime = (
   const stopDictations = startAiDictationRuntime();
   const state: AiRuntimeState = {
     listeners,
+    approvalListeners,
     stop: () => {
       if (running !== state) return;
       controller.abort();
       stopDictations();
       clearInterval(sweepTimer);
       listeners.clear();
+      approvalListeners.clear();
       running = null;
       refCount = 0;
     },
   };
   running = state;
   log.info("AI runtime started", { workerId: AI_WORKER_ID, concurrency });
-  return releaseAiRuntime(listener);
+  return releaseAiRuntime(listener, approvalListener);
 };
 
-const releaseAiRuntime = (listener: ((event: AiTurnFinalizedEvent) => Promise<void>) | null): (() => void) => {
+const releaseAiRuntime = (
+  listener: ((event: AiTurnFinalizedEvent) => Promise<void>) | null,
+  approvalListener: ApprovalRequestedListener | null,
+): (() => void) => {
   let released = false;
   return () => {
     if (released) return;
@@ -635,6 +670,7 @@ const releaseAiRuntime = (listener: ((event: AiTurnFinalizedEvent) => Promise<vo
     const state = running;
     if (!state) return;
     if (listener) state.listeners.delete(listener);
+    if (approvalListener) state.approvalListeners.delete(approvalListener);
     refCount = Math.max(0, refCount - 1);
     if (refCount === 0) state.stop();
   };

package/src/ai/settings.ts

@@ -315,6 +315,7 @@ export const resolveAiSettingsStateFromRaw = async (input: {
   visionModelId?: string;
   profilesJson: string;
   globalInstructions?: string;
+  localClientInstructions?: string;
   compactionInstructions?: string;
   maxToolResultChars?: unknown;
   firecrawlApiKey?: string;
@@ -327,6 +328,7 @@ export const resolveAiSettingsStateFromRaw = async (input: {
     defaultModelId: input.defaultModelId ?? "",
     visionModelId: input.visionModelId ?? "",
     globalInstructions: input.globalInstructions ?? "",
+    localClientInstructions: input.localClientInstructions ?? "",
     compactionInstructions: input.compactionInstructions ?? "",
     maxToolResultChars: normalizeMaxToolResultChars(input.maxToolResultChars),
     firecrawlConfigured: Boolean(input.firecrawlApiKey?.trim()),
@@ -417,6 +419,7 @@ const readAiSettingsSnapshot = async (): Promise<{ state: AiSettingsState; crede
     visionModelId,
     profilesJson,
     globalInstructions,
+    localClientInstructions,
     compactionInstructions,
     maxToolResultChars,
     firecrawlApiKey,
@@ -426,6 +429,7 @@ const readAiSettingsSnapshot = async (): Promise<{ state: AiSettingsState; crede
     coreSettings.get<string>("ai.vision_model_id"),
     coreSettings.get<string>("ai.model_profiles_json"),
     coreSettings.get<string>("ai.global_instructions"),
+    coreSettings.get<string>("ai.local_client_instructions"),
     coreSettings.get<string>("ai.compaction_instructions"),
     coreSettings.get<number>("ai.max_tool_result_chars"),
     coreSettings.get<string>(AI_FIRECRAWL_API_KEY_SETTING_KEY),
@@ -446,6 +450,7 @@ const readAiSettingsSnapshot = async (): Promise<{ state: AiSettingsState; crede
     visionModelId: visionModelId ?? "",
     profilesJson: profilesJson ?? "[]",
     globalInstructions: globalInstructions ?? "",
+    localClientInstructions: localClientInstructions ?? "",
     compactionInstructions: compactionInstructions ?? "",
     maxToolResultChars,
     firecrawlApiKey: firecrawlApiKey ?? "",

package/src/ai/skill-catalog.ts

@@ -4,9 +4,18 @@ import type { AiSkillSummary } from "./skills";
 export const AI_SKILL_CATALOG_MAX_CHARS = 8_000;
 const AI_SKILL_CATALOG_MIN_CHARS = AI_SKILL_NAME_MAX_CHARS + AI_SKILL_DESCRIPTION_MAX_CHARS + 8;
 
-export type AiSkillCatalogEntry = Pick<AiSkillSummary, "name" | "description">;
+export type AiSkillCatalogEntry = Pick<AiSkillSummary, "name" | "description"> & { source?: "local"; manualOnly?: boolean };
 
-const catalogLine = (skill: AiSkillCatalogEntry): string => `- ${skill.name}: ${skill.description.replace(/\s+/g, " ").trim()}`;
+export const mergeAiSkillCatalog = (
+  cloud: readonly AiSkillCatalogEntry[],
+  local: readonly AiSkillCatalogEntry[],
+): AiSkillCatalogEntry[] => {
+  const localNames = new Set(local.map((skill) => skill.name));
+  return [...cloud.filter((skill) => !skill.manualOnly && !localNames.has(skill.name)), ...local.filter((skill) => !skill.manualOnly)];
+};
+
+const catalogLine = (skill: AiSkillCatalogEntry): string =>
+  `- ${skill.name}${skill.source === "local" ? " [local]" : ""}: ${skill.description.replace(/\s+/g, " ").trim()}`;
 
 const terms = (value: string): string[] => [
   ...new Set(
@@ -30,7 +39,13 @@ const relevance = (skill: AiSkillCatalogEntry, query: string): number => {
   return score;
 };
 
-const ranked = (skills: readonly AiSkillCatalogEntry[], query: string): AiSkillCatalogEntry[] =>
+export const searchAiSkillCatalog = (skills: readonly AiSkillCatalogEntry[], query: string): AiSkillCatalogEntry[] =>
+  rankAiSkillCatalog(
+    skills.filter((skill) => relevance(skill, query) > 0),
+    query,
+  );
+
+export const rankAiSkillCatalog = (skills: readonly AiSkillCatalogEntry[], query: string): AiSkillCatalogEntry[] =>
   skills
     .map((skill, index) => ({ skill, index, score: relevance(skill, query) }))
     .sort((left, right) => right.score - left.score || left.index - right.index)
@@ -46,12 +61,12 @@ export const selectAiSkillCatalog = (
     AI_SKILL_CATALOG_MAX_CHARS,
     Math.max(AI_SKILL_CATALOG_MIN_CHARS, contextWindow > 0 ? Math.floor(contextWindow * 0.02 * 4) : AI_SKILL_CATALOG_MAX_CHARS),
   );
-  const normalized = skills.map((skill) => ({ name: skill.name, description: skill.description.replace(/\s+/g, " ").trim() }));
+  const normalized = skills.map((skill) => ({ ...skill, description: skill.description.replace(/\s+/g, " ").trim() }));
   if (normalized.map(catalogLine).join("\n").length <= budget) return { skills: normalized, omitted: 0 };
 
   const selected: AiSkillCatalogEntry[] = [];
   let used = 0;
-  for (const skill of ranked(normalized, query)) {
+  for (const skill of rankAiSkillCatalog(normalized, query)) {
     const size = catalogLine(skill).length + (selected.length ? 1 : 0);
     if (used + size > budget) continue;
     selected.push(skill);

package/src/ai/skill-format.ts

@@ -1,4 +1,5 @@
 import { parseDocument, stringify } from "yaml";
+import { AI_SKILL_FILE_MOUNT } from "./file-mount";
 
 export const AI_SKILL_NAME_MAX_CHARS = 64;
 export const AI_SKILL_DESCRIPTION_MAX_CHARS = 1024;
@@ -26,7 +27,11 @@ export type AiSkillDocument = {
   extraFrontmatter: AiSkillExtraFrontmatter;
 };
 
-const OPTIONAL_FRONTMATTER_FIELDS = new Set(["license", "compatibility", "metadata", "allowed-tools"]);
+export const isAiSkillManualOnly = (extraFrontmatter: AiSkillExtraFrontmatter): boolean =>
+  extraFrontmatter["disable-model-invocation"] === true;
+
+export const mountAiSkillInstructionLinks = (name: string, instructions: string): string =>
+  instructions.replace(/\]\((references\/[a-z0-9][a-z0-9._-]*\.md)\)/g, (_, path: string) => `](${AI_SKILL_FILE_MOUNT}/${name}/${path})`);
 
 const assertJsonValue = (value: unknown, path: string): void => {
   if (value === null || typeof value === "string" || typeof value === "boolean") return;
@@ -35,7 +40,7 @@ const assertJsonValue = (value: unknown, path: string): void => {
     value.forEach((item, index) => assertJsonValue(item, `${path}[${index}]`));
     return;
   }
-  if (typeof value === "object") {
+  if (typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
     for (const [key, child] of Object.entries(value)) assertJsonValue(child, `${path}.${key}`);
     return;
   }
@@ -73,8 +78,8 @@ export const validateAiSkillInstructions = (value: string): string => {
 
 export const validateAiSkillExtraFrontmatter = (value: AiSkillExtraFrontmatter = {}): AiSkillExtraFrontmatter => {
   for (const key of Object.keys(value)) {
-    if (!OPTIONAL_FRONTMATTER_FIELDS.has(key)) {
-      throw new Error(`Unsupported SKILL.md frontmatter field "${key}".`);
+    if (key === "name" || key === "description") {
+      throw new Error(`SKILL.md frontmatter field "${key}" must not appear in extraFrontmatter; it would collide on export.`);
     }
   }
   assertJsonValue(value, "Skill frontmatter");
@@ -109,7 +114,8 @@ export const validateAiSkillReferences = (references: readonly AiSkillReferenceI
   });
 };
 
-export const parseAiSkillMarkdown = (source: string): AiSkillDocument => {
+/** Split SKILL.md into its frontmatter fields and body without validating either; local clients apply their own rules. */
+export const splitAiSkillMarkdown = (source: string): { fields: Record<string, unknown>; body: string } => {
   const normalized = source.replace(/\r\n/g, "\n");
   if (!normalized.startsWith("---\n")) throw new Error("SKILL.md must start with YAML frontmatter.");
   const end = normalized.indexOf("\n---\n", 4);
@@ -120,7 +126,11 @@ export const parseAiSkillMarkdown = (source: string): AiSkillDocument => {
   if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
     throw new Error("SKILL.md frontmatter must be a YAML object.");
   }
-  const fields = { ...(frontmatter as Record<string, unknown>) };
+  return { fields: { ...(frontmatter as Record<string, unknown>) }, body: normalized.slice(end + 5) };
+};
+
+export const parseAiSkillMarkdown = (source: string): AiSkillDocument => {
+  const { fields, body } = splitAiSkillMarkdown(source);
   if (typeof fields.name !== "string") throw new Error("SKILL.md frontmatter requires a string name.");
   if (typeof fields.description !== "string") throw new Error("SKILL.md frontmatter requires a string description.");
   const name = validateAiSkillName(fields.name);
@@ -130,7 +140,7 @@ export const parseAiSkillMarkdown = (source: string): AiSkillDocument => {
   return {
     name,
     description,
-    instructions: validateAiSkillInstructions(normalized.slice(end + 5)),
+    instructions: validateAiSkillInstructions(body),
     extraFrontmatter: validateAiSkillExtraFrontmatter(fields),
   };
 };