@k2b/cloud 0.23.0 → 0.24.0

package/src/_internal/page-responses.ts

@@ -23,7 +23,7 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     // Auth middleware may reject before ssr() initializes page metadata.
     c.set("page", { lang: getLocale(c) });
     c.header("Cache-Control", "private, no-store");
-    await preloadLayoutAnnouncements(c);
+    if (options.layout !== "pwa") await preloadLayoutAnnouncements(c);
     // Load JSX only after the application's SSR plugin has been installed.
     const { renderPageError } = await import("../ssr/PageError");
     const response = await html(renderPageError(c, status, options), c.get("page"));

package/src/_internal/registry.ts

@@ -1,6 +1,7 @@
 import type { EphemeralConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import type { DashboardWidgetPresentation } from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
@@ -174,24 +175,98 @@ const capabilityEndpoint = (baseUrl: string): string | null => {
 const appAccent = (value: string | undefined): AppAppearanceColor | undefined =>
   /^#[0-9a-f]{6}$/i.test(value ?? "") ? (value as AppAppearanceColor) : undefined;
 
+/** Last manifest per app whose left-out entries were checked, so each registered manifest logs once. */
+const checkedLeftOutEntries = new Map<string, string>();
+
+/**
+ * Logs the entries of a registered manifest that this release left out, typically because the app runs a
+ * newer Cloud release. Core answers those operations as not found, so the operator needs their names.
+ * A left-out file provider is named too, because the app then quietly stops offering files. `manifest` is
+ * the manifest as read, before the file-provider contract check, which logs its own rejections.
+ */
+const reportLeftOutEntries = (sent: unknown, manifest: CapabilityManifest): void => {
+  if (checkedLeftOutEntries.get(manifest.appId) === manifest.manifestHash) return;
+  checkedLeftOutEntries.set(manifest.appId, manifest.manifestHash);
+  const kept = new Set([...manifest.types, ...manifest.queries, ...manifest.actions, ...manifest.commands].map((entry) => entry.localId));
+  const groups = sent as Record<string, unknown>;
+  const leftOut = (["types", "queries", "actions", "commands"] as const).flatMap((group) => {
+    const entries = groups[group];
+    if (!Array.isArray(entries)) return [];
+    return entries.flatMap((entry: unknown) => {
+      const localId = entry && typeof entry === "object" ? (entry as { localId?: unknown }).localId : undefined;
+      return typeof localId === "string" && !kept.has(localId) ? [`${group}/${localId}`] : [];
+    });
+  });
+  if (groups.fileProvider !== undefined && !manifest.fileProvider) leftOut.push("fileProvider");
+  if (leftOut.length === 0) return;
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      source: "capability-registry",
+      message: "Left out capability entries this Cloud release cannot read",
+      appId: manifest.appId,
+      manifestHash: manifest.manifestHash,
+      leftOutCount: leftOut.length,
+      leftOut: leftOut.slice(0, 20),
+    }),
+  );
+};
+
+/** Last checked manifest per app: its hash and whether its file provider passed the contract check. */
+const checkedFileProviders = new Map<string, { manifestHash: string; valid: boolean }>();
+
+/**
+ * Ignores a file provider that does not match the contract, logging once per manifest; the app's other
+ * capabilities stay available. The delivered `manifestHash` stays, because it identifies what the app registered.
+ */
+const withValidFileProvider = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.fileProvider) return manifest;
+  const checked = checkedFileProviders.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = fileProviderIssues(manifest);
+    valid = issues.length === 0;
+    checkedFileProviders.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid) {
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored a file provider that does not match the file-provider contract",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues: issues
+            .slice(0, 10)
+            .map(({ function: name, localId, code, path, message }) => ({ function: name, localId, code, path, message })),
+        }),
+      );
+    }
+  }
+  if (valid) return manifest;
+  const { fileProvider: _ignored, ...rest } = manifest;
+  return rest;
+};
+
+/** Ignores record fields from a newer release; the endpoint always comes from the live app registry. */
 export const resolveLiveCapabilityRegistryEntry = (
   key: string,
   value: unknown,
   app: AppRegistryEntry | undefined,
 ): CapabilityRegistryEntry | null => {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  if (Object.keys(value).some((field) => field !== "appId" && field !== "manifest" && field !== "presentation")) return null;
   const record = value as Partial<CapabilityRegistryRecord>;
   if (!app || typeof record.appId !== "string" || key !== `capabilities/${record.appId}` || record.appId !== app.id) return null;
   if (!app.capabilities) return null;
   const endpoint = capabilityEndpoint(app.baseUrl);
   if (!endpoint) return null;
   try {
-    const manifest = parseCapabilityManifest(record.manifest, app.id);
-    const presentation = compileCapabilityPresentation(manifest, record.presentation);
+    const read = parseCapabilityManifest(record.manifest, app.id);
+    const manifest = withValidFileProvider(read);
+    const presentation = compileCapabilityPresentation(manifest, record.presentation, "reader");
     if (app.capabilities.protocolVersion !== manifest.protocolVersion || app.capabilities.manifestHash !== manifest.manifestHash) {
       return null;
     }
+    reportLeftOutEntries(record.manifest, read);
     return {
       appId: app.id,
       appName: app.name,

package/src/ai/chat/blocks.tsx

@@ -705,11 +705,12 @@ function ToolBlockView(props: { turnId: string; block: ToolBlock; active?: boole
 
 /** Render one unified turn block. Shared by persisted assistant groups and the live turn. */
 export function AiTurnBlockView(props: { block: AiTurnBlock; turnId: string; streaming?: boolean; active?: boolean }) {
+  const locale = useLocale();
   // The id/kind remain stable while the immutable block value changes during a turn.
   return (
     <Switch>
       <Match when={props.block.kind === "text" && props.block}>
-        {(block) => <AssistantMarkdownBlock html={markdown.renderSync(block().text)} />}
+        {(block) => <AssistantMarkdownBlock html={markdown.renderSync(block().text, { locale: locale() })} />}
       </Match>
       <Match when={props.block.kind === "thinking" && props.block}>
         {(block) => <ThinkingBlockView text={block().text} streaming={props.streaming} />}

package/src/ai/chat/messages.ts

@@ -22,6 +22,9 @@ const messages = i18n.define({
       thinking: "Thinking",
       showReasoning: "Show reasoning",
       byteRange: ({ start, end }: { start: string; end: string }) => `Bytes ${start}–${end}`,
+      streamLoginRequired: "Your session has ended. Sign in again to continue this chat.",
+      streamAccessDenied: "You no longer have access to this chat.",
+      streamNotFound: "This chat is no longer available.",
     },
     de: {
       backgroundRun: "Hintergrundlauf",
@@ -43,6 +46,9 @@ const messages = i18n.define({
       thinking: "Denkt nach",
       showReasoning: "Denkprozess anzeigen",
       byteRange: ({ start, end }) => `Bytes ${start}–${end}`,
+      streamLoginRequired: "Deine Sitzung ist abgelaufen. Melde dich erneut an, um diesen Chat fortzusetzen.",
+      streamAccessDenied: "Du hast keinen Zugriff mehr auf diesen Chat.",
+      streamNotFound: "Dieser Chat ist nicht mehr verfügbar.",
     },
   },
 });

package/src/ai/client/controller.ts

@@ -1,6 +1,7 @@
 import { type Accessor, createMemo, createSignal, onCleanup } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { type AiAttachmentRef, aiAttachmentMarker } from "../attachments";
+import { aiChatMessages } from "../chat/messages";
 import { type AiStreamEvent, type AiTurnBlock, type AiTurnSnapshot, steerMessageBlockId } from "../protocol";
 import { type AiResourceMarker, aiResourceMarker } from "../resource-markers";
 import type {
@@ -24,7 +25,14 @@ import {
   reduceProjection,
   visibleMessages,
 } from "./projection";
-import { type AiConversationStreamTransport, type AiStreamHandle, aiSseConversationStreamTransport } from "./transport";
+import {
+  type AiConversationStreamTransport,
+  AiStreamError,
+  type AiStreamErrorCode,
+  type AiStreamHandle,
+  aiSseConversationStreamTransport,
+  terminalAiStreamErrorCode,
+} from "./transport";
 
 type ComposerDraftInput = {
   draftContent?: AiDraftContentPart[];
@@ -108,7 +116,7 @@ export type CreateAiChatControllerOptions = {
   frontendTools?: Record<string, AiFrontendToolHandler>;
   /** Explicitly advertise only client tools with a connected handler. */
   clientToolIds?: AiClientToolId[];
-  /** Overrides the default SSE transport, for example with a shared WebSocket channel. */
+  /** Overrides the default SSE transport of the conversation stream. */
   streamTransport?: AiConversationStreamTransport;
 };
 
@@ -142,6 +150,21 @@ const completeFrontendToolBlock = (blocks: AiTurnBlock[], callId: string, result
 const isActiveConversationLoading = (activeConversationId: string | null, loadingConversationId: string | null): boolean =>
   activeConversationId !== null && loadingConversationId === activeConversationId;
 
+/**
+ * Why the stream ended, in the request's locale: the server renders it into
+ * `<html lang>`, which is also what `useLocale()` of `@k2b/ui` resolves in an
+ * island. The controller stays headless and does not load the component library.
+ */
+const streamErrorText = (code: AiStreamErrorCode): string => {
+  const t = aiChatMessages(typeof document === "undefined" ? "en" : document.documentElement.lang || "en");
+  if (code === "login_required") return t.streamLoginRequired;
+  return code === "access_denied" ? t.streamAccessDenied : t.streamNotFound;
+};
+
+/** A chat that cannot continue says why in the page's language; any other error shows its own message. */
+const errorText = (error: unknown, fallback: string): string =>
+  error instanceof AiStreamError ? streamErrorText(error.code) : error instanceof Error ? error.message : fallback;
+
 export const createAiChatController = (options: CreateAiChatControllerOptions) => {
   const [activeConversationId, setActiveConversationIdSignal] = createSignal<string | null>(options.initialConversationId ?? null);
   const [globalError, setGlobalError] = createSignal<string | null>(options.initialError ?? null);
@@ -330,13 +353,18 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
       // or action in this chat can subscribe again.
       onError: (error) => {
         if (!isCurrentStreamSession(streamSession, session)) return;
-        closeStream();
-        streamError = error.message;
-        setConversationError(conversationId, error.message);
+        endStream(conversationId, error);
       },
     });
   };
 
+  /** Stops the chat's stream for good and shows why. */
+  const endStream = (conversationId: string, error: Error) => {
+    closeStream();
+    streamError = errorText(error, error.message);
+    setConversationError(conversationId, streamError);
+  };
+
   // ---- frontend tools ---------------------------------------------------
 
   const runFrontendTools = () => {
@@ -393,13 +421,20 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     } catch {}
   };
 
+  /** Loads a chat. A status after which no retry can load it throws an `AiStreamError`, like the stream's. */
+  const fetchDetail = async (conversationId: string, fallback: string): Promise<AiConversationDetail> => {
+    const response = await fetch(url(`/conversations/${conversationId}`));
+    if (response.ok) return (await response.json()) as AiConversationDetail;
+    const message = await readError(response, fallback);
+    const ended = terminalAiStreamErrorCode(response.status);
+    throw ended ? new AiStreamError(ended, message) : new Error(message);
+  };
+
   const loadDetail = async (conversationId: string, shouldReportError: () => boolean): Promise<AiConversationDetail | null> => {
     try {
-      return await request<AiConversationDetail>(`/conversations/${conversationId}`, { method: "GET" }, "Failed to open conversation");
+      return await fetchDetail(conversationId, "Failed to open conversation");
     } catch (loadError) {
-      if (shouldReportError()) {
-        setConversationError(conversationId, loadError instanceof Error ? loadError.message : "Failed to open conversation");
-      }
+      if (shouldReportError()) setConversationError(conversationId, errorText(loadError, "Failed to open conversation"));
       return null;
     }
   };
@@ -474,22 +509,31 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
   };
 
   let conversationRefreshGeneration = 0;
-  const refreshActiveConversation = async (): Promise<void> => {
+  /**
+   * Loads the active chat again. Resolves `false` when it no longer exists or
+   * is no longer readable: the chat then ends like its stream, with the reason
+   * as its error, because no retry can load it. A response that a newer
+   * refresh or a newer opening of a chat overtook changes nothing.
+   */
+  const refreshActiveConversation = async (): Promise<boolean> => {
     const conversationId = activeConversationId();
-    if (!conversationId) return;
+    if (!conversationId) return true;
     const refreshGeneration = ++conversationRefreshGeneration;
     const openGeneration = conversationOpenGeneration;
-    const detail = await request<AiConversationDetail>(
-      `/conversations/${conversationId}`,
-      { method: "GET" },
-      "Failed to refresh conversation",
-    );
-    if (
+    const overtaken = () =>
       !isActiveConversation(conversationId) ||
       refreshGeneration !== conversationRefreshGeneration ||
-      openGeneration !== conversationOpenGeneration
-    )
-      return;
+      openGeneration !== conversationOpenGeneration;
+    let detail: AiConversationDetail;
+    try {
+      detail = await fetchDetail(conversationId, "Failed to refresh conversation");
+    } catch (refreshError) {
+      if (!(refreshError instanceof AiStreamError)) throw refreshError;
+      if (overtaken()) return true;
+      endStream(conversationId, refreshError);
+      return false;
+    }
+    if (overtaken()) return true;
     const currentDraft = state.conversation?.draft;
     if (currentDraft && currentDraft.revision > detail.conversation.draft.revision) detail.conversation.draft = currentDraft;
     const windowOldest = detail.messages[0]?.seq;
@@ -499,6 +543,7 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (detail.timeline) setTimeline(conversationId, detail.timeline);
     setRunError(conversationRunError(detail.conversation));
     openStream(conversationId);
+    return true;
   };
 
   const requestMessagesPage = async (conversationId: string, before: number, limit: number): Promise<AiMessagesPage> => {

package/src/ai/client/transport.ts

@@ -13,10 +13,7 @@ export type AiConversationStreamTransport = {
   }) => AiStreamHandle;
 };
 
-/**
- * Why a conversation stream ended for good. The codes match the live
- * WebSocket's turn errors and revocations.
- */
+/** Why a conversation stream ended for good. A client shows its own text for the code. */
 export type AiStreamErrorCode = "login_required" | "access_denied" | "not_found";
 
 /** A stream that will not recover by reconnecting; `message` comes from the server when it sent one. */
@@ -36,6 +33,9 @@ const TERMINAL_STATUS_CODES: Readonly<Record<number, AiStreamErrorCode>> = {
   404: "not_found",
 };
 
+/** The code of an HTTP status after which a conversation cannot continue, by retrying or reconnecting. */
+export const terminalAiStreamErrorCode = (status: number): AiStreamErrorCode | undefined => TERMINAL_STATUS_CODES[status];
+
 const terminalStreamError = async (response: Response, code: AiStreamErrorCode): Promise<AiStreamError> => {
   const body: unknown = await response.json().catch(() => null);
   const message =
@@ -116,7 +116,7 @@ export const subscribeAiStream = (input: {
         input.onStatus?.(reconnectDelay === RECONNECT_BASE_MS ? "connecting" : "reconnecting");
         const response = await fetchStream(input.url, { signal: attempt.signal, headers: { Accept: "text/event-stream" } });
         if (stopped) return;
-        const terminalCode = TERMINAL_STATUS_CODES[response.status];
+        const terminalCode = terminalAiStreamErrorCode(response.status);
         if (terminalCode) {
           // The connect timeout still bounds reading the error body.
           const error = await terminalStreamError(response, terminalCode);

package/src/ai/code-mode-skill.ts

@@ -4,7 +4,7 @@ import type { AiSkillTemplate } from "./skills";
 
 export const ASSISTANT_CODE_MODE_SKILL = {
   "key": "assistant:code-mode",
-  "version": 56,
+  "version": 57,
   "name": "assistant-code-mode",
   "description": "Inspect and transform unfamiliar data, analyze files, compare results across Cloud apps, or build and improve interactive and agent-only Apps in Assistant Studio. Use for quick code experiments, data analysis, file generation, resource SQL queries and combining discovered Cloud capabilities. For plain arithmetic or date offsets, answer directly or use calculate.",
   "instructions": "# Assistant code mode\n\nChoose the smallest useful result: one-off answer, exported file, or reusable\nStudio App. Apps may expose agent actions, a display-only dashboard, or both.\nPersistence is optional. One-off scripts stay in their chat and cannot be shared. Reuse an\nexisting Cloud feature when it fits. For a\nquick reading of an uploaded PDF or Office document, `read_file` can return\nMarkdown; use code for exact cells, calculations, original PDF text or positions.\n\n## Start from the contract\n\nLoad the needed `code_*` tools individually through `load_tools` and read their\ninput schemas. They are Assistant tools, not capabilities or functions inside\ncode. Discover other Cloud operations before using `capabilities.run`.\n\nRuntime namespaces are globals: no imports or package installation are needed.\nOnly relative imports of the resource's own source files are supported. There is\nno DOM or native network access. Before using a namespace, read its reference\nbelow for signatures, options and return values. Do not invent methods or infer\nan API from a familiar library. For discovered Cloud capabilities and external\nAPIs, obtain their actual contracts separately.\n\nInspect supplied data before joining, filtering or calculating: column names,\ntypes, units, date ranges and missing values. Ask only for decisions or inputs\nthat cannot be established from available evidence. For several real steps,\nkeep a short `todo_write` plan and update it as work changes; skip ceremony for a\nsmall experiment. A failed experiment should change the next hypothesis.\n\n## First file script\n\nPass exact current-chat manifest paths as `code_run.inputPaths`, and this entry\nas `code_run.code` for a small CSV:\n\n```js\nexport default async () => {\n  const [input] = await files.list();\n  if (!input) throw new Error(\"Select a CSV input.\");\n  const rows = await sheet.fromCsv(await files.read(input.name));\n  return { rows: rows.length, columns: Object.keys(rows[0] ?? {}), sample: rows.slice(0, 3) };\n};\n```\n\n`input.name` is the full path, such as `/sales.csv`; pass it unchanged to\n`files.read`, which returns a `File`. CSV rows are objects keyed by headers:\n`rows[0]` is already data. Do not drop it. For older Excel CSVs, use\n`sheet.fromCsv(file, {encoding:\"windows-1252\"})`. Inspect actual headings first.\nFor a tiny experiment without files, `export default () => ({answer:42})` suffices.\nEach run has fresh variables. No saved resource or UI is required.\n\n## Reference routing\n\nRead only the rows relevant to the task. Each link describes its own complete\nsupported surface; links within references add related workflows when needed.\n\n| Task / API | Read |\n| --- | --- |\n| Source entry, input/output files, pickers, CSV, IDs | [Runtime and files](/skills/assistant-code-mode/references/runtime.md) |\n| Inspect PDF pages, read PDF text/positions or XLSX/ODS cells, write ODS | [Documents](/skills/assistant-code-mode/references/documents.md) |\n| Generate a PDF, save one in Files, embed attachments, combine invoice HTML and XML | [PDF generation](/skills/assistant-code-mode/references/pdf.md) |\n| Exact amounts, taxes, allocation, localized money | [Money](/skills/assistant-code-mode/references/money.md) |\n| Export DATEV bookings or SEPA transfers | [DATEV and SEPA](/skills/assistant-code-mode/references/finance.md) |\n| Parse a CAMT bank report | [Bank reports](/skills/assistant-code-mode/references/camt.md) |\n| Calculate, create or read electronic invoices/XML/PDF attachments | [Electronic invoices](/skills/assistant-code-mode/references/einvoice.md) |\n| Controls, layouts and dialogs | [UI and dialogs](/skills/assistant-code-mode/references/ui.md), [Analytics UI](/skills/assistant-code-mode/references/analytics.md) |\n| Chart types, series and axes | [Charts](/skills/assistant-code-mode/references/charts.md) |\n| Long processing, progress, cancellation | [Background work](/skills/assistant-code-mode/references/work.md) |\n| Persist JSON or files locally/shared | [Storage](/skills/assistant-code-mode/references/storage.md) |\n| Copy files between stores; list and download Filesv2 beside Grids documents | [File transfers](/skills/assistant-code-mode/references/files.md) |\n| Resource SQL, schema, row CRUD, imports | [Database](/skills/assistant-code-mode/references/database.md) |\n| Generate text, classify data or extract structured fields | [AI calculations](/skills/assistant-code-mode/references/ai.md) |\n| Discovered Cloud queries/actions | [Capability calls](/skills/assistant-code-mode/references/capabilities.md) |\n| External HTTPS and personal secrets | [HTTP and secrets](/skills/assistant-code-mode/references/http.md) |\n| Call a published App action; declare handlers | [App actions](/skills/assistant-code-mode/references/app-actions.md) |\n| Reuse work across chats, create or edit an App | [Source workflow](/skills/assistant-code-mode/references/source-workflow.md) |\n| Publish, restore, copy | [Publishing](/skills/assistant-code-mode/references/publishing.md) |\n| Find recipients or change App/Skill sharing | [Access](/skills/assistant-code-mode/references/access.md) |\n| Inspect, export, clear server data, or delete an App | [Management](/skills/assistant-code-mode/references/management.md) |\n| Execute, inspect, interact, export, stop, diagnose errors | [Run and debug](/skills/assistant-code-mode/references/debugging.md) |\n| Unfamiliar inputs or cross-app investigation | [Investigation](/skills/assistant-code-mode/references/investigation.md) |\n| Complete app starters | [Examples](/skills/assistant-code-mode/references/examples.md) |\n\nFor a new app, read Source workflow and the closest complete example before\nwriting source, plus only the API references it uses. For analytical reports or\ndashboards, also load `assistant-data-analysis` for metrics and source validation.\n\n## Choose the delivery\n\nFor a one-off chart, calculator, or interactive analysis in this conversation,\nuse `code_run({code,inputPaths})`, test the controls, then\n`code_present({runId,title})`. Read [Chat visualizations](/skills/assistant-code-mode/references/chat.md).\nA successful run is visible to the agent only; present it before saying the\nuser can see it. No saved App or chat file is necessary.\n\nUse a Studio App when the user needs an independently accessible, reusable\napplication. Use `files.save`, `code_export`, and `present` when the requested\nresult is a file. These are separate delivery choices.\n\n## Verify and deliver\n\nRun the actual source (the saved revision for Apps) and test relevant controls with IDs returned by\n`code_run`/`code_interact`, including invalid inputs and picker fixtures. Creating,\ncompiling or saving source does not verify behavior. If `work.status` is\n`running`, wait with `code_inspect({runId,waitMs:30000})`; do not restart the job.\nInspect only when the returned snapshot needs more detail. Errors and\n`outputTruncated` are not successful complete results.\n\nFor a CSV, call `await files.save(sheet.toCsv(rows), \"result.csv\")` inside code;\nfor a spreadsheet, `await files.save(await sheet.toOds(sheets), \"result.ods\")`.\nThen call the **tool** `code_export` with the returned `runId` and captured file\nname, and `present` its returned chat path. `files.save` returns no path.\nReuse exported data via its path/version rather than retyping truncated output.\nReconcile row counts, exclusions and totals before reporting findings.\n\nOpen GUI apps with `code_open`. Saving or testing does\nnot replace a user's already-running app. Stop runs no longer needed that retain\nUI, jobs or output files. Never claim an unexecuted result is verified.\n\nAgent execution runs independently of the user's tab. Agent local storage is\ntemporary; shared storage, database writes and external actions are real, even\nin tests. Cancellation and source restore do not undo them. Apps select local\nfiles explicitly; they never gain implicit access to chat attachments. Use\n`code_secret` for credentials, never chat or app controls. Honor normal access\nand approval decisions; availability is not authorization for unrelated actions.",
@@ -64,7 +64,7 @@ export const ASSISTANT_CODE_MODE_SKILL = {
     },
     {
       "path": "references/files.md",
-      "content": "# Explicit file references and transfers\n\nFiles belong to a chat, Project, or App shared store. A location is\n`{scope:\"chat\"|\"project\"|\"app\",id,path}`. A reference adds an opaque string\n`version`. The current chat ID is supplied as `Chat:` in the platform context;\nuse it for `scope:\"chat\"` rather than guessing an ID. Reuse returned locations and references exactly; access to a location\nnever grants access to its whole store or to another resource.\n\nLoad only `code_files`, `code_file_stat`, and `code_file_copy` as needed.\n\n1. `code_files({scope,id,after?:string,limit?:number})` returns `container`,\n   `items:[{location,path,size,mediaType}]`, and `nextAfter`. Limit defaults to\n   100, maximum 1,000. Continue with `nextAfter` until null.\n2. `code_file_stat({file:location})` returns `{exists:false}` or\n   `{exists:true,reference,size,mediaType}`. It does not print file bytes.\n3. `code_file_copy({source:reference,destination:location,expectedVersion})`\n   copies bytes on the server. For a new destination use `expectedVersion:null`;\n   replacing a file requires its exact current version from `code_file_stat`.\n   The result contains the destination `reference,size,mediaType`.\n\nEvery copy receives fresh user review with the exact source, destination, and\noverwrite scope. App and Project files may be readable by other authorized\nusers; copying a private chat attachment there is an explicit disclosure.\nRejection does not copy anything. Source versions, destination versions, current\npermissions, and the destination's byte limits are checked again during execution.\nAfter a conflict, inspect current state and prepare a new review before retrying.\n\nApp file reads and writes require Use, not Manage. Project files require Read\nfor sources and Write for destinations. Chat files require ownership. Transfers\nwork without a running UI and do not mount other chat attachments implicitly.\n\nFor example, inspect an invoice attachment, copy its reference into the target\nApp's shared file store, then call the App's published `importFiles` action with\nthe destination key expected by its discovered input schema. Do not pass a chat\npath to an App and assume it can read it. Action handlers see only their explicit\ninput and authorized App data. Use [App actions](app-actions.md) for discovery.\n\nFor small UTF-8 files that should become App source, use\n`code_write({id,expectedRevision,files:[{path:\"data.json\",fromFile:reference}]})`.\nThis is a reviewed import with the same source references, not a chat-only\nspecial case. Source file/bundle limits still apply; keep larger or private\nruntime data in shared files or the database instead of embedding it in source.\n\nKnown rejections return `CONFLICT` for an occupied or changed destination and\n`STORAGE_FULL` for a destination byte limit. No destination bytes were written.\nChoose another path or reduce the file size, then prepare a new review.\n\n\n## List Filesv2 files beside Grids documents\n\nDiscover the installed contracts first. Call `filesv2.bases.list`, then\n`filesv2.entry.list` for a folder or `filesv2.entry.search-in-base` for names\nbelow a known path. Keep the filters unchanged and follow `data.next` as\n`after` until null, even after an empty page. Each `data.items` entry includes\nits own `{type:\"filesv2.entry\",id}` ref and file metadata. Keep that ref in the\nStudio list, alongside the `grids.document` refs from `grids.document.list`.\nUse both `type` and `id` as the identity; dispatch each type to its own\noperations. Grids uses its own `page` cursor, not Filesv2's `data.next`.\n\nFilesv2 refs identify a base and path, including long paths; they do not grant\naccess or pin a content version. Moving or renaming changes the ref, and\nreplacing bytes at the same path keeps it. Refresh metadata when needed.\nNever construct storage URLs or turn files into public shares for this flow.\n\nOnly on a user's download request, call `filesv2.content.download` with the\nselected Filesv2 ref's exact `id`. Its `data` is `{url,method:\"GET\",expires}`.\nOffer that returned URL unchanged to the requesting user; it is a private\nbearer credential, not a stable resource link. It expires after 60 seconds;\nuse the returned `expires` timestamp and request a fresh lease when needed.\nDo not prefetch leases for list rows, persist them in App/shared data, or\ninclude them in logs. Do not send Cloud cookies or authorization headers to\nthe storage host. Grids documents keep their authenticated download path from\ntheir canonical reader; never send a `grids.document` ID to Filesv2.\n\nEach lease request checks the current user's storage and Unix permissions.\nA 403 means access is denied; a 404 means the ref or file is missing or the\nbase is no longer visible. Refresh the list and do not bypass the denial.\n`not_file` (400) means a folder was selected. `identity_changed` (409) requires\nrefreshing access/identity state before trying again. Storage unavailability is an\nerror, not an empty list. If a lease expires or a transfer fails, discard the\nURL and request a fresh lease through the same capability; if that is denied,\nstop. Revoking Cloud access prevents new leases; an already issued bearer\nlease can remain usable until expiry, subject to storage checks.\n\nFor analysis inside code, use `filesv2.content.read` and\n`capabilities.streams.read` instead of fetching a bearer URL. See\n[Capability calls](capabilities.md) for binary budgets and consent rules.\n"
+      "content": "# Explicit file references and transfers\n\nFiles belong to a chat, Project, or App shared store. A location is\n`{scope:\"chat\"|\"project\"|\"app\",id,path}`. A reference adds an opaque string\n`version`. The current chat ID is supplied as `Chat:` in the platform context;\nuse it for `scope:\"chat\"` rather than guessing an ID. Reuse returned locations and references exactly; access to a location\nnever grants access to its whole store or to another resource.\n\nLoad only `code_files`, `code_file_stat`, and `code_file_copy` as needed.\n\n1. `code_files({scope,id,after?:string,limit?:number})` returns `container`,\n   `items:[{location,path,size,mediaType}]`, and `nextAfter`. Limit defaults to\n   100, maximum 1,000. Continue with `nextAfter` until null.\n2. `code_file_stat({file:location})` returns `{exists:false}` or\n   `{exists:true,reference,size,mediaType}`. It does not print file bytes.\n3. `code_file_copy({source:reference,destination:location,expectedVersion})`\n   copies bytes on the server. For a new destination use `expectedVersion:null`;\n   replacing a file requires its exact current version from `code_file_stat`.\n   The result contains the destination `reference,size,mediaType`.\n\nEvery copy receives fresh user review with the exact source, destination, and\noverwrite scope. App and Project files may be readable by other authorized\nusers; copying a private chat attachment there is an explicit disclosure.\nRejection does not copy anything. Source versions, destination versions, current\npermissions, and the destination's byte limits are checked again during execution.\nAfter a conflict, inspect current state and prepare a new review before retrying.\n\nApp file reads and writes require Use, not Manage. Project files require Read\nfor sources and Write for destinations. Chat files require ownership. Transfers\nwork without a running UI and do not mount other chat attachments implicitly.\n\nFor example, inspect an invoice attachment, copy its reference into the target\nApp's shared file store, then call the App's published `importFiles` action with\nthe destination key expected by its discovered input schema. Do not pass a chat\npath to an App and assume it can read it. Action handlers see only their explicit\ninput and authorized App data. Use [App actions](app-actions.md) for discovery.\n\nFor small UTF-8 files that should become App source, use\n`code_write({id,expectedRevision,files:[{path:\"data.json\",fromFile:reference}]})`.\nThis is a reviewed import with the same source references, not a chat-only\nspecial case. Source file/bundle limits still apply; keep larger or private\nruntime data in shared files or the database instead of embedding it in source.\n\nKnown rejections return `CONFLICT` for an occupied or changed destination and\n`STORAGE_FULL` for a destination byte limit. No destination bytes were written.\nChoose another path or reduce the file size, then prepare a new review.\n\n\n## List Filesv2 files beside Grids documents\n\nDiscover the installed contracts first. Call `filesv2.bases.list`, then\n`filesv2.entry.list` for a folder or `filesv2.entry.search-in-base` for names\nbelow a known path. Keep the filters unchanged and follow `data.next` as\n`after` until null, even after an empty page. Each `data.items` entry includes\nits own `{type:\"filesv2.entry\",id}` ref and file metadata. Keep that ref in the\nStudio list, alongside the `grids.document` refs from `grids.document.list`.\nUse both `type` and `id` as the identity; dispatch each type to its own\noperations. Grids uses its own `page` cursor, not Filesv2's `data.next`.\n\nFilesv2 refs are opaque; they do not grant access or pin a content version.\nOn storage with stable file IDs (`n:…` refs), a ref keeps naming the same file\nacross rename and move; elsewhere it names a base and path, so moving or\nrenaming changes it. Store refs exactly as returned and never build one from a\npath. Different refs can name the same file, because older path refs stay\nvalid. A 404 means not found or no longer visible; 503 is an outage, not a\ndeletion. Refresh metadata when needed. Never construct storage URLs or turn\nfiles into public shares for this flow.\n\nOnly on a user's download request, call `filesv2.content.download` with the\nselected Filesv2 ref's exact `id`. Its `data` is `{url,method:\"GET\",expires}`.\nOffer that returned URL unchanged to the requesting user; it is a private\nbearer credential, not a stable resource link. It expires after 60 seconds;\nuse the returned `expires` timestamp and request a fresh lease when needed.\nDo not prefetch leases for list rows, persist them in App/shared data, or\ninclude them in logs. Do not send Cloud cookies or authorization headers to\nthe storage host. Grids documents keep their authenticated download path from\ntheir canonical reader; never send a `grids.document` ID to Filesv2.\n\nEach lease request checks the current user's storage and Unix permissions.\nA 403 means access is denied; a 404 means the ref or file is missing or the\nbase is no longer visible. Refresh the list and do not bypass the denial.\n`not_file` (400) means a folder was selected. `identity_changed` (409) requires\nrefreshing access/identity state before trying again. Storage unavailability is an\nerror, not an empty list. If a lease expires or a transfer fails, discard the\nURL and request a fresh lease through the same capability; if that is denied,\nstop. Revoking Cloud access prevents new leases; an already issued bearer\nlease can remain usable until expiry, subject to storage checks.\n\nFor analysis inside code, use `filesv2.content.read` and\n`capabilities.streams.read` instead of fetching a bearer URL. See\n[Capability calls](capabilities.md) for binary budgets and consent rules.\n"
     },
     {
       "path": "references/finance.md",

package/src/ai/index.ts

@@ -128,17 +128,10 @@ export {
 export { AI_IMAGE_INPUT_MAX_BYTES, AI_TURN_ATTACHMENT_MAX_ITEMS, AI_TURN_IMAGE_MAX_TOTAL_BYTES } from "./limits";
 export {
   AI_INVALIDATION_DOMAINS,
-  AI_LIVE_WS_TYPE,
   type AiInvalidation,
   type AiInvalidationDomain,
   AiInvalidationDomainSchema,
   AiInvalidationSchema,
-  type AiLiveClientMessage,
-  AiLiveClientMessageSchema,
-  AiLiveCursorSchema,
-  type AiLiveServerMessage,
-  AiLiveServerMessageSchema,
-  parseAiLiveServerMessage,
 } from "./live-events";
 export { AI_ENRICH_CRON_SETTING_KEY, AI_MEMORY_LEARNING_CRON_SETTING_KEY, aiMaintenanceJobs } from "./maintenance";
 export {