@k2b/cloud 0.22.0 → 0.24.0

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 {

package/src/ai/live-events.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import type { AiStreamEvent } from "./protocol";
 
 export const AI_INVALIDATION_DOMAINS = [
   "conversation-list",
@@ -17,8 +16,8 @@ export const AiInvalidationDomainSchema = z.enum(AI_INVALIDATION_DOMAINS);
 export type AiInvalidationDomain = z.infer<typeof AiInvalidationDomainSchema>;
 
 export const AiResourceIdSchema = z.string().regex(/^[0-9A-Za-z]{6}$/);
-export const AiLiveCursorSchema = z.string().regex(/^s6t\.[a-zA-Z0-9_-]+\.\d+$/);
 
+/** The data of one AI live update on the `user` channel of `/api/ai/live`: which views of the user's AI data changed. */
 export const AiInvalidationSchema = z
   .object({
     type: z.literal("ai.invalidated"),
@@ -31,263 +30,3 @@ export const AiInvalidationSchema = z
   .strict();
 
 export type AiInvalidation = z.infer<typeof AiInvalidationSchema>;
-
-export const AI_LIVE_WS_TYPE = {
-  subscribe: "ai.live.subscribe",
-  ready: "ai.live.ready",
-  event: "ai.live.event",
-  scopeChanged: "ai.live.scope_changed",
-  revoked: "ai.live.revoked",
-  error: "ai.live.error",
-  turnSubscribe: "ai.turn.subscribe",
-  turnUnsubscribe: "ai.turn.unsubscribe",
-  turnEvent: "ai.turn.event",
-  turnError: "ai.turn.error",
-} as const;
-
-const AiLiveSubscribeMessageSchema = z
-  .object({
-    type: z.literal(AI_LIVE_WS_TYPE.subscribe),
-    payload: z.object({ fromCursor: AiLiveCursorSchema.nullable(), recover: z.boolean() }).strict(),
-  })
-  .strict();
-
-const AiTurnSubscribeMessageSchema = z
-  .object({
-    type: z.literal(AI_LIVE_WS_TYPE.turnSubscribe),
-    payload: z.object({ conversationId: AiResourceIdSchema }).strict(),
-  })
-  .strict();
-
-const AiTurnUnsubscribeMessageSchema = z
-  .object({
-    type: z.literal(AI_LIVE_WS_TYPE.turnUnsubscribe),
-    payload: z.object({ conversationId: AiResourceIdSchema }).strict(),
-  })
-  .strict();
-
-export const AiLiveClientMessageSchema = z.discriminatedUnion("type", [
-  AiLiveSubscribeMessageSchema,
-  AiTurnSubscribeMessageSchema,
-  AiTurnUnsubscribeMessageSchema,
-]);
-export type AiLiveClientMessage = z.infer<typeof AiLiveClientMessageSchema>;
-
-const AiLiveRevocationCodeSchema = z.enum(["login_required", "access_denied"]);
-const AiLiveErrorCodeSchema = z.enum(["invalid_json", "invalid_message", "backpressure", "internal_error", "stream_failed"]);
-const AiTurnErrorCodeSchema = z.enum(["not_found", "access_denied", "stream_failed"]);
-
-export type AiLiveRevocationCode = z.infer<typeof AiLiveRevocationCodeSchema>;
-export type AiLiveErrorCode = z.infer<typeof AiLiveErrorCodeSchema>;
-export type AiTurnErrorCode = z.infer<typeof AiTurnErrorCodeSchema>;
-
-const AiTurnBlockSchema = z.discriminatedUnion("kind", [
-  z.object({ id: z.string(), kind: z.literal("text"), text: z.string() }).strict(),
-  z.object({ id: z.string(), kind: z.literal("thinking"), text: z.string() }).strict(),
-  z
-    .object({
-      id: z.string(),
-      kind: z.literal("steer_message"),
-      steerId: z.string(),
-      text: z.string(),
-      status: z.enum(["pending", "consumed", "failed"]),
-    })
-    .strict(),
-  z.object({ id: z.string(), kind: z.literal("steer_applied"), steerId: z.string() }).strict(),
-  z
-    .object({
-      id: z.string(),
-      kind: z.literal("tool"),
-      callId: z.string(),
-      name: z.string(),
-      args: z.unknown().optional(),
-      status: z.enum(["running", "awaiting_approval", "awaiting_client", "completed", "failed", "rejected"]),
-      result: z.unknown().optional(),
-      isError: z.boolean().optional(),
-      approval: z.unknown().optional(),
-      frontendMode: z.enum(["client", "client_view", "client_interaction"]).optional(),
-      presentation: z.unknown().optional(),
-    })
-    .strict(),
-  z
-    .object({
-      id: z.string(),
-      kind: z.literal("compaction"),
-      status: z.enum(["running", "completed", "skipped", "failed"]),
-      result: z.unknown().optional(),
-    })
-    .strict(),
-]);
-
-const AiConversationSchema = z
-  .object({
-    id: AiResourceIdSchema,
-    shortId: AiResourceIdSchema,
-    title: z.string(),
-    titleSource: z.enum(["default", "auto", "user"]),
-    description: z.string(),
-    descriptionSource: z.enum(["default", "auto", "user"]),
-    keywords: z.array(z.string()),
-    pinnedAt: z.string().nullable(),
-    archivedAt: z.string().nullable(),
-    done: z.boolean().nullable(),
-    isDone: z.boolean(),
-    lastUsedAt: z.string(),
-    runStatus: z.enum(["idle", "queued", "running", "needs_attention", "waiting_for_browser", "failed"]),
-    runError: z.string().nullable(),
-    unreadCompletion: z.boolean(),
-    projectId: z.string().nullable(),
-    draft: z.object({ content: z.array(z.unknown()), revision: z.number().int(), updatedAt: z.string().nullable() }).strict(),
-    createdByUserId: z.string().nullable(),
-    createdAt: z.string(),
-    updatedAt: z.string(),
-  })
-  .strict();
-
-const AiStoredMessageSchema = z
-  .object({
-    id: AiResourceIdSchema,
-    shortId: AiResourceIdSchema,
-    conversationId: AiResourceIdSchema,
-    seq: z.number().int().nonnegative(),
-    kind: z.enum(["message", "summary"]),
-    message: z.unknown(),
-    loopId: AiResourceIdSchema.nullable(),
-    modelProfileId: z.string().nullable(),
-    providerModel: z.string().nullable(),
-    usage: z.unknown().nullable(),
-    stopReason: z.string().nullable(),
-    loopAggregate: z.unknown().nullable(),
-    loopDoneReason: z.string().nullable(),
-    compactedAt: z.string().nullable(),
-    meta: z.unknown().nullable(),
-    createdAt: z.string(),
-  })
-  .strict();
-
-const AiTurnSnapshotSchema = z
-  .object({
-    turnId: AiResourceIdSchema,
-    attempt: z.number().int().nonnegative(),
-    status: z.enum(["queued", "running", "waiting_for_action", "completed", "failed", "aborted"]),
-    seq: z.number().int().nonnegative(),
-    blocks: z.array(AiTurnBlockSchema),
-    modelProfileId: z.string().nullable(),
-    createdAt: z.string(),
-  })
-  .strict();
-
-const AiWireEventBaseSchema = {
-  v: z.literal(1),
-  conversationId: AiResourceIdSchema,
-  turnId: AiResourceIdSchema,
-  attempt: z.number().int().nonnegative(),
-  seq: z.number().int().nonnegative(),
-} as const;
-
-const AiStreamEventWireSchema = z.union([
-  z
-    .object({
-      type: z.literal("state"),
-      conversation: AiConversationSchema,
-      messages: z.array(AiStoredMessageSchema),
-      hasMoreMessages: z.boolean().optional(),
-      activeTurn: AiTurnSnapshotSchema.nullable(),
-    })
-    .strict(),
-  z
-    .object({
-      ...AiWireEventBaseSchema,
-      type: z.literal("turn_started"),
-      modelProfileId: z.string(),
-      providerModel: z.string(),
-      blocks: z.array(AiTurnBlockSchema).optional(),
-    })
-    .strict(),
-  z.object({ ...AiWireEventBaseSchema, type: z.literal("block_set"), block: AiTurnBlockSchema }).strict(),
-  z
-    .object({
-      ...AiWireEventBaseSchema,
-      type: z.literal("block_delta"),
-      blockId: z.string(),
-      blockKind: z.enum(["text", "thinking"]),
-      delta: z.string(),
-    })
-    .strict(),
-  z
-    .object({
-      ...AiWireEventBaseSchema,
-      type: z.literal("turn_finished"),
-      status: z.enum(["completed", "failed", "aborted"]),
-      error: z.string().nullable(),
-      messages: z.array(AiStoredMessageSchema).optional(),
-    })
-    .strict(),
-]);
-
-export const AiStreamEventSchema = z.custom<AiStreamEvent>((value) => AiStreamEventWireSchema.safeParse(value).success);
-
-export const AiLiveServerMessageSchema = z.discriminatedUnion("type", [
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.ready),
-      payload: z.object({ cursor: AiLiveCursorSchema, recovered: z.boolean() }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.event),
-      payload: z.object({ cursor: AiLiveCursorSchema, event: AiInvalidationSchema }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.scopeChanged),
-      payload: z.object({ at: z.string().datetime() }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.revoked),
-      payload: z.object({ code: AiLiveRevocationCodeSchema, message: z.string().min(1).max(500) }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.error),
-      payload: z.object({ code: AiLiveErrorCodeSchema, message: z.string().min(1).max(500) }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.turnEvent),
-      payload: z.object({ conversationId: AiResourceIdSchema, event: AiStreamEventSchema }).strict(),
-    })
-    .strict(),
-  z
-    .object({
-      type: z.literal(AI_LIVE_WS_TYPE.turnError),
-      payload: z.object({ conversationId: AiResourceIdSchema, code: AiTurnErrorCodeSchema, message: z.string().min(1).max(500) }).strict(),
-    })
-    .strict(),
-]);
-
-export type AiLiveServerMessage = z.infer<typeof AiLiveServerMessageSchema>;
-
-export const aiTurnEventMessage = (conversationId: string, event: AiStreamEvent): AiLiveServerMessage => ({
-  type: AI_LIVE_WS_TYPE.turnEvent,
-  payload: { conversationId, event },
-});
-
-export const parseAiLiveServerMessage = (raw: string): AiLiveServerMessage | null => {
-  try {
-    const parsed = AiLiveServerMessageSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success) return null;
-    if (parsed.data.type !== AI_LIVE_WS_TYPE.turnEvent) return parsed.data;
-    const eventConversationId =
-      parsed.data.payload.event.type === "state" ? parsed.data.payload.event.conversation.id : parsed.data.payload.event.conversationId;
-    return eventConversationId === parsed.data.payload.conversationId ? parsed.data : null;
-  } catch {
-    return null;
-  }
-};

