@xingjisoft/neutrino 0.6.0 → 0.7.0

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>;

package/dist/plugins/cli.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configurePlugin, installPlugin, listPlugins, removePlugin, rollbackPlugin, selectProvider } from "./manager.js";
+import { PluginHost } from "./host.js";
+import { packPlugin } from "./package.js";
+export async function runPluginCLI(args) {
+    let profile = "standard", cwd, trustNative = false;
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--profile") {
+            const p = args[++i];
+            if (p !== "standard" && p !== "pro")
+                throw new Error("Profile must be standard or pro");
+            profile = p;
+        }
+        else if (args[i] === "--workspace") {
+            const value = args[++i];
+            if (!value || value.startsWith("--"))
+                throw new Error("--workspace requires a directory");
+            cwd = path.resolve(value);
+        }
+        else if (args[i] === "--trust-native")
+            trustNative = true;
+        else
+            values.push(args[i]);
+    }
+    const [action, id, extra] = values;
+    const print = (v) => process.stdout.write((typeof v === "string" ? v : JSON.stringify(v, null, 2)) + "\n");
+    if (!action || action === "help" || action === "--help") {
+        print(`Plugin API v1\n\nneutrino plugin list [--profile standard|pro] [--workspace <path>]\nneutrino plugin inspect <id>\nneutrino plugin install <local-directory-or-bundle>\nneutrino plugin enable <id> [--trust-native]\nneutrino plugin disable <id>\nneutrino plugin config <id> '<JSON object>'\nneutrino plugin update <id>\nneutrino plugin rollback <id>\nneutrino plugin remove <id>\nneutrino plugin provider <slot> <plugin-id/contribution-id|default>\nneutrino plugin doctor\nneutrino plugin create <directory>\nneutrino plugin pack <directory> <output.neutrino-plugin>\nneutrino --safe-mode --no-web\n\nInstall is separate from enable. Native plugins execute unrestricted local code.\n`);
+        return;
+    }
+    if (action === "list") {
+        print(listPlugins(profile, cwd));
+        return;
+    }
+    if (action === "pack") {
+        if (!id || !extra)
+            throw new Error("Usage: neutrino plugin pack <directory> <output.neutrino-plugin>");
+        print(packPlugin(path.resolve(id), path.resolve(extra)));
+        return;
+    }
+    if (action === "install") {
+        if (!id)
+            throw new Error("Missing source directory");
+        print(installPlugin(path.resolve(id)));
+        return;
+    }
+    if (action === "enable" || action === "disable") {
+        configurePlugin(id, { enabled: action === "enable", trustNative }, profile, cwd);
+        print(`${id}: ${action}d`);
+        return;
+    }
+    if (action === "config") {
+        configurePlugin(id, { config: JSON.parse(extra ?? "{}") }, profile, cwd);
+        print("Configuration saved");
+        return;
+    }
+    if (action === "remove") {
+        removePlugin(id);
+        print("Plugin removed; immutable files retained for running tasks");
+        return;
+    }
+    if (action === "rollback") {
+        rollbackPlugin(id);
+        print("Previous package revision restored");
+        return;
+    }
+    if (action === "provider") {
+        selectProvider(id, extra === "default" ? "" : extra, profile);
+        print("Provider selected");
+        return;
+    }
+    if (action === "update" || action === "inspect") {
+        const p = listPlugins(profile, cwd).plugins.find(p => p.manifest.id === id);
+        if (!p)
+            throw new Error("Unknown plugin");
+        print(action === "update" ? installPlugin(p.source) : p);
+        return;
+    }
+    if (action === "doctor") {
+        const host = await PluginHost.create({ scope: { profile, cwd: cwd ?? process.cwd(), role: "main" } });
+        try {
+            print({ plugins: host.pins, tools: host.definitions(), commands: [...host.commands.keys()], errors: host.diagnostics });
+            if (host.diagnostics.length)
+                process.exitCode = 1;
+        }
+        finally {
+            await host.dispose();
+        }
+        return;
+    }
+    if (action === "create") {
+        if (!id)
+            throw new Error("Missing target directory");
+        const dir = path.resolve(id);
+        if (fs.existsSync(dir))
+            throw new Error("Target directory already exists");
+        const source = fileURLToPath(new URL("../../examples/plugins/function-tools/", import.meta.url));
+        fs.cpSync(source, dir, { recursive: true });
+        print(`Created ${dir}. Edit neutrino.plugin.json and agent.js, then install the directory.`);
+        return;
+    }
+    throw new Error(`Unknown plugin command ${action}`);
+}

