@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/plugins/manager.js

@@ -0,0 +1,288 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { assert, defaults, ID, object, readManifest, safeFile, satisfies, validateValue } from "./validation.js";
+import { unpackPlugin } from "./package.js";
+export function pluginHome() { return process.env.NEUTRINO_PLUGIN_HOME || path.join(process.env.NEUTRINO_HOME || path.join(os.homedir(), ".neutrino"), "plugins"); }
+export function safeMode() { return process.env.NEUTRINO_SAFE_MODE === "1"; }
+function profileState() { return { plugins: {}, workspaces: {}, providers: {} }; }
+function readState() {
+    const file = path.join(pluginHome(), "state.json");
+    if (!fs.existsSync(file))
+        return { version: 1, revision: 0, packages: {}, profiles: { standard: profileState(), pro: profileState() } };
+    const s = JSON.parse(fs.readFileSync(file, "utf8"));
+    assert(s.version === 1 && object(s.packages) && object(s.profiles) && object(s.profiles.standard) && object(s.profiles.pro), "Invalid plugin state; use --safe-mode and restore state.json");
+    return s;
+}
+function transaction(change, expectedRevision) {
+    fs.mkdirSync(pluginHome(), { recursive: true, mode: 0o700 });
+    const lock = path.join(pluginHome(), ".lock");
+    try {
+        fs.mkdirSync(lock);
+    }
+    catch {
+        throw new Error("Plugin state is being changed by another process; retry after it completes");
+    }
+    const temporary = path.join(pluginHome(), `state.${randomUUID()}.tmp`);
+    try {
+        const state = readState();
+        assert(expectedRevision === undefined || state.revision === expectedRevision, "Plugin state changed; refresh before saving");
+        const result = change(state);
+        // An upgrade may remove a capability's enabled dependency or change its major version.
+        for (const profile of Object.values(state.profiles))
+            for (const values of [profile.plugins, ...Object.values(profile.workspaces)]) {
+                let changed = true;
+                while (changed) {
+                    changed = false;
+                    const effective = { ...profile.plugins, ...values };
+                    for (const record of Object.values(state.packages))
+                        if (effective[record.manifest.id]?.enabled && Object.entries(record.manifest.dependencies ?? {}).some(([id, range]) => !state.packages[id] || !effective[id]?.enabled || !satisfies(state.packages[id].manifest.version, range))) {
+                            values[record.manifest.id] = { ...effective[record.manifest.id], enabled: false };
+                            changed = true;
+                        }
+                }
+            }
+        state.revision++;
+        fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, path.join(pluginHome(), "state.json"));
+        return result;
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+        fs.rmdirSync(lock);
+    }
+}
+function workspaceKey(cwd) {
+    if (!cwd)
+        return undefined;
+    const canonical = fs.realpathSync(cwd);
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+function activation(state, id, profile, cwd) {
+    const base = state.profiles[profile].plugins[id] ?? { enabled: false, config: {} };
+    const key = workspaceKey(cwd);
+    const local = key ? state.profiles[profile].workspaces[key]?.[id] : undefined;
+    return local ? { ...base, ...local, config: { ...base.config, ...local.config } } : structuredClone(base);
+}
+function table(state, profile, cwd) {
+    const key = workspaceKey(cwd);
+    return key ? state.profiles[profile].workspaces[key] ??= {} : state.profiles[profile].plugins;
+}
+/** Re-hash the immutable package so a post-install edit invalidates native trust. */
+export function packageIntegrity(directory) {
+    const hash = createHash("sha256");
+    let files = 0, bytes = 0;
+    const visit = (dir, rel = "") => {
+        for (const item of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+            if ([".git", "node_modules", ".DS_Store"].includes(item.name))
+                continue;
+            const name = path.posix.join(rel, item.name), file = path.join(dir, item.name);
+            assert(!item.isSymbolicLink(), "Plugin packages cannot contain symlinks");
+            if (item.isDirectory()) {
+                visit(file, name);
+                continue;
+            }
+            assert(item.isFile(), "Plugin packages must contain regular files");
+            const data = fs.readFileSync(file);
+            assert(++files <= 2000 && (bytes += data.length) <= 32 * 1024 * 1024, "Plugin exceeds 2000 files or 32 MiB");
+            hash.update(name).update("\0").update(String(data.length)).update("\0").update(data);
+        }
+    };
+    visit(directory);
+    return `sha256-${hash.digest("hex")}`;
+}
+export function installPlugin(source, expectedRevision, sourceLabel) {
+    if (fs.statSync(source).isFile()) {
+        const archive = fs.realpathSync(source), unpacked = unpackPlugin(archive);
+        try {
+            return installPlugin(unpacked.directory, expectedRevision, archive);
+        }
+        finally {
+            unpacked.dispose();
+        }
+    }
+    assert(typeof source === "string" && path.isAbsolute(path.resolve(source)), "A local plugin directory is required");
+    const directory = fs.realpathSync(path.resolve(source));
+    assert(fs.statSync(directory).isDirectory(), "Plugin source must be a directory");
+    const manifest = readManifest(directory);
+    const integrity = packageIntegrity(directory);
+    let target = path.join(pluginHome(), "packages", manifest.id, `${manifest.version}-${integrity.slice(7, 23)}`);
+    if (fs.existsSync(target) && packageIntegrity(target) !== integrity)
+        target += `-repair-${randomUUID().slice(0, 8)}`;
+    // Never copy a package directory into itself (also bounds recursive installs).
+    assert(!path.resolve(pluginHome()).startsWith(directory + path.sep) && directory !== path.resolve(pluginHome()), "Plugin source cannot contain its installation home");
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(target)) {
+        const staging = `${target}.${randomUUID()}.tmp`;
+        try {
+            fs.cpSync(directory, staging, { recursive: true, filter: file => ![".git", "node_modules", ".DS_Store"].includes(path.basename(file)) });
+            assert(packageIntegrity(staging) === integrity, "Plugin source changed during installation; retry");
+            readManifest(staging);
+            fs.renameSync(staging, target);
+        }
+        finally {
+            fs.rmSync(staging, { recursive: true, force: true });
+        }
+    }
+    transaction(state => {
+        const old = state.packages[manifest.id];
+        const previous = old && old.integrity !== integrity ? (({ previous: _, ...rest }) => rest)(old) : old?.previous;
+        state.packages[manifest.id] = { manifest, directory: target, integrity, source: sourceLabel ?? directory, installedAt: new Date().toISOString(), ...(previous ? { previous } : {}) };
+        const newPermissions = (manifest.permissions ?? []).some(p => !old?.manifest.permissions?.includes(p));
+        if (old && old.integrity !== integrity && (newPermissions || manifest.runtime === "native"))
+            for (const profile of Object.values(state.profiles)) {
+                const entries = [profile.plugins, ...Object.values(profile.workspaces)];
+                for (const values of entries)
+                    if (values[manifest.id])
+                        values[manifest.id] = { ...values[manifest.id], enabled: false, nativeTrust: undefined };
+            }
+    }, expectedRevision);
+    return listPlugins().plugins.find(p => p.manifest.id === manifest.id);
+}
+export function listPlugins(profile = "standard", cwd) {
+    const state = readState();
+    const plugins = Object.values(state.packages).map(record => {
+        const a = activation(state, record.manifest.id, profile, cwd);
+        let error;
+        try {
+            checkRecord(record, a, profile);
+        }
+        catch (e) {
+            error = String(e.message);
+        }
+        return { manifest: record.manifest, integrity: record.integrity, source: record.source, installedAt: record.installedAt,
+            enabled: a.enabled, config: { ...defaults(record.manifest.configuration), ...a.config }, error, rollback: Boolean(record.previous) };
+    }).sort((a, b) => a.manifest.id.localeCompare(b.manifest.id));
+    return { revision: state.revision, safeMode: safeMode(), plugins, providers: state.profiles[profile].providers };
+}
+function checkRecord(record, a, profile) {
+    assert(record.manifest.profiles === undefined || record.manifest.profiles.includes(profile), `Plugin does not support ${profile}`);
+    assert(packageIntegrity(record.directory) === record.integrity, "Installed files changed; reinstall the plugin");
+    if (a.enabled && record.manifest.runtime === "native" && record.manifest.entries?.agent)
+        assert(a.nativeTrust === record.integrity, "Native code trust is required for this exact package revision");
+    if (record.manifest.configuration)
+        validateValue({ ...defaults(record.manifest.configuration), ...a.config }, record.manifest.configuration);
+}
+export function configurePlugin(id, patch, profile = "standard", cwd, revision) {
+    assert(ID.test(id), "Invalid plugin id");
+    assert(patch.enabled === undefined || typeof patch.enabled === "boolean", "enabled must be boolean");
+    assert(patch.config === undefined || object(patch.config), "Plugin config must be an object");
+    transaction(state => {
+        const record = state.packages[id];
+        assert(record, "Unknown plugin");
+        const old = activation(state, id, profile, cwd);
+        const next = { ...old, ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }), ...(patch.config === undefined ? {} : { config: patch.config }) };
+        if (patch.trustNative === true)
+            next.nativeTrust = record.integrity;
+        if (next.enabled || patch.config !== undefined)
+            checkRecord(record, next, profile);
+        if (next.enabled) {
+            for (const [dependency, range] of Object.entries(record.manifest.dependencies ?? {})) {
+                assert(state.packages[dependency] && activation(state, dependency, profile, cwd).enabled && satisfies(state.packages[dependency].manifest.version, range), `Enable compatible dependency ${dependency}@${range} first`);
+            }
+        }
+        else {
+            for (const other of Object.values(state.packages))
+                if (activation(state, other.manifest.id, profile, cwd).enabled && other.manifest.dependencies?.[id])
+                    throw new Error(`${other.manifest.id} depends on this plugin; disable it first`);
+        }
+        table(state, profile, cwd)[id] = next;
+        resolveRecords(state, profile, cwd); // cycles fail before persistence
+    }, revision);
+}
+export function removePlugin(id, revision) {
+    transaction(state => {
+        assert(ID.test(id) && state.packages[id], "Unknown plugin");
+        for (const other of Object.values(state.packages))
+            assert(other.manifest.id === id || !other.manifest.dependencies?.[id], `${other.manifest.id} depends on this plugin; remove the dependent first`);
+        delete state.packages[id];
+        for (const p of Object.values(state.profiles)) {
+            delete p.plugins[id];
+            for (const local of Object.values(p.workspaces))
+                delete local[id];
+            for (const [slot, provider] of Object.entries(p.providers))
+                if (provider.startsWith(`${id}/`))
+                    delete p.providers[slot];
+        }
+        // Keep immutable package files for in-flight tasks and rollback/debugging.
+    }, revision);
+}
+export function rollbackPlugin(id, revision) {
+    transaction(state => { const current = state.packages[id]; assert(current?.previous, "No previous plugin version"); const { previous, ...now } = current; state.packages[id] = { ...previous, previous: now }; }, revision);
+}
+export function selectProvider(slot, provider, profile, revision) {
+    assert(["chat.composer", "chat.message.renderer", "chat.card.plan", "chat.card.tool", "persona"].includes(slot), "This slot is not replaceable");
+    transaction(state => { assert(typeof provider === "string" && provider.length <= 160, "Invalid provider"); if (provider)
+        state.profiles[profile].providers[slot] = provider;
+    else
+        delete state.profiles[profile].providers[slot]; }, revision);
+}
+function resolveRecords(state, profile, cwd) {
+    const active = new Map(Object.entries(state.packages).filter(([id]) => activation(state, id, profile, cwd).enabled));
+    const done = new Set(), visiting = new Set(), output = [];
+    const visit = (id) => {
+        if (done.has(id))
+            return;
+        assert(!visiting.has(id), `Plugin dependency cycle at ${id}`);
+        visiting.add(id);
+        const record = active.get(id);
+        for (const [dep, range] of Object.entries(record.manifest.dependencies ?? {})) {
+            assert(active.has(dep) && satisfies(active.get(dep).manifest.version, range), `Missing dependency ${dep}@${range}`);
+            visit(dep);
+        }
+        for (const [dep, range] of Object.entries(record.manifest.optionalDependencies ?? {}))
+            if (active.has(dep) && satisfies(active.get(dep).manifest.version, range))
+                visit(dep);
+        visiting.delete(id);
+        done.add(id);
+        output.push({ ...record, activation: activation(state, id, profile, cwd) });
+    };
+    for (const id of [...active.keys()].sort())
+        visit(id);
+    return output;
+}
+export function pluginRecords(profile = "standard", cwd) {
+    if (safeMode())
+        return [];
+    return resolveRecords(readState(), profile, cwd).map(record => { try {
+        checkRecord(record, record.activation, profile);
+        return record;
+    }
+    catch (e) {
+        return { ...record, error: e.message };
+    } });
+}
+export function providerSelections(profile) { return safeMode() ? {} : readState().profiles[profile].providers; }
+export function pluginAsset(id, file, profile, cwd) {
+    const record = pluginRecords(profile, cwd).find(r => r.manifest.id === id && !r.error);
+    assert(record, "Plugin is disabled or unavailable");
+    // Only assets explicitly used by a UI contribution may reach browsers.
+    const allowed = new Set([...(record.manifest.contributes?.ui ?? []).map(u => u.view), record.manifest.entries?.web, ...record.manifest.webAssets ?? []]);
+    assert(allowed.has(file), "Asset is not a declared plugin view");
+    const resolved = safeFile(record.directory, file);
+    assert(fs.statSync(resolved).size <= 1_000_000, "Plugin view exceeds 1 MB");
+    return fs.readFileSync(resolved, "utf8");
+}
+export function pluginStorage(id, key, value, write = false) {
+    assert(ID.test(id) && /^[a-zA-Z0-9_.-]{1,80}$/.test(key) && key !== "..", "Invalid storage key");
+    const dir = path.join(pluginHome(), "data", id);
+    const file = path.join(dir, `${key}.json`);
+    if (!write)
+        return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null;
+    const body = JSON.stringify(value ?? null);
+    assert(body.length <= 256_000, "Plugin storage value exceeds 256 KB");
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const files = fs.readdirSync(dir).filter(name => name.endsWith(".json"));
+    assert(files.length < 128 || fs.existsSync(file), "Plugin storage exceeds 128 keys");
+    const otherBytes = files.filter(name => name !== `${key}.json`).reduce((sum, name) => sum + fs.statSync(path.join(dir, name)).size, 0);
+    assert(otherBytes + Buffer.byteLength(body) <= 8 * 1024 * 1024, "Plugin storage exceeds 8 MiB");
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temp, body, { mode: 0o600 });
+        fs.renameSync(temp, file);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}