package/src/ai/live.ts

@@ -1,2 +1,31 @@
-export { latestAiInvalidationCursor } from "./live-outbox";
-export { type AiLiveRoutes, type AiLiveRoutesConfig, aiLiveRoutes } from "./live-routes";
+import { z } from "zod";
+import { defineLive, type LiveViewer } from "../events/live";
+import { AiInvalidationSchema } from "./live-events";
+
+/**
+ * Live updates of a user's AI data. Core publishes and serves them at
+ * `/api/ai/live`; the AI's database triggers write them, keyed `u:<user ID>`,
+ * in the transaction of every change. Other applications, such as Assistant,
+ * read `cursor()` before their snapshot.
+ */
+export const aiLive = defineLive({ appId: "core", event: AiInvalidationSchema });
+
+/** The user an AI request acts for: the user, or the user a credential is delegated by. */
+const ownerOf = (viewer: LiveViewer): string | null => (viewer.accessSubject.type === "user" ? viewer.accessSubject.userId : null);
+
+/**
+ * `user` follows the viewer's own AI data: conversations, their files, tasks and
+ * dictations, and the Projects the viewer can read. Its single key admits only
+ * that user; who receives a Project change was decided when it was written.
+ */
+export const aiLiveChannels = {
+  user: {
+    scope: z.object({}).strict(),
+    keys: async (_scope: unknown, viewer: LiveViewer) => {
+      const owner = ownerOf(viewer);
+      return owner ? [`u:${owner}`] : null;
+    },
+    authorize: async (key: string, viewers: readonly LiveViewer[]) =>
+      new Set(viewers.filter((viewer) => `u:${ownerOf(viewer)}` === key).map((viewer) => viewer.id)),
+  },
+};

