@k2b/cloud 0.7.0 → 0.8.0

package/src/ai/code-source-contracts.ts

@@ -1,7 +1,7 @@
-import { AiFileLocation, AiFileReference } from "./file-reference-contracts";
 import { z } from "zod";
-import { CodeResourceId } from "./browser-code-contracts";
 import { PrincipalSchema } from "../contracts/shared";
+import { CodeResourceId } from "./browser-code-contracts";
+import { AiFileLocation, AiFileReference } from "./file-reference-contracts";
 
 // Flat Assistant tool inputs. The owning service also validates its domain contracts.
 const Id = z.object({ id: CodeResourceId }).strict();
@@ -42,76 +42,142 @@ const DatabaseSql = z.object({
 const CodeWriteInput = Id.extend({
   expectedRevision: z.number().int().positive(),
   entry: ArtifactPath.optional(),
-  files: z.array(z.union([ArtifactFile, z.object({ path: ArtifactPath, fromFile: AiFileReference }).strict()])).min(1).max(64),
+  files: z
+    .array(z.union([ArtifactFile, z.object({ path: ArtifactPath, fromFile: AiFileReference }).strict()]))
+    .min(1)
+    .max(64),
 });
 
 export const CODE_SOURCE_TOOLS = {
   code_files: {
-    description: "List authorized files in one explicit chat, Project or App shared store. Returns locations, metadata and nextAfter. Use code_file_stat to obtain the opaque version before copying; does not load bytes into model context.",
-    input: AiFileLocation.omit({ path: true }).extend({ after: z.string().max(500).default(""), limit: z.number().int().min(1).max(1000).default(100) }),
+    description:
+      "List authorized files in one explicit chat, Project or App shared store. Returns locations, metadata and nextAfter. Use code_file_stat to obtain the opaque version before copying; does not load bytes into model context.",
+    input: AiFileLocation.omit({ path: true }).extend({
+      after: z.string().max(500).default(""),
+      limit: z.number().int().min(1).max(1000).default(100),
+    }),
   },
   code_file_stat: {
-    description: "Inspect one authorized file location. Returns exists plus its exact versioned reference, size and mediaType, never its bytes. App files require Use, Project files Read, chats ownership.",
+    description:
+      "Inspect one authorized file location. Returns exists plus its exact versioned reference, size and mediaType, never its bytes. App files require Use, Project files Read, chats ownership.",
     input: z.object({ file: AiFileLocation }).strict(),
   },
   code_file_copy: {
-    description: "Copy one exact file version between chat, Project and App shared stores with fresh review. Source bytes never enter tool output. App destination requires Use, Project destination Write, chat destination ownership. Set expectedVersion null only for a new destination; otherwise use its version from code_file_stat. Source/version, target rights, overwrite and byte limits are rechecked. This grants no access to other files.",
+    description:
+      "Copy one exact file version between chat, Project and App shared stores with fresh review. Source bytes never enter tool output. App destination requires Use, Project destination Write, chat destination ownership. Set expectedVersion null only for a new destination; otherwise use its version from code_file_stat. Source/version, target rights, overwrite and byte limits are rechecked. This grants no access to other files.",
     review: true,
-    input: z.object({ source: AiFileReference, destination: AiFileLocation, expectedVersion: z.string().min(1).max(128).nullable() }).strict(),
+    input: z
+      .object({ source: AiFileReference, destination: AiFileLocation, expectedVersion: z.string().min(1).max(128).nullable() })
+      .strict(),
   },
   code_database_export: {
-    description: "Export an App database backup into the current chat as a file. Manage required. Returns the actual path/version; no backup bytes enter tool output. Never overwrites an existing file. The chat file-size/storage limits apply. This is a Studio backup operation, not access to vendor APIs.",
-    input: Id.extend({ path: z.string().startsWith("/").max(240).default("/database.sqlite").describe("New chat filename; an existing path is rejected. Choose another name after a conflict.") }),
+    description:
+      "Export an App database backup into the current chat as a file. Manage required. Returns the actual path/version; no backup bytes enter tool output. Never overwrites an existing file. The chat file-size/storage limits apply. This is a Studio backup operation, not access to vendor APIs.",
+    input: Id.extend({
+      path: z
+        .string()
+        .startsWith("/")
+        .max(240)
+        .default("/database.sqlite")
+        .describe("New chat filename; an existing path is rejected. Choose another name after a conflict."),
+    }),
   },
   code_manage_read: {
-    description: "Read an App management snapshot before deletion: title, source revision, publication, file/JSON counts, database connection and managementRevision. Manage required. Does not expose another user's credentials or database server internals.", input: Id,
+    description:
+      "Read an App management snapshot before deletion: title, source revision, publication, file/JSON counts, database connection and managementRevision. Manage required. Does not expose another user's credentials or database server internals.",
+    input: Id,
   },
   code_delete: {
-    description: "Permanently delete an App, all source history, publications, grants and server data with fresh review. Read code_manage_read first. Database physical cleanup is queued, not claimed finished. Cannot delete an App that changed since review.", review: true,
+    description:
+      "Permanently delete an App, all source history, publications, grants and server data with fresh review. Read code_manage_read first. Database physical cleanup is queued, not claimed finished. Cannot delete an App that changed since review.",
+    review: true,
     input: Id.extend({ expectedManagementRevision: z.string().regex(/^[a-f0-9]{64}$/) }),
   },
   code_database_read: {
-    description: "Read App database connection status, generation, dataRevision and aggregate overview. Manage required; does not create a database. These are Studio contracts, not access to the backing service API.",
+    description:
+      "Read App database connection status, generation, dataRevision and aggregate overview. Manage required; does not create a database. These are Studio contracts, not access to the backing service API.",
     input: Id,
   },
   code_database_clear: {
-    description: "Permanently clear all table rows with fresh review while preserving schema, source, files and JSON storage. Manage required. Read code_database_read first. Returns completed and clearedTables; partial failure is explicit and cannot be blindly retried.",
+    description:
+      "Permanently clear all table rows with fresh review while preserving schema, source, files and JSON storage. Manage required. Read code_database_read first. Returns completed and clearedTables; partial failure is explicit and cannot be blindly retried.",
     review: true,
     input: Id.extend({ expectedGeneration: z.string().regex(/^[a-f0-9]{64}$/), expectedDataRevision: z.uuid() }),
   },
   code_database_reset: {
-    description: "Disconnect and permanently discard an App database, including schema, with fresh review. Preserves source, publications and files/JSON storage. Next explicit connection creates an empty database; physical deletion is queued. Read code_database_read first. Never use as a routine query fix.",
+    description:
+      "Disconnect and permanently discard an App database, including schema, with fresh review. Preserves source, publications and files/JSON storage. Next explicit connection creates an empty database; physical deletion is queued. Read code_database_read first. Never use as a routine query fix.",
     review: true,
-    input: Id.extend({ expectedGeneration: z.string().regex(/^[a-f0-9]{64}$/).nullable(), expectedDataRevision: z.uuid().nullable() }),
+    input: Id.extend({
+      expectedGeneration: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .nullable(),
+      expectedDataRevision: z.uuid().nullable(),
+    }),
   },
   code_storage_list: {
-    description: "Inspect an App's shared files or JSON keys for administration. Manage required. Returns storageRevision, counts and a page of key/bytes/mediaType/version metadata; no file contents. Follow nextAfter.",
-    input: Id.extend({ area: z.enum(["files", "kv"]), after: z.string().max(240).default(""), limit: z.number().int().min(1).max(1000).default(100) }),
+    description:
+      "Inspect an App's shared files or JSON keys for administration. Manage required. Returns storageRevision, counts and a page of key/bytes/mediaType/version metadata; no file contents. Follow nextAfter.",
+    input: Id.extend({
+      area: z.enum(["files", "kv"]),
+      after: z.string().max(240).default(""),
+      limit: z.number().int().min(1).max(1000).default(100),
+    }),
   },
   code_storage_delete: {
-    description: "Delete one shared file/JSON key, or clear an explicit storage area, with fresh user review. Manage required. Source, publications and database are preserved. Read code_storage_list first.",
+    description:
+      "Delete one shared file/JSON key, or clear an explicit storage area, with fresh user review. Manage required. Source, publications and database are preserved. Read code_storage_list first.",
     review: true,
-    input: Id.extend({ area: z.enum(["files", "kv", "all"]), key: z.string().min(1).max(240).optional().describe("Delete this exact key; omit to clear the entire area. Not valid with area all."), expectedStorageRevision: z.number().int().positive().describe("storageRevision from code_storage_list; concurrent writes invalidate the review.") }).refine(input => input.area !== "all" || input.key === undefined, "all clears both areas and cannot select a key"),
+    input: Id.extend({
+      area: z.enum(["files", "kv", "all"]),
+      key: z.string().min(1).max(240).optional().describe("Delete this exact key; omit to clear the entire area. Not valid with area all."),
+      expectedStorageRevision: z
+        .number()
+        .int()
+        .positive()
+        .describe("storageRevision from code_storage_list; concurrent writes invalidate the review."),
+    }).refine((input) => input.area !== "all" || input.key === undefined, "all clears both areas and cannot select a key"),
   },
   code_access_read: {
-    description: "Read an App's current grants and accessRevision before changing access. Manage required. App Use is read; Manage is admin. Skill access is separate.",
+    description:
+      "Read an App's current grants and accessRevision before changing access. Manage required. App Use is read; Manage is admin. Skill access is separate.",
     input: Id,
   },
   code_access_change: {
-    description: "Grant, change or revoke one App permission with fresh user review. Read code_access_read first. Sharing a referenced Skill is a separate operation.",
+    description:
+      "Grant, change or revoke one App permission with fresh user review. Read code_access_read first. Sharing a referenced Skill is a separate operation.",
     review: true,
     input: Id.extend({
-      expectedAccessRevision: z.string().regex(/^[a-f0-9]{64}$/).describe("Exact accessRevision returned by code_access_read."),
-      principal: PrincipalSchema.refine(principal => principal.type !== "service_account", "Studio Apps support user, group, authenticated or public grants.").optional().describe("New user or group from core.entities.search, authenticated, or public (read/run only, no server data). Service accounts are unsupported. Supply principal OR accessId."),
+      expectedAccessRevision: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .describe("Exact accessRevision returned by code_access_read."),
+      principal: PrincipalSchema.refine(
+        (principal) => principal.type !== "service_account",
+        "Studio Apps support user, group, authenticated or public grants.",
+      )
+        .optional()
+        .describe(
+          "New user or group from core.entities.search, authenticated, or public (read/run only, no server data). Service accounts are unsupported. Supply principal OR accessId.",
+        ),
       accessId: z.uuid().optional().describe("Existing grant ID from code_access_read; supply accessId OR principal."),
       permission: z.enum(["read", "admin"]).nullable().describe("read means Use, admin means Manage; null removes an existing accessId."),
-    }).refine(input => Number(input.principal !== undefined) + Number(input.accessId !== undefined) === 1
-      && (input.principal === undefined || input.permission !== null), "Supply principal with permission OR accessId with permission (null removes)")
-      .refine(input => input.principal?.type !== "public" || input.permission === "read", "Public Apps only support read/run access"),
+    })
+      .refine(
+        (input) =>
+          Number(input.principal !== undefined) + Number(input.accessId !== undefined) === 1 &&
+          (input.principal === undefined || input.permission !== null),
+        "Supply principal with permission OR accessId with permission (null removes)",
+      )
+      .refine((input) => input.principal?.type !== "public" || input.permission === "read", "Public Apps only support read/run access"),
   },
   code_actions: {
-    description: "Discover a visible App's currently published actions and their complete input/output JSON Schemas without running code. Returns publishedVersion for code_action. Requires Use; no draft source or management tools are loaded.",
-    input: Id.extend({ draft: z.boolean().default(false).describe("Inspect current draft actions instead of the publication; Manage required.") }),
+    description:
+      "Discover a visible App's currently published actions and their complete input/output JSON Schemas without running code. Returns publishedVersion for code_action. Requires Use; no draft source or management tools are loaded.",
+    input: Id.extend({
+      draft: z.boolean().default(false).describe("Inspect current draft actions instead of the publication; Manage required."),
+    }),
   },
   code_sql: {
     description:
@@ -163,7 +229,8 @@ export const CODE_SOURCE_TOOLS = {
     }),
   },
   code_unpublish: {
-    description: "Withdraw the current App publication with fresh review. Use code_manage_read first. Preserves source, publication history and data; ordinary Use-level callers can no longer start this App or its actions.",
+    description:
+      "Withdraw the current App publication with fresh review. Use code_manage_read first. Preserves source, publication history and data; ordinary Use-level callers can no longer start this App or its actions.",
     review: true,
     input: Id.extend({ expectedPublishedVersion: z.number().int().positive() }),
   },
