personal-bot 0.0.0-stage → 0.1.0

package/src/extension/subagent-entry.ts

@@ -0,0 +1,181 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { createReadTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TextContent, ImageContent } from "@earendil-works/pi-ai";
+import { AgentFiles, descriptor, launch, status, cycle } from "../storage/agent-files.js";
+import { PythonEnvironmentService } from "../services/workspace/python-environment-service.js";
+import { activatePython } from "../integrations/python-activation.js";
+import { authorizeMutation } from "../services/workspace/workspace-files.js";
+import { agentText } from "../integrations/pi/agent-resources.js";
+import { agentFileTools } from "../integrations/pi/agent-tools.js";
+import { resourceRoot } from "../common/paths.js";
+import { requireThat } from "../common/validation.js";
+import { packageVersion, releaseLine } from "../common/version.js";
+import type { AgentCycle, AgentStatus } from "../model/agent.js";
+
+/** Explicit child composition; never installs main commands or approval capabilities. */
+export default function subagent(pi: ExtensionAPI) {
+  const id = process.env.PBOT_SUBAGENT_RUN_ID, directory = process.env.PBOT_SUBAGENT_DIR, generation = process.env.PBOT_SUBAGENT_GENERATION;
+  requireThat(id && directory && generation, "缺少子会话启动身份。");
+  const files = new AgentFiles(dirname(realpathSync(directory)));
+  requireThat(files.directory(id) === realpathSync(directory), "子会话路径不匹配。");
+  const d = files.read(id, "descriptor.json", descriptor);
+  requireThat(d.agentId === id && releaseLine(d.release) === releaseLine(packageVersion), "子会话身份或版本无效。");
+  requireThat(files.read(id, "launch.json", launch).generation === generation, "子会话启动代次已失效。");
+  const lifetime = new AbortController();
+  let ctx: ExtensionContext | undefined, timer: ReturnType<typeof setInterval> | undefined;
+  let python: PythonEnvironmentService | undefined, restorePython: (() => void) | undefined;
+  let processing = false, closing = false, current: AgentCycle | undefined, startLeaf: string | null = null;
+  let queuedRequests: string[] = [], interactive = false;
+  const accepted = new Set<string>();
+  const saved = files.optional(id, "status.json", status);
+  let snapshot: AgentStatus = { generation, state: "starting", activity: "启动", updatedAt: Date.now() };
+  if (saved?.generation === generation) for (const requestId of saved.accepted ?? []) accepted.add(requestId);
+  let lastActivity = 0;
+  const save = (patch: Partial<AgentStatus>) => {
+    snapshot = { ...snapshot, ...patch, updatedAt: Date.now() };
+    if (current) snapshot.cycle = structuredClone(current);
+    snapshot.accepted = [...accepted];
+    files.write(id, "status.json", snapshot, status);
+  };
+  const ensure = () => {
+    lifetime.signal.throwIfAborted();
+    const run = files.read(id, "launch.json", launch);
+    requireThat(run.generation === generation && !run.stop, "子会话已停止或启动代次变化。");
+    requireThat(python, "子会话尚未就绪。");
+  };
+  const finish = (aborted: boolean) => {
+    if (!ctx || !current) return;
+    const branch = ctx.sessionManager.getBranch();
+    const at = startLeaf === null ? -1 : branch.findIndex(e => e.id === startLeaf);
+    const last = branch.slice(at + 1).filter(e => e.type === "message" && e.message.role === "assistant").at(-1);
+    const assistant = last?.type === "message" && last.message.role === "assistant" ? last.message : undefined;
+    const text = assistant?.content.filter(p => p.type === "text").map(p => p.text).join("\n") ?? "";
+    current = { ...current, finishedAt: Date.now(), leaf: assistant ? ctx.sessionManager.getLeafId() : null,
+      state: aborted ? "cancelled" : assistant?.stopReason === "stop" && text.trim() ? "completed" : "failed",
+      ...(!assistant || assistant.stopReason !== "stop" ? { error: assistant?.errorMessage ?? "没有有效最终回答。" } : {}) };
+    files.write(id, "completions/" + current.cycleId + ".json", current, cycle, true);
+    save({ state: "idle", activity: current.state });
+    current = undefined;
+  };
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    save({ state: "stopping", activity: "停止" });
+    lifetime.abort(); ctx?.abort();
+    await python?.close();
+    ctx?.shutdown();
+  };
+  const pump = async () => {
+    if (processing || !ctx || closing) return;
+    processing = true;
+    try {
+      const run = files.read(id, "launch.json", launch);
+      if (run.generation !== generation || run.stop) { await shutdown(); return; }
+      if (pi.getSessionName() !== run.name) pi.setSessionName(run.name);
+      for (const request of files.messages(id)) {
+        if (request.generation !== generation || accepted.has(request.requestId)) continue;
+        const content: (TextContent | ImageContent)[] = [];
+        for (const path of request.files) {
+          const output = await createReadTool(d.cwd).execute("file-" + request.requestId, { path }, lifetime.signal);
+          content.push(...output.content.filter((p): p is TextContent | ImageContent => p.type === "text" || p.type === "image"));
+        }
+        content.push({ type: "text", text: request.message || "请处理所附文件。" });
+        requireThat(ctx.model, "子会话没有可用模型。");
+        requireThat(ctx.modelRegistry.hasConfiguredAuth(ctx.model) || await ctx.modelRegistry.getProviderAuth(ctx.model.provider), "子会话模型未认证，请配置原生 Pi 认证后显式恢复。");
+        accepted.add(request.requestId);
+        pi.appendEntry("pbot.agent-input", { requestId: request.requestId, generation });
+        if (current) { current.requestIds.push(request.requestId); if (current.source === "interactive") current.source = "mixed"; }
+        else queuedRequests.push(request.requestId);
+        save({ state: "busy", activity: "消息已接收" });
+        pi.sendUserMessage(content, ctx.isIdle() ? {} : { deliverAs: request.delivery });
+        break;
+      }
+    } catch (error) {
+      save({ state: "error", activity: "控制失败", error: String(error) });
+      await shutdown();
+    } finally { processing = false; }
+  };
+  pi.on("resources_discover", async () => {
+    if (d.options.noSkills) return {};
+    const skillPaths = [join(resourceRoot, "skills")];
+    const workspaceSkills = join(d.workspace, ".agents/skills");
+    try {
+      if ((await stat(workspaceSkills)).isDirectory()) skillPaths.push(workspaceSkills);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    return { skillPaths };
+  });
+  pi.on("session_start", async (_event, context) => {
+    ctx = context;
+    try {
+      requireThat(realpathSync(ctx.cwd) === d.cwd && ctx.sessionManager.getSessionFile() === files.session(id), "子会话工作目录或文件不匹配。");
+      for (const entry of ctx.sessionManager.getEntries()) if (entry.type === "custom" && entry.customType === "pbot.agent-input") {
+        const receipt = entry.data as { requestId?: string }; if (receipt.requestId) accepted.add(receipt.requestId);
+      }
+      if (saved?.generation === generation && saved.cycle?.state === "running") {
+        const interrupted: AgentCycle = { ...saved.cycle, state: "interrupted", finishedAt: Date.now() };
+        if (!files.completions(id).some(c => c.cycleId === interrupted.cycleId)) files.write(id, "completions/" + interrupted.cycleId + ".json", interrupted, cycle, true);
+      }
+      const active = pi.getActiveTools();
+      for (const tool of agentFileTools(d.cwd, lifetime.signal, async (path, change, cancel) => {
+        ensure();
+        await authorizeMutation(d.workspace, path, change, async () => false, cancel);
+        ensure();
+      })) pi.registerTool(tool);
+      // Keep the native CLI loadout, including MCP exposure and explicit --tools choices.
+      pi.setActiveTools(active);
+      python = new PythonEnvironmentService(d.workspace);
+      try { const result = await python.setup(lifetime.signal); restorePython = activatePython(result.directory); }
+      catch (error) { ctx.ui.notify(String(error), "warning"); }
+      save({ state: "idle", activity: "空闲" });
+      timer = setInterval(() => void pump(), 250); timer.unref(); void pump();
+    } catch (error) { save({ state: "error", activity: "启动失败", error: String(error) }); ctx.shutdown(); }
+  });
+  pi.on("before_agent_start", async event => {
+    ensure();
+    requireThat(python, "子会话计算环境状态不可用。");
+    event.systemPromptOptions.sections.pbot_environment = JSON.stringify({
+      workspaceRoot: d.workspace, cwd: d.cwd, resourceRoot, python: python.status,
+    });
+    event.systemPromptOptions.sections.pbot_workspace = await readFile(join(resourceRoot, "prompts/workspace.md"), "utf8");
+    event.systemPromptOptions.sections.pbot_child = await agentText("general-purpose", d.workspace);
+  });
+  pi.on("input", event => {
+    if (event.source !== "extension") {
+      if (current) current.source = current.source === "parent" ? "mixed" : current.source;
+      else interactive = true;
+    }
+    return;
+  });
+  pi.on("agent_start", (_event, context) => {
+    ctx = context; startLeaf = ctx.sessionManager.getLeafId();
+    current = { cycleId: randomUUID(), generation, startedAt: Date.now(), state: "running", leaf: null,
+      requestIds: queuedRequests, source: interactive ? queuedRequests.length ? "mixed" : "interactive" : "parent" };
+    queuedRequests = []; interactive = false;
+    save({ state: "busy", activity: "思考" });
+  });
+  pi.on("tool_call", event => {
+    try {
+      ensure();
+      requireThat(event.toolName !== "pbot_agent", "子会话禁止管理和委派。");
+      save({ state: "busy", activity: event.toolName });
+    } catch (error) { return { block: true, reason: String(error) }; }
+    return;
+  });
+  pi.on("message_update", () => { if (current && Date.now() - lastActivity > 1000) { lastActivity = Date.now(); save({ state: "busy", activity: "回答" }); } });
+  pi.on("agent_settled", (event, context) => { ctx = context; finish(event.aborted); });
+  pi.on("session_before_switch", () => ({ cancel: true }));
+  pi.on("session_before_fork", () => ({ cancel: true }));
+  pi.on("session_before_tree", (_event, context) => ({ cancel: !context.isIdle() }));
+  pi.on("session_shutdown", async event => {
+    if (timer) clearInterval(timer); timer = undefined; closing = true; lifetime.abort();
+    if (current) finish(true);
+    await python?.close(); restorePython?.();
+    if (event.reason !== "reload" && snapshot.state !== "error") save({ state: "stopped", activity: "已停止" });
+    ctx = undefined;
+  });
+}

