@k2b/cloud 0.6.0-rc.0 → 0.7.0

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

@@ -0,0 +1,202 @@
+import { AiFileLocation, AiFileReference } from "./file-reference-contracts";
+import { z } from "zod";
+import { CodeResourceId } from "./browser-code-contracts";
+import { PrincipalSchema } from "../contracts/shared";
+
+// Flat Assistant tool inputs. The owning service also validates its domain contracts.
+const Id = z.object({ id: CodeResourceId }).strict();
+const Page = z.number().int().min(1).max(100000).default(1);
+const ArtifactPath = z
+  .string()
+  .min(1)
+  .max(180)
+  .regex(/^[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)*$/)
+  .refine((path) => path.split("/").every((part) => part !== "." && part !== ".."));
+const ArtifactFile = z
+  .object({
+    path: ArtifactPath,
+    content: z
+      .string()
+      .max(1024 * 1024)
+      .describe("Complete source file content; read existing content before replacing it."),
+  })
+  .strict();
+const Icon = z
+  .string()
+  .regex(/^ti ti-[a-z0-9-]+$/)
+  .max(80);
+const ArtifactMetadata = z
+  .object({
+    title: z.string().trim().min(1).max(120).optional(),
+    description: z.string().trim().max(500).optional(),
+    icon: Icon.optional(),
+  })
+  .strict();
+const ArtifactCreate = ArtifactMetadata.required({ title: true });
+const PublicationNote = z.string().trim().min(1).max(1000);
+const DatabaseSql = z.object({
+  sql: z.string().trim().min(1).max(16000).describe("Read-only SELECT; no writes, CTEs or comments. Use LIMIT."),
+  params: z.array(z.json()).max(1000).default([]),
+});
+
+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),
+});
+
+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) }),
+  },
+  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.",
+    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.",
+    review: true,
+    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.") }),
+  },
+  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,
+  },
+  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,
+    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.",
+    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.",
+    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.",
+    review: true,
+    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) }),
+  },
+  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.",
+    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"),
+  },
+  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.",
+    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.",
+    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."),
+      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"),
+  },
+  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.") }),
+  },
+  code_sql: {
+    description:
+      "Run a read-only SELECT directly against an App database without writing code. Supply its id and parameterized SQL. Does not create or connect a database. Requires current resource access; Project access applies only in that Project chat. Narrow columns and add LIMIT for large results.",
+    input: Id.extend(DatabaseSql.shape),
+  },
+  code_versions: {
+    description: "List numbered published versions with notes, author and date. Admin only. Separate from automatic file-save history.",
+    input: Id.extend({ page: Page }),
+  },
+  code_list: {
+    description:
+      "Find accessible Apps, including published Project Apps in the current authorized Project chat. Reuse the intended resource instead of creating duplicates.",
+    input: z
+      .object({
+        page: Page,
+        q: z.string().max(120).optional().describe("Find by title or description; matches only metadata you may access."),
+      })
+      .strict(),
+  },
+  code_read: {
+    description:
+      "Read the current file, or omit path for the directory. Follow nextOffset for long files. revision is optional and only needed to inspect history.",
+    input: Id.extend({
+      path: ArtifactPath.optional().describe("Exact relative file path. Omit to list files."),
+      offset: z.number().int().min(0).default(0).describe("UTF-16 offset; follow nextOffset for the remaining content."),
+      revision: z.number().int().positive().optional().describe("Historical revision from code_history. Omit for current files."),
+    }),
+  },
+  code_history: {
+    description: "List previous saved versions. Use code_read with a returned revision only when historical source is needed.",
+    input: Id.extend({ page: Page }),
+  },
+  code_fork: {
+    description:
+      "Create a private editable copy of an accessible publication. Source is copied; shared data, database and Project associations are not. Project-only access does not permit forks.",
+    input: Id,
+  },
+  code_publish: {
+    description:
+      "Publish tested working source as the next numbered version. A concise change note is required. Never changes sharing. Read current revision first; a concurrent edit causes a conflict.",
+    input: Id.extend({
+      expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .describe("Current working revision from code_read; prevents conflicting publication or restore."),
+      note: PublicationNote,
+    }),
+  },
+  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.",
+    review: true,
+    input: Id.extend({ expectedPublishedVersion: z.number().int().positive() }),
+  },
+  code_restore: {
+    description:
+      "Restore a published version including title, description and icon as the working source and a new latest publication, atomically. Automatically records Restore version X. Preserves publication history and user data; do not call code_publish again.",
+    input: Id.extend({
+      version: z.number().int().positive().describe("Publication number returned by code_versions."),
+      expectedRevision: z
+        .number()
+        .int()
+        .positive()
+        .describe("Current working revision from code_read; prevents conflicting publication or restore."),
+    }),
+  },
+  code_update: {
+    description: "Change working title, description or Tabler icon. Does not publish. Use e.g. ti ti-calculator or ti ti-chart-bar.",
+    input: Id.extend(ArtifactMetadata.shape),
+  },
+  code_create: {
+    description:
+      "Create a private reusable App with an optional UI, published actions and optional persistence. For one-off analysis, use code_run with code instead. Returns id and entry path; write source with code_write. Optional icon uses the complete class, e.g. ti ti-chart-bar; omit it when unsure. Does not run or share anything.",
+    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),
+    input: CodeWriteInput,
+  },
+  code_remove: {
+    description:
+      "Remove one source file, saving immediately. Source history is retained for recovery; does not delete the app. Removing an absent file is harmless. Returns diagnostics for any broken imports.",
+    input: Id.extend({ path: ArtifactPath.describe("Exact relative path of the file to remove.") }),
+  },
+} as const;
+export type CodeSourceToolName = keyof typeof CODE_SOURCE_TOOLS;

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

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import {
+  capabilityIdempotencyKeyHash,
+  capabilityRequestHash,
+  claimCapabilityIdempotency,
+  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 { LOCALE_HEADER } from "../shared/locale";
+import { CODE_SOURCE_TOOLS, type CodeSourceToolName } from "./code-source-contracts";
+import { resolveAiCapabilityActor } from "./capability-execution";
+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 Reply = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), data: z.unknown() }),
+  z.object({ ok: z.literal(false), error: z.object({ code: z.string(), message: z.string() }) }),
+]);
+
+/** Direct server tools: discovery exposes code_*; Assistant owns the resource services. */
+export function createCodeSourceTool(name: CodeSourceToolName) {
+  const definition = CODE_SOURCE_TOOLS[name];
+  return defineAiTool({
+    name,
+    description:
+      definition.description +
+      (WRITE_TOOLS.has(name) ? " If a write has an unknown outcome, inspect current state before attempting another write." : ""),
+    inputSchema: definition.input,
+    outputSchema: z.unknown(),
+    approval: "never",
+  }).server(async (input, context) => {
+    if (!context.conversationId) throw new Error("Code tools require an Assistant conversation.");
+    const { actor } = await resolveAiCapabilityActor({
+      conversationId: context.conversationId,
+      persistedActor: context.actor,
+      store: aiConversations,
+    });
+    const app = await getApp("assistant");
+    if (!app) throw new Error("Assistant is unavailable.");
+    const signal = context.signal;
+    const send = async (review = false) => {
+      const signed = await withActiveIdentitySigner(
+        "invocation",
+        (signer) =>
+          signInvocationToken({
+            targetAppId: "assistant",
+            callingAppId: "core",
+            operation: `tool:${name}`,
+            schemaHash: null,
+            authority: {
+              sub: actor.user.id,
+              principal_type: "user",
+              access_subject_type: "user",
+              access_subject_id: actor.user.id,
+              credential_kind: "session",
+              scopes: [],
+            },
+            signer,
+            issuer: signer.issuer,
+          }),
+        { signal, timeoutMs: 5000 },
+      );
+      const headers = new Headers({ authorization: `Bearer ${signed.token}`, "content-type": "application/json" });
+      if (context.locale) headers.set(LOCALE_HEADER, context.locale);
+      const response = await fetch(new URL(`/_internal/assistant/tools/${name}`, app.baseUrl), {
+        method: "POST",
+        headers,
+        redirect: "manual",
+        signal,
+        body: JSON.stringify({ input, conversationId: context.conversationId, ...(review ? { review: true } : {}) }),
+      });
+      const parsed = await readBoundedJson(response, 256 * 1024);
+      if (!parsed.ok) throw new Error("Invalid Assistant tool response. A write may have completed; inspect its state before retrying.");
+      const reply = Reply.safeParse(parsed.data);
+      if (!reply.success) throw new Error("Assistant tool request failed. Inspect resource state before retrying a write.");
+      if (!reply.data.ok) throw new Error(`${reply.data.error.code}: ${reply.data.error.message}`);
+      if (!response.ok) throw new Error("Assistant tool request failed.");
+      return { data: reply.data.data, status: response.status };
+    };
+    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.");
+    }
+    // Reuse the platform replay guard; these tools are not registered capabilities.
+    const claim = WRITE_TOOLS.has(name)
+      ? {
+          appId: "assistant",
+          capability: `tool:${name}`,
+          principal: `user:${actor.user.id}`,
+          keyHash: capabilityIdempotencyKeyHash(`${context.conversationId}:${context.callId}`),
+        }
+      : null;
+    if (claim) {
+      if (!context.callId) throw new Error("A write requires a tool call ID.");
+      const state = await claimCapabilityIdempotency(claim, capabilityRequestHash(input));
+      if (state.state === "replay")
+        throw new Error("This write already completed. Use code_list or code_read to inspect current state; do not repeat the write.");
+      if (state.state !== "claimed")
+        throw new Error(`Write outcome ${state.state}; inspect current state before attempting another write.`);
+    }
+    try {
+      const response = await send();
+      if (claim) await completeCapabilityClaim(claim, response.status, response.data);
+      return response.data;
+    } catch (error) {
+      if (claim) await markCapabilityClaimUncertain(claim);
+      throw error;
+    }
+  });
+}
+
+export const createCodeSourceTools = () => [
+  createCodeSourceTool("code_files"),
+  createCodeSourceTool("code_file_stat"),
+  createCodeSourceTool("code_file_copy"),
+  createCodeSourceTool("code_database_export"),
+  createCodeSourceTool("code_manage_read"),
+  createCodeSourceTool("code_delete"),
+  createCodeSourceTool("code_database_read"),
+  createCodeSourceTool("code_database_clear"),
+  createCodeSourceTool("code_database_reset"),
+  createCodeSourceTool("code_storage_list"),
+  createCodeSourceTool("code_storage_delete"),
+  createCodeSourceTool("code_access_read"),
+  createCodeSourceTool("code_access_change"),
+  createCodeSourceTool("code_actions"),
+  createCodeSourceTool("code_sql"),
+  createCodeSourceTool("code_versions"),
+  createCodeSourceTool("code_list"),
+  createCodeSourceTool("code_read"),
+  createCodeSourceTool("code_history"),
+  createCodeSourceTool("code_fork"),
+  createCodeSourceTool("code_publish"),
+  createCodeSourceTool("code_restore"),
+  createCodeSourceTool("code_update"),
+  createCodeSourceTool("code_create"),
+  createCodeSourceTool("code_write"),
+  createCodeSourceTool("code_remove"),
+];

