@k2b/cloud 0.29.1 → 0.31.0

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

@@ -3,8 +3,10 @@ import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { getApp } from "../_internal/registry";
 import type { RequestActor } from "../server";
+import { IDENTITY_REFRESH_TIMEOUT_MS } from "../services/identity/constants";
 import { signInvocationToken } from "../services/identity/invocation-token";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
+import { logger } from "../services/logging";
 import { LOCALE_HEADER } from "../shared/locale";
 import { TIMEZONE_COOKIE } from "../shared/time";
 import { CodeToolFailure } from "./browser-code-contracts";
@@ -12,6 +14,10 @@ import { resolveAiCapabilityActor } from "./capability-execution";
 import { CODE_CAPABILITY_TOKEN_HEADER, codeCapabilityOperation } from "./code-capability-transport";
 import { authorizeCodeExecution } from "./code-execution";
 import { aiConversations } from "./store";
+import type { AiApprovalTarget, AiWebsiteReceipt } from "./types";
+
+const log = logger("ai:code-runtime");
+const ISSUANCE_TIMEOUT_MS = 5_000;
 
 const Reply = z.object({
   ok: z.literal(true),
@@ -19,7 +25,20 @@ const Reply = z.object({
     status: z.enum(["running", "busy", "done", "lost"]),
     phase: z.enum(["starting", "running", "busy", "waiting_for_user"]).optional(),
     result: z.unknown().optional(),
-    approvals: z.array(z.object({ id: z.uuid(), message: z.string(), decision: z.boolean().nullable() })),
+    approvals: z.array(
+      z.object({
+        id: z.uuid(),
+        approvalId: z.uuid().optional(),
+        message: z.string(),
+        decision: z.boolean().nullable(),
+        /** What the person may remember: the website or Action, derived by the host from the stored request. */
+        remember: z.object({ toolName: z.string(), approvalScope: z.string(), always: z.boolean() }).optional(),
+      }),
+    ),
+    /** The next requests a website approval for this chat let through without asking, after `receiptsAfter`. */
+    receipts: z.array(z.object({ method: z.string(), url: z.string() })).default([]),
+    /** More receipts follow; the answer then leaves out the result until the last one is read. */
+    moreReceipts: z.boolean().default(false),
   }),
 });
 type Context = ToolContext & {
@@ -29,6 +48,9 @@ type Context = ToolContext & {
   locale?: string;
   timeZone?: string;
   reportProgress?: (message: string) => Promise<void>;
+  /** Relays a decision; the managed host consumes the linked platform approval before execution. */
+  requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+  reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
 };
 
 /** The tab only renders progress and approvals; server calls own all execution and resumption. */
@@ -49,54 +71,64 @@ export const runManagedCodeTool =
     await context.reportProgress?.(context.locale?.startsWith("de") ? "Ausführungshost verbinden" : "Connecting execution host");
     const app = await getApp("assistant");
     if (!app) throw new Error("Assistant code host is unavailable");
+    const issue = async (audience: { targetAppId: string; callingAppId: string; operation: string }) => {
+      // A token is signed before its request goes out, so a timed-out issuance
+      // never reached the host and is safe to repeat. Retry long enough for a
+      // stalled shared refresh to finish or fall back to the cached key. Every
+      // timeout used up a full attempt or ended a shared load, so this cannot spin.
+      const giveUpAt = Date.now() + IDENTITY_REFRESH_TIMEOUT_MS + ISSUANCE_TIMEOUT_MS;
+      while (true) {
+        try {
+          return await withActiveIdentitySigner(
+            "invocation",
+            (signer) =>
+              signInvocationToken({
+                ...audience,
+                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: context.signal, timeoutMs: ISSUANCE_TIMEOUT_MS },
+          );
+        } catch (error) {
+          if (context.signal.aborted || !(error instanceof DOMException && error.name === "TimeoutError")) throw error;
+          if (Date.now() < giveUpAt) continue;
+          log.warn("Code call gave up on identity issuance", { tool: name, error: error.message });
+          throw new Error(
+            context.locale?.startsWith("de")
+              ? "Der Identitätsdienst hat nicht rechtzeitig geantwortet. Prüfe, ob dieser Aufruf schon gestartet ist, bevor du ihn erneut ausführst."
+              : "The identity service did not respond in time. Check whether this call already started before running it again.",
+            { cause: error },
+          );
+        }
+      }
+    };
+    // Polls run every 250 ms for as long as the code runs. Reuse both tokens
+    // while they stay valid for at least 10 s, so a long run or an approval
+    // round trip does not depend on a fresh issuance for every poll.
+    const usable = (token: Awaited<ReturnType<typeof signInvocationToken>> | undefined) =>
+      token && token.claims.exp * 1000 - Date.now() >= 10_000 ? token : undefined;
+    let signed: Awaited<ReturnType<typeof signInvocationToken>> | undefined;
     let callback: Awaited<ReturnType<typeof signInvocationToken>> | undefined;
-    const request = async (decision?: { id: string; approved: boolean }) => {
+    const request = async ({ decision, receiptsAfter }: { decision?: { id: string; approved: boolean }; receiptsAfter: number }) => {
       context.signal.throwIfAborted();
       await authorizeCodeExecution(context.conversationId!, context.turnId!, actor.user.id);
-      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: context.signal, timeoutMs: 5000 },
-      );
-      if (!callback || callback.claims.exp * 1000 - Date.now() < 10_000) {
-        callback = await withActiveIdentitySigner(
-          "invocation",
-          (signer) =>
-            signInvocationToken({
-              targetAppId: "core",
-              callingAppId: "assistant",
-              operation: codeCapabilityOperation(context.conversationId!, context.turnId!),
-              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: context.signal, timeoutMs: 5000 },
-        );
-      }
+      signed = usable(signed) ?? (await issue({ targetAppId: "assistant", callingAppId: "core", operation: `tool:${name}` }));
+      callback =
+        usable(callback) ??
+        (await issue({
+          targetAppId: "core",
+          callingAppId: "assistant",
+          operation: codeCapabilityOperation(context.conversationId!, context.turnId!),
+        }));
       const headers = new Headers({ authorization: `Bearer ${signed.token}`, "content-type": "application/json" });
       headers.set(CODE_CAPABILITY_TOKEN_HEADER, callback.token);
       if (context.locale) headers.set(LOCALE_HEADER, context.locale);
@@ -112,7 +144,7 @@ export const runManagedCodeTool =
         signal: context.signal,
         body: JSON.stringify({
           conversationId: context.conversationId,
-          input: { turnId: context.turnId, callId: context.callId, name, args, ...(decision ? { decision } : {}) },
+          input: { turnId: context.turnId, callId: context.callId, name, args, receiptsAfter, ...(decision ? { decision } : {}) },
         }),
       });
       const body = await readBoundedJson(response, 256 * 1024);
@@ -120,29 +152,41 @@ export const runManagedCodeTool =
         throw new Error("Code host request failed; inspect the existing call before starting another execution");
       return Reply.parse(body.data).data;
     };
