@evandu/super-pi 0.1.130 → 0.1.131

package/dist/server/knowledge.d.ts

@@ -82,6 +82,8 @@ export type KnowledgeRuntime = {
 export declare function parseRanking(output: string): number[] | null;
 /** Duplicated as a literal in `agents/super-pi-knowledge/index.ts`, the way `TASK_TOOL_NAME` is. */
 export declare const KNOWLEDGE_TOOL_NAME = "knowledge_search";
+/** The import half of the same extension. Duplicated as a literal there, for the same reason. */
+export declare const KNOWLEDGE_IMPORT_TOOL_NAME = "knowledge_import";
 /**
  * Index terms for one string: CJK bigrams plus Latin words.
  *
@@ -152,17 +154,6 @@ export declare class KnowledgeBase {
     private load;
     private invalidate;
     list(workspaceId: string): Promise<Array<Omit<KnowledgeDocument, "text">>>;
-    /**
-     * Whether this workspace has any document at all, which is what decides whether the turn mounts the
-     * extension.
-     *
-     * WHY A DIRECTORY LISTING AND NOT `list()`. This runs once per turn, before every spawn. `list()`
-     * would read and parse every document's full text to answer a yes/no question, so a workspace with
-     * a dozen real documents would pay for parsing all of them on every message - including the
-     * catalogue fetch the extension makes the moment it loads. `readdir` answers the same question for
-     * the price of one directory entry, and a name is all this needs.
-     */
-    hasDocuments(workspaceId: string): Promise<boolean>;
     /**
      * Adds a document, either from a workspace file or from pasted text.
      *
@@ -171,6 +162,10 @@ export declare class KnowledgeBase {
      * newer version that diverges from the one the workspace serves. The path therefore goes through
      * the same `resolveInsideRoot` guard the file editor uses, so symlink and `..` escapes are refused
      * by construction instead of by a check someone has to remember.
+     *
+     * WHO CALLS THIS. The settings window (manage, action "add") AND, since the import tool exists,
+     * the primary agent mid-turn on the user's say-so - through the same guard, the same whitelist and
+     * the same caps, so an agent import can never do more than a person's import could.
      */
     add(workspaceId: string, body: {
         path?: string;
@@ -213,27 +208,42 @@ export declare class KnowledgeBase {
      */
     private rerank;
     /**
-     * Mints a read-only token for one turn. The agent can retrieve, never write: everything a person
-     * puts in a knowledge base is theirs to curate from the settings window.
+     * Mints a token for one turn. The agent can retrieve and IMPORT (a document the user just asked it
+     * to add rides through the same `add` guard the settings window uses), but never remove: curation
+     * that deletes a person's documents stays a settings-window act.
      */
     issue(conversationId: string): string;
     release(token: string): void;
     private identity;
-    /** The agent-facing endpoint: a title catalogue and a search. Nothing that writes. */
+    /**
+     * The agent-facing endpoint: a title catalogue, a search, and an import. The import is the SAME
+     * `add` the settings window calls - path guard, format whitelist, size caps, dedupe - so an agent
+     * cannot do anything a person could not, and the one thing it cannot do is `remove`.
+     */
     tool(token: string, body: {
         kind?: string;
         query?: string;
         limit?: number;
+        path?: string;
+        title?: string;
+        text?: string;
     }, signal?: AbortSignal): Promise<{
         documents: {
             title: string;
             source: string;
             characters: number;
         }[];
+        imported?: undefined;
+        hits?: undefined;
+        reranked?: undefined;
+    } | {
+        documents?: undefined;
+        imported: Omit<KnowledgeDocument, "text">;
         hits?: undefined;
         reranked?: undefined;
     } | {
         documents?: undefined;
+        imported?: undefined;
         hits: KnowledgeHit[];
         reranked: boolean;
     }>;

package/dist/server/knowledge.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { looksBinary, resolveInsideRoot } from "./files.js";
+import { documentFormatOf, DocumentError, extractText } from "./documents.js";
 /** 1 MB. Big enough for a design doc or a spec, small enough that chunking stays instant. */
 export const MAX_DOCUMENT_BYTES = 1024 * 1024;
 /** A pasted document rides inside a JSON body, so the request cap leaves room for escaping overhead. */
@@ -53,6 +54,8 @@ const HEADING = /^#{1,6}\s+(.*\S)\s*$/;
 const PASTED_SOURCE = "pasted";
 /** Duplicated as a literal in `agents/super-pi-knowledge/index.ts`, the way `TASK_TOOL_NAME` is. */
 export const KNOWLEDGE_TOOL_NAME = "knowledge_search";
+/** The import half of the same extension. Duplicated as a literal there, for the same reason. */
+export const KNOWLEDGE_IMPORT_TOOL_NAME = "knowledge_import";
 /** Extensions a document may be imported from. Mirrors `files.TEXT_EXTENSIONS`, minus the source languages. */
 const IMPORTABLE = new Set([
     ".md", ".markdown", ".mdx", ".txt", ".text", ".log", ".rst", ".org",
@@ -369,30 +372,6 @@ export class KnowledgeBase {
         const documents = (await this.readAll(workspaceId)).map(document => this.summarise(document));
         return documents.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
-    /**
-     * Whether this workspace has any document at all, which is what decides whether the turn mounts the
-     * extension.
-     *
-     * WHY A DIRECTORY LISTING AND NOT `list()`. This runs once per turn, before every spawn. `list()`
-     * would read and parse every document's full text to answer a yes/no question, so a workspace with
-     * a dozen real documents would pay for parsing all of them on every message - including the
-     * catalogue fetch the extension makes the moment it loads. `readdir` answers the same question for
-     * the price of one directory entry, and a name is all this needs.
-     */
-    async hasDocuments(workspaceId) {
-        if (!this.enabled())
-            return false;
-        if (!this.store.snapshot().workspaces.some(workspace => workspace.id === workspaceId))
-            return false;
-        try {
-            return (await readdir(this.folder(workspaceId))).some(name => name.endsWith(".json"));
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return false;
-            throw error;
-        }
-    }
     /**
      * Adds a document, either from a workspace file or from pasted text.
      *
@@ -401,6 +380,10 @@ export class KnowledgeBase {
      * newer version that diverges from the one the workspace serves. The path therefore goes through
      * the same `resolveInsideRoot` guard the file editor uses, so symlink and `..` escapes are refused
      * by construction instead of by a check someone has to remember.
+     *
+     * WHO CALLS THIS. The settings window (manage, action "add") AND, since the import tool exists,
+     * the primary agent mid-turn on the user's say-so - through the same guard, the same whitelist and
+     * the same caps, so an agent import can never do more than a person's import could.
      */
     async add(workspaceId, body) {
         this.requireWorkspace(workspaceId);
@@ -417,17 +400,42 @@ export class KnowledgeBase {
             if (!info.isFile())
                 throw new Error("只能导入文件");
             format = extname(absolute).toLocaleLowerCase();
-            if (!IMPORTABLE.has(format))
+            const documentFormat = documentFormatOf(format);
+            if (!IMPORTABLE.has(format) && !documentFormat) {
                 throw new Error(`不支持的文件类型 ${format || "(无扩展名)"}；请先转换为 Markdown 或纯文本`);
+            }
             if (info.size > MAX_DOCUMENT_BYTES)
                 throw new Error(`文件过大：${info.size} 字节超过 ${MAX_DOCUMENT_BYTES} 的上限`);
-            const buffer = await readFile(absolute);
-            if (looksBinary(buffer.subarray(0, 4096)))
-                throw new Error("看起来是二进制文件，无法索引");
-            text = buffer.toString("utf8");
             source = body.path.trim();
             if (!title)
                 title = basename(absolute);
+            if (documentFormat) {
+                // A DOCUMENT IS PARSED, NOT DECODED. The bytes on disk are a container - a PDF's or a
+                // docx's - and what goes into the knowledge base is the TEXT they contain. The format
+                // recorded on the document stays the SOURCE format (`.pdf`), because that is what the next
+                // re-import of this path has to parse it as: the extracted text is not a PDF, and treating
+                // it as one would make an update fail to parse at all.
+                //
+                // A DOCUMENT THAT COULD NOT BE READ IS A REFUSAL, NOT AN EMPTY DOCUMENT. The parser's own
+                // 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, because a person who is told
+                // "读取失败" learns nothing about what to do next.
+                try {
+                    const extracted = await extractText(absolute, documentFormat);
+                    text = extracted.text;
+                }
+                catch (error) {
+                    if (error instanceof DocumentError)
+                        throw new Error(error.message);
+                    throw error;
+                }
+            }
+            else {
+                const buffer = await readFile(absolute);
+                if (looksBinary(buffer.subarray(0, 4096)))
+                    throw new Error("看起来是二进制文件，无法索引");
+                text = buffer.toString("utf8");
+            }
         }
         const trimmed = text.trim();
         if (!trimmed)
@@ -677,8 +685,9 @@ export class KnowledgeBase {
         }
     }
     /**
-     * Mints a read-only token for one turn. The agent can retrieve, never write: everything a person
-     * puts in a knowledge base is theirs to curate from the settings window.
+     * Mints a token for one turn. The agent can retrieve and IMPORT (a document the user just asked it
+     * to add rides through the same `add` guard the settings window uses), but never remove: curation
+     * that deletes a person's documents stays a settings-window act.
      */
     issue(conversationId) {
         const conversation = this.store.snapshot().conversations.find(item => item.id === conversationId);
@@ -697,13 +706,19 @@ export class KnowledgeBase {
             throw new Error("知识库授权已失效");
         return identity;
     }
-    /** The agent-facing endpoint: a title catalogue and a search. Nothing that writes. */
+    /**
+     * The agent-facing endpoint: a title catalogue, a search, and an import. The import is the SAME
+     * `add` the settings window calls - path guard, format whitelist, size caps, dedupe - so an agent
+     * cannot do anything a person could not, and the one thing it cannot do is `remove`.
+     */
     async tool(token, body, signal) {
         const identity = this.identity(token);
         if (!this.enabled())
             throw new Error("知识库已关闭");
         if (body.kind === "catalogue")
             return { documents: (await this.list(identity.workspaceId)).map(document => ({ title: document.title, source: document.source, characters: document.characters })) };
+        if (body.kind === "import")
+            return { imported: await this.add(identity.workspaceId, { path: body.path, title: body.title, text: body.text }) };
         if (body.kind !== "search")
             throw new Error("未知知识库操作");
         // The reranker needs the conversation it is ranking FOR: that is whose model answers, whose

package/dist/server/pi-session-pool.js

@@ -22,7 +22,7 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { createPiSession, sameFingerprint, superPiExtensionPaths, } from "./pi-session.js";
+import { createPiSession, sameFingerprint, superPiExtensionPaths, superPiSkillPaths, } from "./pi-session.js";
 /** How long an idle session survives before it is evicted. */
 const IDLE_EVICTION_MS = 10 * 60_000;
 /**
@@ -170,6 +170,7 @@ export class PiSessionPool {
             sessionId: request.conversationId,
             sessionDir: this.sessionDir,
             extensionPaths: superPiExtensionPaths(this.repositoryRoot),
+            skillPaths: superPiSkillPaths(this.repositoryRoot),
             extensionEnv: request.extensionEnv,
             ...(request.systemPromptFile ? { systemPromptFile: request.systemPromptFile } : {}),
             ...(request.systemPromptMode ? { systemPromptMode: request.systemPromptMode } : {}),

package/dist/server/pi-session.d.ts

@@ -343,6 +343,8 @@ export interface SessionCreation {
     sessionDir: string;
     /** Super Pi's extensions to mount, as absolute paths. */
     extensionPaths: string[];
+    /** Super Pi's built-in skills to expose beside the user's and workspace's skills. */
+    skillPaths?: string[];
     /** The environment those extensions read when they are loaded. */
     extensionEnv: Record<string, string>;
     /** The agent's system prompt file, or undefined for Pi's own defaults. */
@@ -420,3 +422,5 @@ export interface PromptTemplateSummary {
 }
 export declare function loadPromptTemplateSummaries(cwd: string): Promise<PromptTemplateSummary[]>;
 export declare function superPiExtensionPaths(repositoryRoot: string): string[];
+/** Skills shipped by Super Pi itself. Paths are explicit so installed and development layouts agree. */
+export declare function superPiSkillPaths(repositoryRoot: string): string[];

package/dist/server/pi-session.js

@@ -269,6 +269,7 @@ export async function createPiSession(creation) {
             cwd: creation.cwd,
             agentDir,
             ...(creation.extensionPaths.length ? { additionalExtensionPaths: creation.extensionPaths } : {}),
+            ...(creation.skillPaths?.length ? { additionalSkillPaths: creation.skillPaths } : {}),
             ...(creation.systemPromptFile && creation.systemPromptMode === "replace"
                 ? { systemPrompt: creation.systemPromptFile }
                 : creation.systemPromptFile
@@ -413,6 +414,16 @@ export function superPiExtensionPaths(repositoryRoot) {
         join(repositoryRoot, "agents", "super-pi-task", "index.ts"),
         join(repositoryRoot, "agents", "super-pi-memory", "index.ts"),
         join(repositoryRoot, "agents", "super-pi-knowledge", "index.ts"),
+        join(repositoryRoot, "agents", "super-pi-web", "index.ts"),
+        // The document tools. They are mounted for every session, and the extension itself decides
+        // whether to register anything: with no endpoint in its environment it returns without
+        // registering a tool, so a runtime without a document endpoint mounts nothing harmful.
+        join(repositoryRoot, "agents", "super-pi-documents", "index.ts"),
     ];
     return paths.filter((path) => existsSync(path));
 }
+/** Skills shipped by Super Pi itself. Paths are explicit so installed and development layouts agree. */
+export function superPiSkillPaths(repositoryRoot) {
+    const paths = [join(repositoryRoot, "skills", "presentation")];
+    return paths.filter((path) => existsSync(join(path, "SKILL.md")));
+}

package/dist/server/presentations/schema.d.ts

@@ -0,0 +1,120 @@
+/** Versioned, renderer-independent contract for structured presentation tools. */
+export declare const PRESENTATION_SPEC_VERSION: 1;
+export declare const PRESENTATION_LIMITS: {
+    readonly maxSlides: 200;
+    readonly maxElementsPerSlide: 500;
+    readonly maxTextCharacters: 100000;
+    readonly maxTableCells: 10000;
+    readonly maxChartPoints: 20000;
+};
+export type PresentationSpec = {
+    version: typeof PRESENTATION_SPEC_VERSION;
+    metadata?: {
+        title?: string;
+        subject?: string;
+        author?: string;
+        company?: string;
+        language?: string;
+    };
+    canvas: {
+        width: number;
+        height: number;
+    };
+    theme?: PresentationTheme;
+    slides: PresentationSlide[];
+};
+export type PresentationTheme = {
+    colors?: Record<string, string>;
+    fonts?: {
+        heading?: string;
+        body?: string;
+        mono?: string;
+    };
+};
+export type PresentationSlide = {
+    id: string;
+    title?: string;
+    notes?: string;
+    background?: string;
+    elements: PresentationElement[];
+};
+type Frame = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type BaseElement = Frame & {
+    id: string;
+    altText?: string;
+    name?: string;
+    hidden?: boolean;
+    rotation?: number;
+};
+export type TextElement = BaseElement & {
+    type: "text";
+    text: string;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    link?: string;
+};
+export type ShapeElement = BaseElement & {
+    type: "shape";
+    shape: "rectangle" | "roundRectangle" | "ellipse" | "triangle" | "chevron";
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+};
+export type LineElement = BaseElement & {
+    type: "line";
+    stroke?: string;
+    strokeWidth?: number;
+    dash?: "solid" | "dash" | "dot";
+    beginArrow?: boolean;
+    endArrow?: boolean;
+};
+export type ImageElement = BaseElement & {
+    type: "image";
+    source: string;
+    fit?: "contain" | "cover" | "stretch";
+    link?: string;
+};
+export type TableElement = BaseElement & {
+    type: "table";
+    rows: Array<Array<string | number | boolean | null>>;
+    headerRows?: number;
+};
+export type ChartElement = BaseElement & {
+    type: "chart";
+    chart: "bar" | "column" | "line" | "area" | "pie" | "doughnut" | "scatter";
+    categories?: string[];
+    series: Array<{
+        name: string;
+        values: Array<number | null>;
+        xValues?: Array<number | null>;
+    }>;
+    showLegend?: boolean;
+    showValues?: boolean;
+};
+export type PresentationElement = TextElement | ShapeElement | LineElement | ImageElement | TableElement | ChartElement;
+export type PresentationDiagnostic = {
+    code: "invalid_type" | "invalid_value" | "unsupported_version" | "duplicate_id" | "limit_exceeded" | "out_of_bounds";
+    severity: "error" | "warning";
+    path: string;
+    message: string;
+};
+export type PresentationValidationResult = {
+    valid: true;
+    spec: PresentationSpec;
+    diagnostics: PresentationDiagnostic[];
+} | {
+    valid: false;
+    diagnostics: PresentationDiagnostic[];
+};
+export declare function validatePresentationSpec(input: unknown): PresentationValidationResult;
+export {};

package/dist/server/presentations/schema.js

@@ -0,0 +1,128 @@
+/** Versioned, renderer-independent contract for structured presentation tools. */
+export const PRESENTATION_SPEC_VERSION = 1;
+export const PRESENTATION_LIMITS = {
+    maxSlides: 200,
+    maxElementsPerSlide: 500,
+    maxTextCharacters: 100_000,
+    maxTableCells: 10_000,
+    maxChartPoints: 20_000,
+};
+const ELEMENT_TYPES = new Set(["text", "shape", "line", "image", "table", "chart"]);
+const ID_PATTERN = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+export function validatePresentationSpec(input) {
+    const diagnostics = [];
+    const error = (code, path, message) => diagnostics.push({ code, severity: "error", path, message });
+    if (!isObject(input)) {
+        error("invalid_type", "$", "Presentation spec must be an object.");
+        return { valid: false, diagnostics };
+    }
+    if (input.version !== PRESENTATION_SPEC_VERSION) {
+        error("unsupported_version", "$.version", `Only presentation spec version ${PRESENTATION_SPEC_VERSION} is supported.`);
+    }
+    const canvas = input.canvas;
+    if (!isObject(canvas))
+        error("invalid_type", "$.canvas", "Canvas must be an object.");
+    else {
+        positiveNumber(canvas.width, "$.canvas.width", error);
+        positiveNumber(canvas.height, "$.canvas.height", error);
+    }
+    if (!Array.isArray(input.slides)) {
+        error("invalid_type", "$.slides", "Slides must be an array.");
+    }
+    else {
+        if (input.slides.length > PRESENTATION_LIMITS.maxSlides) {
+            error("limit_exceeded", "$.slides", `A deck may contain at most ${PRESENTATION_LIMITS.maxSlides} slides.`);
+        }
+        const ids = new Set();
+        input.slides.forEach((slide, slideIndex) => validateSlide(slide, slideIndex, canvas, ids, error));
+    }
+    if (input.theme !== undefined)
+        validateTheme(input.theme, error);
+    return diagnostics.some((item) => item.severity === "error")
+        ? { valid: false, diagnostics }
+        : { valid: true, spec: input, diagnostics };
+}
+function validateSlide(slide, index, canvas, ids, error) {
+    const path = `$.slides[${index}]`;
+    if (!isObject(slide))
+        return error("invalid_type", path, "Slide must be an object.");
+    validateId(slide.id, `${path}.id`, ids, error);
+    if (!Array.isArray(slide.elements))
+        return error("invalid_type", `${path}.elements`, "Elements must be an array.");
+    if (slide.elements.length > PRESENTATION_LIMITS.maxElementsPerSlide) {
+        error("limit_exceeded", `${path}.elements`, `A slide may contain at most ${PRESENTATION_LIMITS.maxElementsPerSlide} elements.`);
+    }
+    slide.elements.forEach((element, elementIndex) => validateElement(element, `${path}.elements[${elementIndex}]`, canvas, ids, error));
+}
+function validateElement(element, path, canvas, ids, error) {
+    if (!isObject(element))
+        return error("invalid_type", path, "Element must be an object.");
+    validateId(element.id, `${path}.id`, ids, error);
+    if (typeof element.type !== "string" || !ELEMENT_TYPES.has(element.type)) {
+        error("invalid_value", `${path}.type`, "Element type is not supported.");
+        return;
+    }
+    for (const key of ["x", "y", "width", "height"])
+        positiveNumber(element[key], `${path}.${key}`, error, key === "x" || key === "y");
+    if (isObject(canvas) && finite(element.x) && finite(element.y) && finite(element.width) && finite(element.height)
+        && finite(canvas.width) && finite(canvas.height)
+        && (element.x < 0 || element.y < 0 || element.x + element.width > canvas.width || element.y + element.height > canvas.height)) {
+        error("out_of_bounds", path, "Element frame must fit within the canvas.");
+    }
+    if (element.type === "text") {
+        if (typeof element.text !== "string")
+            error("invalid_type", `${path}.text`, "Text must be a string.");
+        else if (element.text.length > PRESENTATION_LIMITS.maxTextCharacters)
+            error("limit_exceeded", `${path}.text`, "Text is too long.");
+    }
+    else if (element.type === "image") {
+        if (typeof element.source !== "string" || !element.source.trim())
+            error("invalid_value", `${path}.source`, "Image source is required.");
+        if (!element.altText)
+            error("invalid_value", `${path}.altText`, "Images require alt text.");
+    }
+    else if (element.type === "table") {
+        if (!Array.isArray(element.rows))
+            error("invalid_type", `${path}.rows`, "Table rows must be an array.");
+        else if (element.rows.reduce((sum, row) => sum + (Array.isArray(row) ? row.length : 0), 0) > PRESENTATION_LIMITS.maxTableCells)
+            error("limit_exceeded", `${path}.rows`, "Table contains too many cells.");
+    }
+    else if (element.type === "chart")
+        validateChart(element, path, error);
+}
+function validateChart(chart, path, error) {
+    if (!Array.isArray(chart.series) || chart.series.length === 0)
+        return error("invalid_value", `${path}.series`, "Chart requires at least one series.");
+    let points = 0;
+    for (const [index, series] of chart.series.entries()) {
+        if (!isObject(series) || typeof series.name !== "string" || !Array.isArray(series.values)) {
+            error("invalid_type", `${path}.series[${index}]`, "Series requires a name and numeric values.");
+            continue;
+        }
+        if (series.values.some((value) => value !== null && !finite(value)))
+            error("invalid_value", `${path}.series[${index}].values`, "Chart values must be finite numbers or null.");
+        points += series.values.length;
+    }
+    if (points > PRESENTATION_LIMITS.maxChartPoints)
+        error("limit_exceeded", `${path}.series`, "Chart contains too many data points.");
+}
+function validateTheme(theme, error) {
+    if (!isObject(theme))
+        return error("invalid_type", "$.theme", "Theme must be an object.");
+    if (theme.colors !== undefined && (!isObject(theme.colors) || Object.values(theme.colors).some((value) => typeof value !== "string"))) {
+        error("invalid_type", "$.theme.colors", "Theme colors must map token names to color strings.");
+    }
+}
+function validateId(value, path, ids, error) {
+    if (typeof value !== "string" || !ID_PATTERN.test(value))
+        return error("invalid_value", path, "ID must start with a letter and contain only letters, digits, dot, underscore, or hyphen.");
+    if (ids.has(value))
+        error("duplicate_id", path, `ID '${value}' is already used in this deck.`);
+    ids.add(value);
+}
+function positiveNumber(value, path, error, allowZero = false) {
+    if (!finite(value) || (allowZero ? value < 0 : value <= 0))
+        error("invalid_value", path, allowZero ? "Value must be a non-negative finite number." : "Value must be a positive finite number.");
+}
+function finite(value) { return typeof value === "number" && Number.isFinite(value); }
+function isObject(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/dist/server/runtime.d.ts

@@ -512,6 +512,11 @@ export declare const catalogKey: (selection?: ModelSelection) => string;
  * warning on a path that is genuinely optional rather than a startup crash on a build that skipped it.
  */
 export declare function taskExtensionPath(from?: string): string;
+/**
+ * The document extension's file, resolved the same way the task extension's is: two `..` segments
+ * from `import.meta.dirname` reach the repository root both after `tsc -b` and under `tsx watch`.
+ */
+export declare function documentExtensionPath(from?: string): string;
 export declare class PiRpcRuntime implements AgentRuntime {
     private readonly sessionDir;
     /**
@@ -635,6 +640,8 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private modelEpoch;
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     private warnedMissingExtension;
+    /** Latches the "the document extension is missing" warning, for the same reason. */
+    private warnedMissingDocumentExtension;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
     private warnedMissingSdk;
     /**
@@ -701,6 +708,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
         workflowEndpoint?: string;
         questionEndpoint?: string;
         toolsEndpoint?: string;
+        documentsEndpoint?: string;
         uploadsDir?: string;
         sessionFactory?: PiSessionFactory;
         sessionMode?: "sdk" | "oneshot";
@@ -784,6 +792,18 @@ export declare class PiRpcRuntime implements AgentRuntime {
      *   knowing and worth not repeating on every keystroke.
      */
     private taskExtensionArgs;
+    /**
+     * The document extension's spawn argument.
+     *
+     * IT IS MOUNTED UNCONDITIONALLY, unlike the knowledge extension. The knowledge extension is only
+     * worth mounting when the workspace HAS documents, because its tool returns nothing otherwise; the
+     * document tools are about the files in the workspace, and a workspace with no PDF in it is exactly
+     * the workspace where an agent might be asked to WRITE one.
+     *
+     * The endpoint is the gate: without it the extension returns without registering anything, so a
+     * runtime with no document endpoint mounts nothing rather than a tool whose every call fails.
+     */
+    private documentExtensionArgs;
     /**
      * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
      * written out on both sides rather than imported.
@@ -906,7 +926,33 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * because `toolFlags` treats an explicit false as outranking a host extra.
      */
     private extensionToolNames;
+    /**
+     * A TURN, WITH THE REASONING TAKEN OUT OF THE ANSWER.
+     *
+     * This is the ONE place every turn passes through, whichever path it runs on - the persistent
+     * session or a one-shot process - so it is where the model's own text is read once and read
+     * properly.
+     *
+     * WHAT IT DOES. A model that has no reasoning channel answers in one stream of text and marks its
+     * thinking up inside it with `<think>…</think>`. Pi's adapter passes that through as ordinary
+     * text, because Pi only knows the four reasoning FIELDS a provider can use and a tag is not one
+     * of them. Left alone, the reasoning would be drawn as part of the answer, unlabelled, with the
+     * tags in it.
+     *
+     * WHY IT IS HERE AND NOT IN THE USER'S `models.json`. The alternative is to tell every reader to
+     * go and set a vendor-specific switch in a file Super Pi owns but Pi reads. A user who never
+     * hears of it sees a broken transcript and has no way to find out why. Super Pi reads the tags
+     * itself, for every provider, so the transcript reads the same way whichever endpoint is behind
+     * it - and the reasoning goes where the reasoning goes: into a thinking block, over the same
+     * channel Pi's own reasoning events use, so the fold, the live indicator and the persisted
+     * transcript all work without knowing where the reasoning came from.
+     */
     answer(input: AnswerInput): AsyncIterable<string>;
+    /**
+     * THE TURN ITSELF, on whichever path it runs. See `answer`, which is the seam the reasoning is
+     * separated at.
+     */
+    private answerTurn;
     /**
      * The one-shot path: a fresh child process for a single turn.
      *