package/src/ai/compaction.ts

@@ -89,6 +89,23 @@ const findLoopSplitIndex = (entries: StoreEntry[], keepLoops: number): number =>
   return -1;
 };
 
+/** 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] : []);
+  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>();
+  let safe = -1;
+  for (let index = 0; index < candidate; index++) {
+    const message = entries[index]!.message;
+    if (message.role === "assistant") {
+      for (const block of message.content) if (block.type === "tool_call") pending.add(block.id);
+    } else if (message.role === "tool_result") pending.delete(message.callId);
+    if (pending.size === 0) safe = index + 1;
+  }
+  return safe;
+};
+
 const buildCompactionPrompt = (additionalInstructions: string, source: string) => ({
   systemPrompt: buildAiTaskPrompt({
     baseInstructions: DEFAULT_COMPACTION_PROMPT,
@@ -113,13 +130,16 @@ export const createCloudCompactFn = (input: {
   keepRecentLoops?: number;
 }): CompactFn => {
   return (ctx) => {
-    if (!ctx.force && (typeof ctx.fillRatio !== "number" || ctx.fillRatio < COMPACTION_FILL_RATIO)) return null;
+    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;
+    if (!ctx.force && (typeof fillRatio !== "number" || fillRatio < COMPACTION_FILL_RATIO)) return null;
 
     const totalLoops = countConversationLoops(ctx.entries);
-    const keepLoops = input.keepRecentLoops ?? keepLoopsForFillRatio(ctx.fillRatio, totalLoops);
-    if (totalLoops <= keepLoops) return null;
-
-    const splitIndex = findLoopSplitIndex(ctx.entries, keepLoops);
+    const keepLoops = input.keepRecentLoops ?? keepLoopsForFillRatio(fillRatio, totalLoops);
+    const loopSplit = totalLoops > keepLoops ? findLoopSplitIndex(ctx.entries, keepLoops) : -1;
+    const splitIndex = loopSplit > 0 ? loopSplit : findRoundSplitIndex(ctx.entries);
     if (splitIndex < 1) return null;
 
     const sourceEntries = ctx.entries.slice(0, splitIndex);
@@ -162,6 +182,7 @@ export const createCloudCompactFn = (input: {
 
       await aiConversations.compactMessages({
         conversationId: input.conversationId,
+        turnId: input.turnId,
         checkpointSeq: checkpoint.seq,
         modelProfileId: input.modelProfileId,
         summary: {
@@ -179,4 +200,4 @@ export const createCloudCompactFn = (input: {
   };
 };
 
-export const __compactionTest = { countConversationLoops, findLoopSplitIndex, keepLoopsForFillRatio };
+export const __compactionTest = { countConversationLoops, findLoopSplitIndex, findRoundSplitIndex, keepLoopsForFillRatio };

package/src/ai/data-analysis-skill.ts

@@ -0,0 +1,10 @@
+// Generated by packages/assistant/scripts/generate-code-mode-skill.ts.
+import type { AiSkillTemplate } from "./skills";
+export const ASSISTANT_DATA_ANALYSIS_SKILL = {
+  "key": "assistant:data-analysis",
+  "version": 6,
+  "name": "assistant-data-analysis",
+  "description": "Analyze source data, explain metrics and comparisons, and build evidence-backed reports or interactive dashboards in Assistant Code Mode. Use for multi-step analysis, data exploration, and dashboards; a simple chart only needs the Code Mode charts reference.",
+  "instructions": "# Analyze data and deliver an inspectable result\n\nStart with the question the reader needs to answer. Choose a direct answer,\nan interactive visualization in this chat, an exported file, or a reusable Studio app accordingly.\nFor a one-time visual analysis, prefer a chat visualization; filters and buttons\ndo not by themselves require a Studio App.\nLoad `assistant-code-mode` for execution and read its `references/analytics.md`\nfor the built-in UI. Loading this skill does not install a library or grant access.\n\n## Keep a working plan\n\nFor work with several real steps, use `todo_write` to keep a short chat plan.\nReplace the full `todos` list each time; give each item a stable `id`, actionable\n`content`, and `status` (`pending`, `in_progress`, `completed`, or `cancelled`).\nAt most one step is active. Update as work changes, including user corrections;\nmark a step completed only after doing and checking it. Preserve exact commands\nwhen they matter. Skip this tool for a simple calculation or conversational reply.\n\nFor analysis, useful steps are reconcile source data, build the analysis, and\nverify totals, filters and conclusions. A rendered dashboard alone is not proof\nthat its numbers are correct. Keep blocked source work open and explain why.\n\n## Establish the data\n\nIdentify the actual source, unit of observation, time window, timezone, and\nlatest complete period. Read files or discover the relevant Cloud capabilities\nbefore selecting fields. External APIs use `http.fetch`; credentials are entered\nonly through the trusted `code_secret` dialog.\n\nInspect a bounded sample, missing values, duplicate keys, types, and coverage.\nReconcile totals and join cardinalities before drawing conclusions. Keep raw\nnumbers separate from display formatting. Distinguish zero from unavailable data;\nstate exclusions and denominator choices. Do not substitute fixture data for a\nblocked source unless the user requested a mockup.\n\nKeep the source query or transformation in the saved source or an accompanying\nfile so another run can reproduce the result. Preserve the source identity and\nretrieval timestamp, without credentials or credential-bearing URLs.\n\n## Build one consistent analysis\n\nDerive charts, metrics, and tables from the same reviewed data. Aggregate large\ninputs before crossing the UI bridge. Chart Explorer rows identify selectable\nentities with stable string keys; derived bins and groups need explicit mark\nmappings. Shared keys across charts mean the same entity, not equal values.\n\nChoose the simplest chart that answers the question. Use tables for exact\nrecords, bars for category comparisons, lines for ordered trends, and distributions\nfor spread. State units, comparison windows, and whether a percent is a fraction\nor an already scaled number. Do not imply causation from correlation.\n\nLead reports with the finding, then supporting evidence and limitations.\nLead dashboards with the important measurements, then trends and diagnostic\nbreakdowns. Use shared filters only when they affect all claimed views. Keep the\ninitial view useful without interaction. Avoid unrelated metrics added merely to\nfill a grid.\n\nAttach source context to Explorer data: `mode`, `asOf`, `sources`, and relevant\n`status`/`note`. A timestamp records when the data was retrieved; it does not prove\nthat the upstream source is complete. Label partial or fixture data visibly.\n\n## Validate before delivery\n\nRun the actual source with `code_run`. Inspect the result; use `code_interact`\nwith structured UI events to test filters, chart/table switching, selection,\nempty results, and recovery from a failed load. Reconcile displayed values with\nthe reviewed totals and check that filters describe the data actually displayed.\nA successful schema validation does not establish analytical correctness.\n\nValidate the actual presented source (the saved revision for Apps), rather than pasting its formulas into a\nsecond test script. Keep an independent expectation from the input data: row\ncounts, unmatched joins, totals and representative boundary cases. For targets,\nstate their grain (for example month × region) and aggregate each target once;\nmultiple selected regions must sum their distinct targets. Compare inspected raw\nKPI values and plotted series with independent expectations. A formatted value\nmatching after rounding does not validate the raw ratio. Never round fractions\nbefore passing them to percent-formatted controls. Preserve precision\nuntil display formatting. Test reset, one/multiple/all selections, empty results,\nand complete versus partial periods. A newly generated timestamp is not source\nfreshness: keep the real retrieval or file-snapshot timestamp stable.\n\nFor a Studio App data snapshot, export the validated dataset with `files.save` and\n`code_export`, then copy its exact path/version into the resource with\n`code_write({id,expectedRevision,files:[{path:\"data.json\",fromFile:reference}]})`.\nObtain the exact reference with `code_file_stat`; importing private files into\nApp source receives fresh review.\nImport that file in the app. Never rebuild a truncated dataset by copying tool\noutput. Keep transformations and source identity alongside the snapshot.\n\nHuman approval and uncertain HTTP outcomes follow the Code Mode HTTP contract.\nDo not replay an external mutation to refresh a chart. Separate local filtering\nfrom external loading; an Apply button can avoid a request for every slider move.\n\n## Save, share, and hand off\n\nFor chat visualizations, test `code_run` and relevant `code_interact` controls,\nthen deliver with `code_present({runId,title})`. A successful run alone is not\nvisible to the user. Retain source identity, reviewed input data and their real\nretrieval timestamp. Put writes and external reloads behind explicit buttons;\nopening an old result must not repeat earlier actions. The user can download the\ncurrent view as PDF/HTML or an individual chart as SVG.\n\nFor reusable Studio Apps, reuse one Cloud resource for later revisions of the same report or dashboard.\nSave its source, test that revision, and use the normal Code Mode publication\nworkflow when publication is requested. Publishing a version and granting reader\naccess are separate operations. Preserve existing access; a dashboard request\ndoes not authorize broadening it. Personal secrets are never copied to readers.\n\nA published source version is not automatically a frozen data snapshot. A frozen\nreport must retain the reviewed data explicitly in its authorized resource or\noutput file. A live app must implement its loader and display the retrieval time;\nloading once is not continuous monitoring. No background refresh exists unless\nimplemented through an appropriate supported workflow.\n\nPresent the chat visualization, resource link or exported file, the data timestamp, and material\ncoverage limitations. Say whether it is a snapshot or reloads from its sources.\nIf publication fails, retain the tested resource and report the failed stage;\ndo not claim success or create a different public destination. Sites-specific\nhosting, access policies, and editor storage are not part of this Cloud workflow.",
+  "extraFrontmatter": {}
+} satisfies AiSkillTemplate;

package/src/ai/default-tools.ts

@@ -1,3 +1,9 @@
+import { createAiTodoTool } from "./todo-tool";
+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,
@@ -20,6 +26,7 @@ import { createCloudAiWebExtractTool, createCloudAiWebSearchTool, isCloudAiFirec
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
 import { defineAiTool } from "./tools";
 import type { AiDataBoundary, AiRuntimeTool } from "./types";
+import { createCloudAiTranscribeAudioTool } from "./audio-tool";
 import { createCloudAiViewImageTool } from "./vision-tool";
 
 export {
@@ -87,10 +94,24 @@ export const createCloudAiLocalBashTool = () =>
       "use local_bash only when work on the user's local CLI computer is necessary; every command requires local confirmation and its result must be checked.",
   }).client();
 
-export const createDefaultCloudAiTools = () => [createCloudAiSurveyTool(), createCloudAiTextEditorTool()];
+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")),
+];
+
+export const createDefaultCloudAiTools = () => [createAiTodoTool(), createCloudAiSurveyTool(), createCloudAiTextEditorTool()];
 
 /** Built-ins advertised through discovery and loaded only when needed. */
-export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set([
+export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
+  ...CODE_RUNTIME_TOOL_NAMES,
+  ...Object.keys(CODE_SOURCE_TOOLS),
   "survey",
   "text_editor",
   "list_files",
@@ -108,6 +129,7 @@ export const createConfiguredDefaultCloudAiTools = async (config?: {
 }) => {
   const tools: AiRuntimeTool[] = [
     ...createDefaultCloudAiTools(),
+    ...createCodeSourceTools(),
     createCloudAiListFilesTool(),
     createCloudAiReadFileTool(),
     createCloudAiFetchFileTool(),
@@ -116,6 +138,7 @@ export const createConfiguredDefaultCloudAiTools = async (config?: {
     createCloudAiPresentTool(),
     createCloudAiCalculateTool(),
     createCloudAiViewImageTool(),
+    createCloudAiTranscribeAudioTool(),
   ];
   const firecrawlConfigured =
     config && "firecrawlApiKey" in config ? Boolean(config.firecrawlApiKey?.trim()) : await isCloudAiFirecrawlConfigured();