@evandu/super-pi 0.1.129 → 0.1.131

package/dist/client/index.html

@@ -8,7 +8,7 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-D_c-CYAr.js"></script>
+    <script type="module" crossorigin src="/assets/index-BApJ3Zbq.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CXB6U5mz.css">
   </head>
   <body>

package/dist/server/active-memory.d.ts

@@ -70,6 +70,18 @@ export declare class ActiveMemory {
         content: string;
     }[];
     private ensureIndex;
+    /**
+     * Drops a workspace's search index so the next search rebuilds it from the store.
+     *
+     * WHY THIS EXISTS. `ensureIndex` builds once per workspace and `addToIndex` only ever adds, so the
+     * index outlives the messages it indexed: a revert removes messages from the store while the index
+     * keeps their text, and the next recall then hands the model a turn the user has just withdrawn -
+     * measured by scripts/revert-real-pi.test.mjs, where the withdrawn codeword came back as "recalled
+     * history" after a revert every file-level assertion proved had really truncated. The store is the
+     * source of truth; the index is a cache of it, and a cache that survives an event that invalidated
+     * its source is wrong by definition.
+     */
+    invalidateSearchIndex(workspaceId: string): void;
     private addToIndex;
     tool(token: string, body: {
         kind?: string;

package/dist/server/active-memory.js

@@ -71,7 +71,16 @@ export class ActiveMemory {
             // The live set is whatever SURVIVED, read back rather than derived from the dropped ids: deriving it
             // as "everything not dropped" would be wrong the moment an entry was removed by someone else.
             const live = new Set((await this.notes.apply(conversation.workspaceId, "", { target: "skills", action: "list" })).map((entry) => entry.id));
-            for (const name of await readdir(folder)) {
+            // The skills folder exists only once a skill has been written for this workspace, so its absence is
+            // the ordinary note-only case and not a failure. Throwing on it here used to discard the forget
+            // result above with it: the entries were already dropped, but the caller read the catch's zero as
+            // "nothing was withdrawn", and the log lied about the very rewind this method exists to do.
+            let skillFiles = [];
+            try {
+                skillFiles = await readdir(folder);
+            }
+            catch { /* no skill has ever been written for this workspace */ }
+            for (const name of skillFiles) {
                 if (name.endsWith(".md") && !live.has(name.slice(0, -3)))
                     await unlink(join(folder, name)).catch(() => { });
             }
@@ -135,6 +144,21 @@ export class ActiveMemory {
         this.inverted.set(workspaceId, index);
         this.indexedWorkspaces.add(workspaceId);
     }
+    /**
+     * Drops a workspace's search index so the next search rebuilds it from the store.
+     *
+     * WHY THIS EXISTS. `ensureIndex` builds once per workspace and `addToIndex` only ever adds, so the
+     * index outlives the messages it indexed: a revert removes messages from the store while the index
+     * keeps their text, and the next recall then hands the model a turn the user has just withdrawn -
+     * measured by scripts/revert-real-pi.test.mjs, where the withdrawn codeword came back as "recalled
+     * history" after a revert every file-level assertion proved had really truncated. The store is the
+     * source of truth; the index is a cache of it, and a cache that survives an event that invalidated
+     * its source is wrong by definition.
+     */
+    invalidateSearchIndex(workspaceId) {
+        this.indexedWorkspaces.delete(workspaceId);
+        this.inverted.delete(workspaceId);
+    }
     addToIndex(conversation, message) {
         if (!this.indexedWorkspaces.has(conversation.workspaceId) || (message.role !== "user" && message.role !== "assistant"))
             return;

package/dist/server/application/conversation-service.js

@@ -356,6 +356,11 @@ export class ConversationService {
         // so this runs on data that is settled and cannot be racing the store's own writes.
         const firstRemoved = conversation.messages[applied.boundaryIndex + 1];
         const forgotten = firstRemoved ? await this.memory?.forgetAfter(conversationId, firstRemoved.createdAt) ?? 0 : 0;
+        // The recall index is a cache of the store's messages, and the store just lost several: left alone it
+        // keeps answering the memory extension's searches with the withdrawn turns, so the model is told about
+        // history the person reverted away even though the transcript, Pi's file and the memory store all
+        // agree it is gone. Invalidate it and the next search rebuilds from what actually survived.
+        this.memory?.invalidateSearchIndex(workspaceId);
         console.log(`Super Pi: reverted conversation ${conversationId} to ${applied.boundaryIndex + 1} message(s): ` +
             `${plan.removedMessageIds.length} message(s) and ${applied.doomedRunIds.length} sub-agent run(s) dropped from state.json; ` +
             `Pi's file ${outcome.sessionFile} kept ${outcome.linesKept} line(s) and lost ${outcome.entriesDropped}; ` +

package/dist/server/application/document-service.d.ts

@@ -0,0 +1,68 @@
+import type { Store } from "../store.js";
+import type { DocumentFormat } from "../documents.js";
+/**
+ * The largest request the document endpoint accepts.
+ *
+ * A document's extracted text rides in the request, so the cap is the document cap - a request past
+ * it is refused outright rather than truncated into a document that silently lost its tail.
+ */
+export declare const MAX_DOCUMENT_REQUEST_BYTES: number;
+/**
+ * THE DOCUMENT SERVICE: what an agent can do with the files in a workspace.
+ *
+ * It is the agent-facing half of the parsing layer. The knowledge base uses the same parsing code
+ * (see `knowledge.ts`), so a PDF reads the same way whether it was imported into the knowledge base
+ * or read straight out of the workspace - which is the point of having one parsing layer.
+ *
+ * WHY THE SERVICE OWNS THE PATH GUARD AND NOT THE EXTENSION. The extension runs in Pi's process and
+ * could ask for any path it liked. The service resolves every path against the workspace root with
+ * the same `resolveInsideRoot` guard the file panel uses, so a `..` or a symlink pointing outside
+ * the workspace is refused by construction rather than by a check somebody has to remember.
+ */
+export declare class DocumentService {
+    private readonly store;
+    constructor(store: Store);
+    /**
+     * The workspace a conversation works in, taken from the store.
+     *
+     * The conversation is the caller's identity, and the workspace is derived from it. A request that
+     * named its own workspace would be a request that could read another workspace.
+     */
+    private workspacePath;
+    /**
+     * Reads a file's contents.
+     *
+     * A text file is returned as it is; a document is parsed. The distinction matters because the two
+     * fail differently: a text file that does not exist is a missing file, while a document that
+     * cannot be parsed is a document with a reason.
+     */
+    read(conversationId: string, path: string): Promise<{
+        text: string;
+        format: string;
+        warnings: string[];
+        etag: string;
+    }>;
+    /**
+     * Writes a document into the workspace.
+     *
+     * The content is Markdown for a Word or PDF document and CSV for a spreadsheet, and the format is
+     * taken from the file's extension - so the caller says "write this report to REPORT.docx" and the
+     * right writer is chosen. An extension that names no document format is refused, because writing
+     * a `.txt` file is what Pi's own `write` tool is for, and a second way to do it is a second way to
+     * be wrong about it.
+     *
+     * OVERWRITING AN EXISTING FILE NEEDS THE VERSION THE CALLER READ, the same rule the file panel's
+     * write enforces (docs/DOCUMENTS.md: 覆盖已有文件前要确认，etag 语义和文件面板一致). A document is a
+     * file a person edits; an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit
+     * made an hour ago with no refusal, no diff, no warning. A missing etag over an existing file and a
+     * stale one are both refused, and the refusal carries the CURRENT etag - which is what makes an
+     * informed overwrite possible, the same way the panel's 409 does: re-sending the current etag is
+     * the deliberate "仍然覆盖", not a skipped check. A file that does not exist yet is the ordinary
+     * create case and needs no confirmation.
+     */
+    write(conversationId: string, path: string, content: string, title?: string, baseEtag?: string): Promise<{
+        path: string;
+        bytes: number;
+        format: DocumentFormat;
+    }>;
+}

package/dist/server/application/document-service.js

@@ -0,0 +1,120 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, extname } from "node:path";
+import { buildDocument, documentFormatOf, DocumentError, extractText } from "../documents.js";
+import { fileEtag, resolveInsideRoot } from "../files.js";
+/**
+ * The largest request the document endpoint accepts.
+ *
+ * A document's extracted text rides in the request, so the cap is the document cap - a request past
+ * it is refused outright rather than truncated into a document that silently lost its tail.
+ */
+export const MAX_DOCUMENT_REQUEST_BYTES = 8 * 1024 * 1024;
+/**
+ * THE DOCUMENT SERVICE: what an agent can do with the files in a workspace.
+ *
+ * It is the agent-facing half of the parsing layer. The knowledge base uses the same parsing code
+ * (see `knowledge.ts`), so a PDF reads the same way whether it was imported into the knowledge base
+ * or read straight out of the workspace - which is the point of having one parsing layer.
+ *
+ * WHY THE SERVICE OWNS THE PATH GUARD AND NOT THE EXTENSION. The extension runs in Pi's process and
+ * could ask for any path it liked. The service resolves every path against the workspace root with
+ * the same `resolveInsideRoot` guard the file panel uses, so a `..` or a symlink pointing outside
+ * the workspace is refused by construction rather than by a check somebody has to remember.
+ */
+export class DocumentService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * The workspace a conversation works in, taken from the store.
+     *
+     * The conversation is the caller's identity, and the workspace is derived from it. A request that
+     * named its own workspace would be a request that could read another workspace.
+     */
+    workspacePath(conversationId) {
+        const conversation = this.store.snapshot().conversations.find(item => item.id === conversationId);
+        if (!conversation)
+            throw new Error("会话不存在");
+        const workspace = this.store.snapshot().workspaces.find(item => item.id === conversation.workspaceId);
+        if (!workspace)
+            throw new Error("工作区不存在");
+        return workspace.path;
+    }
+    /**
+     * Reads a file's contents.
+     *
+     * A text file is returned as it is; a document is parsed. The distinction matters because the two
+     * fail differently: a text file that does not exist is a missing file, while a document that
+     * cannot be parsed is a document with a reason.
+     */
+    async read(conversationId, path) {
+        const root = this.workspacePath(conversationId);
+        const absolute = await resolveInsideRoot(root, path);
+        const info = await stat(absolute).catch(() => null);
+        if (!info || !info.isFile())
+            throw new Error(`找不到文件：${path}`);
+        const extension = extname(absolute).toLocaleLowerCase();
+        const format = documentFormatOf(extension);
+        if (format) {
+            try {
+                const extracted = await extractText(absolute, format);
+                return { text: extracted.text, format, warnings: extracted.warnings, etag: await fileEtag(absolute) };
+            }
+            catch (error) {
+                // The parser's reasons are already written for a person - a scan with no text layer, an
+                // encrypted file, a missing package - and they are passed through unchanged. A model that
+                // is told "读取失败" cannot help the person; a model that is told "这份 PDF 是扫描件" can.
+                if (error instanceof DocumentError)
+                    throw new Error(error.message);
+                throw error;
+            }
+        }
+        const { readFile } = await import("node:fs/promises");
+        const buffer = await readFile(absolute);
+        // The etag rides along so a follow-up `document_write` over this file can present the version it
+        // read - the same confirm-before-overwrite the file panel's editor lives by (see `write`).
+        return { text: buffer.toString("utf8"), format: extension || "text", warnings: [], etag: await fileEtag(absolute) };
+    }
+    /**
+     * Writes a document into the workspace.
+     *
+     * The content is Markdown for a Word or PDF document and CSV for a spreadsheet, and the format is
+     * taken from the file's extension - so the caller says "write this report to REPORT.docx" and the
+     * right writer is chosen. An extension that names no document format is refused, because writing
+     * a `.txt` file is what Pi's own `write` tool is for, and a second way to do it is a second way to
+     * be wrong about it.
+     *
+     * OVERWRITING AN EXISTING FILE NEEDS THE VERSION THE CALLER READ, the same rule the file panel's
+     * write enforces (docs/DOCUMENTS.md: 覆盖已有文件前要确认，etag 语义和文件面板一致). A document is a
+     * file a person edits; an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit
+     * made an hour ago with no refusal, no diff, no warning. A missing etag over an existing file and a
+     * stale one are both refused, and the refusal carries the CURRENT etag - which is what makes an
+     * informed overwrite possible, the same way the panel's 409 does: re-sending the current etag is
+     * the deliberate "仍然覆盖", not a skipped check. A file that does not exist yet is the ordinary
+     * create case and needs no confirmation.
+     */
+    async write(conversationId, path, content, title, baseEtag) {
+        const root = this.workspacePath(conversationId);
+        const absolute = await resolveInsideRoot(root, path);
+        const extension = extname(absolute).toLocaleLowerCase();
+        const format = documentFormatOf(extension);
+        if (!format) {
+            throw new Error(`只能写 PDF、Word（.docx）和 Excel（.xlsx）文件；${extension || "这个文件"} 请用 write 工具直接写文本。`);
+        }
+        const existing = await stat(absolute).catch(() => null);
+        if (existing?.isFile()) {
+            const current = await fileEtag(absolute);
+            if (!baseEtag) {
+                throw new Error(`文件已存在：${path}。覆盖它必须先确认版本——先用 document_read 读取该文件，把它返回的 etag 作为 baseEtag 传入；当前 etag：${current}。`);
+            }
+            if (baseEtag !== current) {
+                throw new Error(`文件在磁盘上已被其他程序修改，未写入：${path}（当前 etag：${current}，你提供的是 ${baseEtag}）。如确认覆盖，请带着当前 etag 重试。`);
+            }
+        }
+        const { bytes } = await buildDocument({ format, content, title });
+        await mkdir(dirname(absolute), { recursive: true });
+        await writeFile(absolute, bytes);
+        return { path, bytes: bytes.length, format };
+    }
+}

package/dist/server/application/run-service.js

@@ -60,7 +60,14 @@ function composePrompt(message) {
     const summary = summaryMatch ? summaryMatch[1].trim() : "后台任务";
     const stateMatch = /<task id="[^"]+" state="([^"]+)"/.exec(content);
     const state = stateMatch ? stateMatch[1] : "completed";
-    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*?)\n?<\/(?:task_result|task_error)>/.exec(content);
+    // GREEDY ON PURPOSE. The envelope is machine-built with the command's RAW output interpolated before
+    // its closing tags, so the body may itself contain `</task_result>` - printed XML, a log excerpt, the
+    // model's own echoed envelope format. A non-greedy match stops at the FIRST such tag and hands the
+    // model a truncated half-result while the reader sees the full one (measured by
+    // scripts/background-result-body.test.mjs with `hello </task_result> world`). Matching greedily lands
+    // on the envelope's own closing tag - the LAST one in the content - which is where the body ends
+    // regardless of what the command printed.
+    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*)\n?<\/(?:task_result|task_error)>/.exec(content);
     const body = bodyMatch ? bodyMatch[1] : content;
     const stateLabel = state === "completed" ? "已完成" : state === "error" ? "失败" : state;
     return `[后台任务「${summary}」${stateLabel}]\n\n${body}`;
@@ -239,14 +246,33 @@ export class RunService {
                 // processes the result" contract, and the auto-triggered turn goes through the same
                 // `composePrompt` path the success case does (so a helper failure surfaces as `state="error"`
                 // prose the agent can react to).
+                // EXACTLY ONE DELIVERY PER RESULT. The custom channel hands the result straight to Pi's own
+                // follow-up queue, but it knows nothing about the `waiting` row queued above, and
+                // `takeNextWaitingMessage` knows nothing about Pi's queue - so delivering through the channel
+                // while leaving the row waiting gave the model the SAME result twice (once as the custom
+                // message, once as the row's own prose turn). Measured by
+                // scripts/background-result-delivery.test.mjs. So a successful custom delivery CONSUMES the row,
+                // and a failed one - `SteerUnavailableError`, which is what oneshot mode and a not-yet-created
+                // session throw - falls back to the queue path, the same semantics the sub-agent result path
+                // (processWaitingMessage only) has always had.
+                let deliveredViaCustom = false;
                 const custom = this.runtime.sendCustomMessage;
                 if (custom) {
-                    await custom.call(this.runtime, task.conversationId, {
-                        customType: "super-pi-task-result",
-                        content: body,
-                        display: "后台任务结果",
-                        details: { taskId: sessionId, source: "exec", state: exitCode === 0 ? "completed" : "error", summary: task.title },
-                    });
+                    try {
+                        await custom.call(this.runtime, task.conversationId, {
+                            customType: "super-pi-task-result",
+                            content: body,
+                            display: "后台任务结果",
+                            details: { taskId: sessionId, source: "exec", state: exitCode === 0 ? "completed" : "error", summary: task.title },
+                        });
+                        deliveredViaCustom = true;
+                    }
+                    catch (error) {
+                        console.warn(`Super Pi: custom delivery of the exec result failed, the queue path takes over: ${error instanceof Error ? error.message : "unknown error"}`);
+                    }
+                }
+                if (deliveredViaCustom) {
+                    await this.store.takeWaitingMessage(task.conversationId, queued.id);
                 }
                 else if (!this.activeRuns.has(task.conversationId) && !this.interruptTargets.has(task.conversationId)) {
                     void this.processWaitingMessage(task.conversationId, queued.id).catch((error) => {
@@ -551,6 +577,22 @@ export class RunService {
     async stopRunUnsafe(conversationId) {
         this.memory?.cancel(conversationId);
         this.extensionUiService.cancelPendingUi(conversationId, "aborted");
+        // THE `question` TOOL IS A PENDING ASK THE STOP MUST SETTLE, not a client-only state. Its row only
+        // ever leaves `pending` through the user's `question.answer` command, so a stop used to leave the
+        // ask waiting forever: the extension's HTTP handler never returned, the ask's 250ms full-snapshot
+        // poll never cleared, and the card stayed interactive on a dead turn (measured by
+        // scripts/question-stop.test.mjs). The same settlement the Extension UI channel gets from
+        // `cancelPendingUi` above - answered `cancelled`, never a default - applied to the question rows.
+        const stopped = this.store.snapshot().conversations.find((item) => item.id === conversationId);
+        for (const message of stopped?.messages ?? []) {
+            for (let index = 0; index < (message.toolCalls?.length ?? 0); index += 1) {
+                const question = message.toolCalls?.[index]?.question;
+                if (question?.status !== "pending")
+                    continue;
+                const calls = await this.store.updateToolCall(conversationId, message.id, index, { question: { items: question.items, status: "cancelled" } });
+                this.broadcaster.broadcast({ type: "message.tools", conversationId, messageId: message.id, toolCalls: calls });
+            }
+        }
         await this.store.setStatus(conversationId, "stopped");
         if (this.subagents.stopConversation(conversationId)) {
             console.log(`Super Pi: stopped the sub-agent runs of conversation ${conversationId}.`);

package/dist/server/documents.d.ts

@@ -0,0 +1,152 @@
+/**
+ * THE DOCUMENT PARSING LAYER.
+ *
+ * It turns the files a person actually has - PDFs, Word documents, spreadsheets - into text, and it
+ * turns text back into those files. Everything else in Super Pi - the knowledge base, the agent's
+ * document tool - goes through here, so the same file reads the same way in both places.
+ *
+ * WHY IT LIVES ON THE SERVER AND NOT IN A PI EXTENSION. A Pi extension runs inside Pi's process, and
+ * Pi's process resolves `node_modules` against PI's install, not against Super Pi's. The parsing
+ * libraries are Super Pi's dependencies, so an extension could not load them: the code would work in
+ * the dev checkout and fail in every installed layout, which is the exact failure mode
+ * `scripts/installed-layout.test.mjs` exists to catch. The server is also the only layer that holds
+ * both the workspace's absolute paths and the capability tokens, so the path guard and the
+ * credential check live in the same place as the parsing.
+ *
+ * WHY EVERY LIBRARY IS OPTIONAL. The knowledge base's vector layer is optional for the same reason:
+ * a missing package must degrade the FEATURE, not break the PANEL. A user who did not install
+ * pdfjs-dist should still be able to run Super Pi and read their Markdown; they should get a clear
+ * sentence about which package to install when they try to read a PDF.
+ */
+/**
+ * The document formats this layer understands, by file extension.
+ *
+ * `ppt` is READ-ONLY: the legacy binary format has no pure-JS writer, and generating a real
+ * PowerPoint 97 file means reimplementing a 1997 binary format. Reading it is a record walk; writing
+ * it is refused with a pointer to `.pptx`.
+ */
+export type DocumentFormat = "pdf" | "docx" | "xlsx" | "pptx" | "ppt";
+/**
+ * The tools the agent sees.
+ *
+ * Duplicated as literals in `agents/super-pi-documents/index.ts`, the way `KNOWLEDGE_TOOL_NAME` is:
+ * the extension runs in Pi's process and cannot import from the server, and a name that exists in
+ * only one of the two places is a name one of them will get wrong.
+ */
+export declare const DOCUMENT_READ_TOOL_NAME = "document_read";
+export declare const DOCUMENT_WRITE_TOOL_NAME = "document_write";
+/** What a caller needs to know about a document after it has been read. */
+export type ExtractResult = {
+    /** The extracted text. Empty only when the source genuinely had no text layer. */
+    text: string;
+    /** The format the text came from. */
+    format: DocumentFormat;
+    /** How many pages the document had, when the format has pages. */
+    pages?: number;
+    /**
+     * What was lost in the conversion, stated rather than hidden.
+     *
+     * WHY THIS IS A FIELD AND NOT A LOG LINE. A Word document's tables become pipe-separated lines and
+     * its images become nothing at all. A caller that knows the extraction was lossy can say so to the
+     * person; a caller that does not will present a flattened table as if it were the document.
+     */
+    warnings: string[];
+};
+/** The failure of a document that could not be read, in a form a person can act on. */
+export declare class DocumentError extends Error {
+    readonly code: DocumentErrorCode;
+    constructor(code: DocumentErrorCode, message: string);
+}
+/**
+ * WHY THE CODES EXIST. "Read failed" is not actionable, and the ways a document fails are
+ * genuinely different from one another: a dependency is missing (install something), a PDF has no
+ * text layer (it is a scan - use a different route), a PDF is encrypted (it needs a password), and
+ * the file is simply broken (nothing to do about it). Each of those needs a different sentence, and
+ * a person who is told "read failed" learns nothing.
+ */
+export type DocumentErrorCode = "missing_dependency" | "missing_asset" | "no_text_layer" | "encrypted" | "corrupt" | "unsupported" | "empty";
+/**
+ * Whether an extension names a document this layer can read.
+ *
+ * The name is checked BEFORE the bytes are sniffed, because the caller needs to know whether to
+ * attempt a parse at all - and because a `.pdf` that is really a text file is a different situation
+ * from a file with no extension that happens to be a PDF.
+ */
+export declare function isDocumentFormat(extension: string): boolean;
+/** The format an extension names, or null when it names none. */
+export declare function documentFormatOf(extension: string): DocumentFormat | null;
+/** The extension a format is written with. */
+export declare function extensionForFormat(format: DocumentFormat): string;
+/**
+ * Reads a document's text.
+ *
+ * The file is read here rather than handed in as a buffer because the parsers differ in what they
+ * want: pdfjs wants a path or a typed array, mammoth wants a buffer, exceljs wants a stream or a
+ * buffer. Reading once here keeps that difference from leaking into the callers.
+ */
+export declare function extractText(path: string, format: DocumentFormat): Promise<ExtractResult>;
+/**
+ * Reads a document's text from bytes already in hand.
+ *
+ * Split out from `extractText` so the parsers can be exercised without touching the filesystem, and
+ * so a caller that already has the bytes (an upload, an API request) does not write them to a
+ * temporary file to read them back.
+ */
+export declare function extractTextFromBytes(bytes: Buffer, format: DocumentFormat): Promise<ExtractResult>;
+/**
+ * WHAT A DOCUMENT IS TO BE WRITTEN FROM.
+ *
+ * The content is Markdown for prose documents and CSV for spreadsheets, chosen by the format rather
+ * than by the caller: a spreadsheet built from Markdown is a table with the wrong shape, and the
+ * caller should not have to know that.
+ */
+export type DocumentSpec = {
+    format: DocumentFormat;
+    /** The content. Markdown for `docx`, `pdf` and `pptx`, CSV for `xlsx`. */
+    content: string;
+    /** The document's title, used for the Word heading and the PDF title line. */
+    title?: string;
+};
+/**
+ * Builds a document's bytes.
+ *
+ * The output is a REAL document - it opens in Word, Excel and a PDF reader - not a renamed text
+ * file. The structure is simple on purpose: headings, paragraphs, lists and tables for Word;
+ * sheets of cells for Excel; lines of text for a PDF.
+ */
+export declare function buildDocument(spec: DocumentSpec): Promise<{
+    bytes: Buffer;
+    format: DocumentFormat;
+}>;
+/**
+ * The blocks a Markdown document is made of.
+ *
+ * A full Markdown parser is not needed here, and pulling one in would mean deciding what to do with
+ * the constructs it supports that a Word document has no place for. The subset below is the one a
+ * person actually uses when they ask for "a Word version of this".
+ */
+type Block = {
+    kind: "heading";
+    level: number;
+    text: string;
+} | {
+    kind: "paragraph";
+    text: string;
+} | {
+    kind: "list";
+    items: string[];
+} | {
+    kind: "table";
+    header: string[];
+    rows: string[][];
+} | {
+    kind: "code";
+    text: string;
+};
+/** Splits Markdown into the blocks a document is built from. Exported for the tests to exercise directly. */
+export declare function parseMarkdownBlocks(markdown: string): Block[];
+/**
+ * The format a file's extension names, for the callers that hold a path rather than a format.
+ */
+export declare function formatOfPath(path: string): DocumentFormat | null;
+export {};