@xingjisoft/neutrino 0.6.2 → 0.7.0

package/dist/llm/subagent.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Sub-agents.
+ *
+ * A sub-agent is an agent loop inside an agent loop: the parent hands one
+ * self-contained task to a fresh conversation, the child works with the same
+ * tools in the same directory, and only its final report travels back. Its
+ * intermediate messages are dropped on purpose — that isolation is the point: a
+ * survey that reads thirty files must not fill the parent's context with thirty
+ * files.
+ *
+ * That dropped transcript is why the loop keeps its own evidence. The last
+ * round is sent without tools, so a child that has spent its budget can only
+ * write; and a child that still runs out hands back what it actually ran and
+ * read, instead of the half-sentence it happened to say last.
+ *
+ * This module owns the child loop and nothing else. Everything that touches the
+ * app — which model, how a call is approved, where progress is shown, how tokens
+ * are counted — is passed in, so the terminal session and the browser session
+ * run the exact same sub-agent.
+ */
+import type { LLMClient, UsageInfo } from "./client.js";
+import type { RetryNotice } from "./retry.js";
+import type { ApprovalDecision } from "./approval.js";
+import type { ToolDefinition } from "./tools.js";
+import { TaskRuntime, type AgentResult, type TaskScope } from "./runtime.js";
+/** One message of the child's private transcript. */
+export interface SubAgentMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string;
+    /** Thinking text echoed back on an assistant tool-call message. */
+    reasoning_content?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+    anthropic_content?: unknown[];
+}
+export interface SubAgentOptions {
+    runtime?: TaskRuntime;
+    scope?: TaskScope;
+    readOnly?: boolean;
+    writePaths?: readonly string[];
+    signal?: AbortSignal;
+    /** A fresh client per round; the loop owns usage and retries. */
+    createClient(): LLMClient;
+    /** The sub-agent's system prompt (see `loadSubAgentPrompt`). */
+    system: string;
+    /** The delegated task, already flattened into a standalone brief. */
+    task: string;
+    tools: ToolDefinition[];
+    /** The same approval gate the parent turn uses. */
+    approve(name: string, args: Record<string, unknown>): Promise<ApprovalDecision>;
+    /** Run one approved call. */
+    execute(name: string, args: Record<string, unknown>): Promise<string>;
+    /** What the child is doing right now, for the parent's status line. */
+    onProgress?(label: string): void;
+    /** Tokens spent by the child, added to the parent's conversation counters. */
+    onUsage?(usage: UsageInfo): void;
+    /** A dropped request is being retried, so the parent can explain the silence. */
+    onRetry?(notice: RetryNotice): void;
+    /** True once the parent turn was paused, superseded or cleared. */
+    cancelled?(): boolean;
+    maxRounds?: number;
+    /** Pro role capacity; ordinary sub-agents retain the historical behaviour. */
+    contextWindow?: number;
+}
+export interface SubAgentRun extends AgentResult {
+    /** The child's final message: the only thing the parent receives. */
+    report: string;
+    /** The parent turn ended before the child finished. */
+    aborted: boolean;
+    /** The child used up its rounds without finishing. */
+    exhausted: boolean;
+    rounds: number;
+    calls: number;
+}
+/**
+ * Rounds one sub-agent may take, the last of which has no tools. Enough for real
+ * work, few enough that a runaway child cannot cost a fortune.
+ */
+export declare const SUBAGENT_MAX_ROUNDS = 16;
+/** A wrap-up round is only worth anything with at least one round of work before it. */
+export declare const SUBAGENT_MIN_ROUNDS = 2;
+/** A report is evidence for the parent, not a transcript of the child. */
+export declare const SUBAGENT_MAX_REPORT = 8000;
+/** The configured round budget, reconciled with what the loop can honour. */
+export declare function subAgentRounds(configured: unknown): number;
+/** The task brief handed to the child: where it works, what it has, what to do. */
+export declare function buildSubAgentTask(input: {
+    task: string;
+    context?: string;
+    cwd?: string;
+    rounds?: number;
+}): string;
+/**
+ * Run one sub-agent to its report.
+ *
+ * The child sees only its own task, its own tool results and the parent's
+ * approval decisions. Nothing it says reaches the parent except the last
+ * message, which is why the sub-agent prompt insists that the report be
+ * complete on its own.
+ */
+export declare const FINISH_TASK_TOOL = "finish_task";
+export declare const FINISH_TASK_DEFINITION: ToolDefinition;
+export declare function runSubAgent(options: SubAgentOptions): Promise<SubAgentRun>;
+/** The tool result the parent sees: the report, or why there is none. */
+export declare function formatSubAgentResult(run: SubAgentRun): string;

