personal-bot 0.2.4 → 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/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;
+}

package/lib/storage/agent-files.js

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonical, object } from "../common/json.js";
+import { requireThat } from "../common/validation.js";
+import { readJsonFile, writeJsonFile } from "./atomic-json.js";
+import { fileId, privateDirectory } from "./file-access.js";
+const text = (v) => typeof v === "string" && v.length > 0;
+const number = (v) => typeof v === "number" && Number.isFinite(v);
+export function descriptor(v) {
+    requireThat(object(v) && text(v.agentId) && text(v.release) && text(v.workspace) && text(v.cwd) && text(v.parentSessionId) &&
+        (v.parentLeaf === null || text(v.parentLeaf)) && number(v.createdAt) && object(v.options), "子会话身份无效。");
+    fileId(v.agentId);
+    return v;
+}
+export function sessionRef(v) {
+    requireThat(object(v) && (v.file === null || (text(v.file) && isAbsolute(v.file) && !v.file.includes("\0"))), "子会话引用无效。");
+    return v;
+}
+function dshSessionRef(v) {
+    requireThat(object(v) && v.host === "dsh" && text(v.sessionId), "dsh 原生会话引用无效。");
+    fileId(v.sessionId);
+    return v;
+}
+export function launch(v) {
+    requireThat(object(v) && text(v.generation) && text(v.name) && Number.isSafeInteger(v.sequence) && typeof v.stop === "boolean" && number(v.startedAt), "子会话启动状态无效。");
+    return v;
+}
+export function message(v) {
+    requireThat(object(v) && text(v.requestId) && text(v.generation) && Number.isSafeInteger(v.sequence) && typeof v.message === "string" &&
+        ["steer", "followUp"].includes(String(v.delivery)) && Array.isArray(v.files) && v.files.every(text), "子会话消息无效。");
+    return v;
+}
+export function cycle(v) {
+    requireThat(object(v) && text(v.cycleId) && text(v.generation) && number(v.startedAt) &&
+        ["running", "completed", "failed", "cancelled", "interrupted"].includes(String(v.state)) &&
+        (v.leaf === null || text(v.leaf)) && Array.isArray(v.requestIds) && v.requestIds.every(text) &&
+        ["parent", "interactive", "mixed"].includes(String(v.source)) && (v.finishedAt === undefined || number(v.finishedAt)), "子会话周期无效。");
+    return v;
+}
+export function status(v) {
+    requireThat(object(v) && text(v.generation) && ["starting", "busy", "idle", "stopping", "stopped", "error"].includes(String(v.state)) &&
+        typeof v.activity === "string" && number(v.updatedAt), "子会话状态无效。");
+    if (v.cycle)
+        cycle(v.cycle);
+    return v;
+}
+export class AgentFiles {
+    root;
+    host;
+    #failure;
+    constructor(root, host = "pi") {
+        this.root = root;
+        this.host = host;
+    }
+    check() { if (this.#failure)
+        throw this.#failure; }
+    fail(error) { this.#failure = error; }
+    directory(id) { return join(this.root, fileId(id)); }
+    read(id, path, parse) { return readJsonFile(this.directory(id), path, parse); }
+    optional(id, path, parse) {
+        try {
+            return this.read(id, path, parse);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    write(id, path, value, parse, create = false) {
+        this.check();
+        parse(value);
+        let published;
+        try {
+            published = writeJsonFile(this.directory(id), path, value, parse, create);
+        }
+        catch (error) {
+            this.fail(error);
+            throw error;
+        }
+        requireThat(published, "子会话文件已存在。");
+    }
+    create(value, run) {
+        this.check();
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        mkdirSync(this.directory(value.agentId), { mode: 0o700 });
+        for (const dir of ["inbox", "completions"])
+            privateDirectory(this.directory(value.agentId), dir);
+        this.write(value.agentId, "descriptor.json", value, descriptor, true);
+        this.write(value.agentId, "launch.json", run, launch, true);
+        if (this.host === "pi")
+            this.write(value.agentId, "session-ref.json", { file: null }, sessionRef, true);
+        else
+            this.write(value.agentId, "native-session.json", { host: "dsh", sessionId: value.agentId }, dshSessionRef, true);
+    }
+    list() {
+        if (!existsSync(this.root))
+            return [];
+        return readdirSync(this.root, { withFileTypes: true }).filter(e => e.isDirectory() && !e.name.startsWith(".")).flatMap(e => {
+            const d = this.optional(e.name, "descriptor.json", descriptor);
+            return d ? [d] : [];
+        });
+    }
+    messages(id) {
+        return readdirSync(join(this.directory(id), "inbox")).filter(n => n.endsWith(".json"))
+            .map(n => this.read(id, "inbox/" + n, message)).sort((a, b) => a.sequence - b.sequence);
+    }
+    completions(id) {
+        return readdirSync(join(this.directory(id), "completions")).filter(n => n.endsWith(".json"))
+            .map(n => this.read(id, "completions/" + n, cycle)).sort((a, b) => (a.finishedAt ?? 0) - (b.finishedAt ?? 0));
+    }
+    reference(id) {
+        if (this.host === "pi")
+            return { host: "pi", file: this.session(id) };
+        const ref = this.read(id, "native-session.json", dshSessionRef);
+        requireThat(ref.sessionId === id, "dsh 原生会话身份不匹配。");
+        return ref;
+    }
+    session(id) {
+        requireThat(this.host === "pi", "该宿主不使用 Pi 会话文件引用。");
+        const ref = this.optional(id, "session-ref.json", sessionRef);
+        requireThat(ref, "缺少原生会话引用；不导入旧记录，请重新 start。");
+        return ref.file;
+    }
+    /** The child fixes the native path before accepting input; never reset it to null. */
+    bindSession(id, file) {
+        const previous = this.session(id);
+        requireThat(previous === null || previous === file, "子会话文件引用不匹配。");
+        if (previous === null)
+            this.write(id, "session-ref.json", { file }, sessionRef);
+    }
+    /** Short controller edits are serialized; an abandoned lock fails closed. */
+    control(work) {
+        this.check();
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        const path = join(this.root, ".control");
+        try {
+            mkdirSync(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            throw Object.assign(new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关执行实例后手动移除。"), { code: "PBOT_CONTROL_BUSY" });
+        }
+        try {
+            return work();
+        }
+        finally {
+            rmSync(path, { recursive: true });
+        }
+    }
+    enqueue(id, text, delivery, files = [], requestId = randomUUID()) {
+        fileId(requestId);
+        const run = this.read(id, "launch.json", launch), previous = this.optional(id, "inbox/" + requestId + ".json", message);
+        if (previous) {
+            requireThat(previous.generation === run.generation && previous.message === text && previous.delivery === delivery && canonical(previous.files) === canonical(files), "请求 ID 已被不同输入使用。");
+            return previous;
+        }
+        run.sequence++;
+        this.write(id, "launch.json", run, launch);
+        const value = { requestId, generation: run.generation, sequence: run.sequence, message: text, delivery, files };
+        this.write(id, "inbox/" + value.requestId + ".json", value, message, true);
+        return value;
+    }
+}

package/lib/storage/atomic-json.d.ts

@@ -0,0 +1,11 @@
+/** The root must already exist. Never follow aliases inside internal storage. */
+export declare function internalPath(directory: string, relative: string): string;
+export declare function syncDirectory(directory: string): void;
+/** Validators return plain data and must reject incomplete contracts. */
+export declare function readJsonFile<T>(directory: string, relative: string, validate: (value: unknown) => T): T;
+/**
+ * A failure after publication does not mean that the old value remains.
+ * Callers must stop writes/sends on I/O failure, even if a subsequent read succeeds.
+ * createOnly publishes by link, so an existing destination is never overwritten.
+ */
+export declare function writeJsonFile<T>(directory: string, relative: string, value: unknown, validate: (value: unknown) => T, createOnly?: boolean): boolean;