personal-bot 0.2.3 → 0.2.5

package/lib/services/history/history-service.js

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import { requireThat } from "../../common/validation.js";
+/** Shared prefixes reuse nodes; only consecutive exchanges on one native branch can merge. */
+export function indexHistory(session, previous, host = "pi") {
+    const id = previous?.id ?? (host === "dsh" ? "dsh-" : "") + randomUUID(), nodes = new Map();
+    const old = new Map(previous?.nodes.map(node => [node.id, node])), changed = new Set();
+    const add = (value, level, children = []) => {
+        const key = `${id}:${level}:${value.entryIds.at(-1)}`, found = nodes.get(key);
+        if (found)
+            return found;
+        const before = old.get(key), same = before && JSON.stringify(before.children) === JSON.stringify(children) &&
+            (level ? children.every(child => !changed.has(child)) : before.text === value.text && before.completed === value.completed);
+        const node = { ...value, id: key, kind: level ? "summary" : "exchange", level, children, parents: [],
+            text: level ? same ? before.text : "" : value.text, ready: level ? Boolean(same && before.ready) : true };
+        if (!same)
+            changed.add(key);
+        nodes.set(key, node);
+        return node;
+    };
+    const roots = new Set();
+    for (const branch of session.branches) {
+        let layer = branch.map(exchange => add(exchange, 0)), level = 1;
+        while (layer.length >= 4) {
+            const count = Math.floor(layer.length / 4) * 4, next = [];
+            layer.slice(count).forEach(node => roots.add(node.id));
+            for (let i = 0; i < count; i += 4) {
+                const children = layer.slice(i, i + 4), first = children[0], last = children.at(-1);
+                next.push(add({ entryIds: [first.entryIds[0], last.entryIds.at(-1)], text: "", from: first.from, to: last.to,
+                    completed: children.every(node => node.completed) }, level, children.map(node => node.id)));
+            }
+            layer = next;
+            level++;
+        }
+        layer.forEach(node => roots.add(node.id));
+    }
+    const dates = [...nodes.values()].flatMap(node => [node.from, node.to]).sort();
+    nodes.set(id, { id, kind: "session", level: -1, entryIds: [], text: session.name, ready: true, completed: [...nodes.values()].every(node => node.completed),
+        from: dates[0] ?? "", to: dates.at(-1) ?? "", parents: [],
+        children: [...roots].sort((a, b) => nodes.get(a).from.localeCompare(nodes.get(b).from)) });
+    for (const node of nodes.values())
+        for (const child of node.children)
+            nodes.get(child).parents.push(node.id);
+    return { id, sessionId: session.sessionId, name: session.name, nodes: [...nodes.values()] };
+}
+const page = (values, offset, limit) => ({ values: values.slice(offset, offset + limit),
+    nextOffset: offset + limit < values.length ? offset + limit : null });
+const brief = ({ host, record }, node) => ({ host, id: node.id, kind: node.kind, sessionId: record.sessionId,
+    name: record.name, preview: node.text.replace(/\s+/g, " ").slice(0, 100), from: node.from, to: node.to, ready: node.ready, completed: node.completed });
+const rawSource = (record) => record && JSON.stringify({ name: record.name,
+    exchanges: record.nodes.filter(node => node.kind === "exchange").map(node => [node.id, node.entryIds, node.text, node.from, node.to, node.completed]) });
+const summarySource = (node) => [node.id, node.entryIds, node.children, node.text, node.from, node.to, node.completed, node.ready];
+/** Validate the exact inputs again under the source lock; another writer's ready summary wins. */
+export function completeHistorySummary(record, id, children, text) {
+    const node = record.nodes.find(value => value.id === id);
+    if (!node || node.kind !== "summary" || node.ready || JSON.stringify(node.children) !== JSON.stringify(children.map(child => child.id)))
+        return false;
+    const current = node.children.map(id => record.nodes.find(value => value.id === id));
+    if (current.some(value => !value) || JSON.stringify(current.map(value => summarySource(value))) !== JSON.stringify(children.map(summarySource)))
+        return false;
+    requireThat(text.trim(), "历史摘要为空。");
+    node.text = text.trim();
+    node.ready = true;
+    return true;
+}
+export class HistoryService {
+    root;
+    files;
+    source;
+    previousFiles;
+    otherFiles;
+    #records = [];
+    #closed = false;
+    #loaded = false;
+    #refresh;
+    #work;
+    #sourceWarnings = [];
+    #summaryError;
+    constructor(root, files, source, previousFiles, otherFiles) {
+        this.root = root;
+        this.files = files;
+        this.source = source;
+        this.previousFiles = previousFiles;
+        this.otherFiles = otherFiles;
+        requireThat(source.host === files.host && (!otherFiles || otherFiles.host !== files.host), "历史来源与归档目录不匹配。");
+        requireThat(files.host === "pi" || !previousFiles, "dsh 不导入 Pi 旧归档。");
+    }
+    check() { requireThat(!this.#closed, "历史服务已关闭。"); }
+    get warnings() { return [...this.#sourceWarnings, ...(this.#summaryError ? [this.files.host + " 摘要：" + this.#summaryError] : [])]; }
+    get status() {
+        return { loaded: this.#loaded, organizing: Boolean(this.#work), pending: this.#loaded ? this.#records.filter(value => value.host === this.files.host)
+                .reduce((total, value) => total + value.record.nodes.filter(node => node.kind === "summary" && !node.ready).length, 0) : null, warnings: this.warnings };
+    }
+    refresh(location, signal) {
+        this.check();
+        // Each caller keeps its own cancellation. A closed page cannot cancel a server-owned refresh.
+        const work = (this.#refresh ?? Promise.resolve()).catch(() => { }).then(() => this.load(location, signal));
+        this.#refresh = work;
+        return work.finally(() => { if (this.#refresh === work)
+            this.#refresh = undefined; });
+    }
+    async load(location, signal) {
+        this.check();
+        signal?.throwIfAborted();
+        const warnings = [], records = [];
+        const warning = (host, error) => { this.check(); signal?.throwIfAborted(); warnings.push(host + ": " + String(error)); };
+        let known = [];
+        try {
+            const before = this.files.list();
+            known = before;
+            let imports = [], importedPrevious = !this.previousFiles;
+            if (this.previousFiles) {
+                try {
+                    imports = this.previousFiles.list(this.root);
+                    importedPrevious = true;
+                }
+                catch (error) {
+                    warning("pi", error);
+                }
+            }
+            let sessions = [];
+            try {
+                const scanned = await this.source.scan(location, signal);
+                sessions = scanned.sessions;
+                warnings.push(...scanned.warnings.map(value => this.files.host + ": " + value));
+            }
+            catch (error) {
+                warning(this.files.host, error);
+            }
+            this.check();
+            signal?.throwIfAborted();
+            if (sessions.length || imports.length || (this.files.host === "pi" && before.some(value => "file" in value))) {
+                known = this.files.control(() => {
+                    this.check();
+                    signal?.throwIfAborted();
+                    const latest = this.files.list(), current = new Map(latest.map(record => [record.sessionId, record])), imported = new Set();
+                    if (this.files.host === "pi") {
+                        for (const value of latest)
+                            if ("file" in value) {
+                                const { id, sessionId, name, nodes } = value, clean = { id, sessionId, name, nodes };
+                                this.files.save(clean);
+                                current.set(sessionId, clean);
+                            }
+                        for (const { id, sessionId, name, nodes } of imports)
+                            if (!current.has(sessionId)) {
+                                const value = { id, sessionId, name, nodes };
+                                this.files.save(value);
+                                current.set(sessionId, value);
+                                imported.add(sessionId);
+                            }
+                    }
+                    for (const session of sessions) {
+                        const previous = current.get(session.sessionId), captured = before.find(record => record.sessionId === session.sessionId);
+                        // A concurrent source update must not be overwritten by this older scan. Summary-only updates remain reusable.
+                        if (captured && rawSource(captured) !== rawSource(previous))
+                            continue;
+                        if (!captured && previous && !imported.has(session.sessionId))
+                            continue;
+                        const value = indexHistory(session, previous, this.files.host);
+                        if (JSON.stringify(previous) !== JSON.stringify(value))
+                            this.files.save(value);
+                        current.set(session.sessionId, value);
+                    }
+                    return [...current.values()];
+                });
+            }
+            if (importedPrevious)
+                this.previousFiles = undefined;
+        }
+        catch (error) {
+            warning(this.files.host, error);
+        }
+        records.push(...known.map(record => ({ host: this.files.host, record })));
+        if (this.otherFiles) {
+            try {
+                records.push(...this.otherFiles.list().map(record => ({ host: this.otherFiles.host, record })));
+            }
+            catch (error) {
+                warning(this.otherFiles.host, error);
+            }
+        }
+        this.check();
+        signal?.throwIfAborted();
+        this.#records = records;
+        this.#sourceWarnings = warnings;
+        this.#loaded = true;
+    }
+    search({ host, query = "", sessionId, from, to, offset = 0, limit = 20 } = {}) {
+        this.check();
+        const needle = query.trim().toLowerCase(), after = from === undefined ? -Infinity : Date.parse(from), before = to === undefined ? Infinity : Date.parse(to);
+        requireThat(!Number.isNaN(after) && !Number.isNaN(before) && after <= before, "时间范围无效，请使用 ISO 日期或时间。");
+        const matches = this.#records.filter(value => (!host || value.host === host) && (!sessionId || value.record.sessionId === sessionId)).flatMap(value => value.record.nodes
+            .filter(node => (needle ? node.kind !== "session" && node.ready && node.text.toLowerCase().includes(needle) : node.kind === "session") &&
+            Date.parse(node.to) >= after && Date.parse(node.from) <= before)
+            .map(node => {
+            const start = Math.max(0, node.text.toLowerCase().indexOf(needle) - 80);
+            return { ...brief(value, node), parents: node.parents, snippet: node.text.slice(start, start + 400) };
+        })).sort((a, b) => b.to.localeCompare(a.to) || a.id.localeCompare(b.id));
+        const result = page(matches, offset, limit);
+        return { matches: result.values, total: matches.length, nextOffset: result.nextOffset, warnings: this.warnings };
+    }
+    find(id, host) {
+        const values = this.#records.filter(value => (!host || value.host === host) && value.record.nodes.some(node => node.id === id));
+        requireThat(values.length, "历史节点不存在，请重新搜索。");
+        requireThat(values.length === 1, "历史节点来源不明确，请指定 host。");
+        const value = values[0], node = value.record.nodes.find(node => node.id === id);
+        return { value, node };
+    }
+    read(id, offset = 0, limit = 12000, childrenOffset = 0, host) {
+        this.check();
+        const { value, node } = this.find(id, host), lookup = new Map(value.record.nodes.map(node => [node.id, node]));
+        requireThat(offset <= node.text.length, "读取位置超出正文。");
+        if (offset && /[\uDC00-\uDFFF]/.test(node.text[offset] ?? ""))
+            offset--;
+        let end = Math.min(node.text.length, offset + limit);
+        if (end < node.text.length && /[\uD800-\uDBFF]/.test(node.text[end - 1] ?? ""))
+            end += end - offset === 1 ? 1 : -1;
+        const children = page(node.children, childrenOffset, 20);
+        return { ...brief(value, node), text: node.text.slice(offset, end), totalLength: node.text.length,
+            nextOffset: end < node.text.length ? end : null,
+            parents: node.parents.map(id => brief(value, lookup.get(id))), children: children.values.map(id => brief(value, lookup.get(id))),
+            nextChildrenOffset: children.nextOffset, source: { host: value.host, sessionId: value.record.sessionId, entryIds: node.entryIds }, warnings: this.warnings };
+    }
+    /** Only this source is organized. Model calls run outside the write lock. */
+    organize(summarize, signal) {
+        this.check();
+        const run = async () => {
+            for (;;) {
+                this.check();
+                signal.throwIfAborted();
+                let pending;
+                for (const record of this.files.list()) {
+                    const lookup = new Map(record.nodes.map(node => [node.id, node]));
+                    const node = [...record.nodes].sort((a, b) => a.level - b.level).find(node => node.kind === "summary" && !node.ready && node.children.every(id => lookup.get(id).ready));
+                    if (node) {
+                        pending = { record, node, children: node.children.map(id => lookup.get(id)) };
+                        break;
+                    }
+                }
+                if (!pending)
+                    return;
+                const { record, node, children } = pending;
+                const text = await summarize(children.map(child => `[${child.from} — ${child.to}${child.completed ? "" : "；未完成"}]\n${child.text}`).join("\n\n"), signal);
+                this.check();
+                signal.throwIfAborted();
+                const committed = this.files.control(() => {
+                    this.check();
+                    signal.throwIfAborted();
+                    const current = this.files.list().find(value => value.id === record.id);
+                    if (!current || !completeHistorySummary(current, node.id, children, text))
+                        return;
+                    this.files.save(current);
+                    return current;
+                });
+                if (!committed)
+                    return;
+                this.#records = this.#records.map(value => value.host === this.files.host && value.record.id === committed.id ? { host: value.host, record: committed } : value);
+            }
+        };
+        const work = (this.#work ?? Promise.resolve()).catch(() => { }).then(run).then(() => { this.#summaryError = undefined; }).catch(error => {
+            if (!signal.aborted && !this.#closed)
+                this.#summaryError = String(error);
+            throw error;
+        });
+        this.#work = work;
+        return work.finally(() => { if (this.#work === work)
+            this.#work = undefined; });
+    }
+    async close() { this.#closed = true; await Promise.allSettled([this.#work, this.#refresh]); this.#records = []; this.#loaded = false; }
+}

package/lib/services/installation/setup-service.js

@@ -0,0 +1,121 @@
+import { npmName, ordinaryNpm } from "../../common/package-source.js";
+export const pbotPackage = {
+    id: "pbot", label: "Personal Bot", description: "工作区个人助手", source: "npm:personal-bot", defaultSelected: true,
+};
+export function parseCatalog(value) {
+    if (!Array.isArray(value))
+        throw new Error("插件清单必须是数组。");
+    const ids = new Set(["pbot"]), names = new Set(["personal-bot"]);
+    return value.map((item) => {
+        if (!item || typeof item !== "object")
+            throw new Error("无效插件清单项。");
+        const entry = item;
+        for (const field of ["id", "label", "description", "source"]) {
+            if (typeof entry[field] !== "string" || !entry[field].trim() || /[\x00-\x1f\x7f]/.test(entry[field])) {
+                throw new Error(`无效插件字段：${field}`);
+            }
+        }
+        const plugin = entry;
+        const name = npmName(plugin.source);
+        if (!/^[a-z0-9-]+$/.test(plugin.id) || !name || !ordinaryNpm(plugin.source) ||
+            typeof plugin.defaultSelected !== "boolean" || ids.has(plugin.id) || names.has(name)) {
+            throw new Error(`无效或重复的插件：${plugin.id}`);
+        }
+        ids.add(plugin.id);
+        names.add(name);
+        return { id: plugin.id, label: plugin.label, description: plugin.description,
+            source: `npm:${name}`, defaultSelected: plugin.defaultSelected };
+    });
+}
+export function packageChoices(catalog, installed) {
+    const first = !installed.some(pkg => pkg.name === "personal-bot");
+    return [pbotPackage, ...catalog].map(plugin => {
+        const matches = installed.filter(pkg => pkg.name === npmName(plugin.source));
+        // A project npm entry overrides the same npm identity in user settings. Different
+        // git/local identities still need an explicit decision before changing sources.
+        const localNpm = matches.some(pkg => pkg.scope === "project" && npmName(pkg.source));
+        const existing = matches.filter(pkg => !(localNpm && pkg.scope === "user" && npmName(pkg.source)));
+        const custom = existing.some(pkg => !ordinaryNpm(pkg.source));
+        return { plugin, required: plugin.id === "pbot", existing,
+            selected: plugin.id === "pbot" || (first ? plugin.defaultSelected : existing.length > 0), keep: custom };
+    });
+}
+export function parseSetupArgs(args) {
+    if (!args.length || args.length === 1 && ["--help", "-h"].includes(args[0]))
+        return { action: "help" };
+    if (args.length === 1 && ["--version", "-v"].includes(args[0]))
+        return { action: "version" };
+    if (args[0] !== "setup")
+        throw new Error("用法：pbot setup [--workspace <目录>]");
+    let workspace;
+    for (let index = 1; index < args.length; index++) {
+        const arg = args[index];
+        if ((arg === "--help" || arg === "-h") && args.length === 2)
+            return { action: "help" };
+        if (arg !== "--workspace" || workspace !== undefined)
+            throw new Error(`不支持的参数：${arg}`);
+        const value = args[++index];
+        if (!value || value.startsWith("--") || /[\x00-\x1f\x7f]/.test(value))
+            throw new Error("--workspace 需要目录。");
+        workspace = value;
+    }
+    return workspace === undefined ? { action: "setup" } : { action: "setup", workspace };
+}
+export async function executeSetup(plan, operations, report, signal) {
+    const results = [];
+    const add = (result) => { results.push(result); report(result); };
+    let pi;
+    try {
+        signal.throwIfAborted();
+        if (plan.tmux) {
+            await operations.installTmux(plan.tmux);
+            add({ name: "tmux", state: "done", detail: "已安装" });
+        }
+        signal.throwIfAborted();
+        pi = await operations.ensurePi(plan.pi, plan.piVersion);
+        add({ name: "Pi", state: "done", detail: pi.version });
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        add({ name: "运行环境", state: "failed", detail: String(error) });
+        return { results };
+    }
+    for (const choice of plan.packages) {
+        signal.throwIfAborted();
+        const name = choice.plugin.label;
+        if (!choice.selected) {
+            add({ name, state: "skipped", detail: "本次不处理" });
+            continue;
+        }
+        if (choice.error) {
+            add({ name, state: "failed", detail: choice.error });
+            if (choice.required)
+                return { results };
+            continue;
+        }
+        if (choice.keep) {
+            try {
+                const source = await operations.verifyKeptPackage(pi, plan.workspace, choice);
+                add({ name, state: "kept", detail: source });
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                add({ name, state: "failed", detail: String(error) });
+                if (choice.required)
+                    return { results };
+            }
+            continue;
+        }
+        try {
+            const version = await operations.installPackage(pi, plan.workspace, choice);
+            add({ name, state: "done", detail: version });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            add({ name, state: "failed", detail: String(error) });
+            if (choice.required)
+                return { results };
+        }
+    }
+    return { pi, results };
+}

package/lib/services/workspace/python-environment-service.d.ts

@@ -0,0 +1,15 @@
+export declare class PythonEnvironmentService {
+    #private;
+    private readonly root;
+    constructor(root: string);
+    get status(): {
+        state: "unprepared" | "preparing" | "ready" | "error";
+        directory?: string;
+        error?: string;
+    };
+    setup(signal?: AbortSignal): Promise<{
+        directory: string;
+        python: string;
+    }>;
+    close(): Promise<void>;
+}

package/lib/services/workspace/python-environment-service.js

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import { object } from "../../common/json.js";
+import { runCommand } from "../../integrations/process.js";
+import { requireThat } from "../../common/validation.js";
+import { resourceRoot } from "../../common/paths.js";
+export class PythonEnvironmentService {
+    root;
+    #shutdown = new AbortController();
+    #pending;
+    #status = { state: "unprepared" };
+    constructor(root) {
+        this.root = root;
+    }
+    get status() { return { ...this.#status }; }
+    setup(signal) {
+        const cancel = signal ? AbortSignal.any([this.#shutdown.signal, signal]) : this.#shutdown.signal;
+        if (cancel.aborted)
+            return Promise.reject(cancel.reason);
+        if (this.#pending)
+            return this.#pending;
+        this.#status = { state: "preparing" };
+        this.#pending = (async () => {
+            try {
+                const environment = {};
+                for (const [key, value] of Object.entries(process.env))
+                    if (value !== undefined)
+                        environment[key] = value;
+                const result = await runCommand("/bin/sh", ["-c", 'exec "$(command -v python3 || command -v python)" "$@"',
+                    "pbot-python", "-I", "-B", join(resourceRoot, "../scripts/setup-python.py")], undefined, this.root, environment, cancel, { timeoutMs: 15 * 60_000 });
+                cancel.throwIfAborted();
+                requireThat(result.success && object(result.data) && typeof result.data.directory === "string" && typeof result.data.python === "string", "共享 Python 环境未就绪；修复后执行 /pbot python setup。\n" + JSON.stringify(result.data).slice(-6000));
+                const ready = { directory: result.data.directory, python: result.data.python };
+                this.#status = { state: "ready", directory: ready.directory };
+                return ready;
+            }
+            catch (error) {
+                this.#status = { state: "error", error: error instanceof Error ? error.message : String(error) };
+                throw error;
+            }
+            finally {
+                this.#pending = undefined;
+            }
+        })();
+        return this.#pending;
+    }
+    async close() {
+        this.#shutdown.abort();
+        await this.#pending?.catch(() => undefined);
+    }
+}

package/lib/services/workspace/workspace-files.d.ts

@@ -0,0 +1,2 @@
+export declare function mutationScope(root: string, target: string): "outside" | "inside";
+export declare function authorizeMutation(root: string, path: string, change: unknown, confirm: (value: unknown) => Promise<boolean>, signal: AbortSignal): Promise<void>;

package/lib/services/workspace/workspace-files.js

@@ -0,0 +1,17 @@
+import { relative, isAbsolute } from "node:path";
+import { mutationTarget } from "../../common/files.js";
+import { requireThat } from "../../common/validation.js";
+export function mutationScope(root, target) {
+    const rel = relative(root, target);
+    if (rel === ".." || rel.startsWith("../") || isAbsolute(rel))
+        return "outside";
+    return "inside";
+}
+export async function authorizeMutation(root, path, change, confirm, signal) {
+    signal.throwIfAborted();
+    const target = await mutationTarget(path), scope = mutationScope(root, target);
+    if (scope === "outside")
+        requireThat(await confirm({ path: target, change }), "用户未确认文件修改。");
+    signal.throwIfAborted();
+    requireThat(await mutationTarget(path) === target, "确认期间文件路径已变化。");
+}

package/lib/services/workspace/workspace-preparation.d.ts

@@ -0,0 +1,2 @@
+export declare const directories: string[];
+export declare function prepareWorkspace(root: string): Promise<void>;

package/lib/services/workspace/workspace-preparation.js

@@ -0,0 +1,18 @@
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { requireThat } from "../../common/validation.js";
+import { resourceRoot } from "../../common/paths.js";
+export const directories = ["areas", "projects", "knowledge", "providers", "scratch", "agents"];
+export async function prepareWorkspace(root) {
+    for (const part of directories) {
+        const path = join(root, part);
+        await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST")
+            throw error; });
+        const entry = await lstat(path);
+        requireThat(entry.isDirectory() && !entry.isSymbolicLink(), "工作区目录不能使用符号链接：" + path);
+    }
+    const agents = await readFile(join(resourceRoot, "templates/workspace-agents.md"), "utf8");
+    await writeFile(join(root, "AGENTS.md"), agents, { flag: "wx" })
+        .catch(error => { if (error.code !== "EEXIST")
+        throw error; });
+}

package/lib/storage/agent-files.d.ts

@@ -0,0 +1,30 @@
+import type { AgentDescriptor, AgentLaunch, AgentMessage, AgentStatus, AgentCycle, AgentSessionRef, AgentSessionReference } from "../model/agent.js";
+export declare function descriptor(v: unknown): AgentDescriptor;
+export declare function sessionRef(v: unknown): AgentSessionRef;
+export declare function launch(v: unknown): AgentLaunch;
+export declare function message(v: unknown): AgentMessage;
+export declare function cycle(v: unknown): AgentCycle;
+export declare function status(v: unknown): AgentStatus;
+export declare class AgentFiles {
+    #private;
+    readonly root: string;
+    readonly host: AgentSessionReference["host"];
+    constructor(root: string, host?: AgentSessionReference["host"]);
+    check(): void;
+    fail(error: unknown): void;
+    directory(id: string): string;
+    read<T>(id: string, path: string, parse: (v: unknown) => T): T;
+    optional<T>(id: string, path: string, parse: (v: unknown) => T): T | undefined;
+    write<T>(id: string, path: string, value: T, parse: (v: unknown) => T, create?: boolean): void;
+    create(value: AgentDescriptor, run: AgentLaunch): void;
+    list(): AgentDescriptor[];
+    messages(id: string): AgentMessage[];
+    completions(id: string): AgentCycle[];
+    reference(id: string): AgentSessionReference;
+    session(id: string): string | null;
+    /** The child fixes the native path before accepting input; never reset it to null. */
+    bindSession(id: string, file: string): void;
+    /** Short controller edits are serialized; an abandoned lock fails closed. */
+    control<T>(work: () => T): T;
+    enqueue(id: string, text: string, delivery: AgentMessage["delivery"], files?: string[], requestId?: string): AgentMessage;
+}