+    const backgroundApproval = async (): Promise<boolean> => {
+      throw new Error("Background code cannot request interactive approval. Update task grants in the normal chat.");
+    };
     return waitForManagedCodeCall(
       request,
-      runConfig.background
-        ? {
-            ...context,
-            requestApproval: async () => {
-              throw new Error("Background code cannot request interactive approval. Update task grants in the normal chat.");
-            },
-          }
-        : context,
+      runConfig.background ? { ...context, requestApproval: backgroundApproval, requestRelayedApproval: backgroundApproval } : context,
     );
   };
 
-/** Ordered reviews are replayed through Nessi before consuming a durable result. */
+/**
+ * Ordered reviews are replayed through Nessi before consuming a durable result. Each request a website approval let
+ * through is reported as a receipt as soon as the host names it, so the chat shows it with its full URL whatever the
+ * run's outcome. Receipts arrive page by page after the ones already reported.
+ */
 export async function waitForManagedCodeCall(
-  request: (decision?: { id: string; approved: boolean }) => Promise<z.infer<typeof Reply>["data"]>,
-  context: Pick<ToolContext, "signal" | "requestApproval"> & { locale?: string; reportProgress?: (message: string) => Promise<void> },
+  request: (input: { decision?: { id: string; approved: boolean }; receiptsAfter: number }) => Promise<z.input<typeof Reply>["data"]>,
+  context: Pick<ToolContext, "signal" | "requestApproval"> & {
+    locale?: string;
+    reportProgress?: (message: string) => Promise<void>;
+    /** Relays a decision; the managed host consumes the linked platform approval before execution. */
+    requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+    reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
+  },
 ): Promise<z.infer<ReturnType<typeof z.json>>> {
   const seen = new Set<string>();
   let lastPhase: string | undefined;
+  let receiptsAfter = 0;
   while (true) {
     context.signal.throwIfAborted();
-    const state = await request();
+    const state = Reply.shape.data.parse(await request({ receiptsAfter }));
+    if (state.receipts.length) {
+      await context.reportWebsiteReceipts?.(state.receipts.map((receipt, index) => ({ index: receiptsAfter + index, ...receipt })));
+      receiptsAfter += state.receipts.length;
+    }
+    if (state.moreReceipts) continue;
     if (state.phase && state.phase !== lastPhase) {
       lastPhase = state.phase;
       const labels = context.locale?.startsWith("de")
@@ -164,9 +208,13 @@ export async function waitForManagedCodeCall(
     // Skipping already resolved reviews would shift Nessi's child action IDs.
     for (const approval of state.approvals) {
       if (seen.has(approval.id)) continue;
-      const approved = await context.requestApproval(approval.message);
+      if (!context.requestRelayedApproval) throw new Error("Managed code approval requires a relay context");
+      const approved = await context.requestRelayedApproval(approval.message, {
+        approvalId: approval.approvalId,
+        target: approval.remember,
+      });
       seen.add(approval.id);
-      if (approval.decision === null) await request({ id: approval.id, approved });
+      if (approval.decision === null) await request({ decision: { id: approval.id, approved }, receiptsAfter });
     }
     if (state.status === "done") {
       // Nessi records a thrown error as a failed tool result the model can act on.

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

@@ -12,15 +12,6 @@ const ArtifactPath = z
   .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-]+$/)
@@ -39,15 +30,6 @@ const DatabaseSql = z.object({
   params: z.array(z.json()).max(1000).default([]),
 });
 
-const CodeWriteInput = Id.extend({
-  expectedRevision: z.number().int().positive(),
-  entry: ArtifactPath.optional().describe("index.html for an app with an interface, or the script that code_run executes."),
-  files: z
-    .array(z.union([ArtifactFile, z.object({ path: ArtifactPath, fromFile: AiFileReference }).strict()]))
-    .min(1)
-    .max(64),
-});
-
 const DbName = z
   .string()
   .regex(/^[A-Za-z][A-Za-z0-9_]*$/)
@@ -305,11 +287,33 @@ export const CODE_SOURCE_TOOLS = {
       "Create a private reusable App: an index.html interface with optional style.css and app.js, published actions and optional persistence. Starts with a minimal index.html. 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 }),
   },
+  // Source text stays top-level because some providers corrupt strings nested in arrays.
+  // Imports carry only references, so they keep an array and one review per batch.
   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,
+      "Save one complete source file against expectedRevision from code_read, code_create or the previous write. Other files stay unchanged. Write a multi-file app with one call per file and wait for each result, passing its returned revision as the next expectedRevision; calls sent together in one response share a stale revision, so all but the first fail with CONFLICT. Returns revision, the lines and length of every file, and compiler diagnostics for the saved state; an import of a file not yet written is reported as missing until it is saved. Never runs. Copy exact chat, Project or App files with code_import.",
+    input: Id.extend({
+      expectedRevision: z.number().int().positive().describe("Revision from code_read, code_create or the previous write."),
+      path: ArtifactPath.describe("Relative path of the file to save."),
+      content: z
+        .string()
+        .max(1024 * 1024)
+        .describe("Complete file content as plain text; read existing content before replacing it."),
+      entry: ArtifactPath.optional().describe("index.html for an app with an interface, or the script that code_run executes."),
+    }),
+  },
+  code_import: {
+    description:
+      "Atomically import exact chat, Project or App file references as UTF-8 source files against expectedRevision, without printing their bytes. One fresh review covers the whole batch because source may be shared or published. Use code_file_stat first; source file and bundle byte limits apply. Returns revision, the lines and length of every file, imported and diagnostics. Write source text with code_write.",
+    review: true,
+    input: Id.extend({
+      expectedRevision: z.number().int().positive(),
+      entry: ArtifactPath.optional().describe("index.html for an app with an interface, or the script that code_run executes."),
+      files: z
+        .array(z.object({ path: ArtifactPath, fromFile: AiFileReference }).strict())
+        .min(1)
+        .max(64),
+    }),
   },
   code_remove: {
     description:

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

@@ -21,6 +21,7 @@ import { defineAiTool } from "./tools";
 const WRITE_TOOLS = new Set([
   "code_create",
   "code_write",
+  "code_import",
   "code_remove",
   "code_update",
   "code_fork",
@@ -131,7 +132,7 @@ export function createCodeSourceTool(name: CodeSourceToolName) {
       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)) {
+    if ("review" in definition && definition.review) {
       const preview = z.object({ data: z.object({ message: z.string().min(1) }) }).parse((await send(true)).data).data;
       if (!authorizeDatabase && !(await context.requestApproval(preview.message)))
         throw new Error("The user declined this change. No mutation was sent.");
@@ -191,5 +192,6 @@ export const createCodeSourceTools = () => [
   createCodeSourceTool("code_update"),
   createCodeSourceTool("code_create"),
   createCodeSourceTool("code_write"),
+  createCodeSourceTool("code_import"),
   createCodeSourceTool("code_remove"),
 ];

package/src/ai/default-tool-contracts.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { chartDataIssue, chartDateTime, chartDrawingIssue } from "./chart-block";
 
 const ToneSchema = z.enum(["neutral", "blue", "teal", "green", "amber", "red"]);
 
@@ -14,6 +15,202 @@ export const CloudAiCardInputSchema = z.object({
 });
 export const CloudAiCardOutputSchema = z.object({ displayed: z.boolean() });
 
+/** The chart palette has eight colors; a ninth series would repeat one. */
+export const CLOUD_AI_CHART_MAX_SERIES = 8;
+/** Charts draw on a 480-unit wide plane: more values per list than units cannot be told apart. */
+export const CLOUD_AI_CHART_MAX_VALUES = 480;
+
+// Every chart schema is built by a function whose call is marked pure. Bundles that only use other exports of this
+// module, such as every Studio app frame through `@k2b/cloud/ai/browser`, can then leave the chart contract out.
+const chartParts = () => {
+  const ChartLabel = z.string().trim().min(1).max(80);
+  const ChartDate = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2})?)?$/)
+    .refine((value) => chartDateTime(value) !== undefined, "Not a valid date.");
+  const ChartPoint = z.object({
+    x: z
+      .union([z.number(), ChartDate])
+      .describe(
+        "A number, a date YYYY-MM-DD, or a date and time YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss in the user's time zone without an offset.",
+      ),
+    y: z.number(),
+  });
+  return {
+    ChartLabel,
+    ChartAxis: z.object({
+      label: ChartLabel.optional(),
+      domain: z.array(z.number()).length(2).optional().describe("Exact [min, max]; must contain every value."),
+      ticks: z.number().int().min(2).max(12).optional(),
+      scale: z.enum(["linear", "log"]).optional().describe("log needs values above zero."),
+    }),
+    ChartCategory: z.object({ label: ChartLabel, value: z.number() }),
+    ChartSlice: z.object({ label: ChartLabel, value: z.number().min(0) }),
+    ChartSeries: (points: z.ZodArray<typeof ChartPoint>) => z.object({ label: ChartLabel.optional(), data: points }),
+    ChartPoints: z.array(ChartPoint).max(CLOUD_AI_CHART_MAX_VALUES),
+    ChartBins: z
+      .union([
+        z.number().int().min(1).max(CLOUD_AI_CHART_MAX_VALUES),
+        z
+          .array(z.number())
+          .min(2)
+          .max(CLOUD_AI_CHART_MAX_VALUES + 1),
+      ])
+      .describe("A bin count or ascending bin edges."),
+    ChartCommon: {
+      title: z.string().trim().min(1).max(160),
+      subtitle: z.string().trim().min(1).max(300).optional().describe("Unit, period or source, shown under the title."),
+    },
+  };
+};
+
+const chartKinds = () => {
+  const { ChartAxis, ChartBins, ChartCategory, ChartCommon, ChartLabel, ChartPoints, ChartSeries, ChartSlice } = chartParts();
+  return z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("bar"),
+      ...ChartCommon,
+      data: z.array(ChartCategory).min(1).max(CLOUD_AI_CHART_MAX_VALUES),
+      yAxis: ChartAxis.optional(),
+      colorByBar: z.boolean().optional(),
+      showValues: z.boolean().optional(),
+      legend: z.boolean().optional(),
+    }),
+    z.object({
+      kind: z.literal("line"),
+      ...ChartCommon,
+      series: z
+        .array(
+          ChartSeries(ChartPoints.min(2, "A line needs at least two points per series; show single values as a bar or scatter chart.")),
+        )
+        .min(1)
+        .max(CLOUD_AI_CHART_MAX_SERIES),
+      xAxis: ChartAxis.optional(),
+      yAxis: ChartAxis.optional(),
+      legend: z.boolean().optional(),
+      area: z.boolean().optional(),
+      smooth: z.boolean().optional(),
+    }),
+    z.object({
+      kind: z.literal("scatter"),
+      ...ChartCommon,
+      series: z
+        .array(ChartSeries(ChartPoints.min(1)))
+        .min(1)
+        .max(CLOUD_AI_CHART_MAX_SERIES),
+      xAxis: ChartAxis.optional(),
+      yAxis: ChartAxis.optional(),
+      legend: z.boolean().optional(),
+    }),
+    z.object({
+      kind: z.enum(["pie", "donut"]),
+      ...ChartCommon,
+      data: z.array(ChartSlice).min(1).max(CLOUD_AI_CHART_MAX_VALUES),
+      legend: z.boolean().optional(),
+      showLabels: z.boolean().optional(),
+    }),
+    z.object({
+      kind: z.literal("histogram"),
+      ...ChartCommon,
+      data: z.array(z.number()).min(1).max(CLOUD_AI_CHART_MAX_VALUES),
+      bins: ChartBins.optional(),
+    }),
+    z.object({
+      kind: z.literal("gauge"),
+      ...ChartCommon,
+      value: z.number(),
+      min: z.number().optional(),
+      max: z.number().optional(),
+      label: ChartLabel.optional(),
+      unit: z.string().trim().min(1).max(12).optional(),
+    }),
+    z.object({
+      kind: z.literal("sparkline"),
+      ...ChartCommon,
+      data: z.array(z.number()).min(2).max(CLOUD_AI_CHART_MAX_VALUES),
+      area: z.boolean().optional(),
+    }),
+  ]);
+};
+
+/** Checks run on complete input only, so out-of-range input fails on its bounds before anything is computed or drawn. */
+const whenValid = { when: (payload: { issues: readonly unknown[] }) => payload.issues.length === 0 };
+
+const chartSchema = () =>
+  chartKinds().superRefine((chart, context) => {
+    const issue = chartDataIssue(chart);
+    if (issue) context.addIssue({ code: "custom", message: issue });
+  }, whenValid);
+const ChartSchema = /* @__PURE__ */ chartSchema();
+
+/** One chart as the renderers read it: a `cloud.chart()` kind with its options. */
+export type CloudAiChartInput = z.output<ReturnType<typeof chartKinds>>;
+
+/**
+ * Reads the arguments of a `chart` call without drawing them; undefined when they are not a chart. The tool schema
+ * has drawn them once already, so renderers draw only for display.
+ */
+export const parseCloudAiChartInput = (value: unknown): CloudAiChartInput | undefined => {
+  const parsed = ChartSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+};
+
+const chartInputSchema = () => {
+  const { ChartAxis, ChartBins, ChartCategory, ChartCommon, ChartLabel, ChartPoints, ChartSeries } = chartParts();
+  return z
+    .object({
+      kind: z.enum(["bar", "line", "scatter", "pie", "donut", "histogram", "gauge", "sparkline"]),
+      ...ChartCommon,
+      data: z
+        .union([z.array(ChartCategory).min(1).max(CLOUD_AI_CHART_MAX_VALUES), z.array(z.number()).min(1).max(CLOUD_AI_CHART_MAX_VALUES)])
+        .optional()
+        .describe("bar, pie, donut: [{ label, value }]. histogram: raw observations to count into bins. sparkline: values in order."),
+      series: z
+        .array(ChartSeries(ChartPoints.min(1)))
+        .min(1)
+        .max(CLOUD_AI_CHART_MAX_SERIES)
+        .optional()
+        .describe("line and scatter: one entry per series. A line needs at least two points per series."),
+      xAxis: ChartAxis.optional().describe("line and scatter."),
+      yAxis: ChartAxis.optional().describe("bar, line and scatter."),
+      legend: z
+        .boolean()
+        .optional()
+        .describe(
+          "bar (with colorByBar), line, scatter, pie, donut. Defaults to true for several series, and for pie and donut unless showLabels is set.",
+        ),
+      colorByBar: z.boolean().optional().describe("bar: one palette color per bar."),
+      showValues: z.boolean().optional().describe("bar: print each value on its bar."),
+      area: z.boolean().optional().describe("line and sparkline: fill the area under the line."),
+      smooth: z.boolean().optional().describe("line."),
+      showLabels: z.boolean().optional().describe("pie and donut: name each slice next to it instead of in a legend."),
+      bins: ChartBins.optional().describe("histogram: a bin count or ascending bin edges."),
+      value: z.number().optional().describe("gauge: the value to show."),
+      min: z.number().optional().describe("gauge: start of the scale, default 0."),
+      max: z.number().optional().describe("gauge: end of the scale, default 100."),
+      label: ChartLabel.optional().describe("gauge: what the value measures."),
+      unit: z.string().trim().min(1).max(12).optional().describe("gauge: unit after the value."),
+    })
+    .superRefine((value, context) => {
+      const parsed = ChartSchema.safeParse(value);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) context.addIssue({ code: "custom", message: issue.message, path: issue.path });
+        return;
+      }
+      const issue = chartDrawingIssue(parsed.data);
+      if (issue) context.addIssue({ code: "custom", message: issue });
+    }, whenValid);
+};
+
+/**
+ * The `cloud.chart()` options of Studio code as plain data, without `width`, `height` and `format` functions. Model
+ * providers accept only an object at the root of a tool schema, so every kind shares one object and each field names
+ * the kinds it belongs to; the kind's own rules are checked after that. Valid input also draws: values outside a
+ * domain, values at or below zero on a log axis, or a pie too small for its legend fail here instead of in the chat.
+ */
+export const CloudAiChartInputSchema = /* @__PURE__ */ chartInputSchema();
+export const CloudAiChartOutputSchema = z.object({ displayed: z.boolean() });
+
 const SurveyQuestionSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("single"),
