@k2b/cloud 0.29.0 → 0.30.0

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

package/src/ai/executor.ts

@@ -1574,29 +1574,12 @@ export class AiTurnExecutor {
     const approvalScope = capabilityApprovalScope ?? aiToolApprovalScope(toolName, approvalPolicy);
     const allowAlways = allowRememberedApprovals && (capabilityApprovalScope !== undefined || aiToolAllowsAlways(approvalPolicy));
 
-    const runConfig = await aiConversations.getTurnRunConfig({ conversationId, turnId });
-    if (runConfig?.kind !== "compact" && (runConfig?.background || runConfig?.mandate)) {
-      input.onBackgroundBlocked?.(
-        `Background operation ${toolName} requires ${event.kind === "client_tool" ? "an interactive browser" : "interactive approval"}. Update the task in the normal chat.`,
-      );
-      if (event.kind === "client_tool")
-        loop.push({
-          type: "tool_result",
-          callId: event.callId,
-          result: { error: "This operation requires an interactive browser and is unavailable in a background run." },
-        });
-      else loop.push({ type: "approval_response", callId: event.callId, approved: false });
-      return false;
-    }
-
-    // Display-only client_view tools (e.g. cards) never need user input — resolve
-    // inline and keep streaming instead of taking a full suspend/continuation trip.
+    // Display-only client_view tools (cards, charts) need neither a browser nor input: Cloud answers them itself, in
+    // background runs too, whose transcript shows them later. The block goes from running straight to completed:
+    // a published awaiting_client would read as an open request to clients and remount the result in the chat.
+    // nessi emits no tool_execution_end for client tools, so Cloud ends the call itself.
     if (frontendMode === "client_view") {
-      await pipeline.apply(event);
       loop.push({ type: "tool_result", callId: event.callId, result: { displayed: true } });
-      // Mark the block completed immediately: nessi emits no tool_execution_end
-      // for client tools, and a block stuck in awaiting_client would look like
-      // an open action request if the turn suspends for another tool later.
       await pipeline.apply({
         type: "tool_execution_end",
         callId: event.callId,
@@ -1610,6 +1593,21 @@ export class AiTurnExecutor {
       return false;
     }
 
+    const runConfig = await aiConversations.getTurnRunConfig({ conversationId, turnId });
+    if (runConfig?.kind !== "compact" && (runConfig?.background || runConfig?.mandate)) {
+      input.onBackgroundBlocked?.(
+        `Background operation ${toolName} requires ${event.kind === "client_tool" ? "an interactive browser" : "interactive approval"}. Update the task in the normal chat.`,
+      );
+      if (event.kind === "client_tool")
+        loop.push({
+          type: "tool_result",
+          callId: event.callId,
+          result: { error: "This operation requires an interactive browser and is unavailable in a background run." },
+        });
+      else loop.push({ type: "approval_response", callId: event.callId, approved: false });
+      return false;
+    }
+
     // Remembered approvals resolve inline too.
     if (event.kind !== "client_tool" && allowAlways && approvalContext) {
       const remembered = await hasRememberedAiToolApproval(approvalContext, { toolName, approvalScope }).catch(() => false);

package/src/ai/index.ts

@@ -1,3 +1,4 @@
+export { type AiAppSkillIssue, aiAppSkills, appSkillsRegistryState, reconcileAppSkills } from "./app-skill-store";
 export { type AiApprovalPreferenceRoutes, type AiApprovalPreferenceView, createAiApprovalPreferenceRoutes } from "./approval-routes";
 export {
   type AiToolApprovalContext,
@@ -47,11 +48,17 @@ export { authorizeCodeExecution } from "./code-execution";
 export { CODE_SOURCE_TOOLS, type CodeSourceToolName } from "./code-source-contracts";
 export { listAiCredentialProfileIds } from "./credentials";
 export {
+  CLOUD_AI_CHART_MAX_SERIES,
+  CLOUD_AI_CHART_MAX_VALUES,
   CLOUD_AI_TEXT_EDITOR_MAX_CHARS,
   type CloudAiCardInput,
   CloudAiCardInputSchema,
   type CloudAiCardOutput,
   CloudAiCardOutputSchema,
+  type CloudAiChartInput,
+  CloudAiChartInputSchema,
+  type CloudAiChartOutput,
+  CloudAiChartOutputSchema,
   type CloudAiLocalBashInput,
   CloudAiLocalBashInputSchema,
   type CloudAiLocalBashOutput,
@@ -64,6 +71,7 @@ export {
   CloudAiTextEditorInputSchema,
   type CloudAiTextEditorOutput,
   CloudAiTextEditorOutputSchema,
+  parseCloudAiChartInput,
 } from "./default-tool-contracts";
 export {
   type AiChatEnrichment,
@@ -258,6 +266,7 @@ export {
   type AiSkillAccess,
   type AiSkillAdminListItem,
   type AiSkillAdminSummary,
+  AiSkillAppForbiddenError,
   AiSkillInputError,
   AiSkillLastAdminError,
   type AiSkillPermission,
@@ -265,7 +274,6 @@ export {
   AiSkillRevisionConflictError,
   type AiSkillSummary,
   aiSkills,
-  seedCloudAiSkills,
 } from "./skills";
 export { type AiSkillsRoutes, aiSkillsRoutes } from "./skills-routes";
 export { aiConversations } from "./store";

package/src/ai/migrate.ts

@@ -1620,18 +1620,65 @@ export const migrateCloudAi = async (): Promise<void> => {
   await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_skills_name ON ai.skills(name)`.simple();
   await sql`ALTER TABLE ai.skills ADD COLUMN IF NOT EXISTS managed_key TEXT`.simple();
   await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_skills_managed_key ON ai.skills(managed_key) WHERE managed_key IS NOT NULL`.simple();
-  await sql`
-    CREATE TABLE IF NOT EXISTS ai.skill_seeds (
-      key TEXT PRIMARY KEY,
-      seeded_at TIMESTAMPTZ NOT NULL DEFAULT now()
-    )
-  `.simple();
-  // A seed's UUID deliberately has no FK: it is a durable deletion tombstone.
-  await sql`ALTER TABLE ai.skill_seeds ADD COLUMN IF NOT EXISTS skill_id UUID`.simple();
-  await sql`ALTER TABLE ai.skill_seeds ADD COLUMN IF NOT EXISTS catalog_version INTEGER NOT NULL DEFAULT 0`.simple();
-  await sql`ALTER TABLE ai.skills ADD COLUMN IF NOT EXISTS template_id TEXT,
-    ADD COLUMN IF NOT EXISTS template_version INTEGER, ADD COLUMN IF NOT EXISTS template_hash TEXT`.simple();
-  await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_skills_template_id ON ai.skills(template_id) WHERE template_id IS NOT NULL`.simple();
+  await sql.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext('cloud:ai:app-skills'))`;
+    await tx`CREATE TABLE IF NOT EXISTS ai.app_skill_catalogs (
+      app_id text NOT NULL, manifest_hash text NOT NULL, skills jsonb NOT NULL,
+      created_at timestamptz NOT NULL DEFAULT now(), last_seen_at timestamptz NOT NULL DEFAULT now(),
+      PRIMARY KEY (app_id, manifest_hash)
+    )`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS idx_ai_app_skill_catalogs_last_seen ON ai.app_skill_catalogs(last_seen_at)`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS ai.app_skills (
+      key text PRIMARY KEY, app_id text NOT NULL, app_name text NOT NULL, name text NOT NULL,
+      skill_id uuid NULL, source jsonb NULL, source_hash text NULL, applied_hash text NULL,
+      manifest_hash text NULL, available boolean NOT NULL DEFAULT false, required_roles text[] NULL,
+      conflict text NULL CHECK (conflict IN ('name_taken', 'invalid')),
+      updated_at timestamptz NOT NULL DEFAULT now()
+    )`.simple();
+    await tx`CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_app_skills_skill ON ai.app_skills(skill_id) WHERE skill_id IS NOT NULL`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS idx_ai_app_skills_app ON ai.app_skills(app_id)`.simple();
+    // Adopt only durable seed associations. A missing linked row remains a deletion tombstone.
+    await tx`DO $$ BEGIN
+      IF to_regclass('ai.skill_seeds') IS NOT NULL THEN
+        -- Installations from before seed links lack these columns; their seeds adopt nothing.
+        ALTER TABLE ai.skill_seeds ADD COLUMN IF NOT EXISTS skill_id uuid;
+        ALTER TABLE ai.skills ADD COLUMN IF NOT EXISTS template_id text, ADD COLUMN IF NOT EXISTS template_hash text;
+        -- A seed never installed its Skill again. An unlinked seed whose name is free stays deleted through a link
+        -- to no Skill; when a Skill holds the name, it stays unlinked and an administrator decides who owns it.
+        INSERT INTO ai.app_skills(key, app_id, app_name, name, skill_id, applied_hash)
+        SELECT 'app:' || mapping.app_id || '/' || mapping.name, mapping.app_id, mapping.app_name, mapping.name,
+          CASE WHEN seed.skill_id IS NOT NULL THEN seed.skill_id
+            WHEN NOT EXISTS (SELECT 1 FROM ai.skills named WHERE named.name = mapping.name) THEN gen_random_uuid() END,
+          CASE WHEN skill.template_id = seed.key THEN skill.template_hash ELSE NULL END
+        FROM ai.skill_seeds seed
+        JOIN (VALUES
+          ('grids:cloud-grids', 'grids', 'Grids', 'cloud-grids'),
+          ('assistant:cloud-assistant', 'assistant', 'Assistant', 'cloud-assistant'),
+          ('assistant:scheduled-tasks', 'assistant', 'Assistant', 'scheduled-tasks'),
+          ('core:skill-creator', 'assistant', 'Assistant', 'skill-creator'),
+          ('mail:cloud-mail', 'mail', 'Mail', 'cloud-mail'),
+          ('notebooks:cloud-notebooks', 'notebooks', 'Notebooks', 'cloud-notebooks'),
+          ('contacts:cloud-contacts', 'contacts', 'Contacts', 'cloud-contacts'),
+          ('spaces:cloud-spaces', 'spaces', 'Spaces', 'cloud-spaces'),
+          ('weather:cloud-weather', 'weather', 'Weather', 'cloud-weather'),
+          ('assistant:code-mode', 'assistant', 'Assistant', 'assistant-code-mode'),
+          ('assistant:data-analysis', 'assistant', 'Assistant', 'assistant-data-analysis')
+        ) mapping(seed_key, app_id, app_name, name) ON mapping.seed_key = seed.key
+        LEFT JOIN ai.skills skill ON skill.id = seed.skill_id
+        WHERE true
+        ON CONFLICT (key) DO NOTHING;
+        DROP TABLE ai.skill_seeds;
+      END IF;
+    END $$`.simple();
+    // Only alter ai.skills once: ALTER TABLE takes an exclusive lock even when nothing changes.
+    await tx`DO $$ BEGIN
+      IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'ai' AND table_name = 'skills'
+        AND column_name IN ('template_id', 'template_version', 'template_hash')) THEN
+        ALTER TABLE ai.skills DROP COLUMN IF EXISTS template_id,
+          DROP COLUMN IF EXISTS template_version, DROP COLUMN IF EXISTS template_hash;
+      END IF;
+    END $$`.simple();
+  });
   await backfillAiShortIds(
     "idx_ai_skills_short_id",
     await sql<{ id: string }[]>`SELECT id FROM ai.skills WHERE short_id IS NULL`,

package/src/ai/protocol.ts

@@ -45,7 +45,10 @@ export type AiTurnBlock =
       isError?: boolean;
       /** Present while status is awaiting_approval. */
       approval?: { message?: string; review?: CapabilityActionReview; allowAlways: boolean };
-      /** The user approved this call in the chat; the decided approval stays visible as a receipt. */
+      /**
+       * `true` once the user approved this call in the chat; `false` when its turn ended while the approval still
+       * waited. Either way the approval stays visible as a receipt.
+       */
       approved?: boolean;
       /** Present for frontend tools. */
       frontendMode?: AiFrontendToolMode;
@@ -224,7 +227,7 @@ export const buildBlocksFromMessages = (
     meta?: {
       steerId?: string;
       toolPresentations?: Record<string, AiToolPresentation>;
-      toolOutcomes?: Record<string, "rejected" | "approved">;
+      toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
     } | null;
   }[],
 ): AiTurnBlock[] => {
@@ -239,6 +242,7 @@ export const buildBlocksFromMessages = (
         } else if (block.type === "thinking") {
           blocks.push({ id: messageBlockId(seq, index), kind: "thinking", text: block.thinking });
         } else if (block.type === "tool_call") {
+          const outcome = meta?.toolOutcomes?.[block.id];
           toolIndex.set(block.id, blocks.length);
           blocks.push({
             id: toolBlockId(block.id),
@@ -248,8 +252,9 @@ export const buildBlocksFromMessages = (
             args: block.args,
             status: "running",
             presentation: meta?.toolPresentations?.[block.id],
-            // A turn that ended before an approved call returned records the approval on the call's message.
-            ...(meta?.toolOutcomes?.[block.id] === "approved" ? { approved: true } : {}),
+            // A turn that ended before an approved call returned records the approval on the call's message, and an
+            // approval it left waiting as expired.
+            ...(outcome === "approved" || outcome === "expired" ? { approved: outcome === "approved" } : {}),
           });
         }
       });

package/src/ai/runtime-tools.ts

@@ -2,6 +2,7 @@ export { CloudAiTranscribeAudioInputSchema, CloudAiTranscribeAudioOutputSchema,
 export {
   CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES,
   createCloudAiCardTool,
+  createCloudAiChartTool,
   createCloudAiCodeTools,
   createCloudAiLocalBashTool,
   createCloudAiSurveyTool,

package/src/ai/skill-content.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import {
+  type AiSkillDocument,
+  type AiSkillExtraFrontmatter,
+  type AiSkillReferenceInput,
+  validateAiSkillDescription,
+  validateAiSkillExtraFrontmatter,
+  validateAiSkillInstructions,
+  validateAiSkillName,
+  validateAiSkillReferences,
+} from "./skill-format";
+
+export type AiSkillContent = AiSkillDocument & { references: readonly AiSkillReferenceInput[] };
+
+export const validateSkillContent = (input: {
+  name: string;
+  description: string;
+  instructions: string;
+  extraFrontmatter?: AiSkillExtraFrontmatter;
+  references?: readonly AiSkillReferenceInput[];
+}): AiSkillContent => ({
+  name: validateAiSkillName(input.name),
+  description: validateAiSkillDescription(input.description),
+  instructions: validateAiSkillInstructions(input.instructions),
+  extraFrontmatter: validateAiSkillExtraFrontmatter(input.extraFrontmatter),
+  references: validateAiSkillReferences(input.references ?? []).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+});
+
+// Keep the former template hash algorithm: key order and reference insertion order are immaterial.
+export const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object")
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(",")}}`;
+  const result = JSON.stringify(value);
+  if (result === undefined) throw new Error("Skill content must be JSON.");
+  return result;
+};
+export const canonicalHash = (value: unknown): string => createHash("sha256").update(canonicalJson(value)).digest("hex");
+export const contentHash = (fields: AiSkillContent): string =>
+  canonicalHash({
+    name: fields.name,
+    description: fields.description,
+    instructions: fields.instructions,
+    extraFrontmatter: fields.extraFrontmatter,
+    references: [...fields.references].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+  });
+
+/** How an installed app Skill relates to its app: the app's version, an administrator's override, or an override with a newer app version. */
+export type AppSkillStatus = "current" | "modified" | "update_available";
+export const appSkillStatus = (rowHash: string, sourceHash: string | null, appliedHash: string | null): AppSkillStatus =>
+  rowHash === (sourceHash ?? appliedHash) ? "current" : sourceHash === null || sourceHash === appliedHash ? "modified" : "update_available";