@k2b/cloud 0.45.0 → 0.47.0

package/src/ai/chat/message-utils.ts

@@ -327,6 +327,7 @@ export const displayToolName = (name: string, locale: string) => {
 
 const BUILT_IN_TOOL_ICONS = new Map<string, string>([
   ["card", "ti ti-layout-cards"],
+  ["map", "ti ti-map-search"],
   ["cloud_card", "ti ti-layout-cards"],
   ["chart", "ti ti-chart-bar"],
   ["survey", "ti ti-forms"],

package/src/ai/chat/tool-names.ts

@@ -10,6 +10,7 @@ const toolNames = i18n.define({
     en: {
       calculate: "Calculate",
       card: "Card",
+      map: "Places and maps",
       chart: "Chart",
       survey: "Survey",
       text_editor: "Text editor",
@@ -86,6 +87,7 @@ const toolNames = i18n.define({
     de: {
       calculate: "Rechnen",
       card: "Karte",
+      map: "Orte und Karten",
       chart: "Diagramm",
       survey: "Umfrage",
       text_editor: "Texteditor",

package/src/ai/chat/turn-layout.ts

@@ -70,11 +70,12 @@ const resultTarget = (block: ToolBlock): string | null => {
 };
 
 const isResult = (block: ToolBlock, phase: AiTurnPhase, codePresentations: boolean): boolean => {
+  if (block.name === "map" && block.result && typeof block.result === "object" && "map" in block.result) return true;
   if (isFailedTool(block) || block.status === "rejected" || block.status === "awaiting_approval") return false;
   // A running delivery reserves its place once its arguments arrived: a new version of an earlier result must find the
   // earlier place before it takes one of its own.
   const delivered = block.status === "completed" || (live(phase) && block.status === "running" && block.args !== undefined);
-  if (block.name === "present" || isCardToolName(block.name) || isChartToolName(block.name)) return delivered;
+  if (block.name === "map" || block.name === "present" || isCardToolName(block.name) || isChartToolName(block.name)) return delivered;
   if (block.name === "code_present") return codePresentations && delivered;
   return hasCapabilityTable(block);
 };

package/src/ai/chat/turn-view.tsx

@@ -23,6 +23,7 @@ import { CompactionBlockView, CompactToolRow, SurveyToolView, TextEditorToolView
 import { CapabilityTablePreview } from "./capability-table";
 import { CloudChartBlock } from "./chart-block";
 import { PresentToolBlock } from "./file-tools";
+import { AiMapToolBlock } from "./map-widget";
 import { useAiChatActions } from "./message-actions";
 import { aiToolIcon, displayToolName, isCardToolName, isChartToolName, isRecord, isSurveyToolName } from "./message-utils";
 import { aiChatMessages } from "./messages";
@@ -438,6 +439,9 @@ function AiTurnResultView(props: { result: Accessor<AiTurnResult | undefined>; r
     <Show when={block()}>
       {(current) => (
         <Switch>
+          <Match when={current().name === "map"}>
+            <AiMapToolBlock block={current()} />
+          </Match>
           <Match when={current().name === "present"}>
             <PresentToolBlock block={current()} />
           </Match>
@@ -653,7 +657,18 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
   const chatActions = useAiChatActions();
   const layout = () => props.segment().layout;
   const results = createMemo(() => new Map(layout().results.map((result) => [result.id, result])));
-  const resultIds = createMemo(() => [...results().keys()]);
+  const isMapFollowup = (id: string) => {
+    const block = results().get(id)?.block;
+    return (
+      block?.name === "map" &&
+      typeof block.result === "object" &&
+      block.result !== null &&
+      "anchor" in block.result &&
+      block.result.anchor === false
+    );
+  };
+  const resultIds = createMemo(() => [...results().keys()].filter((id) => !isMapFollowup(id)));
+  const mapFollowupIds = createMemo(() => [...results().keys()].filter(isMapFollowup));
   const actions = createMemo(() => new Map(layout().actions.map((action) => [action.id, action])));
   const actionIds = createMemo(() => [...actions().keys()]);
   const live = () => isLive(props.segment().phase);
@@ -709,6 +724,7 @@ export function AiTurnView(props: { segment: Accessor<AiTurnSegment>; disclosure
             earlier={() => props.segment().earlier}
           />
         </Show>
+        <For each={mapFollowupIds()}>{(id) => <AiTurnResultView result={() => results().get(id)} receipt={() => false} />}</For>
         <Show when={props.segment().scheduledTask?.stop ? undefined : props.segment().scheduledTask?.reason}>
           {(reason) => (
             <Chat.Activity

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { chartDataIssue, chartDateTime, chartDrawingIssue, chartSteppingIssue, cloudAiChartMarks } from "./chart-block";
+import { chartDataIssue, chartDrawingIssue, cloudAiChartMarks } from "./chart-block";
 
 const ToneSchema = z.enum(["neutral", "blue", "teal", "green", "amber", "red"]);
 
@@ -28,261 +28,30 @@ export const CLOUD_AI_VIEW_MAX_MARKS = CLOUD_AI_CHART_MAX_SERIES * CLOUD_AI_CHAR
  */
 export const CLOUD_AI_GROUP_MAX_CHARTS = 6;
 
-// Every chart schema is built by a function whose call is marked pure, so a bundle that imports neither chart contract
-// leaves them out. App frames include the app contract through `cloud.chart()`.
-export const cloudAiNumberFormatSchema = () =>
-  z
-    .strictObject({
-      style: z.enum(["number", "percent", "currency"]).optional(),
-      currency: z
-        .string()
-        .regex(/^[A-Z]{3}$/)
-        .optional(),
-      // Units fit after a value in the shared renderer, like the existing gauge unit.
-      unit: z.string().trim().min(1).max(12).optional(),
-      // Intl.NumberFormat supports this precision; table formats already use 0..10.
-      decimals: z.number().int().min(0).max(10).optional(),
-      compact: z.boolean().optional(),
-    })
-    .superRefine((value, ctx) => {
-      if ((value.style === "currency") !== (value.currency !== undefined))
-        ctx.addIssue({ code: "custom", path: ["currency"], message: "Currency is required exactly when style is currency." });
-    });
-const dateFormatSchema = () => z.strictObject({ date: z.enum(["day", "minute", "second"]) });
-export const cloudAiFormatSchema = () => z.union([cloudAiNumberFormatSchema(), dateFormatSchema()]);
-export type CloudAiNumberFormat = z.output<ReturnType<typeof cloudAiNumberFormatSchema>>;
-export type CloudAiDateFormat = z.output<ReturnType<typeof dateFormatSchema>>;
-export type CloudAiFormat = CloudAiNumberFormat | CloudAiDateFormat;
+import {
+  type ChartInput as CloudAiChartInput,
+  type ChartDateFormat as CloudAiDateFormat,
+  type ChartFormat as CloudAiFormat,
+  type ChartNumberFormat as CloudAiNumberFormat,
+  chartKinds,
+  chartParts,
+  chartSchema,
+  chartKindSchema as cloudAiChartKindSchema,
+  chartFormatSchema as cloudAiFormatSchema,
+  chartNumberFormatSchema as cloudAiNumberFormatSchema,
+} from "@k2b/editor/charts";
 
-export const cloudAiChartKindSchema = () =>
-  z.enum(["bar", "line", "scatter", "pie", "donut", "histogram", "gauge", "sparkline", "boxplot", "heatmap", "barGauge", "stat"]);
+export type { CloudAiChartInput, CloudAiDateFormat, CloudAiFormat, CloudAiNumberFormat };
+// Portable formats and chart types retain their existing Cloud export names.
+export { cloudAiChartKindSchema, cloudAiFormatSchema, cloudAiNumberFormatSchema };
 
-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()
-    : z
-        .custom<number>((value) => typeof value === "number", "Expected a number, null or undefined.")
-        .nullable()
-        .optional()
-        .transform((value) => value ?? Number.NaN);
-  const list = <T extends z.ZodType>(item: T, min: number, max?: number, message?: string) => {
-    const array = z.array(item);
-    const bounded = limits && min > 0 ? array.min(min) : array;
-    return limits && max !== undefined ? bounded.max(max, message) : bounded;
-  };
-  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([ChartNumber, ChartDate]).describe("line, scatter: number or YYYY-MM-DD[THH:mm[:ss]], wall-clock time without an offset."),
-    y: ChartNumber.describe("line, scatter: value."),
-  });
-  // As many lines as series a reader can tell apart.
-  const ChartReferences = list(
-    z.object({ value: z.union([z.number(), ChartDate]), axis: z.enum(["x", "y"]).optional(), label: ChartLabel.optional() }),
-    0,
-    CLOUD_AI_CHART_MAX_SERIES,
-    `Use at most ${CLOUD_AI_CHART_MAX_SERIES} references.`,
-  );
-  // One palette color per band.
-  const ChartThresholds = list(
-    z.object({ value: z.number(), label: ChartLabel.optional() }),
-    1,
-    CLOUD_AI_CHART_MAX_SERIES,
-    `Use at most ${CLOUD_AI_CHART_MAX_SERIES} thresholds.`,
-  );
-  return {
-    ChartLabel,
-    ChartTooltip,
-    ChartNumber,
-    list,
-    ChartReferences,
-    ChartThresholds,
-    ChartAxis: z.object({
-      label: ChartLabel.optional(),
-      domain: z.array(z.number()).length(2).optional().describe("Exact [min, max]; must contain every value and reference."),
-      ticks: (limits ? z.number().int().min(2).max(12) : z.number().int().min(2)).optional(),
-      scale: z.enum(["linear", "log"]).optional().describe("log needs values above zero."),
-      format: cloudAiFormatSchema().optional(),
-    }),
-    ChartCategory: z.object({ label: ChartLabel, value: ChartNumber }),
-    ChartSlice: z.object({ label: ChartLabel, value: limits ? z.number().min(0) : ChartNumber }),
-    ChartSeries: (points: z.ZodArray<typeof ChartPoint>) =>
-      z.object({
-        label: ChartLabel.optional(),
-        data: points,
-        role: z.literal("reference").optional(),
-      }),
-    ChartPoints: list(ChartPoint, 0, CLOUD_AI_CHART_MAX_VALUES),
-    ChartBins: z
-      .union([
-        limits ? z.number().int().min(1).max(CLOUD_AI_CHART_MAX_VALUES) : z.number().int().min(1),
-        limits
-          ? z
-              .array(z.number())
-              .min(2)
-              .max(CLOUD_AI_CHART_MAX_VALUES + 1)
-          : z.array(z.number()).min(2),
-      ])
-      .describe("histogram: a bin count or ascending bin edges."),
-    ChartCommon: {
-      title: (limits ? z.string().trim().min(1).max(160) : z.string()).describe("All kinds and groups: chart title."),
-      subtitle: (limits ? z.string().trim().min(1).max(300) : z.string())
-        .optional()
-        .describe("All kinds and groups: unit, period or source."),
-    },
-    ChartUnit: limits ? z.string().trim().min(1).max(12) : z.string(),
-    ChartBox: z.object({ label: ChartLabel, values: list(ChartNumber, 1) }),
-    ChartCell: z.object({ x: ChartLabel, y: ChartLabel, value: ChartNumber }),
-    ChartBarGauge: z.object({ label: ChartLabel, value: ChartNumber, min: z.number().optional(), max: z.number().optional() }),
-  };
-};
-
-const chartKinds = (limits = true) => {
-  const {
-    ChartNumber,
-    list,
-    ChartAxis,
-    ChartBins,
-    ChartCategory,
-    ChartCommon,
-    ChartTooltip,
-    ChartLabel,
-    ChartPoints,
-    ChartSeries,
-    ChartSlice,
-    ChartReferences,
-    ChartThresholds,
-    ChartUnit,
-    ChartBox,
-    ChartCell,
-    ChartBarGauge,
-  } = chartParts(limits);
-  const ChartKindCommon = { ...ChartCommon, tooltip: ChartTooltip.optional() };
-  const numberFormat = cloudAiNumberFormatSchema();
-  return z.discriminatedUnion("kind", [
-    z.object({
-      kind: z.literal("bar"),
-      ...ChartKindCommon,
-      data: list(ChartCategory, 1, CLOUD_AI_CHART_MAX_VALUES),
-      xAxis: ChartAxis.pick({ label: true }).strict().optional(),
-      yAxis: ChartAxis.optional(),
-      colorByBar: z.boolean().optional(),
-      showValues: z.boolean().optional(),
-      legend: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("line"),
-      ...ChartKindCommon,
-      series: list(
-        ChartSeries(
-          limits
-            ? ChartPoints.min(2, "A line needs at least two points per series; show single values as a bar or scatter chart.")
-            : ChartPoints,
-        ).extend({ style: z.enum(["solid", "dashed", "dotted"]).optional() }),
-        1,
-        CLOUD_AI_CHART_MAX_SERIES,
-      ),
-      xAxis: ChartAxis.optional(),
-      yAxis: ChartAxis.optional(),
-      legend: z.boolean().optional(),
-      area: z.boolean().optional(),
-      smooth: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("scatter"),
-      ...ChartKindCommon,
-      series: list(ChartSeries(limits ? ChartPoints.min(1) : ChartPoints), 1, CLOUD_AI_CHART_MAX_SERIES),
-      xAxis: ChartAxis.optional(),
-      yAxis: ChartAxis.optional(),
-      legend: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.enum(["pie", "donut"]),
-      ...ChartKindCommon,
-      data: list(ChartSlice, 1, CLOUD_AI_CHART_MAX_VALUES),
-      legend: z.boolean().optional(),
-      showLabels: z.boolean().optional(),
-      format: numberFormat.optional(),
-    }),
-    z.object({
-      kind: z.literal("histogram"),
-      ...ChartKindCommon,
-      data: list(ChartNumber, 1, CLOUD_AI_CHART_MAX_VALUES),
-      bins: ChartBins.optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("gauge"),
-      ...ChartKindCommon,
-      value: ChartNumber,
-      min: z.number().optional(),
-      max: z.number().optional(),
-      label: ChartLabel.optional(),
-      unit: ChartUnit.optional(),
-      format: numberFormat.optional(),
-      thresholds: ChartThresholds.optional(),
-    }),
-    z.object({
-      kind: z.literal("sparkline"),
-      ...ChartKindCommon,
-      data: list(ChartNumber, 2, CLOUD_AI_CHART_MAX_VALUES),
-      area: z.boolean().optional(),
-    }),
-    z.object({
-      kind: z.literal("boxplot"),
-      ...ChartKindCommon,
-      data: list(ChartBox, 1, CLOUD_AI_CHART_MAX_VALUES),
-      yAxis: ChartAxis.optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("heatmap"),
-      ...ChartKindCommon,
-      data: list(ChartCell, 1, CLOUD_AI_VIEW_MAX_MARKS),
-      format: numberFormat.optional(),
-      showValues: z.boolean().optional(),
-      min: z.number().optional(),
-      max: z.number().optional(),
-    }),
-    z.object({
-      kind: z.literal("barGauge"),
-      ...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(),
-      max: z.number().optional(),
-      unit: ChartUnit.optional(),
-      format: numberFormat.optional(),
-      thresholds: ChartThresholds.optional(),
-    }),
-    z.object({
-      kind: z.literal("stat"),
-      ...ChartKindCommon,
-      value: ChartNumber,
-      format: numberFormat.optional(),
-      unit: ChartUnit.optional(),
-      delta: limits ? z.number().optional() : ChartNumber,
-      better: z.enum(["up", "down"]).optional(),
-      sparkline: list(ChartNumber, 2, CLOUD_AI_CHART_MAX_VALUES).optional(),
-    }),
-  ]);
-};
+const chartLimits = { maxSeries: CLOUD_AI_CHART_MAX_SERIES, maxValues: CLOUD_AI_CHART_MAX_VALUES, maxMarks: CLOUD_AI_VIEW_MAX_MARKS };
 
 /** 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 };
 
 export const cloudAiChartSchema = () =>
-  chartKinds().superRefine((chart, context) => {
+  chartKinds(chartLimits).superRefine((chart, context) => {
     const total = cloudAiChartMarks(chart);
     const issue =
       total > CLOUD_AI_VIEW_MAX_MARKS
@@ -291,16 +60,9 @@ export const cloudAiChartSchema = () =>
     if (issue) context.addIssue({ code: "custom", message: issue });
   }, whenValid);
 /** Apps retain the renderer's permissive data contract, except values that would stall tick generation. */
-export const cloudAiAppChartSchema = () =>
-  chartKinds(false).superRefine((chart, context) => {
-    const issue = chartSteppingIssue(chart);
-    if (issue) context.addIssue({ code: "custom", message: issue });
-  }, whenValid);
+export const cloudAiAppChartSchema = chartSchema;
 const ChartSchema = /* @__PURE__ */ cloudAiChartSchema();
 
-/** One chart as the renderers read it: a `cloud.chart()` kind with its options. */
-export type CloudAiChartInput = z.output<ReturnType<typeof chartKinds>>;
-
 /**
  * Reads one chart without drawing it; undefined when it is not a chart. Writers have drawn it once already, so
  * renderers draw only for display.
@@ -311,7 +73,7 @@ export const parseCloudAiChartInput = (value: unknown): CloudAiChartInput | unde
 };
 
 export const cloudAiGroupSchema = () => {
-  const { ChartCommon } = chartParts();
+  const { ChartCommon } = chartParts(chartLimits);
   return z
     .strictObject({
       ...ChartCommon,
@@ -354,7 +116,7 @@ const flatChartSchema = () => {
     ChartThresholds,
     ChartUnit,
     ChartTooltip,
-  } = chartParts();
+  } = chartParts(chartLimits);
   return z.object({
     kind: cloudAiChartKindSchema().optional().describe("Single charts: kind. Omit for groups."),
     ...ChartCommon,

package/src/ai/default-tools.ts

@@ -56,6 +56,7 @@ import {
   CloudAiLocalWriteInputSchema,
   CloudAiLocalWriteOutputSchema,
 } from "./local-tool-contracts";
+import { createCloudAiMapTool } from "./map-tool";
 import { createCloudAiMarkdownToPdfTool } from "./markdown-pdf-tool";
 import { createAiTodoTool } from "./todo-tool";
 import { defineAiTool } from "./tools";
@@ -303,6 +304,7 @@ export const CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES = new Set<string>([
   "markdown_to_pdf",
   "html_to_pdf",
   "present",
+  "map",
   "read_cloud_resource",
 ]);
 
@@ -314,6 +316,7 @@ export const createConfiguredDefaultCloudAiTools = async (config?: {
 }) => {
   const tools: AiRuntimeTool[] = [
     ...createDefaultCloudAiTools(),
+    createCloudAiMapTool(),
     ...createCodeSourceTools(),
     createCloudAiListFilesTool(),
     createCloudAiReadFileTool(),

package/src/ai/executor.ts

@@ -547,7 +547,7 @@ const createEventMapper = (
       args: "args" in patch ? patch.args : existing?.args,
       status: patch.status ?? existing?.status ?? "running",
       at: patch.at ?? existing?.at,
-      result: "result" in patch ? patch.result : existing?.result,
+      result: patch.isError && existing?.result !== undefined ? existing.result : "result" in patch ? patch.result : existing?.result,
       isError: "isError" in patch ? patch.isError : existing?.isError,
       approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false, allowChat: false } : approval,
       review: patch.review ?? existing?.review,
@@ -1080,6 +1080,11 @@ export class AiTurnExecutor {
     const dynamicToolRuntimeContext = {
       turnId,
       reportToolProgress: (callId: string, message: string) => pipeline.reportToolProgress(callId, message),
+      reportToolResult: (callId: string, result: unknown) => pipeline.reportToolResult(callId, result),
+      maxToolResultChars: resolveAiToolResultMaxChars({
+        contextWindow: resolved.provider.contextWindow,
+        configuredMaxChars: settings.maxToolResultChars,
+      }),
       reportWebsiteReceipts: (callId: string, receipts: AiWebsiteReceipt[]) => pipeline.reportWebsiteReceipts(callId, receipts),
       localToolsEnabled: activeTools.some((tool) => tool.def.name === "local_upload"),
       attachedFilePaths: new Set(config.files?.attached.map((file) => file.path) ?? []),
@@ -2501,6 +2506,13 @@ class StreamPipeline {
     await this.maybeSnapshot();
   }
 
+  async reportToolResult(callId: string, result: unknown): Promise<void> {
+    const block = this.blocks.find((block) => block.kind === "tool" && block.callId === callId);
+    if (!block || block.kind !== "tool" || block.status !== "running") return;
+    await this.emitOp(this.mapper.setTool(callId, { result }));
+    await this.maybeSnapshot();
+  }
+
   async reportToolProgress(callId: string, progress: string): Promise<void> {
     const block = this.blocks.find((block) => block.kind === "tool" && block.callId === callId);
     if (!block || block.kind !== "tool" || block.progress === progress) return;

package/src/ai/map-contracts.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import {
+  GeoAddressSchema,
+  GeoAvailabilityDataSchema,
+  GeoCategorySchema,
+  GeoCostsSchema,
+  GeoPlaceSchema,
+  GeoPlaceSearchInputSchema,
+  GeoPointSchema,
+} from "../contracts/geo";
+import {
+  GeoRouteChangesSchema,
+  GeoRouteOptionsSchema,
+  GeoRoutePlanSchema,
+  GeoRouteSchema,
+  GeoRouteUpdateDataSchema,
+} from "../contracts/geo-route";
+
+/** Provider website text is optional and is not guaranteed to be a valid URL. */
+export const aiMapWebsite = (value: string | undefined): string | undefined => {
+  try {
+    const url = new URL(value ?? "");
+    return url.protocol === "https:" || url.protocol === "http:" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const label = z.string().trim().min(1).max(160);
+const web = z.object({ placeId: z.string().max(2048), description: z.string().max(600), url: z.url().max(2000) }).strict();
+// A map may accumulate two full Places result pages. Subsequent searches replace the secondary group.
+export const AiMapSchema = z
+  .object({
+    id: z.uuid(),
+    conversationId: z.string(),
+    revision: z.number().int().positive(),
+    title: label,
+    selectionId: z.string().optional(),
+    timeZone: z.string().optional(),
+    kind: z.enum(["places", "route"]),
+    pending: z.boolean().optional(),
+    pendingTurnId: z.uuid().optional(),
+    retryUsesMarks: z.boolean().optional(),
+    originCallId: z.string().optional(),
+    anchorSeq: z.number().int().positive().optional(),
+    viewedAt: z.iso.datetime().optional(),
+    lastSearch: z
+      .object({
+        categories: z.array(GeoCategorySchema),
+        name: GeoPlaceSearchInputSchema.shape.name,
+        near: z.string().optional(),
+        placeId: z.string().optional(),
+        radiusMeters: z.number().optional(),
+        title: label,
+        along: z.object({ fromKm: z.number(), toKm: z.number(), bufferMeters: z.number().optional() }).optional(),
+      })
+      .optional(),
+    searchAddress: z.object({ text: z.string(), address: GeoAddressSchema }).strict().optional(),
+    availability: GeoAvailabilityDataSchema,
+    groups: z.array(z.object({ title: label, places: z.array(GeoPlaceSchema).max(20) }).strict()).max(2),
+    web: z.array(web).max(40),
+    route: GeoRouteSchema.optional(),
+    plan: GeoRoutePlanSchema.optional(),
+    preview: z.object({ result: GeoRouteUpdateDataSchema, changes: GeoRouteChangesSchema, title: label }).strict().optional(),
+    undo: z.object({ route: GeoRouteSchema, title: label }).strict().optional(),
+    receipt: z.object({ title: label, at: z.iso.datetime() }).strict().optional(),
+    candidates: z.array(GeoAddressSchema).max(5).optional(),
+    ambiguousStopId: z.string().optional(),
+    picker: z.array(GeoPlaceSchema).max(5).optional(),
+    retryInsertStopId: z.uuid().optional(),
+    issue: z
+      .object({
+        code: z.string(),
+        scope: z.enum(["person", "cloud"]).optional(),
+        resetsAt: z.string().optional(),
+        retryAfterSeconds: z.number().optional(),
+        costs: GeoCostsSchema.optional(),
+        requiredCredits: z.number().nonnegative().optional(),
+        availableCredits: z.number().optional(),
+        turnId: z.uuid().optional(),
+        requiresCostConfirmation: z.literal(true).optional(),
+        shortfallCredits: z.number().nonnegative().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type AiMap = z.infer<typeof AiMapSchema>;
+
+const search = z
+  .object({
+    categories: z.array(GeoCategorySchema).min(1).max(5),
+    name: GeoPlaceSearchInputSchema.shape.name,
+    near: z.string().min(1).max(300).optional(),
+    placeId: z.string().max(2048).optional(),
+    radiusMeters: z.number().min(1).max(50000).optional(),
+    along: z
+      .object({ fromKm: z.number().nonnegative(), toKm: z.number().positive(), bufferMeters: z.number().min(100).max(5000).optional() })
+      .strict()
+      .optional(),
+    title: label,
+  })
+  .strict();
+// Model-facing inputs cannot inject points, polylines, or a provider result. These are resolved on the server.
+const stop = z
+  .object({
+    id: z.string().min(1).max(40),
+    address: z.string().min(1).max(300).optional(),
+    placeId: z.string().max(2048).optional(),
+    label: label.optional(),
+  })
+  .strict()
+  .refine((value) => Boolean(value.address) !== Boolean(value.placeId), "Supply exactly one address or verified place ID");
+export const AiMapCommandSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("places"), search, web: z.array(web).max(20).optional() }).strict(),
+  z
+    .object({
+      type: z.literal("route"),
+      stops: z
+        .array(stop)
+        .min(2)
+        .max(26)
+        .refine((stops) => new Set(stops.map((s) => s.id)).size === stops.length, "Stop IDs must be unique"),
+      options: GeoRouteOptionsSchema.optional(),
+      title: label,
+    })
+    .strict(),
+  z.object({ type: z.literal("search"), search, insert: z.boolean().optional(), web: z.array(web).max(20).optional() }).strict(),
+  z.object({ type: z.literal("describe"), web: z.array(web).max(40) }).strict(),
+  z
+    .object({
+      type: z.literal("preview"),
+      change: z.discriminatedUnion("type", [
+        z.object({ type: z.literal("insert"), placeId: z.string().max(2048), afterStopId: z.string().optional() }).strict(),
+        z.object({ type: z.literal("move"), stopId: z.string(), toIndex: z.number().int().min(0).max(25) }).strict(),
+        z.object({ type: z.literal("optimize") }).strict(),
+        z
+          .object({
+            type: z.literal("options"),
+            options: GeoRouteOptionsSchema,
+            leg: z.object({ fromStopId: z.string(), toStopId: z.string() }).strict().optional(),
+          })
+          .strict(),
+      ]),
+    })
+    .strict(),
+  z.object({ type: z.literal("choose"), index: z.number().int().min(0).max(4) }).strict(),
+  z.object({ type: z.literal("accept") }).strict(),
+  z.object({ type: z.literal("discard") }).strict(),
+  z.object({ type: z.literal("undo") }).strict(),
+  z.object({ type: z.literal("retry") }).strict(),
+]);
+export const AiMapBrowserCommandSchema = z.union([
+  AiMapCommandSchema,
+  z.object({ type: z.literal("location"), destinationId: z.string(), point: GeoPointSchema }).strict(),
+  z
+    .object({ type: z.literal("repair"), stopId: z.string(), address: z.string().trim().min(1).max(300), point: GeoPointSchema.optional() })
+    .strict(),
+]);
+export type AiMapCommand = z.infer<typeof AiMapBrowserCommandSchema>;
+export const AiMapToolInputSchema = z
+  .object({ mapId: z.uuid().optional(), revision: z.number().int().positive().optional(), command: AiMapCommandSchema })
+  .strict();
+export const AiMapReferenceSchema = AiMapSchema.pick({
+  id: true,
+  conversationId: true,
+  revision: true,
+  title: true,
+  kind: true,
+  pending: true,
+  anchorSeq: true,
+}).extend({ reference: z.literal(true) });
+export const AiMapToolResultSchema = z
+  .object({ map: z.union([AiMapSchema, AiMapReferenceSchema]), anchor: z.boolean(), summary: z.unknown().optional() })
+  .strict();
+/** Geometry belongs to the durable map, never to the model context or streaming result budget. */
+export const aiMapToolResult = (map: AiMap, anchor: boolean): z.infer<typeof AiMapToolResultSchema> => ({
+  anchor,
+  map: {
+    reference: true,
+    id: map.id,
+    conversationId: map.conversationId,
+    revision: map.revision,
+    title: map.title,
+    kind: map.kind,
+    pending: map.pending,
+    anchorSeq: map.anchorSeq,
+  },
+  summary: {
+    mapId: map.id,
+    revision: map.revision,
+    places: map.groups.map((g) => ({
+      title: g.title.slice(0, 64),
+      places: g.places.map((p, i) => ({
+        id: map.groups.indexOf(g) === 0 ? String(i + 1) : String.fromCharCode(65 + i),
+        name: p.name.slice(0, 48),
+      })),
+    })),
+    candidates: map.candidates?.map((p, index) => ({ index, address: p.formatted.slice(0, 96) })),
+    picker: map.picker?.map((p, i) => ({ id: `pick-${i + 1}`, name: p.name.slice(0, 48), atMeters: p.atMeters })),
+    stops: map.route?.stops.map((s) => ({ id: s.id, label: s.label?.slice(0, 48) })),
+    distanceMeters: map.route?.distanceMeters,
+    durationSeconds: map.route?.durationSeconds,
+    preview: map.preview ? { title: map.preview.title, delta: map.preview.result.delta } : undefined,
+    issue: map.issue,
+  },
+});
+export type AiMapToolResult = z.infer<typeof AiMapToolResultSchema>;
+export const AiMapActionSchema = z.object({ revision: z.number().int().positive(), command: AiMapBrowserCommandSchema }).strict();