package/dist/llm/subagent.js

@@ -1,3 +1,4 @@
+import { pluginPrompt } from "../plugins/session.js";
 import { describeError } from "./retry.js";
 import { prepareContext, outputAllowance } from "./context.js";
 import { currentTask, TaskRuntime, TaskControlError, linkSignals } from "./runtime.js";
@@ -156,10 +157,11 @@ export async function runSubAgent(options) {
         runId = currentTask()?.runId ?? runId;
         scopeSignal = currentTask()?.signal;
         const messages = [
-            { role: "system", content: `${options.system}\n\n${runtime.instructions()}` },
+            { role: "system", content: `${pluginPrompt(options.system, currentTask()?.role ?? "subagent")}\n\n${runtime.instructions()}` },
             { role: "user", content: options.task },
         ];
-        const tools = runtime.availableTools([...options.tools.filter(tool => tool.function.name !== FINISH_TASK_TOOL), FINISH_TASK_DEFINITION]);
+        const tools = runtime.availableTools([...new Map([...options.tools.filter(tool => tool.function.name !== FINISH_TASK_TOOL),
+                ...(runtime.plugins?.definitions(currentTask()?.role) ?? []), FINISH_TASK_DEFINITION].map(tool => [tool.function.name, tool])).values()]);
         const names = new Set(tools.map(tool => tool.function.name));
         let lastPromptTokens = 0;
         let emptyReplies = 0;

package/dist/llm/tools.d.ts

@@ -0,0 +1,20 @@
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** The tool a parent agent calls to hand work to a sub-agent. */
+export declare const DELEGATE_TOOL = "delegate";
+/**
+ * The toolset a sub-agent runs with: the same tools as its parent, minus
+ * `delegate` - one level of delegation, never a tree of agents that nobody can
+ * follow (or stop). The sub-agent prompt says so as well; removing the tool
+ * makes it true.
+ */
+export declare function getSubAgentToolDefinitions(): ToolDefinition[];
+/** Every tool a top-level agent can call: the base set plus delegation. */
+export declare function getToolDefinitions(): ToolDefinition[];
+export declare function executeTool(name: string, args: Record<string, unknown>, cwd?: string, signal?: AbortSignal): Promise<string>;

package/dist/llm/tools.js

@@ -142,6 +142,7 @@ export function getSubAgentToolDefinitions() {
                 },
             },
         },
+        ...(currentTask()?.runtime.plugins?.definitions() ?? []),
     ];
 }
 /** Every tool a top-level agent can call: the base set plus delegation. */
