personal-bot 0.0.0-stage → 0.1.0

package/src/services/workspace/workspace-preparation.ts

@@ -0,0 +1,17 @@
+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: string) {
+  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/src/storage/agent-files.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { 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";
+import type { AgentDescriptor, AgentLaunch, AgentMessage, AgentStatus, AgentCycle } from "../model/agent.js";
+
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+const number = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+export function descriptor(v: unknown): AgentDescriptor {
+  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 as string); return v as unknown as AgentDescriptor;
+}
+export function launch(v: unknown): AgentLaunch {
+  requireThat(object(v) && text(v.generation) && text(v.name) && Number.isSafeInteger(v.sequence) && typeof v.stop === "boolean" && number(v.startedAt), "子会话启动状态无效。");
+  return v as unknown as AgentLaunch;
+}
+export function message(v: unknown): AgentMessage {
+  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 as unknown as AgentMessage;
+}
+export function cycle(v: unknown): AgentCycle {
+  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 as unknown as AgentCycle;
+}
+export function status(v: unknown): AgentStatus {
+  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 as unknown as AgentStatus;
+}
+export class AgentFiles {
+  constructor(readonly root: string) {}
+  directory(id: string) { return join(this.root, fileId(id)); }
+  read<T>(id: string, path: string, parse: (v: unknown) => T): T { return readJsonFile(this.directory(id), path, parse); }
+  optional<T>(id: string, path: string, parse: (v: unknown) => T): T | undefined {
+    try { return this.read(id, path, parse); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+  }
+  write<T>(id: string, path: string, value: T, parse: (v: unknown) => T, create = false) {
+    requireThat(writeJsonFile(this.directory(id), path, value, parse, create), "子会话文件已存在。");
+  }
+  create(value: AgentDescriptor, run: AgentLaunch) {
+    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);
+  }
+  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: string) {
+    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: string) {
+    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));
+  }
+  session(id: string) { return join(realpathSync(this.directory(id)), "session.jsonl"); }
+  /** Short controller edits are serialized; an abandoned lock fails closed. */
+  control<T>(work: () => T): T {
+    mkdirSync(this.root, { recursive: true, mode: 0o700 });
+    const path = join(this.root, ".control");
+    try { mkdirSync(path, { mode: 0o700 }); }
+    catch { throw new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关 Pi 后手动移除。"); }
+    try { return work(); } finally { rmSync(path, { recursive: true }); }
+  }
+  enqueue(id: string, text: string, delivery: AgentMessage["delivery"], files: string[] = []) {
+    const run = this.read(id, "launch.json", launch); run.sequence++;
+    this.write(id, "launch.json", run, launch);
+    const value: AgentMessage = { requestId: randomUUID(), generation: run.generation, sequence: run.sequence, message: text, delivery, files };
+    this.write(id, "inbox/" + value.requestId + ".json", value, message, true); return value;
+  }
+}

package/src/storage/atomic-json.ts

@@ -0,0 +1,74 @@
+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: string, relative: string): string {
+  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 as NodeJS.ErrnoException).code !== "ENOENT" || index !== parts.length - 1) throw error;
+    }
+  }
+  return path;
+}
+
+export function syncDirectory(directory: string): void {
+  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<T>(directory: string, relative: string, validate: (value: unknown) => T): T {
+  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: unknown;
+    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<T>(directory: string, relative: string, value: unknown,
+  validate: (value: unknown) => T, createOnly = false): boolean {
+  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 as NodeJS.ErrnoException).code === "EEXIST") return false; throw error; }
+    } else renameSync(temporary, path);
+    syncDirectory(parent);
+    return true;
+  } finally {
+    try { unlinkSync(temporary); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+}

package/src/storage/file-access.ts

@@ -0,0 +1,19 @@
+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: string) {
+  requireThat(/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id), "内部记录 ID 无效。"); return id;
+}
+export function privateDirectory(root: string, relative: string) {
+  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 as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    requireThat(lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink(), "内部状态目录无效。"); parent = path;
+  }
+}

