@k2b/cloud 0.37.0 → 0.38.0

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

@@ -59,6 +59,9 @@ export const cloudAiChartKindSchema = () =>
 
 const chartParts = (limits = true) => {
   const ChartLabel = limits ? z.string().trim().min(1).max(80) : z.union([z.string(), z.number().transform(String)]);
+  const ChartTooltip = z
+    .strictObject({ label: ChartLabel.optional(), format: cloudAiNumberFormatSchema().optional() })
+    .describe("All kinds: what tooltips and the data table call the value and how they format it; axes keep their own format.");
   // Missing observations stay numeric so the renderer can omit them with its finite-value checks.
   const ChartNumber = limits
     ? z.number()
@@ -96,6 +99,7 @@ const chartParts = (limits = true) => {
   );
   return {
     ChartLabel,
+    ChartTooltip,
     ChartNumber,
     list,
     ChartReferences,
@@ -148,6 +152,7 @@ const chartKinds = (limits = true) => {
     ChartBins,
     ChartCategory,
     ChartCommon,
+    ChartTooltip,
     ChartLabel,
     ChartPoints,
     ChartSeries,
@@ -159,11 +164,12 @@ const chartKinds = (limits = true) => {
     ChartCell,
     ChartBarGauge,
   } = chartParts(limits);
+  const ChartKindCommon = { ...ChartCommon, tooltip: ChartTooltip.optional() };
   const numberFormat = cloudAiNumberFormatSchema();
   return z.discriminatedUnion("kind", [
     z.object({
       kind: z.literal("bar"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartCategory, 1, CLOUD_AI_CHART_MAX_VALUES),
       yAxis: ChartAxis.optional(),
       colorByBar: z.boolean().optional(),
@@ -173,7 +179,7 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("line"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       series: list(
         ChartSeries(
           limits
@@ -192,7 +198,7 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("scatter"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       series: list(ChartSeries(limits ? ChartPoints.min(1) : ChartPoints), 1, CLOUD_AI_CHART_MAX_SERIES),
       xAxis: ChartAxis.optional(),
       yAxis: ChartAxis.optional(),
@@ -201,7 +207,7 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.enum(["pie", "donut"]),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartSlice, 1, CLOUD_AI_CHART_MAX_VALUES),
       legend: z.boolean().optional(),
       showLabels: z.boolean().optional(),
@@ -209,14 +215,14 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("histogram"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartNumber, 1, CLOUD_AI_CHART_MAX_VALUES),
       bins: ChartBins.optional(),
       references: ChartReferences.optional(),
     }),
     z.object({
       kind: z.literal("gauge"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       value: ChartNumber,
       min: z.number().optional(),
       max: z.number().optional(),
@@ -227,20 +233,20 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("sparkline"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartNumber, 2, CLOUD_AI_CHART_MAX_VALUES),
       area: z.boolean().optional(),
     }),
     z.object({
       kind: z.literal("boxplot"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartBox, 1, CLOUD_AI_CHART_MAX_VALUES),
       yAxis: ChartAxis.optional(),
       references: ChartReferences.optional(),
     }),
     z.object({
       kind: z.literal("heatmap"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       data: list(ChartCell, 1, CLOUD_AI_VIEW_MAX_MARKS),
       format: numberFormat.optional(),
       showValues: z.boolean().optional(),
@@ -249,7 +255,7 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("barGauge"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       // The shared renderer draws 280 units high and a bar gauge row is 28 units, so 8 rows fit without a taller drawing.
       data: list(ChartBarGauge, 1, CLOUD_AI_CHART_MAX_SERIES, `Use at most ${CLOUD_AI_CHART_MAX_SERIES} bar gauge items.`),
       min: z.number().optional(),
@@ -260,7 +266,7 @@ const chartKinds = (limits = true) => {
     }),
     z.object({
       kind: z.literal("stat"),
-      ...ChartCommon,
+      ...ChartKindCommon,
       value: ChartNumber,
       format: numberFormat.optional(),
       unit: ChartUnit.optional(),
@@ -336,11 +342,22 @@ export const cloudAiGroupSchema = () => {
 };
 
 const flatChartSchema = () => {
-  const { ChartAxis, ChartBins, ChartCommon, ChartLabel, ChartPoints, ChartSeries, ChartReferences, ChartThresholds, ChartUnit } =
-    chartParts();
+  const {
+    ChartAxis,
+    ChartBins,
+    ChartCommon,
+    ChartLabel,
+    ChartPoints,
+    ChartSeries,
+    ChartReferences,
+    ChartThresholds,
+    ChartUnit,
+    ChartTooltip,
+  } = chartParts();
   return z.object({
     kind: cloudAiChartKindSchema().optional().describe("Single charts: kind. Omit for groups."),
     ...ChartCommon,
+    tooltip: ChartTooltip.optional(),
     // One item object preserves every kind's fields before canonical validation; unions would strip overlapping items.
     data: z
       .union([

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

@@ -1,9 +1,11 @@
 import type { ClientRequest, IncomingHttpHeaders, IncomingMessage } from "node:http";
 import { type RequestOptions as HttpsRequestOptions, request as httpsRequest } from "node:https";
 import { z } from "zod";
+import { DOCUMENT_EXTRACTION_MAX_INPUT_BYTES, DOCUMENT_EXTRACTION_MAX_OUTPUT_BYTES } from "../services/document-extraction";
 import { type PublicNetworkAddress, resolvePublicNetworkAddresses } from "../services/network-security";
 import { AI_FILES_MAX_FILE_BYTES_DEFAULT, aiFileStore, guessAiMediaType, normalizeAiFilePath } from "./files-store";
 import { authorizeWebRead } from "./firecrawl-tools";
+import { htmlToReadableMarkdown } from "./readable-html";
 import { defineAiTool } from "./tools";
 
 const FETCH_FILE_MAX_REDIRECTS = 5;
@@ -38,6 +40,7 @@ export const CloudAiFetchFileOutputSchema = z.object({
   size: z.number().int().nonnegative(),
   mediaType: z.string(),
   url: z.string().url(),
+  readable: z.object({ path: z.string(), size: z.number().int().nonnegative(), note: z.string() }).optional(),
 });
 
 const publicHttpsUrl = (rawUrl: string): URL => {
@@ -309,20 +312,51 @@ export const runCloudAiFetchFile = async (
     bytes: downloaded.bytes,
     mediaType: responseMediaType(downloaded.headers, path),
   });
-  return { path: stat.path, size: stat.size, mediaType: stat.mediaType, url: downloaded.url.toString() };
+  const result = { path: stat.path, size: stat.size, mediaType: stat.mediaType, url: downloaded.url.toString() };
+  if (stat.mediaType !== "text/html" && stat.mediaType !== "application/xhtml+xml") return result;
+  try {
+    const contentType = downloaded.headers["content-type"];
+    const markdown = await htmlToReadableMarkdown(downloaded.bytes, {
+      baseUrl: downloaded.url,
+      contentType: Array.isArray(contentType) ? contentType[0] : contentType,
+      // The same bounds as any other document converted to Markdown for the model.
+      maxInputBytes: DOCUMENT_EXTRACTION_MAX_INPUT_BYTES,
+      maxBytes: DOCUMENT_EXTRACTION_MAX_OUTPUT_BYTES,
+      signal: context.signal,
+    });
+    if (!markdown) return result;
+    const basename = stat.path.slice(stat.path.lastIndexOf("/") + 1).replace(/\.(?:html?|xhtml|xht)$/i, "");
+    const readable = await aiFileStore.createAssistantFile({
+      conversationId: context.conversationId,
+      path: `/imports/${basename}.md`,
+      bytes: new TextEncoder().encode(markdown),
+      mediaType: "text/markdown",
+    });
+    return {
+      ...result,
+      readable: {
+        path: readable.path,
+        size: readable.size,
+        note: "Readable Markdown of the page's main content. Read this path first; use the raw path only when you need the HTML markup.",
+      },
+    };
+  } catch {
+    // The raw import already succeeded; a readable copy is best-effort, including on cancellation.
+    return result;
+  }
 };
 
 export const createCloudAiFetchFileTool = (dependencies: FetchFileDependencies = {}) =>
   defineAiTool({
     name: "fetch_file",
     description:
-      "Download one exact public HTTPS file URL into the current conversation. Use this for images, raw GitHub files, documents, or other source files the user wants inspected. This does not browse or clone repositories, authenticate to websites, or fetch private network targets. After downloading, inspect the returned path with read_file or view_image and use present when the user should receive the file.",
+      "Download one exact public HTTPS file URL into this conversation for inspection. Supports images, documents, raw repository files, and web pages; no repository browsing, website authentication, or private network access. For web pages, read readable.path (main-content Markdown) first with read_file when returned; use raw HTML only when markup matters. Inspect other returned paths with read_file or view_image and use present to deliver files.",
     inputSchema: CloudAiFetchFileInputSchema,
     outputSchema: CloudAiFetchFileOutputSchema,
     approval: "never",
     timeoutMs: 90_000,
     promptHint:
-      "fetch an exact public HTTPS source file into the chat when the user provides a file link; inspect it with read_file or view_image and present it when useful.",
+      "fetch an exact public HTTPS source file into the chat; for web pages read readable.path (main-content Markdown) first with read_file when returned; use raw HTML only when markup matters. Inspect other files with read_file or view_image; present when useful.",
   }).server(async (input, context) => {
     const url = publicHttpsUrl(input.url);
     const allowedForChat = await authorizeWebRead("file", url.toString(), context);

package/src/ai/migrate.ts

@@ -516,6 +516,12 @@ export const migrateCloudAi = async (): Promise<void> => {
     WHERE status = 'completed' AND run_config->>'kind' = 'chat'
   `.simple();
 
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_turns_background_finished
+    ON ai.turns(completed_at, id)
+    WHERE run_config ? 'background' AND status IN ('completed', 'failed', 'aborted')
+  `.simple();
+
   await sql`
     CREATE TABLE IF NOT EXISTS ai.conversation_resource_refs (
       conversation_id UUID NOT NULL REFERENCES ai.conversations(id) ON DELETE CASCADE,
@@ -999,12 +1005,23 @@ export const migrateCloudAi = async (): Promise<void> => {
     ON ai.chat_task_occurrences(request_key)
   `.simple();
 
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_chat_task_occurrences_turn
+    ON ai.chat_task_occurrences(turn_id)
+  `.simple();
+
   await sql`
     CREATE INDEX IF NOT EXISTS idx_ai_chat_task_occurrences_queued
     ON ai.chat_task_occurrences(created_at ASC, id ASC)
     WHERE state = 'queued'
   `.simple();
 
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_chat_task_occurrences_finished
+    ON ai.chat_task_occurrences(completed_at, id)
+    WHERE state IN ('completed', 'failed')
+  `.simple();
+
   await sql`
     CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_chat_task_occurrences_active_task
     ON ai.chat_task_occurrences(task_id)
@@ -1273,7 +1290,7 @@ export const migrateCloudAi = async (): Promise<void> => {
       CONSTRAINT ai_memory_learning_runs_kind_check CHECK (run_kind IN ('turn', 'workflow')),
       CONSTRAINT ai_memory_learning_runs_evidence_check CHECK (
         (run_kind = 'turn' AND evidence_key IS NULL)
-        OR (run_kind = 'workflow' AND turn_id IS NOT NULL AND evidence_key IS NOT NULL)
+        OR (run_kind = 'workflow' AND evidence_key IS NOT NULL)
       ),
       CONSTRAINT ai_memory_learning_runs_changes_check CHECK (jsonb_typeof(changes) = 'array')
     )
@@ -1299,7 +1316,7 @@ export const migrateCloudAi = async (): Promise<void> => {
   await sql`
     ALTER TABLE ai.memory_learning_runs ADD CONSTRAINT ai_memory_learning_runs_evidence_check CHECK (
       (run_kind = 'turn' AND evidence_key IS NULL)
-      OR (run_kind = 'workflow' AND turn_id IS NOT NULL AND evidence_key IS NOT NULL)
+      OR (run_kind = 'workflow' AND evidence_key IS NOT NULL)
     )
   `.simple();
   await sql`