package/src/integrations/pi/agent-context.ts

@@ -0,0 +1,18 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentOwner } from "../../model/agent.js";
+export function agentOwner(ctx: ExtensionContext): AgentOwner {
+  return { sessionId: ctx.sessionManager.getSessionId(), leaf: ctx.sessionManager.getLeafId(), branch: ctx.sessionManager.getBranch().map(e => e.id) };
+}
+export function deliveredCycles(ctx: ExtensionContext): Set<string> {
+  const keys = new Set<string>();
+  for (const entry of ctx.sessionManager.getBranch()) {
+    const data = entry.type === "custom_message" && entry.customType === "pbot.agent-results" ? entry.details
+      : entry.type === "custom" && entry.customType === "pbot.agent-read" ? entry.data : undefined;
+    if (entry.type === "custom" && entry.customType === "pbot.agent-read") {
+      const receipt = entry.data as { toolCallId?: string };
+      if (!ctx.sessionManager.getBranch().some(e => e.type === "message" && e.message.role === "toolResult" && e.message.toolCallId === receipt.toolCallId)) continue;
+    }
+    if (data && typeof data === "object" && "keys" in data && Array.isArray(data.keys)) for (const key of data.keys) if (typeof key === "string") keys.add(key);
+  }
+  return keys;
+}

