personal-bot 0.2.3 → 0.2.5

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;

package/lib/storage/atomic-json.js

@@ -0,0 +1,101 @@
+import { constants, closeSync, fstatSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { canonical } from "../common/json.js";
+import { requireThat } from "../common/validation.js";
+/** The root must already exist. Never follow aliases inside internal storage. */
+export function internalPath(directory, relative) {
+    const parts = relative.split("/");
+    requireThat(parts.every(part => part && part !== "." && part !== ".." && !/[\\\x00-\x1f]/.test(part)), "内部状态路径无效。");
+    const info = lstatSync(directory);
+    requireThat(info.isDirectory() && !info.isSymbolicLink(), "内部状态必须使用普通目录。");
+    let path = realpathSync(directory);
+    for (const [index, part] of parts.entries()) {
+        path = join(path, part);
+        try {
+            const info = lstatSync(path);
+            requireThat(!info.isSymbolicLink() && (index === parts.length - 1 ? info.isFile() : info.isDirectory()), "内部状态不能使用符号链接或特殊文件。");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || index !== parts.length - 1)
+                throw error;
+        }
+    }
+    return path;
+}
+export function syncDirectory(directory) {
+    const fd = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Validators return plain data and must reject incomplete contracts. */
+export function readJsonFile(directory, relative, validate) {
+    const path = internalPath(directory, relative);
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        requireThat(fstatSync(fd).isFile(), "内部状态必须是普通文件。");
+        let value;
+        try {
+            value = JSON.parse(readFileSync(fd, "utf8"));
+        }
+        catch (error) {
+            throw new Error("内部 JSON 文件不可读取：" + relative, { cause: error });
+        }
+        return validate(value);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * 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 function writeJsonFile(directory, relative, value, validate, createOnly = false) {
+    const validated = validate(value);
+    // Check before touching disk: JSON.stringify alone silently drops unsupported values.
+    const expected = canonical(validated);
+    const content = JSON.stringify(validated, null, 2) + "\n";
+    requireThat(canonical(JSON.parse(content)) === expected, "JSON 序列化不能改变状态值。");
+    const path = internalPath(directory, relative), parent = dirname(path);
+    const temporary = join(parent, `.tmp-${randomUUID()}`);
+    const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            writeFileSync(fd, content, "utf8");
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        requireThat(internalPath(directory, relative) === path, "内部状态路径已变化。");
+        if (createOnly) {
+            try {
+                linkSync(temporary, path);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    return false;
+                throw error;
+            }
+        }
+        else
+            renameSync(temporary, path);
+        syncDirectory(parent);
+        return true;
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}

package/lib/storage/file-access.d.ts

@@ -0,0 +1,2 @@
+export declare function fileId(id: string): string;
+export declare function privateDirectory(root: string, relative: string): void;

package/lib/storage/file-access.js

@@ -0,0 +1,26 @@
+import { lstatSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { requireThat } from "../common/validation.js";
+import { syncDirectory } from "./atomic-json.js";
+export function fileId(id) {
+    requireThat(/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id), "内部记录 ID 无效。");
+    return id;
+}
+export function privateDirectory(root, relative) {
+    const parts = relative.split("/");
+    let parent = root;
+    for (const part of parts) {
+        fileId(part);
+        const path = join(parent, part);
+        try {
+            mkdirSync(path, { mode: 0o700 });
+            syncDirectory(parent);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        requireThat(lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink(), "内部状态目录无效。");
+        parent = path;
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { HistoryHost, HistoryRecord } from "../model/history.js";
+export declare class HistoryFiles {
+    readonly directory: string;
+    readonly host: HistoryHost;
+    constructor(directory: string, host?: HistoryHost);
+    list(workspace?: string): HistoryRecord[];
+    /** The callback is synchronous: no SDK reads or model work can hold this source's write lock. */
+    control<T>(operation: () => T): T;
+    save(value: HistoryRecord): void;
+}

package/lib/storage/history-files.js

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, readdirSync, rmdirSync } from "node:fs";
+import { join } from "node:path";
+import { object } from "../common/json.js";
+import { requireThat } from "../common/validation.js";
+import { readJsonFile, writeJsonFile } from "./atomic-json.js";
+import { fileId } from "./file-access.js";
+const strings = (value) => Array.isArray(value) && value.every(item => typeof item === "string");
+function record(value) {
+    requireThat(object(value) && typeof value.id === "string" && typeof value.sessionId === "string" &&
+        typeof value.name === "string" && Array.isArray(value.nodes), "历史索引无效。");
+    for (const node of value.nodes)
+        requireThat(object(node) && typeof node.id === "string" &&
+            ["session", "exchange", "summary"].includes(String(node.kind)) && Number.isInteger(node.level) &&
+            strings(node.entryIds) && strings(node.parents) && strings(node.children) && typeof node.text === "string" &&
+            typeof node.from === "string" && typeof node.to === "string" && typeof node.ready === "boolean" && typeof node.completed === "boolean", "历史节点无效。");
+    const result = value, ids = new Set(result.nodes.map(node => node.id));
+    requireThat(ids.size === result.nodes.length && result.nodes.some(node => node.id === result.id && node.kind === "session") &&
+        result.nodes.every(node => [...node.parents, ...node.children].every(id => ids.has(id))), "历史节点关系无效。");
+    return result;
+}
+export class HistoryFiles {
+    directory;
+    host;
+    constructor(directory, host = "pi") {
+        this.directory = directory;
+        this.host = host;
+    }
+    list(workspace) {
+        if (!existsSync(this.directory))
+            return [];
+        return readdirSync(this.directory).filter(name => name.endsWith(".json"))
+            .map(name => readJsonFile(this.directory, name, value => {
+            const result = record(value);
+            requireThat(this.host !== "dsh" || result.id.startsWith("dsh-"), "dsh 历史根 ID 缺少来源前缀。");
+            return result;
+        }))
+            .filter(value => workspace === undefined || ("workspace" in value && value.workspace === workspace));
+    }
+    /** The callback is synchronous: no SDK reads or model work can hold this source's write lock. */
+    control(operation) {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const lock = join(this.directory, ".write");
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw Object.assign(new Error("历史来源写锁被占用：" + this.host), { code: "PBOT_HISTORY_BUSY" });
+            throw error;
+        }
+        try {
+            return operation();
+        }
+        finally {
+            rmdirSync(lock);
+        }
+    }
+    save(value) {
+        requireThat(this.host !== "dsh" || value.id.startsWith("dsh-"), "dsh 历史根 ID 缺少来源前缀。");
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        writeJsonFile(this.directory, fileId(value.id) + ".json", value, record);
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { TeamRecord, TeamReady, TeamLink } from "../model/team.js";
+import { AgentFiles } from "./agent-files.js";
+export declare function teamReady(v: unknown): TeamReady;
+export declare function teamRecord(v: unknown): TeamRecord;
+export declare class TeamFiles {
+    readonly agents: AgentFiles;
+    readonly root: string;
+    constructor(agents: AgentFiles);
+    check(): void;
+    read(id: string): TeamRecord;
+    list(): TeamRecord[];
+    save(value: TeamRecord, create?: boolean): void;
+    ready(id: string): TeamReady | undefined;
+    setReady(id: string, generation: string, ready: boolean): void;
+    links(records?: TeamRecord[]): Map<string, TeamLink>;
+}

package/lib/storage/team-files.js

@@ -0,0 +1,111 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { object } from "../common/json.js";
+import { requireThat } from "../common/validation.js";
+import { AgentFiles } from "./agent-files.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 integer = (v, min = 0) => Number.isSafeInteger(v) && v >= min;
+export function teamReady(v) {
+    requireThat(object(v) && text(v.generation) && typeof v.ready === "boolean", "团队就绪标记无效。");
+    return v;
+}
+export function teamRecord(v) {
+    requireThat(object(v) && text(v.teamId) && text(v.release) && text(v.workspace) && text(v.parentSessionId) &&
+        (v.parentLeaf === null || text(v.parentLeaf)) && text(v.name) && text(v.brief) && typeof v.closed === "boolean" &&
+        Array.isArray(v.members) && v.members.length > 0 && v.members.length <= 50 && Array.isArray(v.runs) && Array.isArray(v.messages), "团队记录无效。");
+    fileId(v.teamId);
+    const members = new Set(), runs = new Set(), requests = new Map(), operations = new Set();
+    for (const m of v.members) {
+        requireThat(object(m) && text(m.agentId) && text(m.role) && !members.has(m.agentId), "团队成员无效或重复。");
+        fileId(m.agentId);
+        members.add(m.agentId);
+    }
+    let running = 0;
+    for (const r of v.runs) {
+        requireThat(object(r) && text(r.runId) && !runs.has(r.runId) && text(r.instruction) &&
+            ["roundRobin", "parallel"].includes(String(r.mode)) && integer(r.rounds, 1) && r.rounds <= 10 &&
+            integer(r.maxConcurrent, 1) && r.maxConcurrent <= members.size && (r.mode !== "roundRobin" || r.maxConcurrent === 1) &&
+            integer(r.deadlineAt, 1) && ["running", "paused", "finished"].includes(String(r.state)) &&
+            (r.reason === undefined || text(r.reason)) && object(r.generations) && Array.isArray(r.issued), "团队批次无效。");
+        fileId(r.runId);
+        runs.add(r.runId);
+        requireThat(Object.keys(r.generations).length === members.size && [...members].every(id => text(r.generations[id])), "团队代次无效。");
+        if (r.state === "running")
+            running++;
+        const turns = new Set();
+        for (const q of r.issued) {
+            requireThat(object(q) && text(q.requestId) && !requests.has(q.requestId) && text(q.agentId) && members.has(q.agentId) &&
+                q.generation === r.generations[q.agentId] && integer(q.round, 1) && q.round <= r.rounds &&
+                integer(q.throughSeq) && q.throughSeq <= v.messages.length && !turns.has(q.agentId + ":" + q.round), "团队请求关联无效。");
+            fileId(q.requestId);
+            requests.set(q.requestId, { agentId: q.agentId, runId: r.runId });
+            turns.add(q.agentId + ":" + q.round);
+        }
+    }
+    requireThat(running <= 1 && (!v.closed || running === 0), "团队运行状态冲突。");
+    for (const [i, m] of v.messages.entries()) {
+        requireThat(object(m) && m.seq === i + 1 && text(m.operationId) && !operations.has(m.operationId) && typeof m.text === "string" &&
+            object(m.author) && ["user", "coordinator", "member"].includes(String(m.author.kind)) && text(m.author.name) &&
+            (m.author.kind === "member" ? text(m.author.agentId) && members.has(m.author.agentId) : m.author.agentId === undefined) &&
+            (m.replyTo === undefined || (integer(m.replyTo, 1) && m.replyTo <= i)) &&
+            (m.runId === undefined || (text(m.runId) && runs.has(m.runId))), "团队消息无效。");
+        if (m.source !== undefined)
+            requireThat(object(m.source) && text(m.source.requestId) && text(m.source.cycleId) &&
+                requests.get(m.source.requestId)?.agentId === m.author.agentId && requests.get(m.source.requestId)?.runId === m.runId, "团队报告关联无效。");
+        operations.add(m.operationId);
+    }
+    return v;
+}
+export class TeamFiles {
+    agents;
+    root;
+    constructor(agents) {
+        this.agents = agents;
+        this.root = join(dirname(agents.root), "teams");
+    }
+    check() { this.agents.check(); }
+    read(id) {
+        const value = readJsonFile(this.root, fileId(id) + "/team.json", teamRecord);
+        requireThat(value.teamId === id, "团队路径与身份不匹配。");
+        return value;
+    }
+    list() {
+        if (!existsSync(this.root))
+            return [];
+        return readdirSync(this.root, { withFileTypes: true }).filter(e => !e.name.startsWith(".")).map(e => this.read(e.name));
+    }
+    save(value, create = false) {
+        this.check();
+        teamRecord(value);
+        let published;
+        try {
+            mkdirSync(this.root, { recursive: true, mode: 0o700 });
+            const directory = lstatSync(this.root);
+            requireThat(directory.isDirectory() && !directory.isSymbolicLink(), "团队状态必须使用普通目录。");
+            if (create)
+                privateDirectory(this.root, fileId(value.teamId));
+            published = writeJsonFile(this.root, fileId(value.teamId) + "/team.json", value, teamRecord, create);
+        }
+        catch (error) {
+            this.agents.fail(error);
+            throw error;
+        }
+        requireThat(published, "团队已存在。");
+    }
+    ready(id) { return this.agents.optional(id, "team-ready.json", teamReady); }
+    setReady(id, generation, ready) {
+        this.agents.write(id, "team-ready.json", { generation, ready }, teamReady);
+    }
+    links(records = this.list()) {
+        const result = new Map();
+        for (const team of records)
+            for (const run of team.runs)
+                for (const request of run.issued) {
+                    requireThat(!result.has(request.requestId), "团队请求 ID 重复。");
+                    result.set(request.requestId, { team, run, request });
+                }
+        return result;
+    }
+}

package/lib/tools/agents/actions.d.ts

@@ -0,0 +1,52 @@
+import type { Static } from "typebox";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import type { AgentOptions, AgentOwner } from "../../model/agent.js";
+import type { agentParametersSchema } from "./contract.js";
+export type AgentInput = Omit<Static<typeof agentParametersSchema>, "thinking"> & {
+    thinking?: string;
+};
+export declare function executeAgent(service: AgentService, input: AgentInput, owner: AgentOwner, defaults?: AgentOptions): Promise<{
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: import("../../common/json.js").Json;
+    structuredContent: import("../../common/json.js").Json;
+} | {
+    details: {
+        agentReadKeys?: string[];
+        error?: string;
+        requestId?: string;
+        cycle?: {
+            error?: string;
+            finishedAt?: number;
+            state: "running" | "completed" | "failed" | "cancelled" | "interrupted";
+            startedAt: number;
+            cycleId: string;
+            requestIds: string[];
+            source: "parent" | "interactive" | "mixed";
+        };
+        report?: string;
+        messageStatus?: "queued";
+        cycles?: {
+            state: string;
+            cycleId: string;
+        }[];
+        totalLength?: number;
+        nextOffset?: number | null;
+        state: "starting" | "busy" | "idle" | "stopping" | "stopped" | "error";
+        agentId: string;
+        cwd: string;
+        createdAt: number;
+        name: string;
+        activity: string;
+        owned: boolean;
+    };
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: import("../../common/json.js").Json;
+}>;

package/lib/tools/agents/actions.js

@@ -0,0 +1,49 @@
+import { markdownResult } from "../result.js";
+function agentOutput(view) {
+    const c = view.cycle;
+    return {
+        agentId: view.agentId, name: view.name, cwd: view.cwd, createdAt: view.createdAt,
+        owned: view.owned, state: view.state, activity: view.activity,
+        ...(c ? { cycle: { cycleId: c.cycleId, startedAt: c.startedAt, state: c.state, requestIds: c.requestIds, source: c.source,
+                ...(c.finishedAt === undefined ? {} : { finishedAt: c.finishedAt }), ...(c.error === undefined ? {} : { error: c.error }) } } : {}),
+        ...(view.error === undefined ? {} : { error: view.error }),
+        ...(view.requestId === undefined ? {} : { requestId: view.requestId }),
+        ...(view.messageStatus === undefined ? {} : { messageStatus: view.messageStatus }),
+        ...(view.cycles === undefined ? {} : { cycles: view.cycles }),
+        ...(view.report === undefined ? {} : { report: view.report }),
+        ...(view.totalLength === undefined ? {} : { totalLength: view.totalLength }),
+        ...(view.nextOffset === undefined ? {} : { nextOffset: view.nextOffset }),
+    };
+}
+export async function executeAgent(service, input, owner, defaults = {}) {
+    let value;
+    switch (input.action) {
+        case "start": {
+            const { action: _action, ...supplied } = input;
+            value = await service.start({ ...defaults, ...supplied }, owner);
+            break;
+        }
+        case "list": return markdownResult({ agents: service.list(owner).map(agentOutput) }, "子会话列表");
+        case "send":
+            value = service.send(input.agentId, input.message, input.delivery ?? "steer", owner);
+            break;
+        case "rename":
+            value = service.rename(input.agentId, input.name, owner);
+            break;
+        case "resume":
+            value = await service.resume(input.agentId, input.message, owner);
+            break;
+        case "stop":
+            value = service.stop(input.agentId, owner);
+            break;
+        case "status":
+            value = service.status(input.agentId, owner);
+            break;
+        case "read": {
+            const page = await service.read(input.agentId, owner, input.cycleId, input.offset, input.limit);
+            const data = agentOutput(page), output = markdownResult(data, "子会话报告");
+            return { ...output, details: { ...data, ...(page.cycle && page.cycle.state !== "running" ? { agentReadKeys: [page.agentId + ":" + page.cycle.cycleId] } : {}) } };
+        }
+    }
+    return markdownResult(agentOutput(value), "子会话状态");
+}