@@ -100,6 +297,7 @@ export const CloudAiLocalBashOutputSchema = z.object({
 
 export type CloudAiCardInput = z.infer<typeof CloudAiCardInputSchema>;
 export type CloudAiCardOutput = z.infer<typeof CloudAiCardOutputSchema>;
+export type CloudAiChartOutput = z.infer<typeof CloudAiChartOutputSchema>;
 export type CloudAiSurveyInput = z.infer<typeof CloudAiSurveyInputSchema>;
 export type CloudAiSurveyOutput = z.infer<typeof CloudAiSurveyOutputSchema>;
 export type CloudAiTextEditorInput = z.infer<typeof CloudAiTextEditorInputSchema>;

package/src/ai/default-tools.ts

@@ -20,6 +20,8 @@ import { createCodeSourceTools } from "./code-source-tools";
 import {
   CloudAiCardInputSchema,
   CloudAiCardOutputSchema,
+  CloudAiChartInputSchema,
+  CloudAiChartOutputSchema,
   CloudAiLocalBashInputSchema,
   CloudAiLocalBashOutputSchema,
   CloudAiSurveyInputSchema,
@@ -48,6 +50,10 @@ export {
   CloudAiCardInputSchema,
   type CloudAiCardOutput,
   CloudAiCardOutputSchema,
+  type CloudAiChartInput,
+  CloudAiChartInputSchema,
+  type CloudAiChartOutput,
+  CloudAiChartOutputSchema,
   type CloudAiLocalBashInput,
   CloudAiLocalBashInputSchema,
   type CloudAiLocalBashOutput,
@@ -73,6 +79,18 @@ export const createCloudAiCardTool = () =>
     promptHint: "show one compact highlight card (metric, KPI, status) — not for tables, lists, or long text.",
   }).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.",
+    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.",
+  }).clientView();
+
 export const createCloudAiSurveyTool = () =>
   defineAiTool({
     name: "survey",
@@ -182,7 +200,12 @@ export const createCloudAiCodeTools = () => [
   }).server(runManagedCodeTool("code_export")),
 ];
 
-export const createDefaultCloudAiTools = () => [createAiTodoTool(), createCloudAiSurveyTool(), createCloudAiTextEditorTool()];
+export const createDefaultCloudAiTools = () => [
+  createAiTodoTool(),
+  createCloudAiSurveyTool(),
+  createCloudAiTextEditorTool(),
+  createCloudAiChartTool(),
+];
 
 /** Built-ins advertised through discovery and loaded only when needed. */
 export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
@@ -190,6 +213,7 @@ export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
   ...Object.keys(CODE_SOURCE_TOOLS),
   "survey",
   "text_editor",
+  "chart",
   "list_files",
   "write_file",
   "markdown_to_pdf",