package/src/integrations/pi/agent-resources.ts

@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resourceRoot } from "../../common/paths.js";
+import { requireThat } from "../../common/validation.js";
+
+export async function agentText(agent: "coordinator" | "general-purpose", root: string) {
+  requireThat(agent === "coordinator" || agent === "general-purpose", "未知职责。");
+  let text = await readFile(join(resourceRoot, "agents", agent + ".md"), "utf8");
+  try {
+    const local = await readFile(join(root, "agents", agent + ".md"), "utf8");
+    text += "\n\n工作区职责补充：\n" + local;
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  requireThat(text.trim(), "专家职责为空。");
+  return text;
+}

package/src/integrations/pi/agent-tools.ts

@@ -0,0 +1,35 @@
+import { access as fileAccess, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { defineTool, createWriteToolDefinition, createEditToolDefinition,
+  type ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+/** Native tools still own parsing, mutation queues and results; authorize at the actual file write. */
+export function agentFileTools(root: string, signal: AbortSignal,
+  authorize: (path: string, change: unknown, signal: AbortSignal) => Promise<void>): ToolDefinition[] {
+  const guardedWrite = (cancel: AbortSignal, parameters: unknown) => async (path: string, content: string) => {
+    await authorize(path, { parameters, content }, cancel);
+    await mkdir(dirname(path), { recursive: true });
+    cancel.throwIfAborted();
+    await writeFile(path, content, "utf8");
+  };
+  return [
+    defineTool({ ...createWriteToolDefinition(root),
+      execute(id, args, inner, update, child) {
+        const cancel = AbortSignal.any([signal, ...(inner ? [inner] : [])]);
+        return createWriteToolDefinition(root, { operations: {
+          // Directory creation belongs to guardedWrite, after authorization.
+          mkdir: async () => {}, writeFile: guardedWrite(cancel, args),
+        } }).execute(id, args, cancel, update, child);
+      },
+    }),
+    defineTool({ ...createEditToolDefinition(root),
+      execute(id, args, inner, update, child) {
+        const cancel = AbortSignal.any([signal, ...(inner ? [inner] : [])]);
+        return createEditToolDefinition(root, { operations: {
+          readFile, access: path => fileAccess(path, constants.R_OK | constants.W_OK), writeFile: guardedWrite(cancel, args),
+        } }).execute(id, args, cancel, update, child);
+      },
+    }),
+  ];
+}

package/src/integrations/pi/pi-agents.ts

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir, getPackageDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { requireThat } from "../../common/validation.js";
+import type { AgentDescriptor } from "../../model/agent.js";
+import type { AgentHost } from "../../services/agents/agent-service.js";
+
+export const agentDirectory = () => join(getAgentDir(), "pbot/subagents");
+export const tmuxName = (id: string) => "pbot-" + id;
+export class PiAgents implements AgentHost {
+  available() {
+    requireThat(spawnSync("tmux", ["-V"], { encoding: "utf8" }).status === 0, "子会话需要 tmux。");
+    requireThat(existsSync(join(getPackageDir(), "dist/cli.js")), "无法定位 Pi CLI。");
+  }
+  alive(id: string) { return spawnSync("tmux", ["has-session", "-t", "=" + tmuxName(id)], { stdio: "ignore" }).status === 0; }
+  kill(id: string) { spawnSync("tmux", ["kill-session", "-t", "=" + tmuxName(id)], { stdio: "ignore" }); }
+  launch(d: AgentDescriptor, directory: string, generation: string) {
+    const o = d.options;
+    const entry = fileURLToPath(new URL("../../extension/subagent-entry.ts", import.meta.url));
+    const compiled = fileURLToPath(new URL("../../extension/subagent-entry.js", import.meta.url));
+    const args = ["--session", join(directory, "session.jsonl"), "--extension", existsSync(entry) ? entry : compiled];
+    if (o.noExtensions !== false) args.push("--no-extensions",
+      "--extension", "builtin:mcp", "--extension", "builtin:codemode", "--extension", "builtin:tool-search");
+    if (o.noSkills) args.push("--no-skills");
+    if (o.noPromptTemplates) args.push("--no-prompt-templates");
+    if (o.noContextFiles) args.push("--no-context-files");
+    // Resume restores native model choices. Explicit model options apply only to a new transcript.
+    if (!existsSync(join(directory, "session.jsonl"))) {
+      args.push("--provider", o.provider!, "--model", o.model!);
+      if (o.thinking) args.push("--thinking", o.thinking);
+    }
+    if (o.tools) args.push("--tools", o.tools.join(","));
+    const result = spawnSync("tmux", ["new-session", "-d", "-s", tmuxName(d.agentId), "-x", "120", "-y", "40", "-c", d.cwd, "--",
+      "env", `PBOT_SUBAGENT_RUN_ID=${d.agentId}`, `PBOT_SUBAGENT_DIR=${directory}`, `PBOT_SUBAGENT_GENERATION=${generation}`,
+      `PI_CODING_AGENT_DIR=${getAgentDir()}`,
+      ...["PATH", "HOME", "XDG_DATA_HOME", "XDG_CONFIG_HOME"].flatMap(key => process.env[key] === undefined ? [] : [`${key}=${process.env[key]}`]),
+      process.execPath, join(getPackageDir(), "dist/cli.js"), ...args], { encoding: "utf8" });
+    requireThat(result.status === 0, result.stderr || "子会话启动失败。");
+  }
+  report(file: string, leaf: string | null) {
+    if (!leaf || !existsSync(file)) return "";
+    const manager = SessionManager.open(file);
+    requireThat(manager.getEntry(leaf), "报告叶节点不存在。");
+    const last = manager.getBranch(leaf).filter(e => e.type === "message" && e.message.role === "assistant").at(-1);
+    return last?.type === "message" && last.message.role === "assistant"
+      ? last.message.content.filter(p => p.type === "text").map(p => p.text).join("\n") : "";
+  }
+}

package/src/integrations/process.ts

@@ -0,0 +1,40 @@
+import { spawn } from "node:child_process";
+import type { Json } from "../common/json.js";
+
+interface ProcessResult {
+  success: boolean;
+  data: Json;
+  raw: Json;
+}
+
+export function processEnvironment(env: Record<string, string>) {
+  return { PATH: process.env.PATH ?? "/usr/bin:/bin", LANG: "C.UTF-8", ...env };
+}
+
+export async function runCommand(command: string, args: string[], input: string | undefined, cwd: string,
+  env: Record<string, string>, signal?: AbortSignal, options: { timeoutMs?: number } = {}): Promise<ProcessResult> {
+  signal?.throwIfAborted();
+  return new Promise(resolve => {
+    const child = spawn(command, args, { cwd, env: processEnvironment(env), shell: false,
+      detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    let bytes = 0, failed = false;
+    const out: Buffer[] = [], err: Buffer[] = [];
+    const kill = () => { if (child.pid) { try { process.kill(-child.pid, "SIGKILL"); } catch { /* Already stopped. */ } } };
+    const stop = () => { failed = true; kill(); };
+    const timer = setTimeout(stop, options.timeoutMs ?? 30_000);
+    signal?.addEventListener("abort", stop, { once: true });
+    const collect = (target: Buffer[]) => (chunk: Buffer) => {
+      bytes += chunk.length; if (bytes > 2 * 1024 * 1024) stop(); else target.push(chunk);
+    };
+    child.stdout.on("data", collect(out)); child.stderr.on("data", collect(err));
+    child.on("error", stop); child.stdin.on("error", stop);
+    child.once("close", code => {
+      clearTimeout(timer); signal?.removeEventListener("abort", stop); kill();
+      const text = Buffer.concat(out).toString("utf8");
+      let data: Json = { stdout: text, stderr: Buffer.concat(err).toString("utf8"), exitCode: code };
+      try { data = JSON.parse(text) as Json; } catch { /* Preserve text and exit code. */ }
+      resolve({ success: !failed && !signal?.aborted && code === 0, data, raw: { stdout: text, stderr: Buffer.concat(err).toString("utf8"), exitCode: code, incomplete: failed || !!signal?.aborted } });
+    });
+    if (signal?.aborted) stop(); child.stdin.end(input);
+  });
+}

package/src/integrations/python-activation.ts

@@ -0,0 +1,23 @@
+import { delimiter, join } from "node:path";
+
+/** Like venv activation, scoped to this Pi process; never edits shell configuration. */
+export function activatePython(directory: string): () => void {
+  const values: Record<string, string | undefined> = {
+    PATH: join(directory, "bin") + delimiter + (process.env.PATH ?? "/usr/bin:/bin"),
+    VIRTUAL_ENV: directory,
+    PYTHONHOME: undefined,
+    PYTHONPATH: undefined,
+    PYTHONNOUSERSITE: "1",
+  };
+  const previous = new Map(Object.keys(values).map(key => [key, process.env[key]]));
+  const assign = (key: string, value: string | undefined) => {
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  };
+  for (const [key, value] of Object.entries(values)) assign(key, value);
+  let restored = false;
+  return () => {
+    if (restored) return;
+    restored = true;
+    for (const [key, value] of previous) if (process.env[key] === values[key]) assign(key, value);
+  };
+}

package/src/model/agent.ts

@@ -0,0 +1,27 @@
+export interface AgentOptions {
+  name?: string; message?: string; files?: string[]; prompts?: string[];
+  provider?: string; model?: string; thinking?: string; cwd?: string; tools?: string[];
+  noExtensions?: boolean; noSkills?: boolean; noPromptTemplates?: boolean; noContextFiles?: boolean;
+}
+export interface AgentOwner { sessionId: string; leaf: string | null; branch: string[] }
+export interface AgentDescriptor {
+  agentId: string; release: string; workspace: string; cwd: string; parentSessionId: string;
+  parentLeaf: string | null; createdAt: number; options: AgentOptions;
+}
+export interface AgentLaunch { generation: string; name: string; sequence: number; stop: boolean; startedAt: number }
+export interface AgentMessage { requestId: string; generation: string; sequence: number; message: string; delivery: "steer" | "followUp"; files: string[] }
+export interface AgentCycle {
+  cycleId: string; generation: string; startedAt: number; finishedAt?: number;
+  state: "running" | "completed" | "failed" | "cancelled" | "interrupted";
+  leaf: string | null; requestIds: string[]; source: "parent" | "interactive" | "mixed";
+  error?: string;
+}
+export interface AgentStatus {
+  generation: string; state: "starting" | "busy" | "idle" | "stopping" | "stopped" | "error";
+  activity: string; updatedAt: number; accepted?: string[]; cycle?: AgentCycle; error?: string;
+}
+export interface AgentView extends AgentDescriptor {
+  name: string; generation: string; state: AgentStatus["state"]; activity: string;
+  cycle?: AgentCycle; error?: string; owned: boolean;
+}
+export interface AgentCompletion { agentId: string; name: string; cycle: AgentCycle; report: string }

package/src/pbot.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PiAgents, agentDirectory } from "./integrations/pi/pi-agents.js";
+import { PythonEnvironmentService } from "./services/workspace/python-environment-service.js";
+import { AgentService } from "./services/agents/agent-service.js";
+import { Confirmations } from "./ui/confirmation.js";
+import { ToolRegistry, mainTools } from "./tools/register.js";
+import { Lifecycle, WorkspaceInstance } from "./extension/lifecycle.js";
+import { registerCommand } from "./extension/command.js";
+import { registerEvents } from "./extension/events.js";
+import { registerAgentEvents } from "./extension/agent-events.js";
+
+export default function pbot(pi: ExtensionAPI) {
+  // The explicitly loaded child entry owns the child; normal discovery never grants main privileges.
+  if (process.env.PBOT_SUBAGENT_RUN_ID) return;
+  const confirmations = new Confirmations(), registry = new ToolRegistry(pi);
+  const lifecycle = new Lifecycle(root => new WorkspaceInstance(root, new PythonEnvironmentService(root),
+    new AgentService(root, agentDirectory(), new PiAgents())),
+  instance => registry.register(mainTools(instance.agents, instance)), () => registry.hide());
+  registerCommand(pi, lifecycle, confirmations);
+  registerEvents(pi, lifecycle, confirmations);
+  registerAgentEvents(pi, lifecycle, confirmations);
+}

package/src/services/agents/agent-service.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { packageVersion, releaseLine } from "../../common/version.js";
+import { requireThat } from "../../common/validation.js";
+import { AgentFiles, descriptor, launch, status, cycle } from "../../storage/agent-files.js";
+import type { AgentOwner, AgentOptions, AgentView, AgentDescriptor, AgentCycle, AgentCompletion } from "../../model/agent.js";
+
+export interface AgentHost {
+  available(): void;
+  alive(id: string): boolean;
+  launch(value: AgentDescriptor, directory: string, generation: string): void;
+  kill(id: string): void;
+  report(file: string, leaf: string | null): string;
+}
+export class AgentService {
+  readonly files: AgentFiles;
+  #closed = false;
+  constructor(readonly root: string, directory: string, readonly host: AgentHost) { this.files = new AgentFiles(directory); }
+  private check() { requireThat(!this.#closed, "子会话服务已关闭。"); }
+  private owned(d: AgentDescriptor, owner: AgentOwner) {
+    return d.workspace === this.root && d.parentSessionId === owner.sessionId && (d.parentLeaf === null || owner.branch.includes(d.parentLeaf));
+  }
+  private get(id: string, owner: AgentOwner) {
+    this.check(); const d = this.files.read(id, "descriptor.json", descriptor);
+    requireThat(this.owned(d, owner), "子会话不属于当前会话分支。");
+    requireThat(releaseLine(d.release) === releaseLine(packageVersion), "子会话版本不兼容；请停止后使用匹配版本。"); return d;
+  }
+  list(owner: AgentOwner): AgentView[] {
+    this.check(); return this.files.list().filter(d => d.workspace === this.root && d.parentSessionId === owner.sessionId).map(d => this.view(d, owner));
+  }
+  private view(d: AgentDescriptor, owner: AgentOwner): AgentView {
+    const run = this.files.read(d.agentId, "launch.json", launch);
+    const saved = this.files.optional(d.agentId, "status.json", status);
+    const current = saved?.generation === run.generation ? saved : undefined;
+    const alive = this.host.alive(d.agentId);
+    return { ...d, name: run.name, generation: run.generation, owned: this.owned(d, owner),
+      state: alive ? run.stop ? "stopping" : current?.state ?? "starting" : current?.state === "error" ? "error" : "stopped",
+      activity: alive ? current?.activity ?? "启动" : current?.error ?? "已停止",
+      ...(current?.cycle ? { cycle: current.cycle } : {}), ...(current?.error ? { error: current.error } : {}) };
+  }
+  start(options: AgentOptions, owner: AgentOwner) {
+    this.check(); this.host.available();
+    options = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined));
+    requireThat(options.provider && options.model, "请选择可在子进程使用的模型。");
+    return this.files.control(() => {
+      requireThat(this.list(owner).filter(v => this.host.alive(v.agentId)).length < 50, "最多 50 个存活子会话；请先停止一个空闲会话。");
+      const agentId = randomUUID();
+      const cwd = realpathSync(resolve(this.root, options.cwd ?? "."));
+      const files = (options.files ?? []).map(p => realpathSync(resolve(this.root, p)));
+      const d: AgentDescriptor = { agentId, release: packageVersion, workspace: this.root, cwd,
+        parentSessionId: owner.sessionId, parentLeaf: owner.leaf, createdAt: Date.now(), options: { ...options, files, cwd } };
+      const run = { generation: randomUUID(), name: options.name ?? agentId.slice(0, 8), sequence: 0, stop: false, startedAt: Date.now() };
+      this.files.create(d, run);
+      const request = this.files.enqueue(agentId, [options.message, ...(options.prompts ?? [])].filter(Boolean).join("\n\n"), "steer", files);
+      try { this.host.launch(d, this.files.directory(agentId), run.generation); }
+      catch (error) {
+        this.files.write(agentId, "status.json", { generation: run.generation, state: "error", activity: "启动失败", updatedAt: Date.now(), error: String(error) }, status);
+        throw error;
+      }
+      return { ...this.view(d, owner), requestId: request.requestId, messageStatus: "queued" as const };
+    });
+  }
+  send(id: string, text: string, delivery: "steer" | "followUp", owner: AgentOwner) {
+    const d = this.get(id, owner);
+    return this.files.control(() => {
+      requireThat(this.host.alive(id) && !this.files.read(id, "launch.json", launch).stop, "子会话已停止，请显式 resume。");
+      const request = this.files.enqueue(id, text, delivery);
+      return { ...this.view(d, owner), requestId: request.requestId, messageStatus: "queued" as const };
+    });
+  }
+  rename(id: string, name: string, owner: AgentOwner) {
+    requireThat(name.trim().length > 0 && name.length <= 64 && !/[\x00-\x1f]/.test(name), "名称必须是 1 到 64 字符的单行文本。");
+    const d = this.get(id, owner);
+    this.files.control(() => { const run = this.files.read(id, "launch.json", launch); run.name = name; this.files.write(id, "launch.json", run, launch); });
+    return this.view(d, owner);
+  }
+  stop(id: string, owner: AgentOwner) {
+    const d = this.get(id, owner); this.requestStop(id); return this.view(d, owner);
+  }
+  private requestStop(id: string) {
+    this.files.control(() => { const run = this.files.read(id, "launch.json", launch); run.stop = true; this.files.write(id, "launch.json", run, launch); });
+  }
+  resume(id: string, text: string, owner: AgentOwner) {
+    const d = this.get(id, owner); this.host.available();
+    return this.files.control(() => {
+      requireThat(!this.host.alive(id), "子会话仍在运行。");
+      requireThat(this.list(owner).filter(v => this.host.alive(v.agentId)).length < 50, "最多 50 个存活子会话。");
+      const previous = this.files.read(id, "launch.json", launch);
+      // The old process is gone: seal its interruption before replacing its generation.
+      for (const ended of this.cycles(id, owner)) {
+        if (ended.generation === previous.generation && !this.files.completions(id).some(c => c.cycleId === ended.cycleId)) {
+          this.files.write(id, "completions/" + ended.cycleId + ".json", ended, cycle, true);
+        }
+      }
+      this.#stopping.delete(id);
+      const run = { ...previous, generation: randomUUID(), sequence: 0, stop: false, startedAt: Date.now() };
+      this.files.write(id, "launch.json", run, launch);
+      const request = this.files.enqueue(id, text, "steer");
+      this.host.launch(d, this.files.directory(id), run.generation);
+      return { ...this.view(d, owner), requestId: request.requestId, messageStatus: "queued" as const };
+    });
+  }
+  cycles(id: string, owner: AgentOwner): AgentCycle[] {
+    const d = this.get(id, owner), view = this.view(d, owner), values = this.files.completions(id);
+    if (view.cycle && !values.some(c => c.cycleId === view.cycle!.cycleId)) {
+      values.push(view.state === "stopped" || view.state === "error" ? { ...view.cycle, state: "interrupted", finishedAt: view.cycle.finishedAt ?? Date.now() } : view.cycle);
+    }
+    if (!values.some(c => c.generation === view.generation) && ["stopped", "error"].includes(view.state)) {
+      const run = this.files.read(id, "launch.json", launch);
+      values.push({ cycleId: run.generation, generation: run.generation, startedAt: run.startedAt, finishedAt: run.startedAt,
+        state: "interrupted", leaf: null, requestIds: [], source: "parent", error: view.error ?? "子进程在交付前退出。" });
+    }
+    return values;
+  }
+  read(id: string, owner: AgentOwner, cycleId?: string, offset = 0, limit = 16000) {
+    const d = this.get(id, owner), cycles = this.cycles(id, owner);
+    const c = cycleId ? cycles.find(v => v.cycleId === cycleId) : cycles.at(-1);
+    requireThat(!cycleId || c, "周期不存在。");
+    const report = c ? this.host.report(this.files.session(id), c.leaf) : "";
+    requireThat(offset <= report.length, "分页位置超出报告。");
+    return { ...this.view(d, owner), ...(c ? { cycle: c } : {}), cycles: cycles.map(v => ({ cycleId: v.cycleId, state: v.state })),
+      report: report.slice(offset, offset + limit), totalLength: report.length, nextOffset: offset + limit < report.length ? offset + limit : null };
+  }
+  completions(owner: AgentOwner): AgentCompletion[] {
+    return this.list(owner).filter(v => v.owned).flatMap(v => this.cycles(v.agentId, owner).filter(c => c.state !== "running").map(c =>
+      ({ agentId: v.agentId, name: v.name, cycle: c, report: this.host.report(this.files.session(v.agentId), c.leaf) })));
+  }
+  /** Called by the parent scanner; stop remains nonblocking to the model. */
+  refresh(owner: AgentOwner) {
+    for (const d of this.files.list().filter(d => d.workspace === this.root && d.parentSessionId === owner.sessionId)) {
+      const run = this.files.read(d.agentId, "launch.json", launch);
+      // A stopped request gets its own grace deadline without modifying child status.
+      if (!run.stop) this.#stopping.delete(d.agentId);
+      if (run.stop && this.host.alive(d.agentId)) {
+        const since = this.#stopping.get(d.agentId) ?? Date.now(); this.#stopping.set(d.agentId, since);
+        if (Date.now() - since > 5000) this.host.kill(d.agentId);
+      }
+    }
+  }
+  readonly #stopping = new Map<string, number>();
+  async close(owner?: AgentOwner, preserve = false) {
+    if (this.#closed) return;
+    if (!preserve && owner) {
+      const ids = this.list(owner).filter(v => this.host.alive(v.agentId)).map(v => v.agentId);
+      for (const id of ids) this.requestStop(id);
+      const deadline = Date.now() + 5000;
+      while (ids.some(id => this.host.alive(id)) && Date.now() < deadline) await new Promise(r => setTimeout(r, 100));
+      for (const id of ids) if (this.host.alive(id)) this.host.kill(id);
+    }
+    this.#closed = true;
+  }
+}

package/src/services/workspace/python-environment-service.ts

@@ -0,0 +1,44 @@
+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 {
+  readonly #shutdown = new AbortController();
+  #pending: Promise<{ directory: string; python: string }> | undefined;
+  #status: { state: "unprepared" | "preparing" | "ready" | "error"; directory?: string; error?: string } = { state: "unprepared" };
+  constructor(private readonly root: string) {}
+  get status() { return { ...this.#status }; }
+
+  setup(signal?: AbortSignal): Promise<{ directory: string; python: string }> {
+    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: Record<string, string> = {};
+        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(): Promise<void> {
+    this.#shutdown.abort();
+    await this.#pending?.catch(() => undefined);
+  }
+}

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

@@ -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: string, target: string): "outside" | "inside" {
+  const rel = relative(root, target);
+  if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) return "outside";
+  return "inside";
+}
+export async function authorizeMutation(root: string, path: string, change: unknown,
+  confirm: (value: unknown) => Promise<boolean>, signal: AbortSignal) {
+  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, "确认期间文件路径已变化。");
+}