cascade-ai 0.66.2 → 0.68.0

package/dist/index.d.ts

@@ -5,6 +5,98 @@ import { OAuthClientInformationMixed, OAuthTokens, OAuthClientMetadata, OAuthCli
 export { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
 import Database from 'better-sqlite3';
 
+/**
+ * Durable resume checkpoints.
+ *
+ * Before this, a stopped run was recoverable only through an in-memory field on
+ * the Cascade instance, set on exactly one path (the budget cap). So the two
+ * interruptions people actually hit — a crash, and Ctrl-C — lost every finished
+ * section, and even a budget stop was lost the moment the process exited. The
+ * work was on disk; the knowledge of what had been done was not.
+ *
+ * A checkpoint records the finished nodes of a run so a resume can restore them
+ * instead of paying to produce them a second time. Design constraints, in the
+ * order that shaped the code:
+ *
+ * - **A crash is one of the triggers.** Writes are atomic (temp file + rename),
+ *   because the process dying mid-write is a case this store must survive, not
+ *   an edge case. A half-written checkpoint that parses as valid JSON would be
+ *   worse than none at all.
+ * - **A corrupt or foreign checkpoint must never break the caller.** Listing
+ *   skips anything unreadable, unparseable, or written by a schema version this
+ *   build doesn't know. Resume is a convenience; it may degrade, never throw.
+ * - **Checkpoints hold the user's prompt and partial output.** They are pruned
+ *   by both count and age so that content does not accumulate in the workspace
+ *   indefinitely.
+ */
+/** Bump when the on-disk shape changes incompatibly. Older files are ignored. */
+declare const RESUME_SCHEMA_VERSION = 1;
+type ResumeReason = 'budget' | 'cancelled' | 'error' | 'breaker';
+/** A node whose work is done and must not be re-run on resume. */
+interface CompletedNode {
+    /** Stable id from the compiled task graph. */
+    id: string;
+    title: string;
+    status: 'COMPLETED' | 'PARTIAL';
+    output: string;
+}
+interface ResumeCheckpoint {
+    version: number;
+    taskId: string;
+    prompt: string;
+    /** ISO-8601. */
+    createdAt: string;
+    reason: ResumeReason;
+    /** Why the run stopped, in the words the user would see. */
+    detail?: string;
+    partialOutput: string;
+    completed: CompletedNode[];
+}
+interface ResumeStoreOptions {
+    /** Directory checkpoints live in (created on demand). */
+    dir: string;
+    /** Keep at most this many, newest first. Default 5. */
+    maxCheckpoints?: number;
+    /** Discard checkpoints older than this. Default 7 days. */
+    maxAgeMs?: number;
+    /** Injectable clock, for tests. */
+    now?: () => number;
+}
+declare class ResumeStore {
+    private readonly dir;
+    private readonly maxCheckpoints;
+    private readonly maxAgeMs;
+    private readonly now;
+    constructor(options: ResumeStoreOptions);
+    /**
+     * Persist a checkpoint and prune. Never throws: failing to save a resume file
+     * must not turn a recoverable stop into a crash, which would be a strictly
+     * worse outcome than the one this store exists to improve.
+     */
+    save(checkpoint: Omit<ResumeCheckpoint, 'version' | 'createdAt'> & {
+        createdAt?: string;
+    }): Promise<void>;
+    /** Valid, unexpired checkpoints, newest first. */
+    list(): Promise<ResumeCheckpoint[]>;
+    /** The most recent resumable run, or null. */
+    latest(): Promise<ResumeCheckpoint | null>;
+    /**
+     * Load a checkpoint and delete it in the same step. Resuming twice from one
+     * checkpoint would re-run restored work, so consumption is part of reading.
+     */
+    consume(taskId?: string): Promise<ResumeCheckpoint | null>;
+    /** Remove every checkpoint for a task id. */
+    delete(taskId: string): Promise<void>;
+    /** Drop expired checkpoints, then any beyond the newest `maxCheckpoints`. */
+    prune(): Promise<void>;
+}
+/**
+ * Render restored work for a correction planner: enough for the model to know
+ * what exists and not redo it, without pasting entire artifacts back into the
+ * prompt (which is what the token budget was being spent on in the first place).
+ */
+declare function summarizeCompleted(completed: readonly CompletedNode[], perNodeChars?: number): string;
+
 type ProviderType = 'anthropic' | 'openai' | 'gemini' | 'azure' | 'openai-compatible' | 'ollama' | 'github-models';
 interface ModelInfo {
     id: string;
@@ -2344,7 +2436,20 @@ declare class T1Administrator extends BaseTier {
     private validatePlan;
     private dispatchT2Managers;
     /**
-     * Runs T2 managers respecting dependsOn declarations using Kahn's algorithm.
+     * Runs T2 managers respecting dependsOn declarations.
+     *
+     * Graph construction, validation and cycle repair now live in
+     * compileSectionGraph (orchestration/adapters.ts), and wave execution in
+     * DependencyScheduler — the same pair T2 uses for its subtasks, so a plan is
+     * ordered by one implementation rather than two that drifted.
+     *
+     * The hand-rolled Kahn pass this replaces treated every node it could not
+     * reach as part of a cycle. That set also contains everything DOWNSTREAM of a
+     * cycle, whose in-degree can never fall to zero while its dependency is stuck,
+     * so breaking a cycle here also cut the dependencies of innocent later
+     * sections and started them immediately — before the sections they consume.
+     * compileTaskGraph uses strongly connected components, so only real cycle
+     * members are touched.
      */
     private runT2sWithDependencies;
     private compileFinalOutput;
@@ -2419,8 +2524,16 @@ declare class Cascade extends EventEmitter {
     /** Orchestration decisions for the CURRENT run — cleared on each run(). */
     private decisionLog;
     private initialized;
-    /** Last task that stopped at the budget cap — powers /continue (resumeRun). */
+    /**
+     * Last interrupted task — powers /continue (resumeRun). Kept in memory as a
+     * fast path for the same-process case; the durable copy lives in `resumeStore`
+     * so a crash or an exit no longer throws away everything already finished.
+     */
     private lastInterruptedRun?;
+    /** Durable resume checkpoints. See core/orchestration/resume-store.ts. */
+    private resumeStore?;
+    /** Section results of the CURRENT run, so an interruption can checkpoint them. */
+    private currentRunCompleted;
     private initPromise?;
     private store?;
     private audit?;
@@ -2556,6 +2669,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.
@@ -2565,8 +2696,24 @@ declare class Cascade extends EventEmitter {
      * see core/router/feedback-prior.ts.
      */
     setFeedbackSource(source: FeedbackSource): void;
-    /** True when a task stopped at the budget cap and can be resumed via /continue. */
+    /**
+     * Write a durable checkpoint for an interrupted run.
+     *
+     * Best-effort throughout: a run is already ending badly on every path that
+     * calls this, and failing to record a resume file must not make that ending
+     * worse. Nothing here is allowed to throw.
+     */
+    private checkpointRun;
+    /** True when a task can be resumed via /continue (this process or a previous one). */
     hasResumableRun(): boolean;
+    /**
+     * True when a checkpoint from ANY process is resumable. Async because the
+     * durable check touches disk; `hasResumableRun` remains the sync in-memory
+     * answer for callers already on a hot path.
+     */
+    hasDurableResume(): Promise<boolean>;
+    /** Interrupted runs available to resume, newest first. */
+    listResumableRuns(): Promise<ResumeCheckpoint[]>;
     /**
      * Raise the per-run token budget for a resume and return the continuation
      * prompt (or null when nothing is resumable). Consumes the interrupted-run
@@ -2576,6 +2723,26 @@ declare class Cascade extends EventEmitter {
     prepareResume(opts?: {
         maxTokens?: number;
     }): string | null;
+    /**
+     * Durable counterpart to prepareResume: recovers a run interrupted in ANY
+     * process, including one that crashed before it could return. Consumes the
+     * checkpoint, so the same finished work is never restored into two runs.
+     */
+    prepareDurableResume(opts?: {
+        maxTokens?: number;
+        taskId?: string;
+    }): Promise<string | null>;
+    /** A resume gets a bigger budget — the previous attempt exhausted the old one. */
+    private raiseBudgetForResume;
+    /**
+     * The resume prompt. Completed sections are named explicitly rather than
+     * gestured at: "do not recreate the files" is an instruction a planner can
+     * only guess at, whereas a list of what is already done, and what it produced,
+     * is something it can act on. That difference is the entire reason node
+     * results are kept — a re-plan that cannot see the finished work will plan the
+     * finished work again, and the user pays for it a second time.
+     */
+    private buildResumePrompt;
     /**
      * Resume the last budget-capped task with a raised budget (SDK/headless).
      * Returns null when there is nothing to resume.
@@ -2881,14 +3048,6 @@ declare class T2Manager extends BaseTier {
      *     then reduce in-degrees of their dependents and repeat.
      */
     private runWithDependencies;
-    /**
-     * Detects cyclic dependencies using Kahn's algorithm and breaks them
-     * by removing back-edges. Returns a sanitized copy of assignments.
-     *
-     * A cycle like t1→t2→t3→t1 is broken at the last edge (t3→t1),
-     * meaning t3 will start without waiting for t1, preventing deadlock.
-     */
-    private breakCycles;
     private retryT3;
     private publishSectionOutput;
     private aggregateResults;
@@ -2979,6 +3138,11 @@ declare class T3Worker extends BaseTier {
      * needed. Best-effort: any parse/error just keeps the current output.
      */
     private reflectAndImprove;
+    /**
+     * Run the acceptance criteria that can be settled by looking at the workspace.
+     * Reads go through the same workspace-relative resolution verifyArtifacts uses.
+     */
+    private checkAcceptance;
     private selfTest;
     /**
      * world-state v2: distill a completed subtask's output into durable
@@ -3000,6 +3164,143 @@ declare class T3Worker extends BaseTier {
     private isFileOperation;
 }
 
+type TaskGraphNodeKind = 'section' | 'subtask';
+type TaskGraphValidationMode = 'strict' | 'repair';
+interface TaskGraphInputNode<TPayload> {
+    id: string;
+    title: string;
+    kind: TaskGraphNodeKind;
+    dependsOn?: readonly string[];
+    payload: TPayload;
+}
+interface TaskGraphNode<TPayload> {
+    id: string;
+    title: string;
+    kind: TaskGraphNodeKind;
+    dependsOn: readonly string[];
+    payload: TPayload;
+    /** Stable source order used to keep execution deterministic. */
+    ordinal: number;
+}
+interface TaskGraph<TPayload> {
+    nodes: readonly TaskGraphNode<TPayload>[];
+}
+type TaskGraphIssueCode = 'INVALID_NODE' | 'DUPLICATE_NODE_ID' | 'SELF_DEPENDENCY' | 'UNKNOWN_DEPENDENCY' | 'CYCLE_EDGE_REMOVED';
+interface TaskGraphIssue {
+    code: TaskGraphIssueCode;
+    message: string;
+    nodeId?: string;
+    dependencyId?: string;
+}
+interface CompiledTaskGraph<TPayload> {
+    graph: TaskGraph<TPayload>;
+    issues: readonly TaskGraphIssue[];
+}
+interface CompileTaskGraphOptions {
+    /**
+     * strict: reject malformed LLM plans.
+     * repair: preserve today's graceful-degradation behaviour by dropping only
+     * invalid dependency edges and duplicate/invalid nodes.
+     */
+    mode?: TaskGraphValidationMode;
+}
+declare class TaskGraphValidationError extends Error {
+    readonly issues: readonly TaskGraphIssue[];
+    constructor(issues: readonly TaskGraphIssue[]);
+}
+/**
+ * Compile untrusted planner output into a deterministic, schedulable graph.
+ * The compiler is the trust boundary between LLM-authored JSON and execution.
+ */
+declare function compileTaskGraph<TPayload>(inputNodes: readonly TaskGraphInputNode<TPayload>[], options?: CompileTaskGraphOptions): CompiledTaskGraph<TPayload>;
+
+type SchedulerExecutionMode = 'parallel' | 'sequential';
+interface SchedulerHooks<TPayload, TResult> {
+    execute(node: TaskGraphNode<TPayload>): Promise<TResult>;
+    onWaveStart?(nodes: readonly TaskGraphNode<TPayload>[], wave: number): void | Promise<void>;
+    onNodeComplete?(node: TaskGraphNode<TPayload>, result: TResult): void | Promise<void>;
+}
+interface SchedulerOptions {
+    mode?: SchedulerExecutionMode;
+}
+interface SchedulerResult<TResult> {
+    results: ReadonlyMap<string, TResult>;
+    waves: readonly (readonly string[])[];
+}
+/**
+ * Shared deterministic dependency scheduler for T1 sections and T2 subtasks.
+ * Graph validation/repair belongs in compileTaskGraph; this class only executes
+ * a valid DAG in stable source order.
+ */
+declare class DependencyScheduler<TPayload, TResult> {
+    private readonly graph;
+    private readonly hooks;
+    private readonly options;
+    constructor(graph: TaskGraph<TPayload>, hooks: SchedulerHooks<TPayload, TResult>, options?: SchedulerOptions);
+    run(): Promise<SchedulerResult<TResult>>;
+}
+
+declare function compileSectionGraph(sections: readonly T1ToT2Assignment[]): CompiledTaskGraph<T1ToT2Assignment>;
+/**
+ * The subtask fields the graph actually needs. Generic over the whole record so
+ * both the planner's `T3SubtaskSpec` and T2's richer `T2ToT3Assignment` compile
+ * without a cast — they carry the same identity and dependency fields, and the
+ * payload comes back out at its original type.
+ */
+interface SubtaskGraphInput {
+    subtaskId: string;
+    subtaskTitle: string;
+    dependsOn?: string[];
+}
+declare function compileSubtaskGraph<TSubtask extends SubtaskGraphInput>(subtasks: readonly TSubtask[]): CompiledTaskGraph<TSubtask>;
+
+/**
+ * The deterministic rung of the verification ladder.
+ *
+ * T1 asks the planner for acceptance criteria that are "1-3 checks a reviewer
+ * could verify mechanically (file exists / contains X / command exits 0)", and
+ * the planner obliges — but nothing ever checked them mechanically. Every
+ * criterion went to selfTest(), an LLM call, which is both slower and a worse
+ * judge of "does this file exist" than `stat` is. A grader that hallucinates a
+ * pass on a file that was never written is exactly the failure the criteria
+ * were introduced to prevent.
+ *
+ * So: decide here what can be decided by looking, and hand the rest to the
+ * model unchanged. The governing rule is that **deferring is always safe and
+ * deciding wrongly is not**, so every pattern below is deliberately narrow.
+ * A criterion this module cannot confidently parse comes back `undecidable`
+ * and the LLM grader sees it exactly as it does today.
+ *
+ * Shell criteria ("command exits 0") are deliberately NOT executed. Acceptance
+ * text is LLM-authored and reaches this code as free prose; running it would
+ * turn a plan into an arbitrary command execution channel. Those stay
+ * undecidable.
+ */
+type AcceptanceVerdict = 'passed' | 'failed' | 'undecidable';
+interface AcceptanceResult {
+    criterion: string;
+    verdict: AcceptanceVerdict;
+    /** Human-readable reason, present for passed/failed. */
+    detail?: string;
+}
+interface AcceptanceProbe {
+    /** null when the path does not exist or is not a regular file. */
+    stat(path: string): Promise<{
+        size: number;
+    } | null>;
+    /** utf-8 contents, or null when unreadable (missing, binary, too large). */
+    read(path: string): Promise<string | null>;
+}
+/**
+ * Evaluate acceptance criteria, deciding only the mechanically checkable ones.
+ * Order and length of the result always match `criteria`.
+ */
+declare function evaluateAcceptance(criteria: readonly string[], ownedFiles: readonly string[], probe: AcceptanceProbe): Promise<AcceptanceResult[]>;
+/** The criteria that still need a model's judgement. */
+declare function undecided(results: readonly AcceptanceResult[]): string[];
+/** Failure messages, phrased so correctOutput can act on them directly. */
+declare function failures(results: readonly AcceptanceResult[]): string[];
+
 /**
  * High-level SDK entry point — loads config from the workspace and runs a task.
  *
@@ -4032,6 +4333,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 +5095,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 AcceptanceProbe, type AcceptanceResult, type AcceptanceVerdict, 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 CompileTaskGraphOptions, type CompiledTaskGraph, type CompleteFn, type CompletedNode, 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, DependencyScheduler, 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, RESUME_SCHEMA_VERSION, type RankedFact, type RefreshResult, type RenderOptions, type Reranker, type ResumeCheckpoint, type ResumeReason, ResumeStore, type ResumeStoreOptions, type RetrievalContext, type RetrievalMode, type RetrievalPlan, Retriever, type RetrieverSearchOptions, type RuntimeNode, type RuntimeNodeLog, type RuntimeRefreshPayload, type RuntimeScope, type RuntimeSession, type RuntimeSnapshotPayload, type ScheduledTask, type SchedulerExecutionMode, type SchedulerHooks, type SchedulerOptions, type SchedulerResult, 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, type TaskGraph, type TaskGraphInputNode, type TaskGraphIssue, type TaskGraphIssueCode, type TaskGraphNode, type TaskGraphNodeKind, TaskGraphValidationError, type TaskGraphValidationMode, 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, compileSectionGraph, compileSubtaskGraph, compileTaskGraph, completeMcpOAuth, connectMcpWithLoopbackOAuth, createCascade, decryptJSON as decryptSyncBlob, diffManifest, disambiguateMcpServerNames, discoverMcpAuthServer, discoverMcpTools, distillSessionFacts, embedderFromProviders, encryptJSON as encryptSyncBlob, evaluateAcceptance, extractCharts, failures, 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, summarizeCompleted, undecided, uniqueMcpServerName };