@k2b/cloud 0.31.0 → 0.32.0

package/src/ai/file-tools.ts

@@ -6,6 +6,7 @@ import {
 } from "@k2b/cloud/services/document-extraction";
 import { z } from "zod";
 import type { RequestActor } from "../server";
+import { aiMissingChatFileError } from "./file-error";
 import {
   AI_PROJECT_FILE_MOUNT,
   AI_SKILL_FILE_MOUNT,
@@ -14,8 +15,9 @@ import {
   mountAiProjectFilePath,
   mountAiSkillFilePath,
 } from "./file-mount";
-import { aiFileStore, guessAiMediaType, isAiWorkingFilePath, normalizeAiFilePath } from "./files-store";
+import { aiFileStore, assertAiModelWritablePath, guessAiMediaType, isAiWorkingFilePath, normalizeAiFilePath } from "./files-store";
 import { defineAiTool } from "./tools";
+import { CLOUD_AI_VIEW_MAX_BYTES, CloudAiViewSummarySchema, cloudAiViewSummary, isAiViewFile, parseCloudAiView } from "./view-block";
 
 const FILE_READ_MAX_BYTES = 64 * 1024;
 const FILE_WRITE_MAX_BYTES = 100 * 1024;
@@ -234,7 +236,7 @@ export const createCloudAiReadFileTool = () => {
             length: input.length,
           })
         : null);
