personal-bot 0.1.2 → 0.2.0

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

@@ -0,0 +1,274 @@
+import { randomUUID } from "node:crypto";
+import { requireThat } from "../../common/validation.js";
+import { packageVersion, releaseLine } from "../../common/version.js";
+import { AgentFiles, descriptor, launch, status, message } from "../../storage/agent-files.js";
+import { TeamFiles } from "../../storage/team-files.js";
+import type { AgentCompletion, AgentOwner } from "../../model/agent.js";
+import type { TeamActor, TeamAgent, TeamInput, TeamLink, TeamMessage, TeamRecord, TeamRunOptions } from "../../model/team.js";
+
+/** Team decisions only. The parent dispatches returned inputs through AgentService. */
+export class TeamService {
+  #failure: unknown;
+  #disposed = false;
+  readonly #recovered = new Set<string>();
+  constructor(readonly root: string, readonly agents: AgentFiles, readonly files: TeamFiles) {}
+  check() { requireThat(!this.#disposed, "团队服务已关闭。"); this.files.check(); if (this.#failure) throw this.#failure; }
+  fail(error: unknown) { this.#failure = error; }
+  dispose() { this.#disposed = true; }
+  private owned(team: TeamRecord, owner: AgentOwner) {
+    return team.workspace === this.root && team.parentSessionId === owner.sessionId && (team.parentLeaf === null || owner.branch.includes(team.parentLeaf));
+  }
+  private records(sessionId?: string) {
+    this.check();
+    return this.files.list().filter(t => t.workspace === this.root && releaseLine(t.release) === releaseLine(packageVersion) &&
+      (!sessionId || t.parentSessionId === sessionId));
+  }
+  private get(id: string, actor: TeamActor) {
+    this.check(); const team = this.files.read(id);
+    requireThat(team.workspace === this.root && releaseLine(team.release) === releaseLine(packageVersion), "团队工作区或版本不匹配。");
+    if (actor.kind === "member") {
+      const d = this.agents.read(actor.agentId, "descriptor.json", descriptor), run = this.agents.read(actor.agentId, "launch.json", launch);
+      requireThat(d.workspace === this.root && d.parentSessionId === team.parentSessionId && team.members.some(m => m.agentId === actor.agentId) &&
+        run.generation === actor.generation && !run.stop, "团队成员身份已失效。");
+    } else requireThat(this.owned(team, actor.owner), "团队不属于当前会话分支。");
+    return team;
+  }
+  private member(id: string, owner: AgentOwner, views: TeamAgent[]) {
+    const v = views.find(v => v.agentId === id), d = this.agents.read(id, "descriptor.json", descriptor);
+    requireThat(v && v.owned && d.workspace === this.root && d.parentSessionId === owner.sessionId &&
+      (d.parentLeaf === null || owner.branch.includes(d.parentLeaf)), "成员不属于当前分支：" + id);
+    requireThat(releaseLine(d.release) === releaseLine(packageVersion), "成员版本不兼容：" + id);
+    return v;
+  }
+  private requests(team: TeamRecord, views: TeamAgent[]) {
+    const states = new Map(team.members.map(m => [m.agentId, { view: views.find(v => v.agentId === m.agentId),
+      saved: this.agents.optional(m.agentId, "status.json", status),
+      cycles: new Map(this.agents.completions(m.agentId).flatMap(c => c.requestIds.map(id => [c.generation + ":" + id, c] as const))) }]));
+    return team.runs.flatMap(run => run.issued.map(q => {
+      const s = states.get(q.agentId)!, ended = s.cycles.get(q.generation + ":" + q.requestId);
+      const accepted = s.saved?.generation === q.generation && !!s.saved.accepted?.includes(q.requestId);
+      const active = !ended && accepted && !!s.view?.alive && s.view.generation === q.generation;
+      let outcome: string | undefined = ended?.state;
+      if (ended && ended.source !== "parent") outcome = ended.source;
+      else if (outcome === "completed" && !team.messages.some(m => m.source?.requestId === q.requestId)) outcome = "unpublished";
+      return { requestId: q.requestId, agentId: q.agentId, runId: run.runId, round: q.round, active,
+        state: outcome ?? (active ? "accepted" : accepted ? "uncertain" : run.state === "running" ? "queued" : "cancelled"),
+        ...(ended ? { cycleId: ended.cycleId } : {}) };
+    }));
+  }
+  private active(team: TeamRecord, views: TeamAgent[]) { return this.requests(team, views).filter(q => q.active); }
+  private available(id: string, owner: AgentOwner, views: TeamAgent[], links: Map<string, TeamLink>) {
+    const v = this.member(id, owner, views), run = this.agents.read(id, "launch.json", launch);
+    const saved = this.agents.optional(id, "status.json", status), ready = this.files.ready(id);
+    const available = (condition: unknown, message: string): void => {
+      if (!condition) throw Object.assign(new Error(message), { code: "TEAM_NOT_READY" });
+    };
+    available(v.alive && v.state === "idle" && !run.stop && v.generation === run.generation && saved?.generation === run.generation && saved.state === "idle", "成员尚未空闲：" + id);
+    available(ready?.ready && ready.generation === run.generation, "成员需加载新版子入口：" + id);
+    available(!this.agents.messages(id).some(q => q.generation === run.generation && !saved?.accepted?.includes(q.requestId) && !links.has(q.requestId)), "成员有待处理私人输入：" + id);
+    return v;
+  }
+  create(owner: AgentOwner, input: Pick<TeamRecord, "name" | "brief" | "members">, views: TeamAgent[]) {
+    this.check();
+    return this.agents.control(() => {
+      const records = this.records();
+      for (const m of input.members) {
+        this.member(m.agentId, owner, views);
+        requireThat(!records.some(t => !t.closed && t.members.some(v => v.agentId === m.agentId)), "成员已属于未关闭团队：" + m.agentId);
+      }
+      const team: TeamRecord = { ...input, members: structuredClone(input.members), teamId: randomUUID(), release: packageVersion,
+        workspace: this.root, parentSessionId: owner.sessionId, parentLeaf: owner.leaf, closed: false, runs: [], messages: [] };
+      this.files.save(team, true); return team;
+    });
+  }
+  run(id: string, owner: AgentOwner, options: TeamRunOptions, views: TeamAgent[]) {
+    this.check();
+    return this.agents.control(() => {
+      const team = this.get(id, { kind: "coordinator", owner }), links = this.files.links(this.records());
+      requireThat(!team.closed && !team.runs.some(r => r.state === "running") && !this.active(team, views).length, "团队仍在工作或已关闭。");
+      const members = team.members.map(m => this.available(m.agentId, owner, views, links));
+      requireThat(options.mode !== "roundRobin" || options.maxConcurrent === undefined || options.maxConcurrent === 1, "轮流讨论并发须为 1。");
+      const rounds = options.rounds ?? 2, maxConcurrent = options.mode === "roundRobin" ? 1 : options.maxConcurrent ?? Math.min(2, members.length);
+      requireThat(Number.isInteger(rounds) && rounds >= 1 && rounds <= 10 && Number.isInteger(maxConcurrent) && maxConcurrent >= 1 && maxConcurrent <= members.length, "轮次或并发无效。");
+      const seconds = options.timeoutSeconds ?? 900;
+      requireThat(Number.isInteger(seconds) && seconds >= 1 && seconds <= 86400, "期限须为 1–86400 秒。");
+      requireThat(options.instruction.trim().length > 0, "新批次需要新的明确要求。");
+      const run = { runId: randomUUID(), instruction: options.instruction, mode: options.mode, rounds, maxConcurrent,
+        deadlineAt: Date.now() + seconds * 1000, generations: Object.fromEntries(members.map(v => [v.agentId, v.generation])),
+        state: "running" as const, issued: [] };
+      team.runs.push(run); this.files.save(team); return run;
+    });
+  }
+  pause(id: string, owner: AgentOwner, reason = "主会话暂停") {
+    this.check(); this.agents.control(() => { const team = this.get(id, { kind: "coordinator", owner }); this.pauseRecord(team, reason); });
+  }
+  private pauseRecord(team: TeamRecord, reason: string) {
+    let changed = false;
+    for (const run of team.runs) if (run.state === "running") { run.state = "paused"; run.reason = reason; changed = true; }
+    if (changed) this.files.save(team);
+  }
+  pauseAll(owner: AgentOwner, reason: string) {
+    this.check(); this.agents.control(() => { for (const team of this.records(owner.sessionId)) this.pauseRecord(team, reason); });
+  }
+  recover(owner: AgentOwner) {
+    if (this.#recovered.has(owner.sessionId)) return;
+    this.pauseAll(owner, "主会话恢复：未自动续排旧批次"); this.#recovered.add(owner.sessionId);
+  }
+  pauseMember(agentId: string, reason: string) {
+    this.check(); this.agents.control(() => { for (const team of this.records()) if (team.members.some(m => m.agentId === agentId)) this.pauseRecord(team, reason); });
+  }
+  close(id: string, owner: AgentOwner, views: TeamAgent[]) {
+    this.check(); this.agents.control(() => {
+      const team = this.get(id, { kind: "coordinator", owner });
+      requireThat(!team.runs.some(r => r.state === "running") && !this.active(team, views).length, "先暂停团队并等待在途工作结束。");
+      if (!team.closed) { team.closed = true; this.files.save(team); }
+    });
+  }
+  post(id: string, actor: TeamActor, operationId: string, text: string, replyTo?: number) {
+    this.check(); requireThat(text.trim().length > 0 && text.length <= 24000 && operationId.length > 0, "消息须为 1–24000 字符。");
+    operationId = actor.kind === "member" ? "post:" + actor.agentId + ":" + actor.generation + ":" + operationId : "post:" + actor.kind + ":" + actor.owner.sessionId + ":" + operationId;
+    return this.agents.control(() => {
+      const team = this.get(id, actor);
+      const prior = team.messages.find(m => m.operationId === operationId);
+      if (prior) {
+        requireThat(prior.text === text && prior.replyTo === replyTo && prior.author.kind === actor.kind &&
+          (actor.kind !== "member" || prior.author.agentId === actor.agentId), "发布操作 ID 冲突。"); return prior;
+      }
+      requireThat(!team.closed, "团队已关闭。");
+      requireThat(replyTo === undefined || team.messages.some(m => m.seq === replyTo), "回复目标不存在。");
+      let runId: string | undefined;
+      if (actor.kind === "member") {
+        const run = team.runs.find(r => r.issued.some(q => q.requestId === actor.requestId && q.agentId === actor.agentId && q.generation === actor.generation));
+        const saved = this.agents.optional(actor.agentId, "status.json", status);
+        requireThat(run && saved?.generation === actor.generation && saved.cycle?.state === "running" && saved.cycle.source === "parent" &&
+          !!actor.requestId && saved.cycle.requestIds.includes(actor.requestId), "只能在自己的团队工作中发言。"); runId = run.runId;
+      }
+      const value: TeamMessage = { seq: team.messages.length + 1, operationId, text,
+        author: actor.kind === "member" ? { kind: "member", agentId: actor.agentId, name: this.agents.read(actor.agentId, "launch.json", launch).name }
+          : { kind: actor.kind, name: actor.kind === "user" ? "用户" : "主会话" },
+        ...(replyTo === undefined ? {} : { replyTo }), ...(runId ? { runId } : {}) };
+      team.messages.push(value); this.files.save(team); return value;
+    });
+  }
+  read(id: string, actor: TeamActor, page: { afterSeq?: number; seq?: number; offset?: number; limit?: number } = {}) {
+    const team = this.get(id, actor), limit = page.limit ?? 16000, after = page.afterSeq ?? 0, offset = page.offset ?? 0;
+    requireThat(Number.isInteger(limit) && limit >= 1 && limit <= 16000 && Number.isInteger(after) && after >= 0 && after <= team.messages.length &&
+      Number.isInteger(offset) && offset >= 0 && (page.seq !== undefined || offset === 0), "分页参数无效。");
+    const values = page.seq === undefined ? team.messages.filter(m => m.seq > after) : team.messages.filter(m => m.seq === page.seq);
+    requireThat(page.seq === undefined || values.length === 1, "消息不存在。");
+    let left = limit;
+    const messages = [];
+    for (const m of values) {
+      const at = page.seq === undefined ? 0 : offset;
+      requireThat(at <= m.text.length, "消息分页位置超出范围。");
+      const text = m.text.slice(at, at + left); left -= Math.max(1, text.length);
+      messages.push({ ...m, text, offset: at, totalLength: m.text.length, nextOffset: at + text.length < m.text.length ? at + text.length : null });
+      if (left <= 0) break;
+    }
+    const last = messages.at(-1)?.seq ?? after;
+    return { teamId: id, messages, lastSeq: team.messages.length, nextAfterSeq: page.seq === undefined && last < team.messages.length ? last : null };
+  }
+  status(id: string, owner: AgentOwner, views: TeamAgent[]) {
+    return this.summary(this.get(id, { kind: "coordinator", owner }), owner, views);
+  }
+  list(owner: AgentOwner, views: TeamAgent[]) { return this.records(owner.sessionId).map(t => this.summary(t, owner, views)); }
+  private summary(team: TeamRecord, owner: AgentOwner, views: TeamAgent[]) {
+    const identity = { teamId: team.teamId, name: team.name, closed: team.closed };
+    if (!this.owned(team, owner)) return { ...identity, owned: false as const };
+    const run = team.runs.at(-1), requests = this.requests(team, views), activeCount = requests.filter(q => q.active).length;
+    return { ...identity, brief: team.brief, owned: true as const,
+      members: team.members.map(m => { const v = views.find(v => v.agentId === m.agentId); return { ...m, name: v?.name ?? m.agentId, state: v?.state ?? "stopped" }; }),
+      lastSeq: team.messages.length, activeCount, unresolved: requests.filter(q => q.state !== "completed"),
+      ...(run ? { run: { runId: run.runId, instruction: run.instruction, mode: run.mode, state: run.state, rounds: run.rounds,
+        maxConcurrent: run.maxConcurrent, deadlineAt: run.deadlineAt, scheduled: run.issued.length,
+        published: team.messages.filter(m => m.runId === run.runId && m.source).length, ...(run.reason ? { reason: run.reason } : {}) } } : {}) };
+  }
+  links() { return this.files.links(this.records()); }
+  /** The callback persists the existing child receipt while the shared control lock is held. */
+  claim(agentId: string, generation: string, requestId: string, commit: () => void): TeamLink | undefined {
+    this.check();
+    return this.agents.control(() => {
+      const link = this.links().get(requestId), run = this.agents.read(agentId, "launch.json", launch), ready = this.files.ready(agentId);
+      const saved = this.agents.optional(agentId, "status.json", status), input = this.agents.optional(agentId, "inbox/" + requestId + ".json", message);
+      if (!link || link.request.agentId !== agentId || link.request.generation !== generation || run.generation !== generation || run.stop ||
+        !ready?.ready || ready.generation !== generation || saved?.generation !== generation || saved.state !== "idle" ||
+        saved.accepted?.includes(requestId) || input?.generation !== generation || link.team.closed || link.run.state !== "running" || link.run.deadlineAt <= Date.now()) return;
+      for (const member of link.team.members) {
+        const memberRun = this.agents.read(member.agentId, "launch.json", launch), memberReady = this.files.ready(member.agentId);
+        if (memberRun.stop || memberRun.generation !== link.run.generations[member.agentId] || !memberReady?.ready || memberReady.generation !== memberRun.generation) return;
+      }
+      commit(); return link;
+    });
+  }
+  advance(owner: AgentOwner, views: TeamAgent[], completions: AgentCompletion[]): TeamInput[] {
+    this.check();
+    return this.agents.control(() => {
+      const inputs: TeamInput[] = [], records = this.records(owner.sessionId), links = this.files.links(records);
+      for (const team of records) {
+        let changed = false;
+        for (const run of team.runs) {
+          for (const q of run.issued) {
+            const done = completions.find(v => v.agentId === q.agentId && v.cycle.generation === q.generation && v.cycle.requestIds.includes(q.requestId));
+            if (!done) continue;
+            if (done.cycle.state !== "completed" || done.cycle.source !== "parent" || done.cycle.requestIds.length !== 1 || !done.report.trim()) {
+              if (run.state === "running") { run.state = "paused"; run.reason = "成员失败或人工接管：" + q.agentId; changed = true; }
+            } else if (!team.messages.some(m => m.source?.requestId === q.requestId)) {
+              team.messages.push({ seq: team.messages.length + 1, operationId: "result:" + q.requestId,
+                author: { kind: "member", agentId: q.agentId, name: done.name }, text: done.report, runId: run.runId,
+                source: { requestId: q.requestId, cycleId: done.cycle.cycleId } }); changed = true;
+            }
+          }
+          if (run.state !== "running") continue;
+          const unavailable = team.members.find(m => {
+            const v = views.find(v => v.agentId === m.agentId), ready = this.files.ready(m.agentId);
+            return !v?.alive || !v.owned || v.generation !== run.generations[m.agentId] || !ready?.ready || ready.generation !== v.generation ||
+              ["stopping", "stopped", "error"].includes(v.state) || (v.cycle?.state === "running" && v.cycle.source !== "parent");
+          });
+          if (!this.owned(team, owner) || unavailable || Date.now() >= run.deadlineAt) {
+            run.state = "paused"; run.reason = !this.owned(team, owner) ? "当前分支无团队归属" : unavailable ? "成员不可用：" + unavailable.agentId : "已到期限";
+            changed = true; continue;
+          }
+          const finished = new Set(team.messages.filter(m => m.runId === run.runId && m.source).map(m => m.source!.requestId));
+          const outstanding = run.issued.filter(q => !finished.has(q.requestId));
+          const round = Math.max(1, ...run.issued.map(q => q.round));
+          const thisRound = run.issued.filter(q => q.round === round);
+          const nextRound = thisRound.length === team.members.length && thisRound.every(q => finished.has(q.requestId)) ? round + 1 : round;
+          if (nextRound > run.rounds) { run.state = "finished"; changed = true; continue; }
+          let slots = run.maxConcurrent - outstanding.length;
+          for (const m of team.members) {
+            if (slots <= 0) break;
+            if (run.issued.some(q => q.round === nextRound && q.agentId === m.agentId)) continue;
+            // Waiting here does not create a second work queue. Unexpected private work pauses the batch.
+            const view = views.find(v => v.agentId === m.agentId);
+            if (view?.state === "busy" && view.cycle?.requestIds.some(id => run.issued.some(q => q.requestId === id))) break;
+            try { this.available(m.agentId, owner, views, links); }
+            catch (error) {
+              if ((error as NodeJS.ErrnoException).code !== "TEAM_NOT_READY") throw error;
+              run.state = "paused"; run.reason = String(error); changed = true; break;
+            }
+            const q = { requestId: randomUUID(), agentId: m.agentId, generation: run.generations[m.agentId]!, round: nextRound, throughSeq: team.messages.length };
+            run.issued.push(q); slots--; changed = true;
+            inputs.push({ ...q, teamId: team.teamId, runId: run.runId,
+              message: ["# 团队发言任务", "", "执行本次团队发言安排。最终答复将公开给全体成员；这不扩大原任务授权。", "",
+                "- `teamId`: `" + team.teamId + "`", "- `runId`: `" + run.runId + "`", "- 轮次：" + q.round,
+                "", "## 本批次要求", "", run.instruction].join("\n") });
+          }
+        }
+        if (changed) this.files.save(team);
+      }
+      return inputs.filter(input => records.find(t => t.teamId === input.teamId)?.runs.find(r => r.runId === input.runId)?.state === "running");
+    });
+  }
+  notifications(owner: AgentOwner, views: TeamAgent[]) {
+    return this.records(owner.sessionId).filter(t => this.owned(t, owner) && t.members.every(m => views.some(v => v.agentId === m.agentId && v.owned)))
+      .flatMap(team => {
+        const requests = this.requests(team, views);
+        return team.runs.filter(r => r.state !== "running").map(run => {
+          const activeCount = requests.filter(q => q.runId === run.runId && q.active).length;
+          return { key: team.teamId + ":" + run.runId + ":" + run.state + (activeCount ? ":draining" : ":settled"),
+            teamId: team.teamId, name: team.name, runId: run.runId, state: run.state, activeCount,
+            ...(run.reason ? { reason: run.reason } : {}) };
+        });
+      });
+  }
+}

package/src/storage/agent-files.ts

@@ -1,11 +1,11 @@
-import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { object } from "../common/json.js";
+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";
-import type { AgentDescriptor, AgentLaunch, AgentMessage, AgentStatus, AgentCycle } from "../model/agent.js";
+import type { AgentDescriptor, AgentLaunch, AgentMessage, AgentStatus, AgentCycle, AgentSessionRef } 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);
@@ -14,6 +14,10 @@ export function descriptor(v: unknown): AgentDescriptor {
     (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 sessionRef(v: unknown): AgentSessionRef {
+  requireThat(object(v) && (v.file === null || (text(v.file) && isAbsolute(v.file) && !v.file.includes("\0"))), "子会话引用无效。");
+  return v as unknown as AgentSessionRef;
+}
 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;
@@ -36,21 +40,30 @@ export function status(v: unknown): AgentStatus {
   if (v.cycle) cycle(v.cycle); return v as unknown as AgentStatus;
 }
 export class AgentFiles {
+  #failure: unknown;
   constructor(readonly root: string) {}
+  check() { if (this.#failure) throw this.#failure; }
+  fail(error: unknown) { this.#failure = error; }
   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), "子会话文件已存在。");
+    this.check(); parse(value);
+    let published: boolean;
+    try { published = writeJsonFile(this.directory(id), path, value, parse, create); }
+    catch (error) { this.fail(error); throw error; }
+    requireThat(published, "子会话文件已存在。");
   }
   create(value: AgentDescriptor, run: AgentLaunch) {
+    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);
+    this.write(value.agentId, "session-ref.json", { file: null }, sessionRef, true);
   }
   list() {
     if (!existsSync(this.root)) return [];
@@ -66,19 +79,39 @@ export class AgentFiles {
     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"); }
+  session(id: string): string | null {
+    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: string, file: string) {
+    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<T>(work: () => T): T {
+    this.check();
     mkdirSync(this.root, { recursive: true, mode: 0o700 });
     const path = join(this.root, ".control");
     try { mkdirSync(path, { mode: 0o700 }); }
-    catch { throw new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关 Pi 后手动移除。"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      throw Object.assign(new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关 Pi 后手动移除。"), { code: "PBOT_CONTROL_BUSY" });
+    }
     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++;
+  enqueue(id: string, text: string, delivery: AgentMessage["delivery"], files: string[] = [], requestId: string = 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: AgentMessage = { requestId: randomUUID(), generation: run.generation, sequence: run.sequence, message: text, delivery, files };
+    const value: AgentMessage = { requestId, 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/team-files.ts

@@ -0,0 +1,93 @@
+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 type { TeamRecord, TeamReady, TeamLink } from "../model/team.js";
+import { AgentFiles } from "./agent-files.js";
+import { readJsonFile, writeJsonFile } from "./atomic-json.js";
+import { fileId, privateDirectory } from "./file-access.js";
+
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+const integer = (v: unknown, min = 0): v is number => Number.isSafeInteger(v) && (v as number) >= min;
+export function teamReady(v: unknown): TeamReady {
+  requireThat(object(v) && text(v.generation) && typeof v.ready === "boolean", "团队就绪标记无效。");
+  return v as unknown as TeamReady;
+}
+export function teamRecord(v: unknown): TeamRecord {
+  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<string>(), runs = new Set<string>(), requests = new Map<string, { agentId: string; runId: string }>(), operations = new Set<string>();
+  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 as Record<string, unknown>)[id])), "团队代次无效。");
+    if (r.state === "running") running++;
+    const turns = new Set<string>();
+    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 as unknown as TeamRecord;
+}
+export class TeamFiles {
+  readonly root: string;
+  constructor(readonly agents: AgentFiles) { this.root = join(dirname(agents.root), "teams"); }
+  check() { this.agents.check(); }
+  read(id: string) {
+    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: TeamRecord, create = false) {
+    this.check(); teamRecord(value);
+    let published: boolean;
+    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: string) { return this.agents.optional(id, "team-ready.json", teamReady); }
+  setReady(id: string, generation: string, ready: boolean) {
+    this.agents.write(id, "team-ready.json", { generation, ready }, teamReady);
+  }
+  links(records = this.list()): Map<string, TeamLink> {
+    const result = new Map<string, TeamLink>();
+    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/src/tools/agents/contract.ts

@@ -24,7 +24,7 @@ const page = {
 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。",
+    description: "start 可省略 message/prompts/files，只创建待命进程；启动选项仅用于 start。list 不带其他字段；其余操作须 agentId。send/resume 须 message，rename 须 name；分页仅用于 read。",
   }),
   agentId: Type.Optional(id), ...options, ...page, delivery,
 }, { additionalProperties: false });

package/src/tools/agents/tool.ts

@@ -5,7 +5,7 @@ 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 { markdownResult } from "../result.js";
 import { agentActionSchema, agentParametersSchema, agentResultSchema, agentViewSchema } from "./contract.js";
 
 type AgentOutput = Static<typeof agentViewSchema>;
@@ -29,7 +29,7 @@ function agentOutput(view: AgentView & Partial<AgentOutput>): AgentOutput {
 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 个存活子会话，空闲也计入。",
+    description: "独立 Pi 子会话，不继承父聊天历史。start 立即返回；未提供 message/prompts/files 时只启动待命进程，不调用模型。完成自动通知，无需轮询。团队占用期间不能私人 send。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();
@@ -38,11 +38,10 @@ export function agentTool(service: AgentService, access: CallAccess) {
       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 "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 = service.resume(input.agentId!, input.message!, owner); break;
@@ -50,11 +49,11 @@ export function agentTool(service: AgentService, access: CallAccess) {
         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);
+          const data = agentOutput(page), output = markdownResult(data, "子会话报告");
           return { ...output, details: { ...data, ...(page.cycle && page.cycle.state !== "running" ? { agentReadKeys: [page.agentId + ":" + page.cycle.cycleId] } : {}) } };
         }
       }
-      return result(agentOutput(value));
+      return markdownResult(agentOutput(value), "子会话状态");
     },
   });
 }

package/src/tools/register.ts

@@ -5,9 +5,12 @@ 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";
+import type { TeamService } from "../services/agents/team-service.js";
+import { teamTool, teamMessageTool } from "./teams/tool.js";
+import { agentOwner } from "../integrations/pi/agent-context.js";
 
-export function mainTools(agents: AgentService, access: CallAccess): ToolDefinition[] {
-  return [agentTool(agents, access)];
+export function mainTools(agents: AgentService, teams: TeamService, access: CallAccess): ToolDefinition[] {
+  return [agentTool(agents, access), teamTool(teams, agents, access), teamMessageTool(teams, access, ctx => ({ kind: "coordinator", owner: agentOwner(ctx) }))];
 }
 export class ToolRegistry {
   readonly #registered = new Map<string, ToolDefinition>();
@@ -16,7 +19,7 @@ export class ToolRegistry {
     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 独立子会话工具。" },
+      const tool = { ...definition, namespace: { name: "pbot", description: "Personal Bot 独立子会话与团队协作工具。" },
         promptGuidelines };
       this.#registered.set(tool.name, tool); this.pi.registerTool(tool);
     }

package/src/tools/result.ts

@@ -1,4 +1,9 @@
 import { json } from "../common/json.js";
+import { markdownFields } from "../common/markdown.js";
+
+export function markdownResult(value: unknown, title: string) {
+  return result(value, false, "# " + title + "\n\n" + markdownFields(json(value)));
+}
 
 export function result(value: unknown, isError = false, text?: string) {
   const data = json(value);

package/src/tools/teams/contract.ts

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+import type { TSchema } from "typebox";
+
+const id = Type.String({ minLength: 1, maxLength: 128 });
+const text = Type.String({ minLength: 1, maxLength: 24000 });
+const name = Type.String({ minLength: 1, maxLength: 64, pattern: "^[^\\r\\n\\x00-\\x1f]+$" });
+const mode = Type.Union([Type.Literal("roundRobin"), Type.Literal("parallel")]);
+const members = Type.Array(Type.Object({ agentId: id, role: Type.String({ minLength: 1, maxLength: 4000 }) }, { additionalProperties: false }), { minItems: 1, maxItems: 50 });
+const run = { instruction: text, mode, rounds: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+  maxConcurrent: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })), timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400 })) };
+const page = { afterSeq: Type.Optional(Type.Integer({ minimum: 0 })), seq: Type.Optional(Type.Integer({ minimum: 1 })),
+  offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000 })) };
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+export const teamParametersSchema = object({
+  action: Type.Union(["create", "list", "status", "read", "run", "pause", "close"].map(v => Type.Literal(v))),
+  teamId: Type.Optional(id), name: Type.Optional(name), brief: Type.Optional(text), members: Type.Optional(members),
+  instruction: Type.Optional(text), mode: Type.Optional(mode), rounds: run.rounds, maxConcurrent: run.maxConcurrent, timeoutSeconds: run.timeoutSeconds, ...page,
+});
+export const teamActionSchema = Type.Union([
+  object({ action: Type.Literal("create"), name, brief: text, members }),
+  object({ action: Type.Literal("list") }),
+  ...["status", "pause", "close"].map(v => object({ action: Type.Literal(v), teamId: id })),
+  object({ action: Type.Literal("run"), teamId: id, ...run }),
+  object({ action: Type.Literal("read"), teamId: id, ...page }),
+]);
+export const teamMessageParametersSchema = object({
+  action: Type.Union([Type.Literal("read"), Type.Literal("post")]), teamId: id, text: Type.Optional(text),
+  replyTo: Type.Optional(Type.Integer({ minimum: 1 })), ...page,
+});
+export const teamMessageActionSchema = Type.Union([
+  object({ action: Type.Literal("read"), teamId: id, ...page }),
+  object({ action: Type.Literal("post"), teamId: id, text, replyTo: Type.Optional(Type.Integer({ minimum: 1 })) }),
+]);
+const nullableInteger = Type.Union([Type.Integer(), Type.Null()]);
+const message = object({ seq: Type.Integer(), operationId: Type.String(),
+  author: object({ kind: Type.Union([Type.Literal("user"), Type.Literal("coordinator"), Type.Literal("member")]), agentId: Type.Optional(id), name: Type.String() }),
+  text: Type.String(), replyTo: Type.Optional(Type.Integer()), runId: Type.Optional(id),
+  source: Type.Optional(object({ requestId: id, cycleId: id })),
+  offset: Type.Integer(), totalLength: Type.Integer(), nextOffset: nullableInteger });
+export const teamPageSchema = object({ teamId: id, messages: Type.Array(message), lastSeq: Type.Integer(), nextAfterSeq: nullableInteger });
+const ownedView = object({ teamId: id, name: Type.String(), brief: Type.String(), closed: Type.Boolean(), owned: Type.Literal(true),
+  members: Type.Array(object({ agentId: id, role: Type.String(), name: Type.String(), state: Type.String() })),
+  lastSeq: Type.Integer(), activeCount: Type.Integer(),
+  unresolved: Type.Array(object({ requestId: id, agentId: id, runId: id, round: Type.Integer(), active: Type.Boolean(), state: Type.String(), cycleId: Type.Optional(id) })),
+  run: Type.Optional(object({ runId: id, instruction: Type.String(), mode, state: Type.Union([Type.Literal("running"), Type.Literal("paused"), Type.Literal("finished")]),
+    rounds: Type.Integer(), maxConcurrent: Type.Integer(), deadlineAt: Type.Number(), scheduled: Type.Integer(), published: Type.Integer(), reason: Type.Optional(Type.String()) })) });
+const view = Type.Union([ownedView, object({ teamId: id, name: Type.String(), closed: Type.Boolean(), owned: Type.Literal(false) })]);
+export const teamResultSchema = Type.Union([view, object({ teams: Type.Array(view) }), teamPageSchema]);
+export const teamMessageResultSchema = Type.Union([teamPageSchema, object({ teamId: id, seq: Type.Integer(), status: Type.Literal("stored") })]);