@k2b/cloud 0.30.0 → 0.32.0

package/src/ai/default-tools.ts

@@ -18,6 +18,7 @@ import { runManagedCodeTool } from "./code-runtime-tools";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTools } from "./code-source-tools";
 import {
+  CLOUD_AI_GROUP_MAX_CHARTS,
   CloudAiCardInputSchema,
   CloudAiCardOutputSchema,
   CloudAiChartInputSchema,
@@ -39,6 +40,22 @@ import {
 } from "./file-tools";
 import { createCloudAiWebExtractTool, createCloudAiWebSearchTool, isCloudAiFirecrawlConfigured } from "./firecrawl-tools";
 import { createCloudAiHtmlToPdfTool } from "./html-pdf-tool";
+import {
+  CloudAiLoadLocalSkillInputSchema,
+  CloudAiLoadLocalSkillOutputSchema,
+  CloudAiLocalDownloadInputSchema,
+  CloudAiLocalDownloadOutputSchema,
+  CloudAiLocalListInputSchema,
+  CloudAiLocalListOutputSchema,
+  CloudAiLocalMoveInputSchema,
+  CloudAiLocalMoveOutputSchema,
+  CloudAiLocalReadInputSchema,
+  CloudAiLocalReadOutputSchema,
+  CloudAiLocalUploadInputSchema,
+  CloudAiLocalUploadOutputSchema,
+  CloudAiLocalWriteInputSchema,
+  CloudAiLocalWriteOutputSchema,
+} from "./local-tool-contracts";
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
 import { createAiTodoTool } from "./todo-tool";
 import { defineAiTool } from "./tools";
@@ -72,23 +89,22 @@ export const createCloudAiCardTool = () =>
   defineAiTool({
     name: "card",
     description:
-      "Render one compact visual highlight card in the chat. Use it only for a single status, metric, KPI, or short result. Use normal markdown for tables, lists, comparisons, and longer explanations. Keep all fields flat; do not pass arrays or nested objects.",
+      "Show one highlight figure you already have, such as a status, metric or short result, as a stat tile in the chat. Keep the value to a short figure or status and the caption to one line. Several figures computed in code_run go through cloud.view.stats in the run, not several card calls; tables, lists and longer explanations stay Markdown. Keep all fields flat; do not pass arrays or nested objects.",
     inputSchema: CloudAiCardInputSchema,
     outputSchema: CloudAiCardOutputSchema,
     approval: "never",
-    promptHint: "show one compact highlight card (metric, KPI, status) — not for tables, lists, or long text.",
+    promptHint: "show one highlight figure already known; several computed figures use cloud.view.stats in code_run.",
   }).clientView();
 
 export const createCloudAiChartTool = () =>
   defineAiTool({
     name: "chart",
-    description:
-      "Show one chart in the chat from data you already have: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge or sparkline. Cloud draws it with the renderer of cloud.chart() in Studio apps and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Aggregate first. Compute derived numbers with calculate or code_run before charting them. Say what the chart shows in title and put the unit, period or source in subtitle. The chart has no state, filters or actions: for interaction show an app in the chat with code_present, and build a saved Studio App only when data must be kept or the app reused. After the chart, state the finding instead of repeating its values.",
+    description: `Show one chart in the chat from a few values you already have that did not come from a code run, such as figures from the conversation, a web page or a small capability result: bar, line (area: true fills it), scatter, pie, donut, histogram, gauge, sparkline, boxplot, heatmap, barGauge or stat. Several related measures go into one call as a group of small charts (charts, at most ${CLOUD_AI_GROUP_MAX_CHARTS}); linkX shares the x cursor between line charts with the same kind of x. There is no second y axis: compare measures with different units as a group. Cloud draws it with the renderer of cloud.chart() and gives the reader a data table and Copy data; no code, sandbox or app check is involved. Values computed in code_run never go here: the script shows them itself with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer, and you present the returned path. Aggregate first. Say what the chart shows in title and put the unit, period or source in subtitle; formats are data ({ style: "percent" } takes fractions). The chart has no state, filters or actions: filters, steps and comparison over computed rows come from cloud.view.explorer in code_run; for other interaction show an app in the chat with code_present, and build a saved Studio App only when data must be kept or the app reused. After the chart, state the finding instead of repeating its values.`,
     inputSchema: CloudAiChartInputSchema,
     outputSchema: CloudAiChartOutputSchema,
     approval: "never",
     promptHint:
-      "show data you already have as a chart in the chat, without code. For interaction use a chat app (code_present); for kept data or reuse, a saved Studio App.",
+      "show a few values you already have (not from a code run) as a chart in the chat. Code results use cloud.view.* and present; filters, steps and comparison use cloud.view.explorer in code_run; interaction beyond that needs a chat app (code_present).",
   }).clientView();
 
 export const createCloudAiSurveyTool = () =>
@@ -118,14 +134,73 @@ export const createCloudAiLocalBashTool = () =>
   defineAiTool({
     name: "local_bash",
     description:
-      "Run one Bash command on the user's local CLI computer after the CLI shows the exact command and the user confirms it. Use only when local computer interaction is necessary. The command runs from the CLI's startup directory as the current OS user. Inspect the returned status, exit code, stdout, and stderr before continuing.",
+      "Run one Bash command in the workspace folder on the user's computer, as the user's OS account. Use it only when no file or Cloud tool fits; the client may ask the user first, and a run does not prove that the user saw the command.",
     inputSchema: CloudAiLocalBashInputSchema,
     outputSchema: CloudAiLocalBashOutputSchema,
     approval: "never",
-    promptHint:
-      "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.",
+    promptHint: "use local_bash only when no local file tool or Cloud tool fits; check status, exit code, and output.",
   }).client();
 
+/** File tools a local client runs in the user's workspace folder; the client applies its path rules and questions. */
+export const createCloudAiLocalTools = () => [
+  defineAiTool({
+    name: "local_list",
+    description:
+      "List files and folders in the user's local workspace, optionally recursive or filtered by a case-insensitive glob such as **/*.pdf, in pages of up to 1000 entries with size and modification time. Folders outside the workspace ask the user first.",
+    inputSchema: CloudAiLocalListInputSchema,
+    outputSchema: CloudAiLocalListOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_read",
+    description:
+      "Read a local text file with line numbers, 16 KiB by default and 64 KiB at most per call; continue with nextOffset. PDFs, images, and office or spreadsheet files are uploaded to this chat instead, and the result names the chat path for read_file or view_image.",
+    inputSchema: CloudAiLocalReadInputSchema,
+    outputSchema: CloudAiLocalReadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_upload",
+    description:
+      "Upload up to 64 local files to this chat and return their chat paths, so Cloud tools such as read_file, view_image, and code mode can use them. Uploads stay in the chat until it is deleted; each file can have up to 50 MB.",
+    inputSchema: CloudAiLocalUploadInputSchema,
+    outputSchema: CloudAiLocalUploadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_download",
+    description:
+      "Save a chat file, text or binary, into the local workspace and create missing folders. It never overwrites an existing file unless replace is true, which asks the user.",
+    inputSchema: CloudAiLocalDownloadInputSchema,
+    outputSchema: CloudAiLocalDownloadOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_write",
+    description:
+      "Write a local text file of up to 100 KiB: create makes a new file and fails if one exists, append adds to an existing file, and replace overwrites one. Append and replace ask the user.",
+    inputSchema: CloudAiLocalWriteInputSchema,
+    outputSchema: CloudAiLocalWriteOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "local_move",
+    description:
+      "Rename or move up to 64 files or folders inside the workspace in one batch, which the user confirms once as a list. It never overwrites: if a target exists, nothing moves and the result names the conflicts.",
+    inputSchema: CloudAiLocalMoveInputSchema,
+    outputSchema: CloudAiLocalMoveOutputSchema,
+    approval: "never",
+  }).client(),
+  defineAiTool({
+    name: "load_local_skill",
+    description:
+      "Load a Skill marked [local] in the Skills section by its exact name. Returns its instructions, folder, and file list; read referenced files with local_read.",
+    inputSchema: CloudAiLoadLocalSkillInputSchema,
+    outputSchema: CloudAiLoadLocalSkillOutputSchema,
+    approval: "never",
+  }).client(),
+];
+
 export const createCloudAiCodeTools = () => [
   defineAiTool({
     name: "code_secret",
@@ -146,16 +221,17 @@ export const createCloudAiCodeTools = () => [
   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.",
+      "For file analysis, data transformations or combining Cloud data, run a short one-off script with code_run; its computed views come from cloud.view.* in the script and present. Load assistant-code-mode for its runtime APIs; no saved app is required.",
     description:
-      "Run one-off script code OR a saved script resource in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes cloud.capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts read explicit chat inputPaths. Returns output, logs and captured files for agent inspection only. Apps with an index.html interface do not run here: show them with code_open or code_present. Runs use real shared and personal data; database writes and capability effects keep normal permissions and approvals.",
+      "Run one-off script code OR a saved script resource in the isolated worker. Optional resourceId binds one-off code to existing app data (Manage required), without editing its source. Includes cloud.capabilities.run(name,input) to chain Cloud capabilities in JavaScript; load assistant-code-mode for its runtime APIs. Scripts read explicit chat inputPaths. Returns output, logs, captured files and view references for agent inspection only. Show computed views with cloud.view.chart, cloud.view.group, cloud.view.table, cloud.view.stats, cloud.view.details or cloud.view.explorer in the script, then present({path}) each returned view; never retype run values into chart arguments, files or Markdown. Apps with an index.html interface do not run here: show them with code_open or code_present. Runs use real shared and personal data; database writes and capability effects keep normal permissions and approvals.",
     inputSchema: CodeRunInput,
     outputSchema: z.json(),
     approval: "never",
   }).server(runManagedCodeTool("code_run")),
   defineAiTool({
     name: "code_inspect",
-    description: "Inspect a script run: status, progress, errors, logs, output and captured files. Use waitMs to wait for background work.",
+    description:
+      "Inspect a script run: status, progress, errors, logs, output, captured files and view references. Use waitMs to wait for background work.",
     inputSchema: CodeInspectInput,
     outputSchema: z.json(),
     approval: "never",