package/dist/plugins/host.d.ts

@@ -0,0 +1,121 @@
+import type { ToolDefinition } from "../llm/tools.js";
+import type { Effect, EventName, InvocationContext, JsonObject, PluginPin, PluginRecord, PluginScope, Profile, PromptContribution, UIContribution } from "./types.js";
+interface Registered {
+    kind: string;
+    handler: string;
+    [key: string]: unknown;
+}
+interface Owned {
+    record: PluginRecord;
+    worker?: PluginWorker;
+}
+interface Tool extends Owned {
+    definition: ToolDefinition;
+    handler: string;
+    effects: Effect[];
+    roles?: string[];
+}
+interface Command extends Owned {
+    handler: string;
+    name: string;
+    description: string;
+    parameters: JsonObject;
+    effects: Effect[];
+}
+export interface OwnedUI extends UIContribution {
+    pluginId: string;
+    key: string;
+    entry?: string;
+    permissions: string[];
+}
+export interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    text: string;
+    pluginId: string;
+}
+interface HostOptions {
+    scope: PluginScope;
+    context?(): InvocationContext;
+    broker?(name: string, args: JsonObject, signal?: AbortSignal): Promise<unknown>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    allowNative?(): boolean;
+}
+declare class PluginWorker {
+    private record;
+    private timeout;
+    private log;
+    private child;
+    private readyResolve;
+    private readyReject;
+    readonly ready: Promise<Registered[]>;
+    private current?;
+    private sequence;
+    private queue;
+    private operationQueue;
+    private closed;
+    private initTimer;
+    constructor(record: PluginRecord, scope: PluginScope, timeout: number, log: (message: string) => void);
+    private resetTimer;
+    private receive;
+    private reply;
+    private fail;
+    invoke(handler: string, value: unknown, context: InvocationContext, operation: (op: string, args: JsonObject, signal: AbortSignal) => Promise<unknown>): Promise<unknown>;
+    dispose(): Promise<void>;
+}
+/** One frozen plugin composition per turn, shared by both frontends and all child scopes. */
+export declare class PluginHost {
+    private options;
+    readonly providers: Record<string, string>;
+    readonly tools: Map<string, Tool>;
+    readonly commands: Map<string, Command>;
+    readonly ui: OwnedUI[];
+    readonly skills: Skill[];
+    readonly pins: PluginPin[];
+    readonly diagnostics: string[];
+    readonly prompts: Array<PromptContribution & {
+        pluginId: string;
+    }>;
+    readonly theme: Record<string, string>;
+    private workers;
+    private hooks;
+    private events;
+    private disposed;
+    get profile(): Profile;
+    private constructor();
+    static create(options: HostOptions): Promise<PluginHost>;
+    private report;
+    private permission;
+    private declarations;
+    private addSkill;
+    private resource;
+    private addPrompt;
+    private addUI;
+    private register;
+    private remove;
+    definitions(role?: string): ToolDefinition[];
+    toolPolicy(name: string): {
+        effects: Effect[];
+        native: boolean;
+        roles?: string[];
+    } | undefined;
+    private context;
+    private invoke;
+    execute(name: string, args: JsonObject): Promise<string>;
+    runCommand(name: string, args?: JsonObject, stack?: string[]): Promise<unknown>;
+    guardTool(name: string, args: JsonObject): Promise<void>;
+    requestSuffix(value: JsonObject): Promise<string>;
+    emit(name: EventName, value: JsonObject): Promise<void>;
+    composePrompt(base: string, role: string): {
+        text: string;
+        sections: Array<{
+            id: string;
+            text: string;
+        }>;
+    };
+    effectiveUI(platform: "web" | "tui"): OwnedUI[];
+    dispose(): Promise<void>;
+}
+export {};