@@ -189,8 +256,9 @@ export const CODE_SOURCE_TOOLS = {
     input: ArtifactCreate.pick({ title: true, description: true, icon: true }),
   },
   code_write: {
-    description: "Atomically save complete source files against expectedRevision from code_read/create. Other files stay unchanged. Returns revision and compiler diagnostics; never runs. fromFile imports one exact chat/Project/App file reference as UTF-8 source without printing bytes. File imports receive fresh review because source may be shared or published. Use code_file_stat first; source file and bundle byte limits apply.",
-    review: (input: unknown) => CodeWriteInput.parse(input).files.some(file => "fromFile" in file),
+    description:
+      "Atomically save complete source files against expectedRevision from code_read/create. Other files stay unchanged. Returns revision and compiler diagnostics; never runs. fromFile imports one exact chat/Project/App file reference as UTF-8 source without printing bytes. File imports receive fresh review because source may be shared or published. Use code_file_stat first; source file and bundle byte limits apply.",
+    review: (input: unknown) => CodeWriteInput.parse(input).files.some((file) => "fromFile" in file),
     input: CodeWriteInput,
   },
   code_remove: {

package/src/ai/code-source-tools.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { getApp } from "../_internal/registry";
 import {
   capabilityIdempotencyKeyHash,
   capabilityRequestHash,
@@ -6,17 +8,29 @@ import {
   completeCapabilityClaim,
   markCapabilityClaimUncertain,
 } from "../capabilities/claims";
-import { getApp } from "../_internal/registry";
-import { readBoundedJson } from "../_internal/bounded-json";
-import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { signInvocationToken } from "../services/identity/invocation-token";
+import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { LOCALE_HEADER } from "../shared/locale";
-import { CODE_SOURCE_TOOLS, type CodeSourceToolName } from "./code-source-contracts";
 import { resolveAiCapabilityActor } from "./capability-execution";
+import { aiChatTasks } from "./chat-tasks";
+import { authorizeCodeExecution } from "./code-execution";
+import { CODE_SOURCE_TOOLS, type CodeSourceToolName } from "./code-source-contracts";
 import { aiConversations } from "./store";
 import { defineAiTool } from "./tools";
 
-const WRITE_TOOLS = new Set(["code_create", "code_write", "code_remove", "code_update", "code_fork", "code_publish", "code_restore", "code_database_export", ...Object.entries(CODE_SOURCE_TOOLS).filter(([, definition]) => "review" in definition && definition.review).map(([name]) => name)]);
+const WRITE_TOOLS = new Set([
+  "code_create",
+  "code_write",
+  "code_remove",
+  "code_update",
+  "code_fork",
+  "code_publish",
+  "code_restore",
+  "code_database_export",
+  ...Object.entries(CODE_SOURCE_TOOLS)
+    .filter(([, definition]) => "review" in definition && definition.review)
+    .map(([name]) => name),
+]);
 
 const Reply = z.discriminatedUnion("ok", [
   z.object({ ok: z.literal(true), data: z.unknown() }),
@@ -41,10 +55,38 @@ export function createCodeSourceTool(name: CodeSourceToolName) {
       persistedActor: context.actor,
       store: aiConversations,
     });
+    const databaseOperations: Partial<Record<CodeSourceToolName, string>> = {
+      code_sql: "query",
+      code_database_read: "status",
+      code_database_export: "export",
+      code_database_clear: "clear",
+      code_database_reset: "reset",
+    };
+    const databaseOperation = databaseOperations[name];
+    let authorizeDatabase: (() => Promise<void>) | undefined;
+    if (context.turnId && databaseOperation) {
+      const config = await aiConversations.getTurnRunConfig({ conversationId: context.conversationId, turnId: context.turnId });
+      if (config?.kind !== "compact" && config?.background) {
+        const { id } = z.object({ id: z.string() }).parse(input);
+        const conversationId = context.conversationId,
+          turnId = context.turnId;
+        authorizeDatabase = async () => {
+          const { config } = await authorizeCodeExecution(conversationId, turnId, actor.user.id);
+          if (!config.mandate) throw new Error("Background database access requires task grants");
+          await aiChatTasks.authorizeRuntime({
+            mandate: config.mandate,
+            kind: "database",
+            input: { resourceId: id, operation: databaseOperation },
+          });
+        };
+      }
+    }
+    await authorizeDatabase?.();
     const app = await getApp("assistant");
     if (!app) throw new Error("Assistant is unavailable.");
     const signal = context.signal;
     const send = async (review = false) => {
+      await authorizeDatabase?.();
       const signed = await withActiveIdentitySigner(
         "invocation",
         (signer) =>
@@ -85,7 +127,8 @@ export function createCodeSourceTool(name: CodeSourceToolName) {
     };
     if ("review" in definition && (typeof definition.review === "function" ? definition.review(input) : definition.review)) {
       const preview = z.object({ data: z.object({ message: z.string().min(1) }) }).parse((await send(true)).data).data;
-      if (!await context.requestApproval(preview.message)) throw new Error("The user declined this change. No mutation was sent.");
+      if (!authorizeDatabase && !(await context.requestApproval(preview.message)))
+        throw new Error("The user declined this change. No mutation was sent.");
     }
     // Reuse the platform replay guard; these tools are not registered capabilities.
     const claim = WRITE_TOOLS.has(name)

package/src/ai/compaction.ts

@@ -91,7 +91,7 @@ const findLoopSplitIndex = (entries: StoreEntry[], keepLoops: number): number =>
 
 /** Preserve recent complete rounds, retaining one when the first loop has only two. */
 const findRoundSplitIndex = (entries: StoreEntry[]): number => {
-  const rounds = entries.flatMap((entry, index) => entry.message.role === "assistant" && entry.kind === "message" ? [index] : []);
+  const rounds = entries.flatMap((entry, index) => (entry.message.role === "assistant" && entry.kind === "message" ? [index] : []));
   if (!rounds.length) return -1;
   const candidate = rounds.length === 1 ? entries.length : rounds[rounds.length - (rounds.length > 2 ? 2 : 1)]!;
   const pending = new Set<string>();
@@ -132,8 +132,8 @@ export const createCloudCompactFn = (input: {
   return (ctx) => {
     const window = ctx.provider.contextWindow;
     const reserve = input.maxOutputTokens ?? 0;
-    const fillRatio = typeof ctx.fillRatio === "number" && window && window > reserve
-      ? ctx.fillRatio * window / (window - reserve) : ctx.fillRatio;
+    const fillRatio =
+      typeof ctx.fillRatio === "number" && window && window > reserve ? (ctx.fillRatio * window) / (window - reserve) : ctx.fillRatio;
     if (!ctx.force && (typeof fillRatio !== "number" || fillRatio < COMPACTION_FILL_RATIO)) return null;
 
     const totalLoops = countConversationLoops(ctx.entries);

package/src/ai/default-tools.ts

@@ -1,9 +1,20 @@
-import { createAiTodoTool } from "./todo-tool";
+import { z } from "zod";
+import { createCloudAiTranscribeAudioTool } from "./audio-tool";
+import {
+  CODE_RUNTIME_TOOL_NAMES,
+  CodeActionInput,
+  CodeExportInput,
+  CodeInspectInput,
+  CodeInteractInput,
+  CodeOpenInput,
+  CodePresentInput,
+  CodeRunInput,
+  CodeSecretInput,
+  CodeStopInput,
+} from "./browser-code-contracts";
 import { runManagedCodeTool } from "./code-runtime-tools";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTools } from "./code-source-tools";
-import { CODE_RUNTIME_TOOL_NAMES, CodeActionInput, CodeRunInput, CodeInspectInput, CodeInteractInput, CodeStopInput, CodeOpenInput, CodeExportInput, CodePresentInput, CodeSecretInput } from "./browser-code-contracts";
-import { z } from "zod";
 import {
   CloudAiCardInputSchema,
   CloudAiCardOutputSchema,
@@ -14,6 +25,7 @@ import {
   CloudAiTextEditorInputSchema,
   CloudAiTextEditorOutputSchema,
 } from "./default-tool-contracts";
+import { createCloudAiFetchFileTool } from "./fetch-file-tool";
 import {
   createCloudAiCalculateTool,
   createCloudAiListFilesTool,
@@ -21,12 +33,11 @@ import {
   createCloudAiReadFileTool,
   createCloudAiWriteFileTool,
 } from "./file-tools";
-import { createCloudAiFetchFileTool } from "./fetch-file-tool";
 import { createCloudAiWebExtractTool, createCloudAiWebSearchTool, isCloudAiFirecrawlConfigured } from "./firecrawl-tools";
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
+import { createAiTodoTool } from "./todo-tool";
 import { defineAiTool } from "./tools";
 import type { AiDataBoundary, AiRuntimeTool } from "./types";
-import { createCloudAiTranscribeAudioTool } from "./audio-tool";
 import { createCloudAiViewImageTool } from "./vision-tool";
 
 export {
@@ -95,15 +106,77 @@ export const createCloudAiLocalBashTool = () =>
   }).client();
 
 export const createCloudAiCodeTools = () => [
-  defineAiTool({name:"code_secret",description:"Open a trusted Secret input dialog. The user enters the value directly into encrypted Assistant storage; only configured/name returns. Never ask for a credential in chat, survey, app controls or code_interact. Personal secrets are scoped to this chat or resource and bound to the exact HTTPS origin, header and prefix. Use secret(name,{prefix}) in http.fetch headers; load assistant-code-mode for HTTP details. Web UI required for secret entry; stored secrets also work from CLI.",inputSchema:CodeSecretInput,outputSchema:z.object({configured:z.boolean(),name:z.string()}),approval:"never"}).client(),
-  defineAiTool({ name: "code_action", description: "Call one published Studio App action using its exact discovered name, publication and input schema. Discover with code_actions first. Use permission is sufficient; draft and management access are not granted. Runtime effects and approvals are real. Never repeat an uncertain mutation blindly.", inputSchema: CodeActionInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_action")),
-  defineAiTool({ name: "code_run", promptHint: "For file analysis, data transformations or combining Cloud data, run a short one-off script with code_run. Load assistant-code-mode for its runtime APIs; no saved app is required.", description: "Run a saved resource id OR one-off code in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts accept current chat inputPaths; app test runs use them only as explicit picker fixtures. Returns output, logs and UI state for agent inspection only; use code_present to show a one-off visualization to the user. Local test storage is temporary; shared data, database writes and capability effects are real and keep normal permissions and approvals.", inputSchema: CodeRunInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_run")),
-  defineAiTool({ name: "code_inspect", description: "Inspect a test run: errors, logs, output, controls and pending modal. Use nodeId to inspect table rows or list items; follow pagination only as needed.", inputSchema: CodeInspectInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_inspect")),
-  defineAiTool({ name: "code_interact", description: "Operate a control or answer a pending modal using its exact snapshot ID. Buttons need only id; controls use event:{type:change,value:...} or event:{type:select,key:...}. Use answer for modal replies, or answer:null to cancel. Copy an interactions example from code_inspect; never send JSON as a string. Use steps:[{id,event?},...] for up to three known sequential interactions; stops on errors, modals or background work. Returns one resulting state with completedSteps and nextStep.", inputSchema: CodeInteractInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_interact")),
-  defineAiTool({ name: "code_stop", description: "Stop and release an isolated test run.", inputSchema: CodeStopInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_stop")),
-  defineAiTool({ name: "code_open", description: "Show the app beside the chat without starting it. For one-off calculations, return the result instead of opening an app.", inputSchema: CodeOpenInput, outputSchema: z.json(), approval: "never" }).client(),
-  defineAiTool({ name: "code_present", description: "Present a successful one-off run as a persistent interactive visualization in this chat. Requires code_run with code, without resourceId or saved app id. Saves source, selected inputs and UI preview. Users can activate controls and download the current view. Test runs are not visible until this succeeds. For reusable apps use code_open instead.", inputSchema: CodePresentInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_present")),
-  defineAiTool({ name: "code_export", description: "Copy a captured output file from a test run into the chat. Returns a path for normal file tools and presentation.", inputSchema: CodeExportInput, outputSchema: z.json(), approval: "never" }).server(runManagedCodeTool("code_export")),
+  defineAiTool({
+    name: "code_secret",
+    description:
+      "Open a trusted Secret input dialog. The user enters the value directly into encrypted Assistant storage; only configured/name returns. Never ask for a credential in chat, survey, app controls or code_interact. Personal secrets are scoped to this chat or resource and bound to the exact HTTPS origin, header and prefix. Use secret(name,{prefix}) in http.fetch headers; load assistant-code-mode for HTTP details. Web UI required for secret entry; stored secrets also work from CLI.",
+    inputSchema: CodeSecretInput,
+    outputSchema: z.object({ configured: z.boolean(), name: z.string() }),
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "code_action",
+    description:
+      "Call one published Studio App action using its exact discovered name, publication and input schema. Discover with code_actions first. Use permission is sufficient; draft and management access are not granted. Runtime effects and approvals are real. Never repeat an uncertain mutation blindly.",
+    inputSchema: CodeActionInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_action")),
+  defineAiTool({
+    name: "code_run",
+    promptHint:
+      "For file analysis, data transformations or combining Cloud data, run a short one-off script with code_run. Load assistant-code-mode for its runtime APIs; no saved app is required.",
+    description:
+      "Run a saved resource id OR one-off code in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts accept current chat inputPaths; app test runs use them only as explicit picker fixtures. Returns output, logs and UI state for agent inspection only; use code_present to show a one-off visualization to the user. Local test storage is temporary; shared data, database writes and capability effects are real and keep normal permissions and approvals.",
+    inputSchema: CodeRunInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_run")),
+  defineAiTool({
+    name: "code_inspect",
+    description:
+      "Inspect a test run: errors, logs, output, controls and pending modal. Use nodeId to inspect table rows or list items; follow pagination only as needed.",
+    inputSchema: CodeInspectInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_inspect")),
+  defineAiTool({
+    name: "code_interact",
+    description:
+      "Operate a control or answer a pending modal using its exact snapshot ID. Buttons need only id; controls use event:{type:change,value:...} or event:{type:select,key:...}. Use answer for modal replies, or answer:null to cancel. Copy an interactions example from code_inspect; never send JSON as a string. Use steps:[{id,event?},...] for up to three known sequential interactions; stops on errors, modals or background work. Returns one resulting state with completedSteps and nextStep.",
+    inputSchema: CodeInteractInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_interact")),
+  defineAiTool({
+    name: "code_stop",
+    description: "Stop and release an isolated test run.",
+    inputSchema: CodeStopInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_stop")),
+  defineAiTool({
+    name: "code_open",
+    description: "Show the app beside the chat without starting it. For one-off calculations, return the result instead of opening an app.",
+    inputSchema: CodeOpenInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "code_present",
+    description:
+      "Present a successful one-off run as a persistent interactive visualization in this chat. Requires code_run with code, without resourceId or saved app id. Saves source, selected inputs and UI preview. Users can activate controls and download the current view. Test runs are not visible until this succeeds. For reusable apps use code_open instead.",
+    inputSchema: CodePresentInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_present")),
+  defineAiTool({
+    name: "code_export",
+    description: "Copy a captured output file from a test run into the chat. Returns a path for normal file tools and presentation.",
+    inputSchema: CodeExportInput,
+    outputSchema: z.json(),
+    approval: "never",
+  }).server(runManagedCodeTool("code_export")),
 ];
 
 export const createDefaultCloudAiTools = () => [createAiTodoTool(), createCloudAiSurveyTool(), createCloudAiTextEditorTool()];

package/src/ai/dictation-runtime.ts

@@ -4,7 +4,7 @@ import { logger, trace } from "../services/logging";
 import { superviseRuntimeTask } from "../services/runtime-lifecycle";
 import { aiModelAccess } from "./model-access";
 import { aiProjects } from "./projects";
-import { AiTranscriptionError, describeTranscriptionFailure, runAiTranscription, type RunAiTranscriptionInput } from "./transcription";
+import { AiTranscriptionError, describeTranscriptionFailure, type RunAiTranscriptionInput, runAiTranscription } from "./transcription";
 
 const log = logger("ai:dictations");
 const queue = lazySync((sync) =>

package/src/ai/draft-content.ts

@@ -1,23 +1,37 @@
 import type { AiDraftContentPart } from "./types";
 
-export const aiDraftPartLabel = (part: AiDraftContentPart): string => part.type === "text" ? part.text
-  : part.type === "resource" ? part.title ?? part.ref.id
-  : part.type === "project-file" ? part.path : part.path.split("/").at(-1) || part.path;
+export const aiDraftPartLabel = (part: AiDraftContentPart): string =>
+  part.type === "text"
+    ? part.text
+    : part.type === "resource"
+      ? (part.title ?? part.ref.id)
+      : part.type === "project-file"
+        ? part.path
+        : part.path.split("/").at(-1) || part.path;
 
-export const aiDraftText = (content: readonly AiDraftContentPart[]) => content.map(part =>
-  part.type === "text" || part.inline ? aiDraftPartLabel(part) : "").join("");
+export const aiDraftText = (content: readonly AiDraftContentPart[]) =>
+  content.map((part) => (part.type === "text" || part.inline ? aiDraftPartLabel(part) : "")).join("");
 
 /** Queue text edits preserve untouched inline identities and ordinary attachments. */
 export function editAiDraftText(content: readonly AiDraftContentPart[], text: string): AiDraftContentPart[] {
   const before = aiDraftText(content);
-  let start = 0, oldEnd = before.length, newEnd = text.length;
+  let start = 0,
+    oldEnd = before.length,
+    newEnd = text.length;
   while (start < oldEnd && start < newEnd && before[start] === text[start]) start++;
-  while (oldEnd > start && newEnd > start && before[oldEnd - 1] === text[newEnd - 1]) { oldEnd--; newEnd--; }
+  while (oldEnd > start && newEnd > start && before[oldEnd - 1] === text[newEnd - 1]) {
+    oldEnd--;
+    newEnd--;
+  }
   let position = 0;
-  const retained = content.flatMap(part => {
-    if (part.type === "text") { position += part.text.length; return []; }
+  const retained = content.flatMap((part) => {
+    if (part.type === "text") {
+      position += part.text.length;
+      return [];
+    }
     if (!part.inline) return [];
-    const from = position; position += aiDraftPartLabel(part).length;
+    const from = position;
+    position += aiDraftPartLabel(part).length;
     if (position <= start) return [{ from, end: position, part }];
     if (from >= oldEnd) return [{ from: from + newEnd - oldEnd, end: position + newEnd - oldEnd, part }];
     return [];
@@ -26,9 +40,10 @@ export function editAiDraftText(content: readonly AiDraftContentPart[], text: st
   let offset = 0;
   for (const item of retained) {
     if (item.from > offset) result.push({ type: "text", text: text.slice(offset, item.from) });
-    result.push(item.part); offset = item.end;
+    result.push(item.part);
+    offset = item.end;
   }
   if (offset < text.length) result.push({ type: "text", text: text.slice(offset) });
-  result.push(...content.filter(part => part.type !== "text" && !part.inline));
+  result.push(...content.filter((part) => part.type !== "text" && !part.inline));
   return result;
 }

package/src/ai/enrich.ts

@@ -1,8 +1,8 @@
-import { AiBackgroundAdmissionError, AiBackgroundCostError } from "./inference-calls";
 import { z } from "zod";
 import { coreSettings } from "../services";
 import type { TraceContext } from "../services/logging";
 import { logger, trace } from "../services/logging";
+import { AiBackgroundAdmissionError, AiBackgroundCostError } from "./inference-calls";
 import { aiConversations } from "./store";
 import type { RunAiStructuredInput, RunAiStructuredResult } from "./structured";
 import { resolveAiBackgroundModel, runAiStructured } from "./structured";

package/src/ai/executor.ts

@@ -1,16 +1,9 @@
-import { createRunToolStore } from "./capabilities";
-import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
-import { AiCapabilityExecutionError } from "./capability-execution";
-import { aiChatTasks } from "./chat-tasks";
-import { assistantQuotaProvider, inferenceProvider } from "./quota-provider";
-import { AiRunTimeout } from "./run-timeout";
-import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type { CompactEvent, NessiLoop, OutboundEvent, Provider, Tool, ToolResolver } from "@k2b/nessi";
 import { compact, nessi } from "@k2b/nessi";
-import { createHelpReader } from "../services/help";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
 import type { AccessSubject, RequestActor } from "../server";
+import { createHelpReader } from "../services/help";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
 import { normalizeLocale } from "../shared/locale";
@@ -22,8 +15,9 @@ import {
   hasRememberedAiToolApproval,
 } from "./approvals";
 import { isAssistantChatTurn } from "./assistant-models";
-import { createAiToolResolver } from "./capabilities";
-import { executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
+import { createAiToolResolver, createRunToolStore } from "./capabilities";
+import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
+import { aiChatTasks } from "./chat-tasks";
 import { createCloudCompactFn } from "./compaction";
 import { createCloudAiCodeTools, createCloudAiLocalBashTool, createConfiguredDefaultCloudAiTools } from "./default-tools";
 import { aiFileStore } from "./files-store";
@@ -46,7 +40,9 @@ import {
   streamBlockId,
   toolBlockId,
 } from "./protocol";
+import { assistantQuotaProvider, inferenceProvider } from "./quota-provider";
 import { collectConversationResourceObservations } from "./resource-refs";
+import { AiRunTimeout } from "./run-timeout";
 import { isAiVisionModelConfigured, type resolveAiModel } from "./settings";
 import { selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool, loadSelectedAiSkills } from "./skill-tool";
@@ -57,6 +53,7 @@ import { composeAiSystemPrompt } from "./system-prompt";
 import { aiToolAudit } from "./tool-audit";
 import { resolveAiToolResultMaxChars } from "./tool-result-budget";
 import { aiToolPromptHints, type PreparedAiTools, prepareAiTools } from "./tools";
+import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type {
   AiChatTurnRunConfig,
   AiFrontendToolMode,
@@ -791,8 +788,7 @@ export class AiTurnExecutor {
     const allowed = allowedTools === null ? null : new Set(allowedTools);
     const activeTools = toolsSupported
       ? runtimeTools.filter(
-          (tool) =>
-            (!allowed || allowed.has(tool.def.name)) && !(config.mandate && CODE_RUNTIME_TOOL_NAMES.some((name) => name === tool.def.name)),
+          (tool) => (!allowed || allowed.has(tool.def.name)) && !(config.mandate && ["code_open", "code_secret"].includes(tool.def.name)),
         )
       : [];
     const memoryToolEnabled = activeTools.some((tool) => tool.def.name === "memory");

package/src/ai/fetch-file-tool.ts

@@ -1,9 +1,9 @@
 import type { ClientRequest, IncomingHttpHeaders, IncomingMessage } from "node:http";
 import { type RequestOptions as HttpsRequestOptions, request as httpsRequest } from "node:https";
-import { resolvePublicNetworkAddresses, type PublicNetworkAddress } from "../services/network-security";
+import { z } from "zod";
+import { type PublicNetworkAddress, resolvePublicNetworkAddresses } from "../services/network-security";
 import { AI_FILES_MAX_FILE_BYTES_DEFAULT, aiFileStore, guessAiMediaType, normalizeAiFilePath } from "./files-store";
 import { defineAiTool } from "./tools";
-import { z } from "zod";
 
 const FETCH_FILE_MAX_REDIRECTS = 5;
 const FETCH_FILE_MAX_ADDRESS_ATTEMPTS = 4;

package/src/ai/file-content-version.ts

@@ -18,5 +18,10 @@ export class AiFileVersionConflict extends Error {
 
 /** A known file write rejection; no destination bytes were written. */
 export class AiFileWriteError extends Error {
-  constructor(readonly code: "CONFLICT" | "STORAGE_FULL", message: string) { super(message); }
+  constructor(
+    readonly code: "CONFLICT" | "STORAGE_FULL",
+    message: string,
+  ) {
+    super(message);
+  }
 }