cascade-ai 0.66.2 → 0.67.0

package/dist/index.d.cts

@@ -2556,6 +2556,24 @@ declare class Cascade extends EventEmitter {
      */
     setCurrentPageProvider(provider: CurrentPageProvider): void;
     private registerMediaTools;
+    /**
+     * Register `generate_document` where there is a real workspace to write into.
+     *
+     * A `.docx`/`.pptx`/`.xlsx` is a ZIP of OOXML parts, so `file_write` — which
+     * does exactly what it says and writes the model's text verbatim — produced
+     * files Word/Excel/PowerPoint correctly reported as corrupted. This tool owns
+     * the conversion (see tools/generate-document.ts for why it isn't folded into
+     * file_write).
+     *
+     * Registered OUTSIDE `enabledTools` for the same reason the media tools are:
+     * that allowlist is a blast-radius control for tools that reach the machine
+     * or the network, and this one only writes the artifact the user asked for,
+     * into the workspace the run already owns. `disabledTools` still removes it.
+     * A host with no filesystem (the cloud) has its own browser-side exporter and
+     * simply never reaches this path — `buildDocumentTools` returns nothing
+     * without a file reader, mirroring `transcribe_audio`.
+     */
+    private registerDocumentTools;
     /**
      * Supply per-model thumbs-up/down counts so Auto routing can weigh how models
      * have actually performed for this user, on top of public benchmarks.
@@ -4032,6 +4050,257 @@ declare class GraphRetriever {
     format(facts: RankedFact[]): string;
 }
 
+/** File extension (lowercased, no dot), or '' when there is none. */
+declare function fileExt(name: string): string;
+/**
+ * Parse CSV/TSV into rows of cells. Handles quoted fields, escaped quotes (""),
+ * and embedded newlines/commas inside quotes. Delimiter is auto-detected from the
+ * extension (tsv → tab) or inferred from the first line. Bounded for safety.
+ */
+declare function parseDelimited(text: string, name?: string): string[][];
+/** Chart shapes we can render. Anything else falls back to a table. */
+type ChartKind = 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter';
+/** Normalise a fence's chart type, or null when it isn't one we can draw. */
+declare function chartKind(raw: string): ChartKind | null;
+interface ChartSeries {
+    name: string;
+    values: number[];
+}
+/** A chart's data, format-independent. Renderers decide how to draw it. */
+interface ChartSpec {
+    kind: ChartKind;
+    /** Optional heading, from a leading `title:` line. */
+    title?: string;
+    /** Label for the category axis — the header row's first cell. */
+    categoryName: string;
+    categories: string[];
+    series: ChartSeries[];
+}
+/**
+ * Parse a `chart:<kind>` fence body into a ChartSpec.
+ *
+ * Returns null for anything that isn't plausibly chartable (fewer than two
+ * rows, or no series column). The caller then keeps the block as CODE rather
+ * than dropping it, so a malformed chart is visible in the output instead of
+ * silently missing.
+ */
+declare function parseChartSpec(kind: ChartKind, body: string): ChartSpec | null;
+/**
+ * The chart's data as table rows — the fallback for every format that cannot
+ * hold a real chart object (Word and PDF; see render.ts).
+ *
+ * Losing the numbers would be strictly worse than the flat table this replaces,
+ * so no renderer is allowed to just skip a chart block.
+ */
+declare function chartToTableRows(spec: ChartSpec): string[][];
+type Block = {
+    t: 'heading';
+    level: number;
+    text: string;
+} | {
+    t: 'para';
+    text: string;
+} | {
+    t: 'bullet';
+    ordered: boolean;
+    index: number;
+    text: string;
+} | {
+    t: 'code';
+    lines: string[];
+} | {
+    t: 'quote';
+    text: string;
+} | {
+    t: 'table';
+    rows: string[][];
+} | {
+    t: 'chart';
+    spec: ChartSpec;
+} | {
+    t: 'hr';
+};
+declare function parseBlocks(md: string): Block[];
+/** One `![alt](url)` reference lifted out of the Markdown. */
+interface ImageRef {
+    alt: string;
+    url: string;
+}
+declare function matchImageLine(s: string): ImageRef | null;
+/** Format + intrinsic size, sniffed from the bytes. */
+interface ImageInfo {
+    /** Narrowed to the four raster types docx's ImageRun accepts. */
+    type: 'png' | 'jpg' | 'gif' | 'bmp';
+    mime: string;
+    width: number;
+    height: number;
+}
+type LoadedImage = ImageInfo & {
+    bytes: Uint8Array;
+    alt: string;
+};
+/**
+ * Read an image's format and pixel dimensions out of its header.
+ *
+ * Both renderers need this and neither can ask a host for it: docx must state
+ * the type and a transformation in pixels up front, and decoding through an
+ * <img> would make the exporter depend on the browser's image pipeline (and
+ * fail under jsdom, and be unavailable in Node entirely). Returns null for
+ * anything we can't measure, which the caller treats as "not embeddable" rather
+ * than guessing a size.
+ */
+declare function sniffImage(b: Uint8Array): ImageInfo | null;
+/**
+ * base64 of raw bytes.
+ *
+ * Node's Buffer where it exists (desktop/CLI, and jsdom tests), otherwise a
+ * chunked btoa so a multi-MB image can't blow the call stack through
+ * String.fromCharCode's argument list. Read off globalThis rather than
+ * referenced directly so a browser bundler never tries to resolve `Buffer`.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/** Strip inline Markdown emphasis to plain text (for renderers with no rich runs). */
+declare function stripInline(s: string): string;
+/** One styled span of a line, from inlineRuns(). */
+interface InlineRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
+/**
+ * Split a line's inline emphasis into styled spans.
+ *
+ * Kept format-neutral (plain objects, not docx TextRuns) so the Word renderer
+ * and any future rich-text renderer share one understanding of what `**bold**`
+ * means. A link becomes its "label (url)" text — no renderer here emits real
+ * hyperlinks yet, and dropping the URL would lose information.
+ */
+declare function inlineRuns(text: string): InlineRun[];
+interface Slide {
+    title: string;
+    body: string[];
+    images: ImageRef[];
+    charts: ChartSpec[];
+}
+/** Split a Markdown deck into slides: on `---` rules, else on top-level headings. */
+declare function splitSlides(md: string): Slide[];
+declare function parseSlide(chunk: string): Slide;
+/**
+ * Pull `chart:` fences out of a source, returning them plus the text with those
+ * fences removed.
+ *
+ * The spreadsheet convention is plain CSV, so a chart block inside an `.xlsx`
+ * source would otherwise be parsed as three junk rows. SheetJS's community
+ * build cannot write a chart OBJECT (see render.ts), so the data instead lands
+ * on its own worksheet — real rows a user can select and chart in one click,
+ * rather than data that vanished.
+ */
+declare function extractCharts(source: string): {
+    charts: ChartSpec[];
+    rest: string;
+};
+
+/** Office formats we can render into a real binary. */
+type DocumentFormat = 'docx' | 'pptx' | 'xlsx';
+declare const DOCUMENT_MIME: Record<DocumentFormat, string>;
+declare function isDocumentFormat(ext: string): ext is DocumentFormat;
+/**
+ * Resolve a Markdown image URL to raw bytes, or null when it can't be had.
+ *
+ * Returning null rather than throwing is the contract: one dead image must
+ * never cost the user the whole document.
+ */
+type ImageByteLoader = (url: string) => Promise<Uint8Array | null>;
+interface RenderOptions {
+    loadImageBytes?: ImageByteLoader;
+    /** Target file name — only used to pick the CSV vs TSV delimiter for xlsx. */
+    name?: string;
+}
+/**
+ * CSV → a real `.xlsx` workbook.
+ *
+ * SheetJS's community build can WRITE cells but not chart objects — charts are
+ * not part of the open-source writer's feature set at any version we can
+ * depend on. So a `chart:` block in a spreadsheet source does not become an
+ * Excel chart; its data lands on its own worksheet as ordinary rows, which the
+ * user can select and chart in one click. Dropping it would be the one
+ * genuinely bad option.
+ */
+declare function renderXlsx(source: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Markdown → a real `.docx`.
+ *
+ * CHART GAP, stated explicitly: the `docx` library exposes no chart API (it
+ * writes WordprocessingML; a Word chart needs a DrawingML chart part plus an
+ * embedded workbook, which the library does not model). A `chart:` block
+ * therefore renders as its title plus a real Word table of the same numbers —
+ * every value preserved, nothing silently dropped. If a caller needs a drawn
+ * chart in Word, the path is to render it to an image first and reference it
+ * with ordinary `![alt](url)` syntax, which this renderer does embed.
+ */
+declare function renderDocx(md: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Markdown slides → a real `.pptx`.
+ *
+ * A `chart:` block becomes a genuine, editable PowerPoint chart via
+ * `addChart` — the numbers live in the chart part's embedded workbook, so the
+ * user can click Edit Data and see the exact values the model wrote. That is
+ * the whole point of the convention: an image model cannot be trusted to draw
+ * an accurate axis, and a Markdown table isn't a chart.
+ */
+declare function renderPptx(md: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Render a document source into the real binary for `format`.
+ *
+ * `source` is Markdown for docx, Markdown slides for pptx, and CSV for xlsx —
+ * the same conventions the hosted `file:<name>.<ext>` blocks already use, so a
+ * model that can produce one can produce the other.
+ */
+declare function renderDocument(format: DocumentFormat, source: string, opts?: RenderOptions): Promise<Uint8Array>;
+
+/** Reads a workspace file; supplied by the host so tests need no real disk. */
+type WorkspaceFileReader = (absPath: string) => Promise<Uint8Array>;
+declare class GenerateDocumentTool extends BaseTool {
+    private readFile;
+    readonly name = "generate_document";
+    readonly description: string;
+    readonly inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    /**
+     * `readFile` is injected so the image loader is testable and so a host with a
+     * different workspace (not plain disk) can supply its own reader.
+     */
+    constructor(readFile?: WorkspaceFileReader);
+    isDangerous(): boolean;
+    execute(input: Record<string, unknown>, options: ToolExecuteOptions): Promise<string>;
+}
+/**
+ * Register the document tool only where there is a workspace to write into.
+ *
+ * Mirrors how buildMediaTools() conditions `transcribe_audio` on a file reader:
+ * a hosted run has no disk, and a tool that always fails is worse than an
+ * absent one — the planner writes steps around it and the run ends in an
+ * apology. The cloud keeps its browser-side exporter instead.
+ */
+declare function buildDocumentTools(readFile?: WorkspaceFileReader): BaseTool[];
+
 /**
  * Lets a worker search the indexed workspace codebase by meaning + keywords and
  * get back the most relevant passages with their file paths. Backed by the
@@ -4543,4 +4812,4 @@ declare function gatherSyncBundle(config: CascadeConfig): SyncBundle;
 /** Merge a pulled bundle into a config, returning the updated config to persist. */
 declare function applySyncBundle(bundle: SyncBundle, config: CascadeConfig): CascadeConfig;
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompleteFn, ConfigManager, type ConversationMessage, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RankedFact, type RefreshResult, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildManifest, buildSessionTranscript, cagCharBudget, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, isMcpToolName, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseRankOrder, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, runCascade, sessionWorthRemembering, streamCascade, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompleteFn, ConfigManager, type ConversationMessage, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, extractCharts, fileExt, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sessionWorthRemembering, sniffImage, splitSlides, streamCascade, stripInline, uniqueMcpServerName };

package/dist/index.d.ts

@@ -2556,6 +2556,24 @@ declare class Cascade extends EventEmitter {
      */
     setCurrentPageProvider(provider: CurrentPageProvider): void;
     private registerMediaTools;
+    /**
+     * Register `generate_document` where there is a real workspace to write into.
+     *
+     * A `.docx`/`.pptx`/`.xlsx` is a ZIP of OOXML parts, so `file_write` — which
+     * does exactly what it says and writes the model's text verbatim — produced
+     * files Word/Excel/PowerPoint correctly reported as corrupted. This tool owns
+     * the conversion (see tools/generate-document.ts for why it isn't folded into
+     * file_write).
+     *
+     * Registered OUTSIDE `enabledTools` for the same reason the media tools are:
+     * that allowlist is a blast-radius control for tools that reach the machine
+     * or the network, and this one only writes the artifact the user asked for,
+     * into the workspace the run already owns. `disabledTools` still removes it.
+     * A host with no filesystem (the cloud) has its own browser-side exporter and
+     * simply never reaches this path — `buildDocumentTools` returns nothing
+     * without a file reader, mirroring `transcribe_audio`.
+     */
+    private registerDocumentTools;
     /**
      * Supply per-model thumbs-up/down counts so Auto routing can weigh how models
      * have actually performed for this user, on top of public benchmarks.
@@ -4032,6 +4050,257 @@ declare class GraphRetriever {
     format(facts: RankedFact[]): string;
 }
 
+/** File extension (lowercased, no dot), or '' when there is none. */
+declare function fileExt(name: string): string;
+/**
+ * Parse CSV/TSV into rows of cells. Handles quoted fields, escaped quotes (""),
+ * and embedded newlines/commas inside quotes. Delimiter is auto-detected from the
+ * extension (tsv → tab) or inferred from the first line. Bounded for safety.
+ */
+declare function parseDelimited(text: string, name?: string): string[][];
+/** Chart shapes we can render. Anything else falls back to a table. */
+type ChartKind = 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter';
+/** Normalise a fence's chart type, or null when it isn't one we can draw. */
+declare function chartKind(raw: string): ChartKind | null;
+interface ChartSeries {
+    name: string;
+    values: number[];
+}
+/** A chart's data, format-independent. Renderers decide how to draw it. */
+interface ChartSpec {
+    kind: ChartKind;
+    /** Optional heading, from a leading `title:` line. */
+    title?: string;
+    /** Label for the category axis — the header row's first cell. */
+    categoryName: string;
+    categories: string[];
+    series: ChartSeries[];
+}
+/**
+ * Parse a `chart:<kind>` fence body into a ChartSpec.
+ *
+ * Returns null for anything that isn't plausibly chartable (fewer than two
+ * rows, or no series column). The caller then keeps the block as CODE rather
+ * than dropping it, so a malformed chart is visible in the output instead of
+ * silently missing.
+ */
+declare function parseChartSpec(kind: ChartKind, body: string): ChartSpec | null;
+/**
+ * The chart's data as table rows — the fallback for every format that cannot
+ * hold a real chart object (Word and PDF; see render.ts).
+ *
+ * Losing the numbers would be strictly worse than the flat table this replaces,
+ * so no renderer is allowed to just skip a chart block.
+ */
+declare function chartToTableRows(spec: ChartSpec): string[][];
+type Block = {
+    t: 'heading';
+    level: number;
+    text: string;
+} | {
+    t: 'para';
+    text: string;
+} | {
+    t: 'bullet';
+    ordered: boolean;
+    index: number;
+    text: string;
+} | {
+    t: 'code';
+    lines: string[];
+} | {
+    t: 'quote';
+    text: string;
+} | {
+    t: 'table';
+    rows: string[][];
+} | {
+    t: 'chart';
+    spec: ChartSpec;
+} | {
+    t: 'hr';
+};
+declare function parseBlocks(md: string): Block[];
+/** One `![alt](url)` reference lifted out of the Markdown. */
+interface ImageRef {
+    alt: string;
+    url: string;
+}
+declare function matchImageLine(s: string): ImageRef | null;
+/** Format + intrinsic size, sniffed from the bytes. */
+interface ImageInfo {
+    /** Narrowed to the four raster types docx's ImageRun accepts. */
+    type: 'png' | 'jpg' | 'gif' | 'bmp';
+    mime: string;
+    width: number;
+    height: number;
+}
+type LoadedImage = ImageInfo & {
+    bytes: Uint8Array;
+    alt: string;
+};
+/**
+ * Read an image's format and pixel dimensions out of its header.
+ *
+ * Both renderers need this and neither can ask a host for it: docx must state
+ * the type and a transformation in pixels up front, and decoding through an
+ * <img> would make the exporter depend on the browser's image pipeline (and
+ * fail under jsdom, and be unavailable in Node entirely). Returns null for
+ * anything we can't measure, which the caller treats as "not embeddable" rather
+ * than guessing a size.
+ */
+declare function sniffImage(b: Uint8Array): ImageInfo | null;
+/**
+ * base64 of raw bytes.
+ *
+ * Node's Buffer where it exists (desktop/CLI, and jsdom tests), otherwise a
+ * chunked btoa so a multi-MB image can't blow the call stack through
+ * String.fromCharCode's argument list. Read off globalThis rather than
+ * referenced directly so a browser bundler never tries to resolve `Buffer`.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/** Strip inline Markdown emphasis to plain text (for renderers with no rich runs). */
+declare function stripInline(s: string): string;
+/** One styled span of a line, from inlineRuns(). */
+interface InlineRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
+/**
+ * Split a line's inline emphasis into styled spans.
+ *
+ * Kept format-neutral (plain objects, not docx TextRuns) so the Word renderer
+ * and any future rich-text renderer share one understanding of what `**bold**`
+ * means. A link becomes its "label (url)" text — no renderer here emits real
+ * hyperlinks yet, and dropping the URL would lose information.
+ */
+declare function inlineRuns(text: string): InlineRun[];
+interface Slide {
+    title: string;
+    body: string[];
+    images: ImageRef[];
+    charts: ChartSpec[];
+}
+/** Split a Markdown deck into slides: on `---` rules, else on top-level headings. */
+declare function splitSlides(md: string): Slide[];
+declare function parseSlide(chunk: string): Slide;
+/**
+ * Pull `chart:` fences out of a source, returning them plus the text with those
+ * fences removed.
+ *
+ * The spreadsheet convention is plain CSV, so a chart block inside an `.xlsx`
+ * source would otherwise be parsed as three junk rows. SheetJS's community
+ * build cannot write a chart OBJECT (see render.ts), so the data instead lands
+ * on its own worksheet — real rows a user can select and chart in one click,
+ * rather than data that vanished.
+ */
+declare function extractCharts(source: string): {
+    charts: ChartSpec[];
+    rest: string;
+};
+
+/** Office formats we can render into a real binary. */
+type DocumentFormat = 'docx' | 'pptx' | 'xlsx';
+declare const DOCUMENT_MIME: Record<DocumentFormat, string>;
+declare function isDocumentFormat(ext: string): ext is DocumentFormat;
+/**
+ * Resolve a Markdown image URL to raw bytes, or null when it can't be had.
+ *
+ * Returning null rather than throwing is the contract: one dead image must
+ * never cost the user the whole document.
+ */
+type ImageByteLoader = (url: string) => Promise<Uint8Array | null>;
+interface RenderOptions {
+    loadImageBytes?: ImageByteLoader;
+    /** Target file name — only used to pick the CSV vs TSV delimiter for xlsx. */
+    name?: string;
+}
+/**
+ * CSV → a real `.xlsx` workbook.
+ *
+ * SheetJS's community build can WRITE cells but not chart objects — charts are
+ * not part of the open-source writer's feature set at any version we can
+ * depend on. So a `chart:` block in a spreadsheet source does not become an
+ * Excel chart; its data lands on its own worksheet as ordinary rows, which the
+ * user can select and chart in one click. Dropping it would be the one
+ * genuinely bad option.
+ */
+declare function renderXlsx(source: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Markdown → a real `.docx`.
+ *
+ * CHART GAP, stated explicitly: the `docx` library exposes no chart API (it
+ * writes WordprocessingML; a Word chart needs a DrawingML chart part plus an
+ * embedded workbook, which the library does not model). A `chart:` block
+ * therefore renders as its title plus a real Word table of the same numbers —
+ * every value preserved, nothing silently dropped. If a caller needs a drawn
+ * chart in Word, the path is to render it to an image first and reference it
+ * with ordinary `![alt](url)` syntax, which this renderer does embed.
+ */
+declare function renderDocx(md: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Markdown slides → a real `.pptx`.
+ *
+ * A `chart:` block becomes a genuine, editable PowerPoint chart via
+ * `addChart` — the numbers live in the chart part's embedded workbook, so the
+ * user can click Edit Data and see the exact values the model wrote. That is
+ * the whole point of the convention: an image model cannot be trusted to draw
+ * an accurate axis, and a Markdown table isn't a chart.
+ */
+declare function renderPptx(md: string, opts?: RenderOptions): Promise<Uint8Array>;
+/**
+ * Render a document source into the real binary for `format`.
+ *
+ * `source` is Markdown for docx, Markdown slides for pptx, and CSV for xlsx —
+ * the same conventions the hosted `file:<name>.<ext>` blocks already use, so a
+ * model that can produce one can produce the other.
+ */
+declare function renderDocument(format: DocumentFormat, source: string, opts?: RenderOptions): Promise<Uint8Array>;
+
+/** Reads a workspace file; supplied by the host so tests need no real disk. */
+type WorkspaceFileReader = (absPath: string) => Promise<Uint8Array>;
+declare class GenerateDocumentTool extends BaseTool {
+    private readFile;
+    readonly name = "generate_document";
+    readonly description: string;
+    readonly inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    /**
+     * `readFile` is injected so the image loader is testable and so a host with a
+     * different workspace (not plain disk) can supply its own reader.
+     */
+    constructor(readFile?: WorkspaceFileReader);
+    isDangerous(): boolean;
+    execute(input: Record<string, unknown>, options: ToolExecuteOptions): Promise<string>;
+}
+/**
+ * Register the document tool only where there is a workspace to write into.
+ *
+ * Mirrors how buildMediaTools() conditions `transcribe_audio` on a file reader:
+ * a hosted run has no disk, and a tool that always fails is worse than an
+ * absent one — the planner writes steps around it and the run ends in an
+ * apology. The cloud keeps its browser-side exporter instead.
+ */
+declare function buildDocumentTools(readFile?: WorkspaceFileReader): BaseTool[];
+
 /**
  * Lets a worker search the indexed workspace codebase by meaning + keywords and
  * get back the most relevant passages with their file paths. Backed by the
@@ -4543,4 +4812,4 @@ declare function gatherSyncBundle(config: CascadeConfig): SyncBundle;
 /** Merge a pulled bundle into a config, returning the updated config to persist. */
 declare function applySyncBundle(bundle: SyncBundle, config: CascadeConfig): CascadeConfig;
 
-export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompleteFn, ConfigManager, type ConversationMessage, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, type DashboardConfig, DashboardServer, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RankedFact, type RefreshResult, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildManifest, buildSessionTranscript, cagCharBudget, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, isMcpToolName, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseRankOrder, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, runCascade, sessionWorthRemembering, streamCascade, uniqueMcpServerName };
+export { AZURE_BASE_MODELS, AZURE_BASE_URL_TEMPLATE, type ApprovalRequest, type ApprovalResponse, type AuditEntry, AuditLogger, type BenchmarksConfig, type Block, type BudgetConfig, CASCADE_AUDIT_FILE, CASCADE_CONFIG_DIR, CASCADE_CONFIG_FILE, CASCADE_DASHBOARD_SECRET_FILE, CASCADE_DB_FILE, CASCADE_IGNORE_FILE, CASCADE_KEYSTORE_FILE, CASCADE_MD_FILE, CASCADE_VERSION, CHARS_PER_TOKEN, COMPLEXITY_T2_COUNT, Cascade, CascadeCancelledError, type CascadeConfig, type CascadeEvent, type CascadeEventType, CascadeIgnore, type CascadeMessage, CascadeRouter, type CascadeRunOptions, type CascadeRunResult, type CascadeThemeName, CascadeToolError, type ChartSeries, type ChartSpec, type Chunk, type ChunkOptions, CloudClient, type CloudConversation, type CloudMessage, type CloudSession, type CloudSessionStore, type CloudTurnInput, type CloudUser, type CodeChunkOptions, type CodeChunker, CodeSearchTool, type CompleteFn, ConfigManager, type ConversationMessage, type CurrentPageProvider, type CurrentPageSnapshot, CurrentPageTool, DEFAULT_API_PORT, DEFAULT_APPROVAL_REQUIRED, DEFAULT_AUTO_SUMMARIZE_AT, DEFAULT_CLOUD_URL, DEFAULT_CONTEXT_LIMIT, DEFAULT_DASHBOARD_PORT, DEFAULT_MAX_SESSION_MESSAGES, DEFAULT_RETENTION_DAYS, DEFAULT_THEME, DOCUMENT_MIME, type DashboardConfig, DashboardServer, type DeviceStart, type DiscoveredMcpTool, type DistilledFact, type ChartKind as DocumentChartKind, type DocumentFormat, type Embedder, type EncryptedBlob, type EscalationDecision, type EscalationPayload, type ExtendedContextConfig, type FileManifest, FileMcpOAuthStore, GITHUB_MODELS_API_VERSION, GITHUB_MODELS_CATALOG_URL, GITHUB_MODELS_INFERENCE_URL, GLOBAL_CONFIG_DIR, GLOBAL_CREDENTIALS_FILE, GLOBAL_DB_FILE, GLOBAL_KEYSTORE_FILE, GLOBAL_RUNTIME_DB_FILE, GenerateDocumentTool, type GenerateOptions, type GenerateResult, type GraphFactSource, GraphRetriever, type GraphSearchOptions, GraphSearchTool, type HookDefinition, type HooksConfig, HooksRunner, type Identity, type ImageAttachment, type ImageByteLoader, type ImageInfo, type ImageRef, type InlineRun, Keystore, LLMReranker, LM_STUDIO_BASE_URL, type LegacyThemeName, type LoadedImage, MAX_PAGE_TEXT_CHARS, MCP_TOOL_PREFIX, MODELS, type ManifestDiff, McpClient, type McpDiscoveryResult, McpOAuthProvider, type McpOAuthState, type McpOAuthStore, type McpServerConfig$1 as McpServerConfig, type McpServerRename, type MemoryConfig, MemoryStore, type Message, type MessageContent, type MessagePayload, type MessageStatus, type MessageType, type ModelInfo, type ModelOverrides, type NativeProvider, OLLAMA_BASE_URL, OpenAICompatibleEmbedder, type OpenAIEmbedderOptions, PROVIDER_DISPLAY_NAMES, type PeerMessage, type PeerMessageEvent, type PeerSyncPayload, type PeerSyncType, type PermissionDecision, type PermissionDecisionPayload, type PermissionRequest, type PermissionTrailEntry, type PlanReviewConfig, type ProviderConfig, type ProviderType, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type ScoredChunk, type SearchOptions, type Session, type SessionCheckpoint, type SessionMetadata, type SessionSubscriptionPayload, type Slide, SqliteVectorStore, type StatusUpdate, type StoredMessage, type StreamChunk, type SyncBundle, T1Administrator, type T1ToT2Assignment, T1_MODEL_PRIORITY, T2Manager, type T2Result, type T2ToT3Assignment, T2_MODEL_PRIORITY, type T3Result, type T3ResultPayload, type T3SubtaskSpec, T3Worker, T3_MODEL_PRIORITY, THEME_NAMES, TOOL_NAMES, type TaskComplexity, TaskScheduler, Telemetry, type TelemetryConfig, type Theme, type ThemeColors, type ThemeName, type TierConfig, type TierLimits, type TierRole, type TierStatus, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecuteOptions, ToolRegistry, type ToolResult, type ToolsConfig, VISION_MODEL_PRIORITY, type VectorStore, type WebSearchConfig, type WebhookConfig, type WorkspaceConfig, type WorkspaceFileReader, WorkspaceIndex, type WorkspaceIndexOptions, applySyncBundle, azureModelForDeployment, beginMcpOAuth, buildDocumentTools, buildManifest, buildSessionTranscript, bytesToBase64, cagCharBudget, chartKind, chartToTableRows, chatCompleterFromProviders, chunkCode, chunkText, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, extractCharts, fileExt, fileOAuthProvider, gatherSyncBundle, hashContent, heuristicCodeChunker, inferAzureBaseModel, inlineRuns, isDocumentFormat, isMcpToolName, matchImageLine, mcpServerPrefix, mcpToolName, nodeHttpFetch, parseBlocks, parseChartSpec, parseDelimited, parseRankOrder, parseSlide, planRetrieval, preferIpv4Host, reciprocalRankFusion, refreshMcpToken, removeMcpServerDenials, renderDocument, renderDocx, renderPptx, renderXlsx, runCascade, sessionWorthRemembering, sniffImage, splitSlides, streamCascade, stripInline, uniqueMcpServerName };