-    if (!stored) throw new Error(`No such file: ${path}`);
+    if (!stored) throw aiMissingChatFileError(path, ctx.localToolsEnabled);
     const extractAsDocument = shouldExtractDocument(path, stored.mediaType);
     if (isTextMediaType(stored.mediaType) && !extractAsDocument) {
       if (input.offset > stored.size) throw new Error(`Offset ${input.offset} is past the end of ${path} (${stored.size} bytes).`);
@@ -271,7 +273,7 @@ export const createCloudAiReadFileTool = () => {
           ? await aiFileStore.readTurnFile({ turnId: ctx.turnId, path })
           : await aiFileStore.read({ conversationId: conversationId(ctx.conversationId, "read_file"), path });
       if (!fullFile) {
-        throw new Error(snapshot ? `Attached file snapshot is unavailable: ${path}` : `No such file: ${path}`);
+        throw snapshot ? new Error(`Attached file snapshot is unavailable: ${path}`) : aiMissingChatFileError(path, ctx.localToolsEnabled);
       }
       try {
         extracted = await extractDocumentMarkdown({ bytes: fullFile.bytes, filename: path, signal: ctx.signal });
@@ -328,6 +330,7 @@ export const createCloudAiWriteFileTool = () =>
     const id = conversationId(ctx.conversationId, "write_file");
     const path = toolPath(input.path, "write");
     assertConversationFilePath(path, "written");
+    assertAiModelWritablePath(path);
     const existing = await aiFileStore.stat({ conversationId: id, path });
     if (existing?.origin === "user") throw new Error(`Cannot overwrite user-uploaded file ${path}. Choose another path.`);
     const bytes = new TextEncoder().encode(input.content);
@@ -356,13 +359,29 @@ export const CloudAiPresentInputSchema = z.object({
       "One sentence in the user's language that says what the file is and what it is for, without repeating its name. Shown next to the file in the chat's results.",
     ),
 });
-export const CloudAiPresentOutputSchema = z.object({ path: z.string(), size: z.number(), mediaType: z.string() });
+export const CloudAiPresentOutputSchema = z.object({
+  path: z.string(),
+  size: z.number(),
+  mediaType: z.string(),
+  view: CloudAiViewSummarySchema.optional(),
+});
+
+/** A view file as it is now; invalid user edits leave an ordinary file. */
+const readView = async (conversationId: string, path: string) => {
+  const file = await aiFileStore.read({ conversationId, path });
+  if (!file || !isAiViewFile(file) || file.bytes.byteLength > CLOUD_AI_VIEW_MAX_BYTES) return undefined;
+  try {
+    return parseCloudAiView(JSON.parse(new TextDecoder().decode(file.bytes)));
+  } catch {
+    return undefined;
+  }
+};
 
 export const createCloudAiPresentTool = () =>
   defineAiTool({
     name: "present",
     description:
-      "Present a conversation file to the user as an openable and downloadable chat attachment. The returned path is a conversation-local file identifier, not a website URL. Refer to the delivered attachment by title; do not turn its path into a Markdown link.",
+      "Present a conversation file to the user as an openable and downloadable chat attachment. The returned path is a conversation-local file identifier, not a website URL. Refer to the delivered attachment by title; do not turn its path into a Markdown link. A view file from cloud.view.* (/views/…view.json) shows inline as its chart, group, table, stats or details view, so present every view the person should see.",
     inputSchema: CloudAiPresentInputSchema,
     outputSchema: CloudAiPresentOutputSchema,
     approval: "never",
@@ -372,8 +391,9 @@ export const createCloudAiPresentTool = () =>
     const path = toolPath(input.path, "read");
     assertConversationFilePath(path, "presented");
     const stat = await aiFileStore.stat({ conversationId: id, path });
-    if (!stat) throw new Error(`No such file: ${path}`);
-    return { path: stat.path, size: stat.size, mediaType: stat.mediaType };
+    if (!stat) throw aiMissingChatFileError(path, ctx.localToolsEnabled);
+    const view = isAiViewFile(stat) && stat.size <= CLOUD_AI_VIEW_MAX_BYTES ? await readView(id, path) : undefined;
+    return { path: stat.path, size: stat.size, mediaType: stat.mediaType, ...(view ? { view: cloudAiViewSummary(view) } : {}) };
   });
 
 type MathToken = { kind: "number"; value: number } | { kind: "ident"; name: string } | { kind: "op"; op: string };

package/src/ai/files-store.ts

@@ -2,6 +2,14 @@ import { type SQL, sql } from "bun";
 import { stripImageMetadata } from "../services/image-metadata";
 import { AiFileVersionConflict, AiFileWriteError, aiFileContentVersion } from "./file-content-version";
 import { isAiImage } from "./file-media-type";
+import {
+  CLOUD_AI_VIEW_MAX_BYTES,
+  CLOUD_AI_VIEW_SUFFIX,
+  type CloudAiViewSummary,
+  checkCloudAiView,
+  cloudAiViewSummary,
+  isAiViewPath,
+} from "./view-block";
 
 export { guessAiMediaType } from "./file-media-type";
 
@@ -697,6 +705,7 @@ export async function createAiConversationArtifact(input: {
   const { aiConversations } = await import("./store");
   const conversation = await aiConversations.getConversation({ conversationId: input.conversationId, ownerUserId: input.ownerUserId });
   if (!conversation || conversation.archivedAt) throw new Error("Conversation access denied");
+  assertAiModelWritablePath(input.path);
   return aiFileStore.createToolArtifact(input);
 }
 
@@ -710,6 +719,57 @@ export async function writeAiConversationFile(input: {
   expectedVersion: string | null;
 }): Promise<AiFileStat> {
   if (normalizeAiFilePath(input.path) !== input.path) throw new Error("Invalid file path");
+  assertAiModelWritablePath(input.path);
   const current = await aiFileStore.stat(input);
   return aiFileStore.write({ ...input, origin: current?.origin ?? "assistant", allowUserOverwrite: current?.origin === "user" });
 }
+
+export function assertAiModelWritablePath(path: string): void {
+  if (isAiViewPath(normalizeAiFilePath(path) ?? path))
+    throw new Error("The /views folder holds views that code runs create with cloud.view.*; choose another path.");
+}
+export class AiViewInvalidError extends Error {
+  constructor(readonly issues: string[]) {
+    super(`View rejected: ${issues.join("; ")}`);
+    this.name = "AiViewInvalidError";
+  }
+}
+
+/** Run-produced views use the same ownership, budget and retry rules as other chat artifacts. */
+export async function createAiConversationView(input: {
+  conversationId: string;
+  ownerUserId: string;
+  turnId: string;
+  runId: string;
+  index: number;
+  view: unknown;
+}): Promise<{ path: string } & CloudAiViewSummary> {
+  const { aiConversations } = await import("./store");
+  const conversation = await aiConversations.getConversation({ conversationId: input.conversationId, ownerUserId: input.ownerUserId });
+  if (!conversation || conversation.archivedAt) throw new Error("Conversation access denied");
+  const checked = checkCloudAiView(input.view);
+  if ("issues" in checked) throw new AiViewInvalidError(checked.issues);
+  const bytes = new TextEncoder().encode(JSON.stringify(checked.view));
+  if (bytes.byteLength > CLOUD_AI_VIEW_MAX_BYTES)
+    throw new AiViewInvalidError([`view: At most ${CLOUD_AI_VIEW_MAX_BYTES} bytes are allowed.`]);
+  const slug =
+    checked.view.title
+      .normalize("NFKD")
+      .replace(/\p{M}/gu, "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 48)
+      .replace(/-+$/g, "") || "view";
+  const key = `${input.turnId}:${input.runId}:${input.index}`;
+  const digest = new Bun.CryptoHasher("sha256").update(key).digest("hex").slice(0, 8);
+  const path = `/views/${slug}-${digest}${CLOUD_AI_VIEW_SUFFIX}`;
+  await aiFileStore.createToolArtifact({
+    conversationId: input.conversationId,
+    path,
+    bytes,
+    mediaType: "application/json",
+    producerCallKey: `view:${key}`,
+  });
+  return { path, ...cloudAiViewSummary(checked.view) };
+}

package/src/ai/html-pdf-tool.ts

@@ -8,6 +8,7 @@ import {
   type RenderHtmlToPdfResult,
   renderHtmlToPdfWithConfig,
 } from "../services/pdf";
+import { aiMissingChatFileError } from "./file-error";
 import { aiProjectFilePathFromMount, aiSkillFilePathFromMount } from "./file-mount";
 import { type AiFileContent, type AiFileStat, aiFileStore, normalizeAiFilePath } from "./files-store";
 import { withAiPdfConversionSlot } from "./pdf-conversions";
@@ -122,7 +123,7 @@ export const createCloudAiHtmlToPdfTool = (dependencies: HtmlPdfToolDependencies
     for (const path of [sourcePath, cssPath, headerPath, footerPath, ...assetPaths]) {
       if (path === undefined) continue;
       const file = await stat({ conversationId, path });
-      if (!file) throw new Error(`No such file: ${path}`);
+      if (!file) throw aiMissingChatFileError(path, ctx.localToolsEnabled);
       if (path === sourcePath && file.origin !== "assistant") {
         throw new Error(`Create an assistant-owned HTML file with write_file before converting ${sourcePath}.`);
       }
@@ -134,7 +135,7 @@ export const createCloudAiHtmlToPdfTool = (dependencies: HtmlPdfToolDependencies
 
     const load = async (path: string): Promise<AiFileContent> => {
       const file = await read({ conversationId, path });
-      if (!file) throw new Error(`No such file: ${path}`);
+      if (!file) throw aiMissingChatFileError(path, ctx.localToolsEnabled);
       return file;
     };
     const text = async (path: string | undefined): Promise<string | undefined> => (path === undefined ? undefined : utf8(await load(path)));

package/src/ai/http.ts

@@ -6,6 +6,7 @@ import { type AuthContext, err, fail, respond } from "../server";
 import { aiAttachmentMarker } from "./attachments";
 import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
 import { AI_TURN_ATTACHMENT_MAX_ITEMS } from "./limits";
+import { AI_LOCAL_TOOL_NAMES, AiLocalClientSchema, AiLocalContextSchema } from "./local-tool-contracts";
 import { AiQuotaError } from "./quotas";
 import { AiResourceMarkerSchema } from "./resource-markers";
 import { AI_SHORT_ID_PATTERN } from "./short-id";
@@ -120,7 +121,10 @@ export const AiUserContentPartSchema = z.union([
 
 export type AiTurnContentPart = z.infer<typeof AiUserContentPartSchema>;
 
-export const AiClientToolIdSchema = z.enum(["local_bash", ...CODE_RUNTIME_TOOL_NAMES] satisfies [AiClientToolId, ...AiClientToolId[]]);
+export const AiClientToolIdSchema = z.enum(["local_bash", ...AI_LOCAL_TOOL_NAMES, ...CODE_RUNTIME_TOOL_NAMES] satisfies [
+  AiClientToolId,
+  ...AiClientToolId[],
+]);
 
 // Names use aiCapabilityToolName's provider grammar and 64-character limit. The 64-item cap matches allowedTools, with headroom
 // for retired and not-yet-known names; 64 names × 64 ASCII characters bounds advertised name text to 4 KiB.
@@ -157,12 +161,21 @@ export const AiTurnInputSchema = z
 
 export type AiTurnInput = z.infer<typeof AiTurnInputSchema>;
 
-export const AiSubmitConversationDraftInputSchema = z.object({
-  queueId: z.uuid().optional(),
-  draftRevision: z.number().int().min(1),
-  modelProfileId: z.string().trim().min(1).optional(),
-  clientToolIds: AiClientToolIdsSchema.optional(),
-});
+export const AiSubmitConversationDraftInputSchema = z
+  .object({
+    queueId: z.uuid().optional(),
+    draftRevision: z.number().int().min(1),
+    modelProfileId: z.string().trim().min(1).optional(),
+    clientToolIds: AiClientToolIdsSchema.optional(),
+    /** Set by a local client such as cld; the web never sends it. */
+    client: AiLocalClientSchema.optional(),
+    /** AGENTS.md files and local Skills a local client found; only valid together with client. */
+    localContext: AiLocalContextSchema.optional(),
+  })
+  .refine((input) => !input.localContext || Boolean(input.client), {
+    message: "Local context requires a local client.",
+    path: ["localContext"],
+  });
 
 export const AiSteerInputSchema = z.object({
   message: z.string().trim().min(1).max(20000),
@@ -187,6 +200,13 @@ export const AiMessageRetryInputSchema = z
       .max(AI_TURN_ATTACHMENT_MAX_ITEMS * 2 + 1)
       .optional(),
     modelProfileId: z.string().trim().min(1).optional(),
+    clientToolIds: AiClientToolIdsSchema.optional(),
+    client: AiLocalClientSchema.optional(),
+    localContext: AiLocalContextSchema.omit({ selectedSkills: true }).optional(),
+  })
+  .refine((input) => !input.localContext || Boolean(input.client), {
+    message: "Local context requires a local client.",
+    path: ["localContext"],
   })
   .refine(
     (input) =>
@@ -272,13 +292,18 @@ export const toAiErrorResponse = (c: Context<AuthContext>, error: unknown) => {
   return respond(c, fail(err.internal(message)));
 };
 
-export const toAiActionFailureResponse = (c: Context<AuthContext>, result: { ok: false; status: 400 | 404 | 409; message: string }) => {
+export const toAiActionFailureResponse = (
+  c: Context<AuthContext>,
+  result: { ok: false; status: 400 | 403 | 404 | 409; message: string },
+) => {
   const failure =
     result.status === 400
       ? err.badInput(result.message)
-      : result.status === 404
-        ? // err.notFound appends " not found" to its subject — the runtime message is already complete.
-          { code: "NOT_FOUND" as const, message: result.message, status: 404 as const }
-        : conflict(result.message);
+      : result.status === 403
+        ? err.forbidden(result.message)
+        : result.status === 404
+          ? // err.notFound appends " not found" to its subject — the runtime message is already complete.
+            { code: "NOT_FOUND" as const, message: result.message, status: 404 as const }
+          : conflict(result.message);
   return respond(c, fail(failure));
 };

package/src/ai/index.ts

@@ -56,7 +56,9 @@ export { listAiCredentialProfileIds } from "./credentials";
 export {
   CLOUD_AI_CHART_MAX_SERIES,
   CLOUD_AI_CHART_MAX_VALUES,
+  CLOUD_AI_GROUP_MAX_CHARTS,
   CLOUD_AI_TEXT_EDITOR_MAX_CHARS,
+  CLOUD_AI_VIEW_MAX_MARKS,
   type CloudAiCardInput,
   CloudAiCardInputSchema,
   type CloudAiCardOutput,
@@ -65,10 +67,13 @@ export {
   CloudAiChartInputSchema,
   type CloudAiChartOutput,
   CloudAiChartOutputSchema,
+  type CloudAiDateFormat,
+  type CloudAiFormat,
   type CloudAiLocalBashInput,
   CloudAiLocalBashInputSchema,
   type CloudAiLocalBashOutput,
   CloudAiLocalBashOutputSchema,
+  type CloudAiNumberFormat,
   type CloudAiSurveyInput,
   CloudAiSurveyInputSchema,
   type CloudAiSurveyOutput,
@@ -77,6 +82,10 @@ export {
   CloudAiTextEditorInputSchema,
   type CloudAiTextEditorOutput,
   CloudAiTextEditorOutputSchema,
+  cloudAiAppChartSchema,
+  cloudAiChartSchema,
+  cloudAiFormatSchema,
+  cloudAiNumberFormatSchema,
   parseCloudAiChartInput,
 } from "./default-tool-contracts";
 export {
@@ -99,7 +108,9 @@ export {
   type AiConversationFileOverview,
   type AiConversationWorkingGroup,
   type AiFileStat,
+  AiViewInvalidError,
   createAiConversationArtifact,
+  createAiConversationView,
   guessAiMediaType,
   isAiWorkingFilePath,
   listAiConversationFiles,
@@ -154,6 +165,50 @@ export {
   AiInvalidationDomainSchema,
   AiInvalidationSchema,
 } from "./live-events";
+export {
+  AI_LOCAL_BATCH_MAX_ITEMS,
+  AI_LOCAL_INSTRUCTIONS_MAX_BYTES,
+  AI_LOCAL_LIST_MAX_LIMIT,
+  AI_LOCAL_READ_MAX_BYTES,
+  AI_LOCAL_SELECTED_SKILLS_MAX_ITEMS,
+  AI_LOCAL_SKILL_FILES_MAX_ITEMS,
+  AI_LOCAL_SKILLS_MAX_ITEMS,
+  AI_LOCAL_TOOL_NAMES,
+  AI_LOCAL_WRITE_MAX_BYTES,
+  type AiLocalClient,
+  AiLocalClientSchema,
+  type AiLocalContext,
+  AiLocalContextSchema,
+  type AiLocalToolName,
+  type CloudAiLoadLocalSkillInput,
+  CloudAiLoadLocalSkillInputSchema,
+  type CloudAiLoadLocalSkillOutput,
+  CloudAiLoadLocalSkillOutputSchema,
+  type CloudAiLocalDownloadInput,
+  CloudAiLocalDownloadInputSchema,
+  type CloudAiLocalDownloadOutput,
+  CloudAiLocalDownloadOutputSchema,
+  type CloudAiLocalListInput,
+  CloudAiLocalListInputSchema,
+  type CloudAiLocalListOutput,
+  CloudAiLocalListOutputSchema,
+  type CloudAiLocalMoveInput,
+  CloudAiLocalMoveInputSchema,
+  type CloudAiLocalMoveOutput,
+  CloudAiLocalMoveOutputSchema,
+  type CloudAiLocalReadInput,
+  CloudAiLocalReadInputSchema,
+  type CloudAiLocalReadOutput,
+  CloudAiLocalReadOutputSchema,
+  type CloudAiLocalUploadInput,
+  CloudAiLocalUploadInputSchema,
+  type CloudAiLocalUploadOutput,
+  CloudAiLocalUploadOutputSchema,
+  type CloudAiLocalWriteInput,
+  CloudAiLocalWriteInputSchema,
+  type CloudAiLocalWriteOutput,
+  CloudAiLocalWriteOutputSchema,
+} from "./local-tool-contracts";
 export { AI_ENRICH_CRON_SETTING_KEY, AI_MEMORY_LEARNING_CRON_SETTING_KEY, aiMaintenanceJobs } from "./maintenance";
 export {
   AI_MEMORY_CONTENT_MAX_CHARS,
@@ -257,6 +312,8 @@ export {
   type AiSkillDocument,
   type AiSkillExtraFrontmatter,
   type AiSkillReferenceInput,
+  isAiSkillManualOnly,
+  mountAiSkillInstructionLinks,
   parseAiSkillMarkdown,
   serializeAiSkillMarkdown,
   validateAiSkillDescription,
@@ -371,6 +428,39 @@ export type {
 } from "./types";
 export { AI_MESSAGE_FEEDBACK_REASONS, isAiImageMediaType } from "./types";
 export { isAiSettingsError } from "./validate";
+export {
+  CLOUD_AI_STATS_MAX_ITEMS,
+  CLOUD_AI_TABLE_MAX_COLUMNS,
+  CLOUD_AI_TABLE_MAX_ROWS,
+  CLOUD_AI_VIEW_DIRECTORY,
+  CLOUD_AI_VIEW_MAX_BYTES,
+  CLOUD_AI_VIEW_SUFFIX,
+  type CloudAiChartView,
+  type CloudAiDetailsView,
+  type CloudAiExplorerRequest,
+  type CloudAiExplorerView,
+  type CloudAiGroupView,
+  type CloudAiStatsView,
+  type CloudAiTableView,
+  type CloudAiView,
+  type CloudAiViewReference,
+  type CloudAiViewSummary,
+  CloudAiViewSummarySchema,
+  type CloudAiViewTable,
+  checkCloudAiView,
+  cloudAiDetailsRows,
+  cloudAiExplorerControls,
+  cloudAiExplorerState,
+  cloudAiStatsTiles,
+  cloudAiTableTsv,
+  cloudAiViewSummary,
+  cloudAiViewTable,
+  isAiViewFile,
+  isAiViewPath,
+  parseCloudAiChartToolView,
+  parseCloudAiView,
+  sortCloudAiViewRows,
+} from "./view-block";
 export {
   type CloudAiViewImageInput,
   CloudAiViewImageInputSchema,

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

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { AI_SKILL_DESCRIPTION_MAX_CHARS, AI_SKILL_INSTRUCTIONS_MAX_CHARS, AI_SKILL_NAME_PATTERN } from "./skill-format";
+
+/**
+ * Contracts of the client tools a local client such as `cld` runs on the user's computer, and of the context it
+ * sends with a turn. Cloud declares and validates them; the client executes them and enforces its own path rules.
+ */
+export const AI_LOCAL_TOOL_NAMES = [
+  "local_list",
+  "local_read",
+  "local_upload",
+  "local_download",
+  "local_write",
+  "local_move",
+  "load_local_skill",
+] as const;
+export type AiLocalToolName = (typeof AI_LOCAL_TOOL_NAMES)[number];
+
+/** Longest absolute path a client reports, Linux PATH_MAX. */
+export const AI_LOCAL_PATH_MAX_CHARS = 4096;
+/** Entries per local_list page by default and at most, like code_files. */
+export const AI_LOCAL_LIST_DEFAULT_LIMIT = 100;
+export const AI_LOCAL_LIST_MAX_LIMIT = 1000;
+/** Bytes per local_read call by default and at most, like read_file. */
+export const AI_LOCAL_READ_DEFAULT_BYTES = 16 * 1024;
+export const AI_LOCAL_READ_MAX_BYTES = 64 * 1024;
+/** Text one local_write call writes, like write_file. */
+export const AI_LOCAL_WRITE_MAX_BYTES = 100 * 1024;
+/** Paths per upload or move batch, like the code-mode input paths and the 64-item request limits. */
+export const AI_LOCAL_BATCH_MAX_ITEMS = 64;
+/** AGENTS.md text one turn carries, the Codex default. */
+export const AI_LOCAL_INSTRUCTIONS_MAX_BYTES = 32 * 1024;
+/** Local Skills one turn lists, like the 64-item request limits. */
+export const AI_LOCAL_SKILLS_MAX_ITEMS = 64;
+/** Local Skills one message selects explicitly. */
+export const AI_LOCAL_SELECTED_SKILLS_MAX_ITEMS = 4;
+/** Files a loaded local Skill lists, like Cloud Skill references. */
+export const AI_LOCAL_SKILL_FILES_MAX_ITEMS = 50;
+
+const LocalPath = z.string().min(1).max(AI_LOCAL_PATH_MAX_CHARS);
+const ChatPath = z.string().trim().min(1).max(500);
+const SkillName = z.string().regex(AI_SKILL_NAME_PATTERN).max(64);
+/** One line of client-reported text: control characters and line breaks never reach the prompt. */
+const FactLine = (max: number) =>
+  z
+    .string()
+    .max(max)
+    .transform((value) => value.replace(/[\p{Cc}\p{Zl}\p{Zp}]+/gu, " ").trim())
+    .pipe(z.string().min(1));
+
+/** A request the client did not run: the person said no, a rule refused it, or it failed. */
+const LocalToolProblem = z.object({
+  status: z.enum(["denied", "failed"]),
+  error: z.string().max(2000),
+});
+
+export const CloudAiLocalListInputSchema = z.object({
+  path: LocalPath.default(".").describe("Folder to list, relative to the workspace."),
+  pattern: z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .optional()
+    .describe("Glob such as **/*.pdf or 2026-09/*.{pdf,jpg}; matching ignores case. ** lists subfolders."),
+  recursive: z.boolean().default(false),
+  limit: z.number().int().min(1).max(AI_LOCAL_LIST_MAX_LIMIT).default(AI_LOCAL_LIST_DEFAULT_LIMIT),
+  after: LocalPath.optional().describe("nextAfter of the previous page."),
+});
+export const CloudAiLocalListOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    path: LocalPath,
+    entries: z
+      .array(
+        z.object({
+          path: LocalPath,
+          type: z.enum(["file", "directory", "other"]),
+          size: z.number().int().min(0),
+          modifiedAt: z.string().max(40),
+        }),
+      )
+      .max(AI_LOCAL_LIST_MAX_LIMIT),
+    nextAfter: LocalPath.nullable(),
+    unreadable: z.array(LocalPath).max(AI_LOCAL_LIST_MAX_LIMIT).optional(),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalReadInputSchema = z.object({
+  path: LocalPath,
+  offset: z.number().int().min(1).default(1).describe("First line to read."),
+  maxBytes: z.number().int().min(1).max(AI_LOCAL_READ_MAX_BYTES).default(AI_LOCAL_READ_DEFAULT_BYTES),
+});
+// Two completed shapes share their status, so this is a plain union rather than one keyed by status.
+export const CloudAiLocalReadOutputSchema = z.union([
+  z.object({
+    status: z.literal("completed"),
+    kind: z.literal("text"),
+    path: LocalPath,
+    /** Lines prefixed with their number and a tab; short lines can make the numbers outweigh the text. */
+    content: z.string().max(AI_LOCAL_READ_MAX_BYTES * 10),
+    firstLine: z.number().int().min(1),
+    lastLine: z.number().int().min(0),
+    totalBytes: z.number().int().min(0),
+    nextOffset: z.number().int().min(1).nullable(),
+  }),
+  z.object({
+    status: z.literal("completed"),
+    kind: z.literal("uploaded"),
+    path: LocalPath,
+    chatPath: ChatPath,
+    mediaType: z.string().max(120),
+    size: z.number().int().min(0),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalUploadInputSchema = z.object({
+  paths: z.array(LocalPath).min(1).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  directory: ChatPath.optional().describe("Chat folder for all files; by default each file keeps its folder from the workspace."),
+});
+export const CloudAiLocalUploadOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    files: z
+      .array(z.object({ path: LocalPath, chatPath: ChatPath, mediaType: z.string().max(120), size: z.number().int().min(0) }))
+      .max(AI_LOCAL_BATCH_MAX_ITEMS),
+    failed: z.array(z.object({ path: LocalPath, error: z.string().max(2000) })).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalDownloadInputSchema = z.object({
+  path: ChatPath.describe("Chat file to save."),
+  to: LocalPath.describe("Target file, relative to the workspace."),
+  replace: z.boolean().default(false),
+});
+export const CloudAiLocalDownloadOutputSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("completed"), path: LocalPath, size: z.number().int().min(0), replaced: z.boolean() }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalWriteInputSchema = z.object({
+  path: LocalPath,
+  content: z.string().refine((value) => new TextEncoder().encode(value).byteLength <= AI_LOCAL_WRITE_MAX_BYTES, "Content exceeds 100 KiB."),
+  mode: z.enum(["create", "append", "replace"]).default("create"),
+});
+export const CloudAiLocalWriteOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    path: LocalPath,
+    mode: z.enum(["create", "append", "replace"]),
+    size: z.number().int().min(0),
+  }),
+  LocalToolProblem,
+]);
+
+const LocalMove = z.object({ from: LocalPath, to: LocalPath });
+export const CloudAiLocalMoveInputSchema = z.object({
+  moves: z.array(LocalMove).min(1).max(AI_LOCAL_BATCH_MAX_ITEMS),
+});
+/** A move batch reports what already moved even when it stops, so the model can name or undo it. */
+export const CloudAiLocalMoveOutputSchema = z.object({
+  status: z.enum(["completed", "denied", "failed"]),
+  moved: z.array(LocalMove).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  conflicts: z.array(z.object({ to: LocalPath, reason: z.string().max(500) })).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  error: z.string().max(2000).optional(),
+});
+
+export const CloudAiLoadLocalSkillInputSchema = z.object({ name: SkillName });
+export const CloudAiLoadLocalSkillOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    name: SkillName,
+    directory: LocalPath,
+    instructions: z.string().max(AI_SKILL_INSTRUCTIONS_MAX_CHARS),
+    files: z.array(LocalPath).max(AI_LOCAL_SKILL_FILES_MAX_ITEMS),
+  }),
+  LocalToolProblem,
+]);
+
+/** Facts about the local client a turn comes from; Cloud renders them into the "# Local client" prompt section. */
+export const AiLocalClientSchema = z.object({
+  kind: z.enum(["cli", "acp"]),
+  /** The editor's ACP clientInfo.name. */
+  name: FactLine(120).optional(),
+  cwd: FactLine(AI_LOCAL_PATH_MAX_CHARS),
+  os: FactLine(120),
+  shell: FactLine(120),
+  localTools: z.enum(["ask", "off"]),
+});
+
+/** AGENTS.md files and local Skills the client found in its workspace for one turn. */
+export const AiLocalContextSchema = z.object({
+  instructions: z
+    .array(z.object({ path: LocalPath, content: z.string() }))
+    .max(64)
+    .refine(
+      (files) =>
+        files.reduce((bytes, file) => bytes + new TextEncoder().encode(file.content).byteLength, 0) <= AI_LOCAL_INSTRUCTIONS_MAX_BYTES,
+      "AGENTS.md content exceeds 32 KiB.",
+    )
+    .default([]),
+  skills: z
+    .array(
+      z.object({
+        name: SkillName,
+        description: z.string().trim().min(1).max(AI_SKILL_DESCRIPTION_MAX_CHARS),
+        scope: z.enum(["project", "global"]),
+        manualOnly: z.boolean().optional(),
+      }),
+    )
+    .max(AI_LOCAL_SKILLS_MAX_ITEMS)
+    .refine((skills) => new Set(skills.map((skill) => skill.name)).size === skills.length, "Local Skill names must be unique.")
+    .default([]),
+  selectedSkills: z
+    .array(
+      z.object({
+        name: SkillName,
+        directory: LocalPath,
+        instructions: z.string().trim().min(1).max(AI_SKILL_INSTRUCTIONS_MAX_CHARS),
+      }),
+    )
+    .max(AI_LOCAL_SELECTED_SKILLS_MAX_ITEMS)
+    .default([]),
+});
+
+export type CloudAiLocalListInput = z.infer<typeof CloudAiLocalListInputSchema>;
+export type CloudAiLocalListOutput = z.infer<typeof CloudAiLocalListOutputSchema>;
+export type CloudAiLocalReadInput = z.infer<typeof CloudAiLocalReadInputSchema>;
+export type CloudAiLocalReadOutput = z.infer<typeof CloudAiLocalReadOutputSchema>;
+export type CloudAiLocalUploadInput = z.infer<typeof CloudAiLocalUploadInputSchema>;
+export type CloudAiLocalUploadOutput = z.infer<typeof CloudAiLocalUploadOutputSchema>;
+export type CloudAiLocalDownloadInput = z.infer<typeof CloudAiLocalDownloadInputSchema>;
+export type CloudAiLocalDownloadOutput = z.infer<typeof CloudAiLocalDownloadOutputSchema>;
+export type CloudAiLocalWriteInput = z.infer<typeof CloudAiLocalWriteInputSchema>;
+export type CloudAiLocalWriteOutput = z.infer<typeof CloudAiLocalWriteOutputSchema>;
+export type CloudAiLocalMoveInput = z.infer<typeof CloudAiLocalMoveInputSchema>;
+export type CloudAiLocalMoveOutput = z.infer<typeof CloudAiLocalMoveOutputSchema>;
+export type CloudAiLoadLocalSkillInput = z.infer<typeof CloudAiLoadLocalSkillInputSchema>;
+export type CloudAiLoadLocalSkillOutput = z.infer<typeof CloudAiLoadLocalSkillOutputSchema>;
+export type AiLocalClient = z.infer<typeof AiLocalClientSchema>;
+export type AiLocalContext = z.infer<typeof AiLocalContextSchema>;