package/src/tools/access.ts

@@ -0,0 +1,7 @@
+
+/** Each tool is bound to one workspace instance, not a mutable global lookup. */
+export interface CallAccess {
+  check(): void;
+  signal(signal?: AbortSignal): AbortSignal;
+  authorizeFile(path: string, change: unknown, confirm: (value: unknown) => Promise<boolean>, signal: AbortSignal): Promise<void>;
+}

package/src/tools/agents/contract.ts

@@ -0,0 +1,54 @@
+import { Type } from "typebox";
+const id = Type.String({ minLength: 1, maxLength: 128 });
+const message = Type.String({ minLength: 1, maxLength: 24000, description: "本次目标、交付要求、资料依据与约束。" });
+const name = Type.String({ minLength: 1, maxLength: 64, pattern: "^[^\\r\\n\\x00-\\x1f]+$" });
+const options = {
+  name: Type.Optional(name), message: Type.Optional(message),
+  files: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { maxItems: 32, description: "随初始消息读取的文件；相对路径基于原工作区根目录。" })),
+  prompts: Type.Optional(Type.Array(message, { maxItems: 32, description: "与 message 按顺序合并为同一初始消息，不是多个执行轮次。" })),
+  provider: Type.Optional(Type.String({ ...id, description: "Pi 模型提供方，默认继承主会话。" })),
+  model: Type.Optional(Type.String({ ...id, description: "子进程可用的 Pi 模型 ID，默认继承主会话。" })),
+  thinking: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh"), Type.Literal("max")], { description: "默认继承主会话思考级别。" })),
+  cwd: Type.Optional(Type.String({ minLength: 1, description: "执行目录，相对原工作区根目录；省略时使用工作区根目录。" })),
+  tools: Type.Optional(Type.Array(id, { minItems: 1, description: "按 Pi 原生规则选择工具，省略时沿用原生默认工具；MCP 工具遵循原生暴露设置。不提供递归委派；这不是宿主隔离。" })),
+  noExtensions: Type.Optional(Type.Boolean({ description: "默认 true，不发现其他扩展。" })),
+  noSkills: Type.Optional(Type.Boolean({ description: "关闭技能发现，默认 false。" })),
+  noPromptTemplates: Type.Optional(Type.Boolean({ description: "关闭提示模板发现，默认 false。" })),
+  noContextFiles: Type.Optional(Type.Boolean({ description: "关闭 Pi 原生上下文文件加载，默认 false。" })),
+};
+const page = {
+  cycleId: Type.Optional(Type.String({ ...id, description: "read 的历史工作周期；省略时读取最近周期。" })),
+  offset: Type.Optional(Type.Integer({ minimum: 0, description: "报告字符偏移，默认 0。" })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000, description: "最多返回字符数，默认 16000。" })),
+};
+const delivery = Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("followUp")], { description: "send 默认 steer 补充当前工作；followUp 排到当前工作之后。" }));
+export const agentParametersSchema = Type.Object({
+  action: Type.Union([Type.Literal("start"), Type.Literal("send"), Type.Literal("rename"), Type.Literal("status"), Type.Literal("list"), Type.Literal("read"), Type.Literal("stop"), Type.Literal("resume")], {
+    description: "start 至少提供 message/prompts/files 之一，其余启动选项仅用于 start。list 不带其他字段；其余操作须 agentId。send/resume 须 message，rename 须 name；分页仅用于 read。",
+  }),
+  agentId: Type.Optional(id), ...options, ...page, delivery,
+}, { additionalProperties: false });
+export const agentActionSchema = Type.Union([
+  Type.Object({ action: Type.Literal("start"), ...options }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("send"), agentId: id, message, delivery }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("rename"), agentId: id, name }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("resume"), agentId: id, message }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("list") }, { additionalProperties: false }),
+  ...["stop", "status"].map(action => Type.Object({ action: Type.Literal(action), agentId: id }, { additionalProperties: false })),
+  Type.Object({ action: Type.Literal("read"), agentId: id, ...page }, { additionalProperties: false }),
+]);
+
+const cycle = Type.Object({ cycleId: Type.String(), startedAt: Type.Number(), finishedAt: Type.Optional(Type.Number()),
+  state: Type.Union([Type.Literal("running"), Type.Literal("completed"), Type.Literal("failed"), Type.Literal("cancelled"), Type.Literal("interrupted")], { description: "本周期的工作结果；completed 仍须核验实际交付。" }),
+  requestIds: Type.Array(Type.String()),
+  source: Type.Union([Type.Literal("parent"), Type.Literal("interactive"), Type.Literal("mixed")]), error: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+export const agentViewSchema = Type.Object({ agentId: Type.String(), name: Type.String(), cwd: Type.String(), createdAt: Type.Number(),
+  owned: Type.Boolean({ description: "是否属于当前父会话分支；false 时须回到所属分支操作。" }),
+  state: Type.Union([Type.Literal("starting"), Type.Literal("busy"), Type.Literal("idle"), Type.Literal("stopping"), Type.Literal("stopped"), Type.Literal("error")], { description: "进程状态；idle 不代表上轮工作成功，结果见 cycle.state。" }),
+  activity: Type.String(), cycle: Type.Optional(cycle), error: Type.Optional(Type.String()),
+  requestId: Type.Optional(Type.String()), messageStatus: Type.Optional(Type.Literal("queued", { description: "消息已入队，不代表模型已阅读或完成。" })),
+  cycles: Type.Optional(Type.Array(Type.Object({ cycleId: Type.String(), state: Type.String() }))),
+  report: Type.Optional(Type.String()), totalLength: Type.Optional(Type.Integer()), nextOffset: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
+}, { additionalProperties: false });
+export const agentResultSchema = Type.Union([agentViewSchema, Type.Object({ agents: Type.Array(agentViewSchema) }, { additionalProperties: false })]);

package/src/tools/agents/tool.ts

@@ -0,0 +1,60 @@
+import type { Static } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import { agentOwner } from "../../integrations/pi/agent-context.js";
+import type { AgentOptions, AgentView } from "../../model/agent.js";
+import type { CallAccess } from "../access.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { result } from "../result.js";
+import { agentActionSchema, agentParametersSchema, agentResultSchema, agentViewSchema } from "./contract.js";
+
+type AgentOutput = Static<typeof agentViewSchema>;
+function agentOutput(view: AgentView & Partial<AgentOutput>): AgentOutput {
+  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 function agentTool(service: AgentService, access: CallAccess) {
+  const valid = schema(agentActionSchema);
+  return defineTool({ name: "pbot_agent", label: "子会话",
+    description: "独立 Pi 子会话，不继承父聊天历史。start 立即返回，完成自动通知，无需轮询。send 继续对话，rename 改名，status/list 查看状态，read 非阻塞读取报告。state 是进程状态，cycle.state 是工作结果，queued 仅表示入队。stop 停止并保留历史，resume 携新 message 恢复，不重放旧工作。独立复核须 start 新上下文。子会话使用原生 CLI/MCP，按委派范围工作，不递归委派。每个父会话最多 50 个存活子会话，空闲也计入。",
+    parameters: agentParametersSchema, outputSchema: agentResultSchema,
+    async execute(_id, args, signal, _update, ctx) {
+      access.check(); signal?.throwIfAborted();
+      requireThat(valid(args), "子会话参数不符合所选 action；请核对必要字段。");
+      const input = args as Static<typeof agentParametersSchema>, owner = agentOwner(ctx);
+      let value: AgentView & Partial<AgentOutput>;
+      switch (input.action) {
+        case "start": {
+          requireThat(input.message || input.prompts?.length || input.files?.length, "start 需要 message、prompts 或 files。");
+          const { action: _action, ...supplied } = input;
+          value = service.start({ provider: ctx.model?.provider, model: ctx.model?.id, thinking: ctx.thinkingLevel, ...supplied } as AgentOptions, owner); break;
+        }
+        case "list": return result({ 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 = service.resume(input.agentId!, input.message!, owner); break;
+        case "stop": value = service.stop(input.agentId!, owner); break;
+        case "status": value = service.read(input.agentId!, owner, undefined, 0, 1); break;
+        case "read": {
+          const page = service.read(input.agentId!, owner, input.cycleId, input.offset, input.limit);
+          const data = agentOutput(page), output = result(data);
+          return { ...output, details: { ...data, ...(page.cycle && page.cycle.state !== "running" ? { agentReadKeys: [page.agentId + ":" + page.cycle.cycleId] } : {}) } };
+        }
+      }
+      return result(agentOutput(value));
+    },
+  });
+}

package/src/tools/register.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { resourceRoot } from "../common/paths.js";
+import type { AgentService } from "../services/agents/agent-service.js";
+import type { CallAccess } from "./access.js";
+import { agentTool } from "./agents/tool.js";
+
+export function mainTools(agents: AgentService, access: CallAccess): ToolDefinition[] {
+  return [agentTool(agents, access)];
+}
+export class ToolRegistry {
+  readonly #registered = new Map<string, ToolDefinition>();
+  constructor(private readonly pi: ExtensionAPI) {}
+  register(tools: ToolDefinition[]) {
+    const promptGuidelines = readFileSync(join(resourceRoot, "prompts/tool-guidelines.md"), "utf8")
+      .trim().split(/\r?\n\s*\r?\n/);
+    for (const definition of tools) {
+      const tool = { ...definition, namespace: { name: "pbot", description: "Personal Bot 独立子会话工具。" },
+        promptGuidelines };
+      this.#registered.set(tool.name, tool); this.pi.registerTool(tool);
+    }
+  }
+  hide() {
+    for (const tool of this.#registered.values()) this.pi.registerTool({ ...tool, exposure: "hidden" });
+  }
+}

package/src/tools/result.ts

@@ -0,0 +1,7 @@
+import { json } from "../common/json.js";
+
+export function result(value: unknown, isError = false, text?: string) {
+  const data = json(value);
+  return { content: [{ type: "text" as const, text: text ?? JSON.stringify(data) }],
+    details: data, structuredContent: data, ...(isError ? { isError: true } : {}) };
+}

package/src/ui/agent-display.ts

@@ -0,0 +1,11 @@
+import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { AgentView } from "../model/agent.js";
+export const agentSummary = (v: AgentView) => `${v.name} · ${v.agentId.slice(0, 8)} · ${v.state} · ${v.activity.replace(/\s+/g, " ")}`;
+export function agentBoard(values: AgentView[], theme: Theme): Component {
+  return { invalidate() {}, render(width) {
+    return values.filter(v => ["starting", "busy", "stopping"].includes(v.state)).map(v => truncateToWidth(
+      theme.fg("accent", "● " + v.name) + theme.fg("dim", ` · ${v.state} · ${Math.max(0, Math.floor((Date.now() - (v.cycle?.startedAt ?? v.createdAt)) / 1000))}s · `) +
+      v.activity.replace(/\s+/g, " "), Math.max(1, width)));
+  } };
+}

package/src/ui/confirmation.ts

@@ -0,0 +1,162 @@
+import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { ScrollView, SelectList, Text, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { requireThat } from "../common/validation.js";
+
+/** One confirmation owns its viewport, selection, and abort listener. */
+export class ConfirmationDialog implements Component {
+  private readonly details: Text;
+  private readonly scroll: ScrollView;
+  private readonly choices: SelectList;
+  private finished = false;
+  private usable = false;
+  private showingRaw = false;
+  private readonly abort = () => this.finish(false);
+
+  constructor(
+    private readonly title: string,
+    private readonly text: string,
+    private readonly theme: Theme,
+    private readonly keys: KeybindingsManager,
+    private readonly rows: () => number,
+    private readonly requestRender: () => void,
+    private readonly done: (allowed: boolean) => void,
+    private readonly signal?: AbortSignal,
+    private readonly summary?: string,
+  ) {
+    this.details = new Text(summary ?? text, 0, 0);
+    this.scroll = new ScrollView(this.details, { overscroll: "contain" });
+    this.choices = new SelectList([{ value: "allow", label: "确认" }, { value: "cancel", label: "取消" }], 2, {
+      selectedPrefix: text => theme.fg("accent", text),
+      selectedText: text => theme.fg("accent", text),
+      description: text => theme.fg("muted", text),
+      scrollInfo: text => theme.fg("dim", text),
+      noMatch: text => theme.fg("dim", text),
+    });
+    this.choices.setSelectedIndex(0);
+    this.choices.onSelect = item => this.finish(item.value === "allow");
+    this.choices.onCancel = () => this.finish(false);
+    signal?.addEventListener("abort", this.abort, { once: true });
+    if (signal?.aborted) this.finish(false);
+  }
+
+  private finish(allowed: boolean) {
+    if (this.finished) return;
+    this.finished = true;
+    this.dispose();
+    this.done(allowed && this.usable && !this.signal?.aborted);
+  }
+
+  dispose() { this.signal?.removeEventListener("abort", this.abort); }
+
+  invalidate() {
+    this.details.invalidate();
+    this.choices.invalidate();
+  }
+
+  render(width: number): string[] {
+    const height = Math.max(1, Math.floor(this.rows() * 0.7));
+    this.usable = width >= 24 && height >= 10;
+    if (!this.usable) {
+      return new Text("窗口过小；请放大终端。Esc 取消。", 0, 0).render(Math.max(1, width)).slice(0, height);
+    }
+    const innerWidth = width - 4;
+    const content = this.scroll.render(innerWidth);
+    const viewport = Math.min(content.length, height - (this.summary === undefined ? 8 : 9));
+    this.scroll.updateLayout(content.length, viewport, this.requestRender);
+    const start = this.scroll.scrollTop;
+    const visible = content.slice(start, start + viewport);
+    const lines = [
+      this.theme.fg("accent", truncateToWidth(this.title, innerWidth)),
+      ...visible,
+      this.theme.fg("dim", truncateToWidth(`${start + 1}–${Math.min(start + viewport, content.length)} / ${content.length}`, innerWidth)),
+      ...this.choices.render(innerWidth),
+      this.theme.fg("dim", truncateToWidth("↑↓滚动详情 PgUp/PgDn翻页", innerWidth)),
+      this.theme.fg("dim", truncateToWidth("Tab切换选项 Enter选 Esc取消", innerWidth)),
+      ...(this.summary === undefined ? [] : [this.theme.fg("dim", truncateToWidth(this.showingRaw ? "D 查看摘要" : "D 查看完整配置", innerWidth))]),
+    ];
+    const border = (text: string) => this.theme.fg("accent", text);
+    return [
+      border(`╭${"─".repeat(width - 2)}╮`),
+      ...lines.map(line => `${border("│")} ${truncateToWidth(line, innerWidth, "", true)} ${border("│")}`),
+      border(`╰${"─".repeat(width - 2)}╯`),
+    ];
+  }
+
+  handleInput(data: string) {
+    if (this.finished) return;
+    if (this.keys.matches(data, "tui.select.cancel") || matchesKey(data, "ctrl+c")) {
+      this.finish(false); return;
+    }
+    if (!this.usable) return;
+    if (matchesKey(data, "d") && this.summary !== undefined) {
+      this.showingRaw = !this.showingRaw;
+      this.details.setText(this.showingRaw ? this.text : this.summary);
+      this.scroll.scrollToStart();
+      this.choices.setSelectedIndex(0);
+    } else if (this.keys.matches(data, "tui.select.up")) this.scroll.scrollBy(-1);
+    else if (this.keys.matches(data, "tui.select.down")) this.scroll.scrollBy(1);
+    else if (matchesKey(data, "pageUp")) this.scroll.scrollBy(-this.scroll.viewportHeight);
+    else if (matchesKey(data, "pageDown")) this.scroll.scrollBy(this.scroll.viewportHeight);
+    else if (matchesKey(data, "home")) this.scroll.scrollToStart();
+    else if (matchesKey(data, "end")) this.scroll.scrollToEnd();
+    else if (matchesKey(data, "tab") || matchesKey(data, "shift+tab")) {
+      this.choices.setSelectedIndex(this.choices.getSelectedItem()?.value === "cancel" ? 0 : 1);
+    } else if (this.keys.matches(data, "tui.select.confirm")) this.finish(this.choices.getSelectedItem()?.value === "allow");
+    this.requestRender();
+  }
+}
+
+export async function ask(ctx: ExtensionContext, title: string, value: unknown, signal?: AbortSignal, summary?: string): Promise<boolean> {
+  requireThat(ctx.hasUI, "此操作需要用户确认通道，非交互模式不能授权。");
+  signal?.throwIfAborted();
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  // RPC clients own their layout. Keep the complete payload separate from the title.
+  const allowed = ctx.mode === "tui"
+    ? await ctx.ui.custom<boolean>((tui, theme, keys, done) => new ConfirmationDialog(
+      title, text, theme, keys, () => tui.terminal.rows, () => tui.requestRender(), done, signal, summary,
+    ), { overlay: true, overlayOptions: { width: "80%", anchor: "center" } })
+    : await ctx.ui.confirm(title, summary === undefined ? text : `${summary}\n\n完整配置：\n${text}`, signal ? { signal } : {});
+  signal?.throwIfAborted();
+  return allowed === true;
+}
+
+export class Confirmations {
+  #queue: Promise<unknown> = Promise.resolve();
+  #epoch = new AbortController();
+  #paused = false;
+  #presenting = false;
+  get presenting() { return this.#presenting; }
+  readonly #resumes = new Set<() => void>();
+  pause() { this.#paused = true; this.#epoch.abort(); }
+  resume() {
+    if (!this.#paused) return;
+    this.#paused = false; this.#epoch = new AbortController();
+    for (const resume of this.#resumes) resume();
+  }
+  async ready(signal?: AbortSignal) {
+    signal?.throwIfAborted();
+    if (!this.#paused) return;
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => { this.#resumes.delete(resume); signal?.removeEventListener("abort", abort); };
+      const resume = () => { cleanup(); resolve(); };
+      const abort = () => { cleanup(); reject(signal?.reason); };
+      this.#resumes.add(resume); signal?.addEventListener("abort", abort, { once: true });
+    });
+    signal?.throwIfAborted();
+  }
+  async ask(ctx: ExtensionContext, title: string, value: unknown, signal?: AbortSignal, summary?: string,
+    recheck?: () => Promise<void>): Promise<boolean> {
+    requireThat(ctx.hasUI, "此操作需要用户确认通道，非交互模式不能授权。");
+    await this.ready(signal);
+    const cancel = AbortSignal.any([this.#epoch.signal, ...(signal ? [signal] : [])]);
+    const pending = this.#queue.then(async () => {
+      cancel.throwIfAborted(); await recheck?.(); cancel.throwIfAborted();
+      this.#presenting = true;
+      try { return await ask(ctx, title, value, cancel, summary); }
+      finally { this.#presenting = false; }
+    });
+    this.#queue = pending.catch(() => undefined);
+    return pending;
+  }
+}