@k2b/cloud 0.30.0 → 0.32.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,
@@ -18,17 +18,18 @@ import {
   v,
 } from "../server";
 import { isRequestCredentialCurrent } from "../server/middleware/auth";
+import { approvalDecisionChannel } from "../services/approvals";
 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";
@@ -48,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";
@@ -60,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 {
@@ -85,29 +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;
-};
-
-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 },
-  };
-};
+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.";
@@ -326,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");
@@ -402,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;
@@ -417,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"))] : []),
@@ -434,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,
@@ -446,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() }));
       })
@@ -890,6 +897,7 @@ export const aiRoutes = (() => {
         try {
           const submission = {
             assistantChat: true as const,
+            ...(ctx.signedInSession ? { signedInSession: true as const } : {}),
             conversationId: conversation.id,
             chatId: conversation.shortId,
             input,
@@ -902,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,
@@ -999,6 +1009,7 @@ export const aiRoutes = (() => {
           }
           const result = await submitAiChatTurn({
             assistantChat: true,
+            ...(ctx.signedInSession ? { signedInSession: true as const } : {}),
             conversationId: conversation.id,
             chatId: conversation.shortId,
             input,
@@ -1016,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(
@@ -1108,24 +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"),
-          toolApprovalContext: ctx.toolApprovalContext,
-        });
-        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;
@@ -1342,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

@@ -4,14 +4,16 @@ import type { QueueMessage } from "@k2b/sync";
 import { z } from "zod";
 import { lazySync } from "../_internal/process-sync";
 import type { RequestActor } from "../server";
+import { type ApprovalDecisionChannel, approvals } from "../services/approvals";
 import { logger } from "../services/logging";
 import { superviseRuntimeTask } from "../services/runtime-lifecycle";
 import { coreSettings } from "../services/settings/api";
-import { type AiToolApprovalContext, aiTurnAllowsRememberedApprovals, rememberAiToolApproval } from "./approvals";
+import { 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";
@@ -87,6 +89,8 @@ export const enqueueExistingAiTurn = (input: AiTurnJob): Promise<unknown> => enq
 export type SubmitAiChatTurnInput = {
   /** Only interactive Assistant HTTP handlers set this server-owned marker. */
   assistantChat?: true;
+  /** Only a handler that saw a signed-in browser session sets this server-owned marker; see `AiChatTurnRunConfig`. */
+  signedInSession?: true;
   conversationId: string;
   /** Stable public ID exposed as runtime context, not instructions. */
   chatId?: string;
@@ -102,6 +106,8 @@ export type SubmitAiChatTurnInput = {
   systemPrompt?: string;
   project?: AiChatTurnRunConfig["project"];
   clientToolIds?: AiClientToolId[];
+  client?: AiLocalClient;
+  localContext?: AiLocalContext;
   toolSource?: AiTurnToolSource;
   canInspectAttachedImages?: boolean;
   toolApprovalContext?: AiToolApprovalContext;
@@ -116,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.");
   }
@@ -153,6 +160,7 @@ export const prepareAiChatTurn = async (input: SubmitAiChatTurnInput) => {
       ),
     ],
     ...(input.assistantChat ? { assistantChat: true } : {}),
+    ...(input.signedInSession ? { signedInSession: true } : {}),
     input: canonicalInput,
     chatId: input.chatId,
     actor: input.actor,
@@ -166,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,
   };
@@ -297,7 +307,7 @@ export const abortAiTurn = async (input: { conversationId: string; turnId: strin
 // ---------------------------------------------------------------------------
 
 export const AiTurnActionSchema = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("approval_response"), approved: z.boolean(), remember: z.literal("always").optional() }),
+  z.object({ type: z.literal("approval_response"), approved: z.boolean(), remember: z.enum(["chat", "always"]).optional() }),
   z.object({ type: z.literal("tool_result"), result: z.unknown() }),
 ]);
 export type AiTurnActionInput = z.infer<typeof AiTurnActionSchema>;
@@ -312,7 +322,7 @@ export const listPendingAiTurnActions = async (input: { conversationId: string;
   const [actions, config] = await Promise.all([aiConversations.listPendingTurnActions(input), aiConversations.getTurnRunConfig(input)]);
   return aiTurnAllowsRememberedApprovals(config)
     ? actions
-    : actions.map((action) => (action.type === "approval_request" ? { ...action, allowAlways: false } : action));
+    : actions.map((action) => (action.type === "approval_request" ? { ...action, allowAlways: false, allowChat: false } : action));
 };
 
 export const submitAiTurnAction = async (input: {
@@ -320,8 +330,11 @@ export const submitAiTurnAction = async (input: {
   turnId: string;
   callId: string;
   action: AiTurnActionInput;
+  decidedBy: { userId: string; via: ApprovalDecisionChannel; deviceId?: string };
   toolApprovalContext?: AiToolApprovalContext;
-}): Promise<{ ok: true } | { ok: false; status: 400 | 404 | 409; message: string }> => {
+  /** 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 | 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") {
@@ -338,18 +351,52 @@ export const submitAiTurnAction = async (input: {
 
   if (input.action.type === "approval_response") {
     if (pending.kind === "client_tool") return { ok: false, status: 400, message: "Frontend tool requests require a tool result." };
-    if (input.action.remember === "always") {
+    const remember = input.action.remember;
+    if (remember) {
       const config = await aiConversations.getTurnRunConfig(input);
-      if (!input.action.approved || !pending.allowAlways || !input.toolApprovalContext || !aiTurnAllowsRememberedApprovals(config)) {
+      const toolName = pending.rememberToolName ?? pending.name;
+      const allowed = remember === "always" ? pending.allowAlways : (pending.allowChat ?? pending.allowAlways);
+      if (
+        !input.action.approved ||
+        !allowed ||
+        !input.toolApprovalContext ||
+        !aiTurnAllowsRememberedApprovals(config) ||
+        // A website is remembered only by a person in a signed-in session: `cld`, an API key, or another delegated
+        // credential can approve this one request, but cannot let the next ones through.
+        (toolName === AI_WEBSITE_APPROVAL_TOOL && (remember !== "chat" || !input.signedInSession))
+      ) {
         return { ok: false, status: 400, message: "This approval cannot be remembered." };
       }
-      await rememberAiToolApproval(input.toolApprovalContext, { toolName: pending.name, approvalScope: pending.approvalScope });
+    }
+    if (pending.approvalId) {
+      const decision = await approvals.decide(pending.approvalId, { approved: input.action.approved }, input.decidedBy);
+      if (!decision.ok)
+        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;
+      await rememberAiToolApproval(input.toolApprovalContext, {
+        toolName,
+        approvalScope: pending.approvalScope,
+        conversationId: remember === "chat" ? input.conversationId : null,
+      });
     }
     await aiToolAudit
       .noteApprovalResolved({
         turnId: input.turnId,
         callId: input.callId,
-        approvalState: input.action.approved ? (input.action.remember === "always" ? "approved_always" : "approved_once") : "rejected",
+        decidedVia: input.decidedBy.via,
+        approvalState: input.action.approved
+          ? remember === "always"
+            ? "approved_always"
+            : remember === "chat"
+              ? "approved_for_chat"
+              : "approved_once"
+          : "rejected",
       })
       .catch(() => undefined);
 
@@ -386,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;
@@ -419,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 });
 };
@@ -427,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;
@@ -449,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,
@@ -511,6 +563,7 @@ export const sweepAiRuntime = async (onTurnFinalized?: (event: AiTurnFinalizedEv
 
 type AiRuntimeState = {
   listeners: Set<(event: AiTurnFinalizedEvent) => Promise<void>>;
+  approvalListeners: Set<ApprovalRequestedListener>;
   stop: () => void;
 };
 
@@ -518,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)));
@@ -538,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) => {
@@ -573,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;
@@ -596,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);