package/dist/plugins/package.d.ts

@@ -0,0 +1,5 @@
+export declare function packPlugin(directory: string, output: string): string;
+export declare function unpackPlugin(file: string): {
+    directory: string;
+    dispose(): void;
+};

package/dist/plugins/package.js

@@ -0,0 +1,53 @@
+/** Dependency-free distributable bundle. No extraction of executable installation scripts. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assert, object, readManifest } from "./validation.js";
+import { packageIntegrity } from "./manager.js";
+export function packPlugin(directory, output) {
+    const base = fs.realpathSync(directory), dest = path.resolve(output);
+    assert(dest !== base && !dest.startsWith(base + path.sep), "Bundle output must be outside the source package");
+    readManifest(directory);
+    const integrity = packageIntegrity(directory);
+    const files = [];
+    const visit = (dir, relative = "") => { for (const item of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (["node_modules", ".git", ".DS_Store"].includes(item.name))
+            continue;
+        const file = path.join(dir, item.name), name = path.posix.join(relative, item.name);
+        if (item.isDirectory())
+            visit(file, name);
+        else
+            files.push({ path: name, data: fs.readFileSync(file).toString("base64") });
+    } };
+    visit(directory);
+    fs.writeFileSync(output, JSON.stringify({ format: "neutrino-plugin", version: 1, integrity, files }), { flag: "wx" });
+    return output;
+}
+export function unpackPlugin(file) {
+    assert(fs.statSync(file).size <= 48 * 1024 * 1024, "Plugin bundle exceeds 48 MiB");
+    const bundle = JSON.parse(fs.readFileSync(file, "utf8"));
+    assert(object(bundle) && bundle.format === "neutrino-plugin" && bundle.version === 1 && typeof bundle.integrity === "string" && Array.isArray(bundle.files) && bundle.files.length <= 2000, "Invalid plugin bundle");
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "neutrino-plugin-unpack-"));
+    try {
+        let bytes = 0;
+        const seen = new Set();
+        for (const item of bundle.files) {
+            assert(object(item) && typeof item.path === "string" && typeof item.data === "string", "Invalid bundle file");
+            const parts = item.path.split("/");
+            assert(parts.every(p => p && p !== "." && p !== ".." && !/[\\:\0]/.test(p)) && !seen.has(item.path), "Unsafe or duplicate bundle path");
+            seen.add(item.path);
+            const data = Buffer.from(item.data, "base64");
+            assert((bytes += data.length) <= 32 * 1024 * 1024, "Plugin data exceeds 32 MiB");
+            const dest = path.join(directory, ...parts);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, data, { flag: "wx", mode: 0o600 });
+        }
+        readManifest(directory);
+        assert(packageIntegrity(directory) === bundle.integrity, "Plugin bundle integrity mismatch");
+        return { directory, dispose: () => fs.rmSync(directory, { recursive: true, force: true }) };
+    }
+    catch (e) {
+        fs.rmSync(directory, { recursive: true, force: true });
+        throw e;
+    }
+}

package/dist/plugins/runner.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugins/runner.js

@@ -0,0 +1,227 @@
+/** Private disposable process. Native code never runs on the terminal/server event loop. */
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import ts from "typescript";
+/** This function is also serialized into QuickJS. It must have no module dependencies. */
+function bootstrap(bridge, initial) {
+    const handlers = new Map();
+    const registrations = [];
+    const effects = [];
+    let counter = 0, sealed = false;
+    const register = (kind, spec, handler) => {
+        if (sealed)
+            throw new Error("Register contributions during activate()");
+        const id = `${kind}:${++counter}`;
+        if (typeof handler === "function")
+            handlers.set(id, handler);
+        const { execute: _, ...data } = spec;
+        const record = { ...data, kind, handler: id };
+        registrations.push(record);
+        return { dispose() { handlers.delete(id); const index = registrations.indexOf(record); if (index >= 0)
+                registrations.splice(index, 1); } };
+    };
+    const call = (operation, args) => bridge(operation, args);
+    const ctx = {
+        id: initial.id, config: Object.freeze(initial.config), scope: Object.freeze(initial.scope),
+        tools: { register: (spec) => register("tool", spec, spec.execute) },
+        commands: { register: (spec) => register("command", spec, spec.execute) },
+        prompts: { register: (spec) => register("prompt", spec) },
+        skills: { register: (file) => register("skill", { file }) },
+        ui: { register: (spec) => register("ui", spec) },
+        hooks: { add: (name, handler) => register("hook", { name }, handler) },
+        events: { on: (name, handler) => register("event", { name }, handler) },
+        fs: {
+            read: (path, reason) => call("read_file", { path, reason }),
+            write: (path, content, reason) => call("write_file", { path, content, reason }),
+            list: (path, reason) => call("list_files", { path, reason }),
+        },
+        net: { fetch: (url, reason) => call("fetch", { url, reason }) },
+        process: { run: (command, reason) => call("run_command", { command, reason }) },
+        storage: { get: (key) => call("storage.get", { key }), set: (key, value) => call("storage.set", { key, value }) },
+        services: { call: (pluginId, command, args = {}) => call("service.call", { pluginId, command, args }) },
+        log: (message) => { void call("log", { message: String(message).slice(0, 4000) }).catch(() => { }); },
+        effect: (dispose) => effects.push(dispose),
+    };
+    return {
+        ctx,
+        seal() { sealed = true; return registrations; },
+        async invoke(id, value, context) {
+            const handler = handlers.get(id);
+            if (!handler)
+                throw new Error("Plugin registration was disposed");
+            return await handler(value, context);
+        },
+        async dispose() { for (const dispose of effects.reverse())
+            await dispose(); handlers.clear(); registrations.length = 0; },
+    };
+}
+const pending = new Map();
+let nextId = 0;
+function send(value) { if (process.connected)
+    process.send?.(value); }
+function bridge(op, value) {
+    return new Promise((resolve, reject) => { const id = ++nextId; pending.set(id, { resolve, reject }); send({ type: "operation", id, op, value }); });
+}
+let execute;
+let dispose;
+let pumping;
+let engine;
+let vm;
+let cpuEnd = 0;
+function evaluate(source) {
+    cpuEnd = Date.now() + 1000;
+    const result = vm.evalCode(source);
+    if (result.error) {
+        const error = vm.dump(result.error);
+        result.error.dispose();
+        throw new Error(typeof error?.message === "string" ? error.message : String(error));
+    }
+    result.value.dispose();
+    pump();
+}
+function pump() {
+    cpuEnd = Date.now() + 1000;
+    const jobs = engine?.executePendingJobs(100);
+    if (jobs && "error" in jobs && jobs.error) {
+        const error = vm.dump(jobs.error);
+        jobs.error.dispose();
+        send({ type: "fatal", error: String(error?.message ?? error) });
+        process.exitCode = 1;
+        process.disconnect();
+    }
+}
+const sandboxCalls = new Map();
+async function start(initial) {
+    if (initial.runtime === "native") {
+        const runtime = bootstrap(bridge, initial);
+        const mod = await import(pathToFileURL(initial.entry).href);
+        const plugin = mod.default ?? mod;
+        if (typeof plugin.activate !== "function")
+            throw new Error("Plugin must export activate(ctx)");
+        const cleanup = await plugin.activate(runtime.ctx);
+        if (typeof cleanup === "function")
+            runtime.ctx.effect(cleanup);
+        execute = runtime.invoke;
+        dispose = runtime.dispose;
+        send({ type: "ready", registrations: runtime.seal() });
+        return;
+    }
+    const { getQuickJS } = await import("quickjs-emscripten");
+    const module = await getQuickJS();
+    engine = module.newRuntime();
+    engine.setMemoryLimit(32 * 1024 * 1024);
+    engine.setMaxStackSize(512 * 1024);
+    engine.setInterruptHandler(() => Date.now() >= cpuEnd);
+    vm = engine.newContext();
+    const host = vm.newFunction("__bridge", (operation, argument) => {
+        const op = vm.getString(operation), value = vm.dump(argument);
+        const deferred = vm.newPromise();
+        void bridge(op, value).then(result => {
+            if (!vm?.alive)
+                return;
+            const handle = vm.evalCode(`(${JSON.stringify(result ?? null)})`);
+            if (handle.error) {
+                deferred.reject(handle.error);
+                handle.error.dispose();
+            }
+            else {
+                deferred.resolve(handle.value);
+                handle.value.dispose();
+            }
+            deferred.dispose();
+            pump();
+        }, error => {
+            if (!vm?.alive)
+                return;
+            const handle = vm.newError(String(error.message));
+            deferred.reject(handle);
+            handle.dispose();
+            deferred.dispose();
+            pump();
+        });
+        return deferred.handle;
+    });
+    vm.setProp(vm.global, "__bridge", host);
+    host.dispose();
+    const settle = vm.newFunction("__settle", (id, error, value) => {
+        const call = sandboxCalls.get(vm.getNumber(id));
+        if (call) {
+            sandboxCalls.delete(vm.getNumber(id));
+            const err = vm.dump(error);
+            if (err)
+                call.reject(new Error(String(err)));
+            else
+                call.resolve(vm.dump(value));
+        }
+    });
+    vm.setProp(vm.global, "__settle", settle);
+    settle.dispose();
+    const compiled = ts.transpileModule(fs.readFileSync(initial.entry, "utf8"), {
+        compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020 }, fileName: initial.entry,
+    }).outputText;
+    const activation = new Promise((resolve, reject) => sandboxCalls.set(0, { resolve, reject }));
+    pumping = setInterval(pump, 10);
+    pumping.unref();
+    evaluate(`globalThis.__runtime = (${bootstrap.toString()})(__bridge, ${JSON.stringify(initial)});
+    globalThis.exports = {}; globalThis.module = { exports };
+    globalThis.require = (id) => { if (id === '@xingjisoft/neutrino/plugin') return { definePlugin: p => p }; throw new Error('Sandbox imports must be bundled: ' + id); };
+    globalThis.console = { log: (...a) => __runtime.ctx.log(a.join(' ')), warn: (...a) => __runtime.ctx.log(a.join(' ')), error: (...a) => __runtime.ctx.log(a.join(' ')) };
+    ${compiled}
+    globalThis.__plugin = module.exports.default || module.exports;
+    Promise.resolve().then(() => __plugin.activate(__runtime.ctx)).then(cleanup => { if (typeof cleanup === 'function') __runtime.ctx.effect(cleanup); __settle(0, null, __runtime.seal()); }, error => __settle(0, String(error), null));`);
+    const registrations = await activation;
+    execute = (handler, value, context) => new Promise((resolve, reject) => {
+        const id = ++nextId;
+        sandboxCalls.set(id, { resolve, reject });
+        try {
+            evaluate(`__runtime.invoke(${JSON.stringify(handler)}, ${JSON.stringify(value)}, ${JSON.stringify(context)}).then(v => __settle(${id}, null, v === undefined ? null : v), e => __settle(${id}, String(e), null))`);
+        }
+        catch (error) {
+            sandboxCalls.delete(id);
+            reject(error);
+        }
+    });
+    dispose = async () => {
+        const id = ++nextId;
+        await new Promise((resolve, reject) => {
+            sandboxCalls.set(id, { resolve: () => resolve(), reject });
+            evaluate(`__runtime.dispose().then(() => __settle(${id}, null, null), e => __settle(${id}, String(e), null))`);
+        });
+    };
+    send({ type: "ready", registrations });
+}
+let queue = Promise.resolve();
+process.on("message", (message) => {
+    if (message.type === "operation-result") {
+        const call = pending.get(message.id);
+        pending.delete(message.id);
+        if (message.error)
+            call?.reject(new Error(message.error));
+        else
+            call?.resolve(message.value);
+    }
+    else if (message.type === "init") {
+        queue = start(message.initial).catch(error => send({ type: "fatal", error: String(error.message) }));
+    }
+    else if (message.type === "invoke") {
+        queue = queue.then(async () => {
+            try {
+                send({ type: "result", id: message.id, value: (await execute(message.handler, message.value, message.context)) ?? null });
+            }
+            catch (error) {
+                send({ type: "result", id: message.id, error: String(error.message) });
+            }
+        });
+    }
+    else if (message.type === "dispose") {
+        queue = queue.finally(async () => { try {
+            await dispose?.();
+        }
+        finally {
+            if (pumping)
+                clearInterval(pumping);
+            process.disconnect();
+        } });
+    }
+});
+process.on("disconnect", () => process.exit(0));

package/dist/plugins/session.d.ts

@@ -0,0 +1,12 @@
+/** Shared integration used by terminal, browser, Pro and their child agents. */
+import { type TaskRuntime } from "../llm/runtime.js";
+import type { ApprovalDecision, ApprovalContext } from "../llm/approval.js";
+import type { JsonObject, PluginScope } from "./types.js";
+export declare function pluginPrompt(base: string, role: string): string;
+/** A view can supply command arguments; quoted authorization phrases in that data are never user consent. */
+export declare function pluginApprovalContext(context: ApprovalContext): ApprovalContext;
+export declare function runPluginTurn(runtime: TaskRuntime, scope: PluginScope, approve: (name: string, args: JsonObject, signal?: AbortSignal) => Promise<ApprovalDecision>, body: () => Promise<void>): Promise<void>;
+export declare function pluginCommand(request: string): {
+    name: string;
+    args: JsonObject;
+} | null;