package/src/ai/migrate.ts

@@ -13,6 +13,14 @@ const backfillAiShortIds = async (
 };
 
 export const migrateCloudAi = async (): Promise<void> => {
+  // AI writes its live updates to Core's platform outbox, in the transaction of every
+  // AI write: without events.enqueue(), every one of them would fail.
+  const [outbox] = await sql<{ ready: boolean }[]>`
+    SELECT to_regprocedure('events.enqueue(uuid,text,text,text,jsonb,text)') IS NOT NULL AS ready
+  `;
+  if (!outbox?.ready) {
+    throw new Error("AI live updates write to events.outbox, which does not exist. Run Core's events migration before the AI migration.");
+  }
   await sql`CREATE SCHEMA IF NOT EXISTS ai`.simple();
   console.log("  ✓ ai schema");
 
@@ -1722,10 +1730,12 @@ export const migrateCloudAi = async (): Promise<void> => {
     WHERE project_id IS NOT NULL AND archived_at IS NULL
   `.simple();
 
-  // Durable Realtime UI invalidations. Triggers live at the persistence seam so
-  // route, worker, tool, enrichment, and scheduler writes cannot bypass them.
-  // The outbox row commits or rolls back with the authoritative domain write;
-  // publishing remains an after-commit runtime responsibility.
+  // Live updates. Triggers live at the persistence seam so route, worker, tool,
+  // enrichment, and scheduler writes cannot bypass them. They write to Core's
+  // platform outbox in the transaction of the domain write (see the start of this migration).
+
+  // The previous outbox. Nothing writes it anymore; an older Core that still runs during
+  // an update finds it empty. The cleanup release drops it with the topic cloud-ai-invalidations.
   await sql`
     CREATE TABLE IF NOT EXISTS ai.live_invalidation_outbox (
       id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1786,6 +1796,10 @@ export const migrateCloudAi = async (): Promise<void> => {
     DROP FUNCTION IF EXISTS ai.enqueue_live_for_user(UUID, TEXT, UUID, TEXT, TEXT, TEXT[])
   `.simple();
 
+  // Every AI live update goes through this function: one update for one user,
+  // keyed `u:<user>`, on Core's live topic. Its data is an `AiInvalidation`.
+  // No coalesce key: the last payload would win and drop the domains of earlier ones.
+  // Gateway health reports a body without events.enqueue: an older Core restored its own.
   await sql`
     CREATE OR REPLACE FUNCTION ai.enqueue_live_for_user(
       p_change_id UUID,
@@ -1796,11 +1810,23 @@ export const migrateCloudAi = async (): Promise<void> => {
     ) RETURNS void AS $$
     BEGIN
       IF p_user_id IS NULL OR cardinality(p_domains) = 0 THEN RETURN; END IF;
-      INSERT INTO ai.live_invalidation_outbox (
-        change_id, audience_user_id, conversation_short_id, project_short_id, domains
-      ) VALUES (
-        p_change_id, p_user_id, p_conversation_short_id, p_project_short_id,
-        ARRAY(SELECT DISTINCT domain FROM unnest(p_domains) domain ORDER BY domain)
+      PERFORM events.enqueue(
+        gen_random_uuid(),
+        'core',
+        'live',
+        'u:' || p_user_id::text,
+        jsonb_build_object(
+          'v', 1,
+          'k', 'u:' || p_user_id::text,
+          'd', jsonb_build_object(
+            'type', 'ai.invalidated',
+            'changeId', p_change_id,
+            'conversationId', p_conversation_short_id,
+            'projectId', p_project_short_id,
+            'domains', to_jsonb(ARRAY(SELECT DISTINCT domain FROM unnest(p_domains) domain ORDER BY domain)),
+            'at', to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')
+          )
+        )
       );
     END
     $$ LANGUAGE plpgsql
@@ -2213,13 +2239,6 @@ export const migrateCloudAi = async (): Promise<void> => {
   )`.simple();
   await sql`CREATE INDEX IF NOT EXISTS ai_dictations_pending ON ai.dictations(conversation_id, created_at, id) WHERE disposition = 'pending'`.simple();
   await sql`CREATE INDEX IF NOT EXISTS ai_dictations_recovery ON ai.dictations(status, next_attempt_at, lease_until) WHERE status IN ('queued', 'running')`.simple();
-  await sql.begin(async (tx) => {
-    await tx`ALTER TABLE ai.live_invalidation_outbox DROP CONSTRAINT IF EXISTS ai_live_invalidation_domains_check`;
-    await tx`ALTER TABLE ai.live_invalidation_outbox ADD CONSTRAINT ai_live_invalidation_domains_check CHECK (
-      domains <@ ARRAY['conversation-list', 'conversation-detail', 'conversation-sources', 'conversation-files', 'conversation-tasks',
-        'conversation-dictations', 'project-list', 'project-detail', 'project-context']::text[] AND cardinality(domains) > 0
-    )`;
-  });
   await sql`DROP TRIGGER IF EXISTS ai_live_dictations_changed ON ai.dictations`.simple();
   await sql`DROP TRIGGER IF EXISTS ai_live_dictations_state_changed ON ai.dictations`.simple();
   await sql`CREATE TRIGGER ai_live_dictations_changed AFTER INSERT OR DELETE ON ai.dictations

package/src/ai/pdf-render.ts

@@ -1,5 +1,5 @@
-import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { spawnCanvasWorker } from "../_internal/canvas-worker";
 
 declare const __CLOUD_PDF_RENDER_WORKER__: string | undefined;
 let activeRenders = 0;
@@ -31,27 +31,7 @@ export async function renderPdfPages(bytes: Uint8Array, pages: number[] = [1], s
       typeof __CLOUD_PDF_RENDER_WORKER__ === "string"
         ? new URL(__CLOUD_PDF_RENDER_WORKER__, import.meta.url)
         : new URL("./pdf-render-worker.ts", import.meta.url);
-    // RLIMIT_DATA bounds the decoder heap/native writable mappings on Linux.
-    // Positional arguments keep paths out of shell code. No elevated privileges.
-    const child = Bun.spawn(
-      ["/bin/sh", "-c", 'ulimit -d 524288 || exit 70; exec "$@"', "pdf-decoder", process.execPath, "--no-env-file", fileURLToPath(worker)],
-      {
-        stdin: new Blob([JSON.stringify({ pdf: Buffer.from(bytes).toString("base64"), pages })]),
-        stdout: "pipe",
-        stderr: "ignore",
-        // No application credentials or configuration reach the decoder, only fixed
-        // thread pool sizes: the Bun work pool, canvas tokio runtime, and JSC GC
-        // markers otherwise grow with the host's cores, and RLIMIT_DATA also counts
-        // each thread's stack and allocator memory.
-        env: {
-          PATH: process.env.PATH,
-          LANG: "C.UTF-8",
-          UV_THREADPOOL_SIZE: "2",
-          TOKIO_WORKER_THREADS: "2",
-          BUN_JSC_numberOfGCMarkers: "2",
-        },
-      },
-    );
+    const child = spawnCanvasWorker(worker, "pdf-decoder", JSON.stringify({ pdf: Buffer.from(bytes).toString("base64"), pages }));
     const stop = () => child.kill("SIGKILL");
     boundedSignal.addEventListener("abort", stop, { once: true });
     if (boundedSignal.aborted) stop();

package/src/ai/routes.ts

@@ -16,6 +16,7 @@ import {
   respond,
   v,
 } from "../server";
+import { isRequestCredentialCurrent } from "../server/middleware/auth";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
 import type { AiToolApprovalContext } from "./approvals";
@@ -1108,11 +1109,11 @@ export const aiRoutes = (() => {
         return createAiConversationStreamResponse({
           conversation,
           signal: c.req.raw.signal,
-          // Both calls hit the database: resolveContext re-runs the app's own
-          // access check, loadConversation re-checks ownership and resource
-          // scope. The actor itself is a request-time snapshot, so this catches
-          // a withdrawn grant but not a revoked credential — see r9358ceb.
+          // The actor is a request-time snapshot: re-authenticate its
+          // credential first, so a revoked session or API key ends the stream,
+          // then re-check ownership and resource scope of the conversation.
           revalidate: async () => {
+            if (!(await isRequestCredentialCurrent(c))) return false;
             const current = await resolveContext(c);
             if (current instanceof Response) return false;
             return Boolean(await loadConversation(c, current));

package/src/ai/runtime.ts

@@ -12,7 +12,6 @@ import { aiChatAccessSubject, selectAssistantAiModelId } from "./assistant-model
 import { startAiDictationRuntime } from "./dictation-runtime";
 import { AiTurnExecutor } from "./executor";
 import { canonicalizeAiConversationAttachments, snapshotAiConversationFiles } from "./file-context";
-import { startAiInvalidationRuntime, stopAiInvalidationRuntime } from "./live-outbox";
 import { drainQueuedMessages } from "./message-queue";
 import { aiQuotas } from "./quotas";
 import { parseAiResourceMarker } from "./resource-markers";
@@ -577,7 +576,6 @@ export const startAiRuntime = (
     },
   };
   running = state;
-  startAiInvalidationRuntime();
   log.info("AI runtime started", { workerId: AI_WORKER_ID, concurrency });
   return releaseAiRuntime(listener);
 };
@@ -591,10 +589,7 @@ const releaseAiRuntime = (listener: ((event: AiTurnFinalizedEvent) => Promise<vo
     if (!state) return;
     if (listener) state.listeners.delete(listener);
     refCount = Math.max(0, refCount - 1);
-    if (refCount === 0) {
-      state.stop();
-      void stopAiInvalidationRuntime();
-    }
+    if (refCount === 0) state.stop();
   };
 };
 

package/src/ai/solid.ts

@@ -7,11 +7,6 @@ export {
   createAiChatController,
 } from "./client/controller";
 export { conversationFileSource } from "./client/file-source";
-export {
-  type AiLiveConnection,
-  type CreateAiLiveConnectionOptions,
-  createAiLiveConnection,
-} from "./client/live-connection";
 export {
   type AiActiveTurn,
   type AiChatProjection,