@@ -180,7 +181,9 @@ export async function executeTool(name, args, cwd = process.cwd(), signal) {
                 result = listFiles(String(args.path ?? ""), base);
                 break;
             default:
-                result = `[Error: unknown tool '${name}']`;
+                result = currentTask()?.runtime.plugins?.tools.has(name)
+                    ? await currentTask().runtime.plugins.execute(name, args)
+                    : `[Error: unknown tool '${name}']`;
         }
     }
     catch (e) {

package/dist/llm/workspace.d.ts

@@ -0,0 +1,6 @@
+/** Recognize an explicit confinement instruction, never permission inferred from tool output. */
+export declare function requestsWorkspaceOnly(request: string): boolean;
+/** Inspect literal shell/program paths, including quoted inline programs and heredoc bodies. */
+export declare function commandWorkspacePaths(command: string, cwd?: string, depth?: number): string[];
+/** Preflight for declared workspace confinement. Arbitrary programs still require the normal approval gate. */
+export declare function workspaceViolation(name: string, args: Record<string, unknown>, cwd: string): string | undefined;

package/dist/llm/workspace.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import ts from "typescript";
+/** Recognize an explicit confinement instruction, never permission inferred from tool output. */
+export function requestsWorkspaceOnly(request) {
+    const english = /\b(?:work|operate)\s+only\s+(?:inside|within)\s+(?:(?:this|the|current|temporary|project|working)\s+)*(?:fixture|workspace|directory)\b/ig;
+    for (const match of request.matchAll(english)) {
+        if (!/(?:do\s+not|don't|never)\s*$/i.test(request.slice(Math.max(0, match.index - 12), match.index)))
+            return true;
+    }
+    return /(?:仅|只)(?:允许|能|可以)?在(?:当前|本|这个)?(?:项目|工作|临时)?(?:目录|工作区|文件夹)(?:内|中)(?:工作|操作|读写|执行|创建|修改)/.test(request);
+}
+function canonical(input) {
+    let cursor = path.resolve(input);
+    const tail = [];
+    // lstat sees a dangling symlink too; realpath will reject it instead of treating it as a new directory.
+    while (!fs.existsSync(cursor)) {
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new Error("Unresolved symbolic link in workspace path");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        tail.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+    const resolved = path.join(fs.realpathSync(cursor), ...tail);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function confined(target, cwd) {
+    if (process.platform !== "win32" && /^[A-Za-z]:[\\/]/.test(target))
+        return false;
+    const expanded = target === "~" || /^~[\\/]/.test(target) ? path.join(os.homedir(), target.slice(1)) : target;
+    const relative = path.relative(canonical(cwd), canonical(path.resolve(cwd, expanded)));
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+const pathLike = (value) => /^(?:\/(?!\/|\*)|[A-Za-z]:[\\/]|\.\.(?:[\\/]|$)|\.[\\/]|~(?:[\\/]|$))/.test(value) ||
+    (!/[\s:]/.test(value) && /^[\w.@+-]+(?:[\\/][\w.@+-]+)*$/.test(value));
+const FILE_CALLS = new Set(["readFile", "readFileSync", "writeFile", "writeFileSync", "appendFile", "appendFileSync",
+    "open", "openSync", "createReadStream", "createWriteStream", "access", "accessSync", "stat", "statSync", "lstat", "lstatSync",
+    "realpath", "realpathSync", "readdir", "readdirSync", "mkdir", "mkdirSync", "mkdtemp", "mkdtempSync", "existsSync",
+    "unlink", "unlinkSync", "rm", "rmSync", "rmdir", "rmdirSync", "rename", "renameSync", "copyFile", "copyFileSync", "cp", "cpSync"]);
+function programPaths(program, cwd, filename) {
+    const paths = [];
+    const initial = { values: new Map([["__dirname", filename ? path.dirname(filename) : cwd], ["__filename", filename ?? path.join(cwd, "[eval]")]]), arrays: new Map(), functions: new Map(), aliases: new Map() };
+    const fork = (env) => ({ values: new Map(env.values), arrays: new Map(env.arrays), functions: new Map(env.functions), aliases: new Map(env.aliases) });
+    const name = (node) => ts.isIdentifier(node) ? node.text : ts.isPropertyAccessExpression(node) ? node.name.text : undefined;
+    const value = (node, env) => {
+        if (!node)
+            return undefined;
+        if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+            return node.text;
+        if (ts.isIdentifier(node))
+            return env.values.get(node.text);
+        if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node))
+            return value(node.expression, env);
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+            const left = value(node.left, env), right = value(node.right, env);
+            return left !== undefined && right !== undefined ? left + right : undefined;
+        }
+        if (ts.isTemplateExpression(node)) {
+            let text = node.head.text;
+            for (const span of node.templateSpans) {
+                const part = value(span.expression, env);
+                if (part === undefined)
+                    return undefined;
+                text += part + span.literal.text;
+            }
+            return text;
+        }
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const receiver = node.expression.expression.getText(), method = node.expression.name.text;
+            if (receiver === "process" && method === "cwd")
+                return cwd;
+            if (receiver === "os" && method === "tmpdir")
+                return os.tmpdir();
+            if (receiver === "os" && method === "homedir")
+                return os.homedir();
+            if (receiver === "path" && ["join", "resolve", "normalize", "dirname", "basename"].includes(method)) {
+                const parts = node.arguments.map(arg => value(arg, env));
+                if (parts.some(part => part === undefined))
+                    return undefined;
+                const strings = parts;
+                if (method === "join")
+                    return path.join(...strings);
+                if (method === "resolve")
+                    return path.resolve(cwd, ...strings);
+                if (method === "normalize")
+                    return path.normalize(strings[0] ?? "");
+                if (method === "dirname")
+                    return path.dirname(strings[0] ?? "");
+                return path.basename(strings[0] ?? "");
+            }
+        }
+        return undefined;
+    };
+    const array = (node, env) => {
+        if (!node)
+            return undefined;
+        if (ts.isIdentifier(node))
+            return env.arrays.get(node.text);
+        if (ts.isArrayLiteralExpression(node) && node.elements.length <= 32) {
+            const entries = node.elements.map(entry => value(entry, env));
+            if (entries.every((entry) => entry !== undefined))
+                return entries;
+        }
+        return undefined;
+    };
+    const add = (target) => { if (target !== undefined && target !== "/dev/null")
+        paths.push(target); };
+    const active = new Set();
+    const visit = (node, env, depth = 0) => {
+        if (depth > 12)
+            return;
+        if (ts.isBlock(node)) {
+            const local = fork(env);
+            for (const statement of node.statements)
+                visit(statement, local, depth + 1);
+            return;
+        }
+        if (ts.isForOfStatement(node) && ts.isVariableDeclarationList(node.initializer)) {
+            const binding = node.initializer.declarations[0]?.name, entries = array(node.expression, env);
+            if (binding && ts.isIdentifier(binding) && entries) {
+                for (const entry of entries) {
+                    const local = fork(env);
+                    local.values.set(binding.text, entry);
+                    visit(node.statement, local, depth + 1);
+                }
+                return;
+            }
+        }
+        if (ts.isFunctionDeclaration(node) && node.name)
+            env.functions.set(node.name.text, node);
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            const bound = value(node.initializer, env);
+            if (bound !== undefined)
+                env.values.set(node.name.text, bound);
+            else
+                env.values.delete(node.name.text);
+            const entries = array(node.initializer, env);
+            if (entries)
+                env.arrays.set(node.name.text, entries);
+            else
+                env.arrays.delete(node.name.text);
+            if (node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)))
+                env.functions.set(node.name.text, node.initializer);
+            else if (node.initializer && ts.isPropertyAccessExpression(node.initializer) && FILE_CALLS.has(node.initializer.name.text))
+                env.aliases.set(node.name.text, node.initializer.name.text);
+        }
+        if (ts.isCallExpression(node)) {
+            const called = name(node.expression), method = called ? env.aliases.get(called) ?? called : undefined;
+            if (method && FILE_CALLS.has(method)) {
+                add(value(node.arguments[0], env));
+                if (/^(?:rename|copyFile|cp)(?:Sync)?$/.test(method))
+                    add(value(node.arguments[1], env));
+            }
+            if (ts.isPropertyAccessExpression(node.expression) && ["forEach", "map", "reduce", "reduceRight"].includes(node.expression.name.text)) {
+                const entries = array(node.expression.expression, env), callback = node.arguments[0];
+                if (entries && callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback))) {
+                    const parameter = callback.parameters[/^reduce/.test(node.expression.name.text) ? 1 : 0]?.name;
+                    if (parameter && ts.isIdentifier(parameter))
+                        for (const entry of entries) {
+                            const local = fork(env);
+                            local.values.set(parameter.text, entry);
+                            visit(callback.body, local, depth + 1);
+                        }
+                }
+            }
+            const helper = called && ts.isIdentifier(node.expression) ? env.functions.get(called) : undefined;
+            if (helper?.body && !active.has(helper)) {
+                active.add(helper);
+                const local = fork(env);
+                helper.parameters.forEach((parameter, i) => {
+                    if (ts.isIdentifier(parameter.name)) {
+                        const bound = value(node.arguments[i], env);
+                        if (bound !== undefined)
+                            local.values.set(parameter.name.text, bound);
+                        else
+                            local.values.delete(parameter.name.text);
+                    }
+                });
+                visit(helper.body, local, depth + 1);
+                active.delete(helper);
+            }
+        }
+        if (ts.isFunctionLike(node)) {
+            const local = fork(env);
+            for (const parameter of node.parameters)
+                if (ts.isIdentifier(parameter.name))
+                    local.values.delete(parameter.name.text);
+            ts.forEachChild(node, child => visit(child, local, depth + 1));
+        }
+        else
+            ts.forEachChild(node, child => visit(child, env, depth));
+    };
+    visit(ts.createSourceFile(filename ?? "workspace-command.js", program, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS), initial);
+    return paths;
+}
+/** Inspect literal shell/program paths, including quoted inline programs and heredoc bodies. */
+export function commandWorkspacePaths(command, cwd = process.cwd(), depth = 0) {
+    const candidates = [];
+    command = command.replace(/([^\n]*<<-?\s*['"]?(\w+)['"]?[^\n]*)\n([\s\S]*?)\n\2(?=\n|;|$)/g, (full, header, _end, body) => {
+        if (!/\bnode\b|\bcat\b[^\n]*\.(?:c?js|mjs)\b/.test(header))
+            return full;
+        candidates.push(...programPaths(body, cwd));
+        return header;
+    });
+    const tokens = command.matchAll(/"(?:\\[\s\S]|[^"\\])*"|'[^']*'|`(?:\\[\s\S]|[^`\\])*`|[^\s"'`;&|<>(){},\[\]]+/g);
+    for (const match of tokens) {
+        const token = match[0];
+        const quoted = /^["'`]/.test(token);
+        const value = quoted ? token.slice(1, -1).replace(/\\(["'`\\])/g, "$1") : token;
+        const segment = command.slice(0, match.index).split(/[;&|\n]/).at(-1) ?? "";
+        const presentation = /^\s*(?:echo|printf)\b/.test(segment) && !/[<>]/.test(segment);
+        const parts = quoted ? [value] : [value, ...(value.includes("=") ? [value.slice(value.indexOf("=") + 1)] : [])];
+        for (const part of parts) {
+            // /dev/null is the standard empty input/output sink, not project data.
+            if (part === "/dev/null")
+                continue;
+            if (!presentation && pathLike(part))
+                candidates.push(part);
+        }
+        if (quoted && /\bnode\b[^\n;&|]*\s--?(?:e|p|eval|print)\s*$/.test(command.slice(0, match.index)))
+            candidates.push(...programPaths(value, cwd));
+        else if (quoted && depth < 3 && (!presentation || /\$\(|`/.test(value)) && /[\n;(){}<>|&]|(?:read|write|require|import)/.test(value))
+            candidates.push(...commandWorkspacePaths(value, cwd, depth + 1));
+    }
+    return [...new Set(candidates)];
+}
+/** Preflight for declared workspace confinement. Arbitrary programs still require the normal approval gate. */
+export function workspaceViolation(name, args, cwd) {
+    const paths = ["write_file", "read_file", "list_files"].includes(name)
+        ? [typeof args.path === "string" && args.path.trim() ? args.path : "."]
+        : name === "run_command" ? commandWorkspacePaths(String(args.command ?? ""), cwd) : [];
+    if (name === "run_command") {
+        // A local Node helper can contain the same literal paths as an inline program.
+        const command = String(args.command ?? "");
+        for (const match of command.matchAll(/(?:^|[\s;&|])node\s+(?:--[\w=-]+\s+)*("[^"]+"|'[^']+'|[^\s;&|]+)/g)) {
+            const script = match[1].replace(/^["']|["']$/g, "");
+            if (script.startsWith("-") || !/\.(?:c?js|mjs)$/.test(script))
+                continue;
+            try {
+                if (!confined(script, cwd)) {
+                    paths.push(script);
+                    continue;
+                }
+                const file = path.resolve(cwd, script);
+                if (fs.existsSync(file) && fs.statSync(file).isFile())
+                    paths.push(...programPaths(fs.readFileSync(file, "utf8"), cwd, file));
+            }
+            catch {
+                paths.push(script);
+            }
+        }
+    }
+    for (const target of paths) {
+        try {
+            if (confined(target, cwd))
+                continue;
+        }
+        catch { /* Unresolved paths fail closed. */ }
+        return `Path ${JSON.stringify(target)} is outside the explicitly confined workspace ${JSON.stringify(cwd)}. Nothing ran. Use workspace-relative paths, including helper scripts, and correct only this call; do not replay completed operations.`;
+    }
+    return undefined;
+}

package/dist/markdown.d.ts

@@ -0,0 +1,58 @@
+import type { Buffer } from "./terminal/buffer.js";
+import { type Style } from "./colors.js";
+export interface Span {
+    text: string;
+    style: Style;
+}
+export interface Line {
+    spans: Span[];
+}
+export type TableAlign = "left" | "center" | "right";
+export type Block = {
+    type: "paragraph";
+    spans: Span[];
+} | {
+    type: "heading";
+    level: number;
+    spans: Span[];
+} | {
+    type: "listItem";
+    ordered: boolean;
+    number: number;
+    level: number;
+    spans: Span[];
+} | {
+    type: "code";
+    lang: string;
+    lines: string[];
+} | {
+    type: "quote";
+    spans: Span[];
+} | {
+    type: "rule";
+} | {
+    type: "table";
+    header: Span[][];
+    rows: Span[][][];
+    align: TableAlign[];
+} | {
+    type: "blank";
+};
+export declare function parseInline(text: string, base?: Style): Span[];
+export declare function parseMarkdown(text: string, base?: Style): Block[];
+/**
+ * Wrap spans into lines, optionally prefixing the first line and indenting
+ * continuation lines. Used for headings, list items and blockquotes.
+ */
+export declare function wrapSpans(spans: Span[], width: number, opts?: {
+    prefix?: Span[];
+    indent?: number;
+}): Line[];
+export declare function renderBlocks(blocks: Block[], width: number): Line[];
+/** Parse and render a markdown string into styled lines. */
+export declare function renderMarkdownText(text: string, width: number, base?: Style): Line[];
+/**
+ * Draw a sequence of styled spans onto the buffer, starting at (x, y),
+ * clipped to `maxWidth` columns.
+ */
+export declare function drawSpans(buf: Buffer, x: number, y: number, spans: Span[], maxWidth: number): void;

package/dist/migration.d.ts

@@ -0,0 +1,8 @@
+import { type AgentId } from "./agents.js";
+import { type Mode, type ModelSelection, type SessionData } from "./config.js";
+export declare class SessionMigrationError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Copy the readable conversation into a fresh native transcript, ready to resume. */
+export declare function migrateAgentSession(agent: AgentId, sourceId: string, cwd: string, selection: ModelSelection, mode?: Mode, proPreset?: string): SessionData;

package/dist/persistence.d.ts

@@ -0,0 +1,14 @@
+/** Bound how much streamed output a hard kill can lose, without writing per token. */
+export declare const CHECKPOINT_MS = 1000;
+export declare class SessionCheckpoint {
+    private readonly write;
+    private timer;
+    constructor(write: () => boolean);
+    register(): void;
+    /** A trailing checkpoint still runs if the provider stalls after one chunk. */
+    schedule(): void;
+    flush(): boolean;
+    dispose(): boolean;
+}
+/** No promises: exit handlers cannot wait for asynchronous disk writes. */
+export declare function flushSessionCheckpoints(): boolean;

package/dist/plugins/catalog.d.ts

@@ -0,0 +1,20 @@
+import type { OwnedUI } from "./host.js";
+import type { Profile } from "./types.js";
+/** Reading the UI catalogue must never activate backend code or start a worker. */
+export declare function pluginCatalog(profile?: Profile, cwd?: string): {
+    ui: OwnedUI[];
+    theme: Record<string, string>;
+    skills: {
+        id: string;
+        description: string;
+    }[];
+    prompts: {
+        id: string;
+        replace: boolean;
+    }[];
+    permissions: Record<string, string[]>;
+    entries: Record<string, string | undefined>;
+    providers: Record<string, string>;
+    errors: string[];
+    safeMode: boolean;
+};

package/dist/plugins/catalog.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import { pluginRecords, providerSelections, safeMode } from "./manager.js";
+import { safeFile } from "./validation.js";
+/** Reading the UI catalogue must never activate backend code or start a worker. */
+export function pluginCatalog(profile = "standard", cwd) {
+    const ui = [], theme = {}, skills = [], prompts = [];
+    const errors = [];
+    const permissions = {}, entries = {};
+    try {
+        for (const record of pluginRecords(profile, cwd)) {
+            const m = record.manifest;
+            if (record.error) {
+                errors.push(`${m.id}: ${record.error}`);
+                continue;
+            }
+            permissions[m.id] = m.permissions ?? [];
+            entries[m.id] = m.entries?.web;
+            if (m.permissions?.includes("ui.contribute")) {
+                for (const item of m.contributes?.ui ?? [])
+                    ui.push({ ...item, key: `${m.id}/${item.id}`, pluginId: m.id, entry: m.entries?.web, permissions: m.permissions ?? [] });
+                Object.assign(theme, m.contributes?.theme ?? {});
+            }
+            if (m.permissions?.includes("prompts.contribute")) {
+                for (const p of m.contributes?.prompts ?? [])
+                    prompts.push({ id: `${m.id}/${p.id}`, replace: p.replace === true });
+                for (const file of m.contributes?.skills ?? []) {
+                    const text = fs.readFileSync(safeFile(record.directory, file), "utf8").slice(0, 64_000);
+                    const name = /^name:\s*["']?([^\r\n"']+)/m.exec(text)?.[1]?.trim() ?? file.split("/").slice(-2, -1)[0];
+                    skills.push({ id: `${m.id}/${name}`, description: /^description:\s*["']?([^\r\n"']+)/m.exec(text)?.[1]?.trim() ?? String(name) });
+                }
+            }
+        }
+    }
+    catch (e) {
+        errors.push(e.message);
+    }
+    let providers = {};
+    try {
+        providers = providerSelections(profile);
+    }
+    catch (e) {
+        errors.push(e.message);
+    }
+    return { ui, theme, skills, prompts, permissions, entries, providers, errors, safeMode: safeMode() };
+}

package/dist/plugins/cli.d.ts

@@ -0,0 +1 @@
+export declare function runPluginCLI(args: string[]): Promise<void>;