@k2b/cloud 0.31.0 → 0.32.0

package/src/ai/protocol.ts

@@ -39,6 +39,8 @@ export type AiTurnBlock =
       name: string;
       args?: unknown;
       status: AiToolBlockStatus;
+      /** ISO time the call reached its outcome. */
+      at?: string;
       /** Localized transient host status, without tool payload data. */
       progress?: string;
       result?: unknown;
@@ -193,7 +195,7 @@ export const reconcileResolvedTurnActions = (
 };
 
 /** Decode complete provider names; hashes and ambiguous separators have no exact inverse. */
-const canonicalToolName = (name: string, presentation?: AiToolPresentation): string => {
+export const canonicalToolName = (name: string, presentation?: AiToolPresentation): string => {
   if (name.length === 64 && /__[0-9a-f]{12}$/.test(name)) return name;
   const decode = (value: string): string | undefined => {
     const tokens = /[a-zA-Z0-9-]|__|_dot_|_u([0-9a-f]+)_/gy;
@@ -241,6 +243,7 @@ export const orderedWebsiteReceipts = (
 export const buildBlocksFromMessages = (
   messages: {
     seq: number;
+    createdAt?: string;
     message: Message;
     meta?: {
       steerId?: string;
@@ -253,7 +256,7 @@ export const buildBlocksFromMessages = (
   const blocks: AiTurnBlock[] = [];
   const toolIndex = new Map<string, number>();
 
-  for (const { seq, message, meta } of messages) {
+  for (const { seq, message, meta, createdAt } of messages) {
     if (message.role === "assistant") {
       message.content.forEach((block, index) => {
         if (block.type === "text") {
@@ -298,6 +301,7 @@ export const buildBlocksFromMessages = (
           status: outcome === "rejected" ? "rejected" : message.isError ? "failed" : "completed",
           result: message.result,
           isError: message.isError,
+          ...(createdAt ? { at: createdAt } : {}),
           ...(outcome === "approved" ? { approved: true } : {}),
         };
       }

package/src/ai/provider.ts

@@ -1,9 +1,16 @@
 import type { Provider, ReasoningEffort } from "@k2b/nessi/ai";
-import { anthropic, gemini, mistral, ollama, openAICompatible, openai, openrouter } from "@k2b/nessi/ai";
+import { anthropic, completeFromStream, gemini, mistral, ollama, openAICompatible, openai, openrouter } from "@k2b/nessi/ai";
 import type { AiModelProfile } from "./types";
 
-/** Bound provider stalls while allowing long-context requests up to 60s to begin streaming. */
-const PROVIDER_TIMEOUTS = { firstByteMs: 60_000, idleMs: 60_000 } as const;
+/** Bound the first token and every gap between chunks to 60s, for chat and complete() calls. */
+export const PROVIDER_TIMEOUTS = { firstByteMs: 60_000, idleMs: 60_000 } as const;
+
+// Non-streaming calls receive headers only after the whole answer, so a first-byte timeout would cap total generation.
+// Streaming makes the timeouts bound the first token and gaps between chunks, as for chat.
+export const completeThroughStream = (provider: Provider): Provider => ({
+  ...provider,
+  complete: (request) => completeFromStream(provider, request),
+});
 
 /**
  * Reasoning for structured tasks and compaction: the requests every provider accepted before Nessi 0.17. A global
@@ -31,6 +38,10 @@ const commonOptions = (profile: AiModelProfile, apiKey?: string) => ({
 
 export const createAiProvider = (profile: AiModelProfile, apiKey?: string, headers?: Record<string, string>): Provider => {
   if (profile.capabilities.includes("transcription")) throw new Error("Transcription profiles cannot be used for chat generation.");
+  return completeThroughStream(createAdapter(profile, apiKey, headers));
+};
+
+const createAdapter = (profile: AiModelProfile, apiKey?: string, headers?: Record<string, string>): Provider => {
   switch (profile.provider) {
     case "openai":
       return openai(profile.model, commonOptions(profile, apiKey));
@@ -39,7 +50,8 @@ export const createAiProvider = (profile: AiModelProfile, apiKey?: string, heade
     case "anthropic":
       return anthropic(profile.model, commonOptions(profile, apiKey));
     case "mistral":
-      return mistral(profile.model, commonOptions(profile, apiKey));
+      // Mistral requires nine alphanumeric characters; map stored and other providers' ids at the transport boundary.
+      return mistral(profile.model, { ...commonOptions(profile, apiKey), normalizeToolCallIds: "strict9" });
     case "gemini":
       return gemini(profile.model, commonOptions(profile, apiKey));
     case "ollama":

package/src/ai/request-context.ts

@@ -0,0 +1,33 @@
+import type { Context } from "hono";
+import { userFromActor } from "../server/actor";
+import { type ApiErrorResponse, respond } from "../server/api";
+import type { AuthContext, RequestActor } from "../server/middleware/auth";
+import { err, fail } from "../server/services";
+import type { AiToolApprovalContext } from "./approvals";
+import { personalAiModelPolicy } from "./personal-agent";
+import type { AiModelPolicy } from "./types";
+
+/** Everything a resolved, authorized request needs to run against the shared runtime. */
+export 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;
+};
+
+export const resolveAiChatRequestContext = async <T extends AuthContext>(
+  c: Context<T>,
+): Promise<AiChatRequestContext | ApiErrorResponse> => {
+  const actor = c.get("actor");
+  const user = userFromActor(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",
+  };
+};

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 ?? "",