personal-bot 0.2.4 → 0.2.5

package/src/services/history/history-service.ts

@@ -1,11 +1,11 @@
 import { randomUUID } from "node:crypto";
-import type { HistoryExchange, HistoryLocation, HistoryNode, HistoryRecord, HistorySession, HistorySource, HistorySummarizer } from "../../model/history.js";
+import type { HistoryExchange, HistoryHost, HistoryLocation, HistoryNode, HistoryRecord, HistorySession, HistorySource, HistorySummarizer } from "../../model/history.js";
 import type { HistoryFiles } from "../../storage/history-files.js";
 import { requireThat } from "../../common/validation.js";
 
 /** Shared prefixes reuse nodes; only consecutive exchanges on one native branch can merge. */
-export function indexHistory(session: HistorySession, previous?: HistoryRecord): HistoryRecord {
-  const id = previous?.id ?? randomUUID(), nodes = new Map<string, HistoryNode>();
+export function indexHistory(session: HistorySession, previous?: HistoryRecord, host: HistoryHost = "pi"): HistoryRecord {
+  const id = previous?.id ?? (host === "dsh" ? "dsh-" : "") + randomUUID(), nodes = new Map<string, HistoryNode>();
   const old = new Map(previous?.nodes.map(node => [node.id, node])), changed = new Set<string>();
   const add = (value: HistoryExchange, level: number, children: string[] = []): HistoryNode => {
     const key = `${id}:${level}:${value.entryIds.at(-1)}`, found = nodes.get(key);
@@ -40,106 +40,167 @@ export function indexHistory(session: HistorySession, previous?: HistoryRecord):
   return { id, sessionId: session.sessionId, name: session.name, nodes: [...nodes.values()] };
 }
 
-export interface HistoryQuery { query?: string; sessionId?: string; from?: string; to?: string; offset?: number; limit?: number }
+export interface HistoryQuery { host?: HistoryHost; query?: string; sessionId?: string; from?: string; to?: string; offset?: number; limit?: number }
+type LocatedRecord = { host: HistoryHost; record: HistoryRecord };
 const page = <T>(values: T[], offset: number, limit: number) => ({ values: values.slice(offset, offset + limit),
   nextOffset: offset + limit < values.length ? offset + limit : null });
-const brief = (record: HistoryRecord, node: HistoryNode) => ({ id: node.id, kind: node.kind, sessionId: record.sessionId,
+const brief = ({ host, record }: LocatedRecord, node: HistoryNode) => ({ host, id: node.id, kind: node.kind, sessionId: record.sessionId,
   name: record.name, preview: node.text.replace(/\s+/g, " ").slice(0, 100), from: node.from, to: node.to, ready: node.ready, completed: node.completed });
+const rawSource = (record?: HistoryRecord) => record && JSON.stringify({ name: record.name,
+  exchanges: record.nodes.filter(node => node.kind === "exchange").map(node => [node.id, node.entryIds, node.text, node.from, node.to, node.completed]) });
+const summarySource = (node: HistoryNode) => [node.id, node.entryIds, node.children, node.text, node.from, node.to, node.completed, node.ready];
+
+/** Validate the exact inputs again under the source lock; another writer's ready summary wins. */
+export function completeHistorySummary(record: HistoryRecord, id: string, children: HistoryNode[], text: string) {
+  const node = record.nodes.find(value => value.id === id);
+  if (!node || node.kind !== "summary" || node.ready || JSON.stringify(node.children) !== JSON.stringify(children.map(child => child.id))) return false;
+  const current = node.children.map(id => record.nodes.find(value => value.id === id));
+  if (current.some(value => !value) || JSON.stringify(current.map(value => summarySource(value!))) !== JSON.stringify(children.map(summarySource))) return false;
+  requireThat(text.trim(), "历史摘要为空。");
+  node.text = text.trim(); node.ready = true; return true;
+}
 
 export class HistoryService {
-  #records: HistoryRecord[] = [];
+  #records: LocatedRecord[] = [];
   #closed = false;
+  #loaded = false;
   #refresh: Promise<void> | undefined;
   #work: Promise<void> | undefined;
-  warnings: string[] = [];
+  #sourceWarnings: string[] = [];
+  #summaryError: string | undefined;
   constructor(readonly root: string, private readonly files: HistoryFiles, private readonly source: HistorySource,
-    private previousFiles?: HistoryFiles) {}
+    private previousFiles?: HistoryFiles, private readonly otherFiles?: HistoryFiles) {
+    requireThat(source.host === files.host && (!otherFiles || otherFiles.host !== files.host), "历史来源与归档目录不匹配。");
+    requireThat(files.host === "pi" || !previousFiles, "dsh 不导入 Pi 旧归档。");
+  }
   check() { requireThat(!this.#closed, "历史服务已关闭。"); }
+  get warnings() { return [...this.#sourceWarnings, ...(this.#summaryError ? [this.files.host + " 摘要：" + this.#summaryError] : [])]; }
+  get status() { return { loaded: this.#loaded, organizing: Boolean(this.#work), pending: this.#loaded ? this.#records.filter(value => value.host === this.files.host)
+    .reduce((total, value) => total + value.record.nodes.filter(node => node.kind === "summary" && !node.ready).length, 0) : null, warnings: this.warnings }; }
   refresh(location: HistoryLocation, signal?: AbortSignal): Promise<void> {
     this.check();
-    if (this.#refresh) return this.#refresh;
-    this.#refresh = this.load(location, signal).finally(() => { this.#refresh = undefined; });
-    return this.#refresh;
+    // Each caller keeps its own cancellation. A closed page cannot cancel a server-owned refresh.
+    const work = (this.#refresh ?? Promise.resolve()).catch(() => {}).then(() => this.load(location, signal));
+    this.#refresh = work;
+    return work.finally(() => { if (this.#refresh === work) this.#refresh = undefined; });
   }
   private async load(location: HistoryLocation, signal?: AbortSignal) {
-    const previous = this.files.list();
-    for (const value of previous) if ("file" in value) {
-      const { id, sessionId, name, nodes } = value;
-      this.files.save({ id, sessionId, name, nodes });
-    }
-    for (const { id, sessionId, name, nodes } of this.previousFiles?.list(this.root) ?? []) {
-      if (previous.some(record => record.sessionId === sessionId)) continue;
-      const value = { id, sessionId, name, nodes };
-      this.files.save(value); previous.push(value);
-    }
-    this.previousFiles = undefined;
-    const { sessions, warnings } = await this.source.scan(location, signal);
     this.check(); signal?.throwIfAborted();
-    const known = new Map(this.files.list().map(record => [record.sessionId, record]));
-    for (const session of sessions) {
-      const before = known.get(session.sessionId), value = indexHistory(session, before);
-      if (JSON.stringify(before) !== JSON.stringify(value)) this.files.save(value);
-      known.set(session.sessionId, value);
+    const warnings: string[] = [], records: LocatedRecord[] = [];
+    const warning = (host: HistoryHost, error: unknown) => { this.check(); signal?.throwIfAborted(); warnings.push(host + ": " + String(error)); };
+    let known: HistoryRecord[] = [];
+    try {
+      const before = this.files.list(); known = before;
+      let imports: HistoryRecord[] = [], importedPrevious = !this.previousFiles;
+      if (this.previousFiles) {
+        try { imports = this.previousFiles.list(this.root); importedPrevious = true; } catch (error) { warning("pi", error); }
+      }
+      let sessions: HistorySession[] = [];
+      try {
+        const scanned = await this.source.scan(location, signal); sessions = scanned.sessions;
+        warnings.push(...scanned.warnings.map(value => this.files.host + ": " + value));
+      } catch (error) { warning(this.files.host, error); }
+      this.check(); signal?.throwIfAborted();
+      if (sessions.length || imports.length || (this.files.host === "pi" && before.some(value => "file" in value))) {
+        known = this.files.control(() => {
+          this.check(); signal?.throwIfAborted();
+          const latest = this.files.list(), current = new Map(latest.map(record => [record.sessionId, record])), imported = new Set<string>();
+          if (this.files.host === "pi") {
+            for (const value of latest) if ("file" in value) {
+              const { id, sessionId, name, nodes } = value, clean = { id, sessionId, name, nodes };
+              this.files.save(clean); current.set(sessionId, clean);
+            }
+            for (const { id, sessionId, name, nodes } of imports) if (!current.has(sessionId)) {
+              const value = { id, sessionId, name, nodes }; this.files.save(value); current.set(sessionId, value); imported.add(sessionId);
+            }
+          }
+          for (const session of sessions) {
+            const previous = current.get(session.sessionId), captured = before.find(record => record.sessionId === session.sessionId);
+            // A concurrent source update must not be overwritten by this older scan. Summary-only updates remain reusable.
+            if (captured && rawSource(captured) !== rawSource(previous)) continue;
+            if (!captured && previous && !imported.has(session.sessionId)) continue;
+            const value = indexHistory(session, previous, this.files.host);
+            if (JSON.stringify(previous) !== JSON.stringify(value)) this.files.save(value);
+            current.set(session.sessionId, value);
+          }
+          return [...current.values()];
+        });
+      }
+      if (importedPrevious) this.previousFiles = undefined;
+    } catch (error) { warning(this.files.host, error); }
+    records.push(...known.map(record => ({ host: this.files.host, record })));
+    if (this.otherFiles) {
+      try { records.push(...this.otherFiles.list().map(record => ({ host: this.otherFiles!.host, record }))); }
+      catch (error) { warning(this.otherFiles.host, error); }
     }
-    this.#records = [...known.values()];
-    this.warnings = warnings;
+    this.check(); signal?.throwIfAborted(); this.#records = records; this.#sourceWarnings = warnings; this.#loaded = true;
   }
-  search({ query = "", sessionId, from, to, offset = 0, limit = 20 }: HistoryQuery = {}) {
+  search({ host, query = "", sessionId, from, to, offset = 0, limit = 20 }: HistoryQuery = {}) {
     this.check();
     const needle = query.trim().toLowerCase(), after = from === undefined ? -Infinity : Date.parse(from), before = to === undefined ? Infinity : Date.parse(to);
     requireThat(!Number.isNaN(after) && !Number.isNaN(before) && after <= before, "时间范围无效，请使用 ISO 日期或时间。");
-    const matches = this.#records.filter(record => !sessionId || record.sessionId === sessionId).flatMap(record => record.nodes
+    const matches = this.#records.filter(value => (!host || value.host === host) && (!sessionId || value.record.sessionId === sessionId)).flatMap(value => value.record.nodes
       .filter(node => (needle ? node.kind !== "session" && node.ready && node.text.toLowerCase().includes(needle) : node.kind === "session") &&
         Date.parse(node.to) >= after && Date.parse(node.from) <= before)
       .map(node => {
         const start = Math.max(0, node.text.toLowerCase().indexOf(needle) - 80);
-        return { ...brief(record, node), parents: node.parents, snippet: node.text.slice(start, start + 400) };
+        return { ...brief(value, node), parents: node.parents, snippet: node.text.slice(start, start + 400) };
       })).sort((a, b) => b.to.localeCompare(a.to) || a.id.localeCompare(b.id));
     const result = page(matches, offset, limit);
     return { matches: result.values, total: matches.length, nextOffset: result.nextOffset, warnings: this.warnings };
   }
-  private find(id: string) {
-    const record = this.#records.find(record => record.nodes.some(node => node.id === id));
-    const node = record?.nodes.find(node => node.id === id);
-    requireThat(record && node, "历史节点不存在，请重新搜索。");
-    return { record, node };
+  private find(id: string, host?: HistoryHost) {
+    const values = this.#records.filter(value => (!host || value.host === host) && value.record.nodes.some(node => node.id === id));
+    requireThat(values.length, "历史节点不存在，请重新搜索。");
+    requireThat(values.length === 1, "历史节点来源不明确，请指定 host。");
+    const value = values[0]!, node = value.record.nodes.find(node => node.id === id)!;
+    return { value, node };
   }
-  read(id: string, offset = 0, limit = 12000, childrenOffset = 0) {
+  read(id: string, offset = 0, limit = 12000, childrenOffset = 0, host?: HistoryHost) {
     this.check();
-    const { record, node } = this.find(id), lookup = new Map(record.nodes.map(value => [value.id, value]));
+    const { value, node } = this.find(id, host), lookup = new Map(value.record.nodes.map(node => [node.id, node]));
     requireThat(offset <= node.text.length, "读取位置超出正文。");
     if (offset && /[\uDC00-\uDFFF]/.test(node.text[offset] ?? "")) offset--;
     let end = Math.min(node.text.length, offset + limit);
     if (end < node.text.length && /[\uD800-\uDBFF]/.test(node.text[end - 1] ?? "")) end += end - offset === 1 ? 1 : -1;
     const children = page(node.children, childrenOffset, 20);
-    return { ...brief(record, node), text: node.text.slice(offset, end), totalLength: node.text.length,
+    return { ...brief(value, node), text: node.text.slice(offset, end), totalLength: node.text.length,
       nextOffset: end < node.text.length ? end : null,
-      parents: node.parents.map(id => brief(record, lookup.get(id)!)), children: children.values.map(id => brief(record, lookup.get(id)!)),
-      nextChildrenOffset: children.nextOffset, source: { sessionId: record.sessionId, entryIds: node.entryIds }, warnings: this.warnings };
+      parents: node.parents.map(id => brief(value, lookup.get(id)!)), children: children.values.map(id => brief(value, lookup.get(id)!)),
+      nextChildrenOffset: children.nextOffset, source: { host: value.host, sessionId: value.record.sessionId, entryIds: node.entryIds }, warnings: this.warnings };
   }
-  /** One worker per workspace instance. Failed or cancelled nodes remain pending for the next idle period. */
+  /** Only this source is organized. Model calls run outside the write lock. */
   organize(summarize: HistorySummarizer, signal: AbortSignal): Promise<void> {
     this.check();
     const run = async () => {
-      for (const record of this.#records) {
-        const lookup = new Map(record.nodes.map(node => [node.id, node]));
-        for (const node of [...record.nodes].sort((a, b) => a.level - b.level)) {
-          this.check(); signal.throwIfAborted();
-          if (node.kind !== "summary" || node.ready) continue;
-          const children = node.children.map(id => lookup.get(id)!);
-          if (children.some(child => !child.ready)) continue;
-          const text = await summarize(children.map(child => `[${child.from} — ${child.to}${child.completed ? "" : "；未完成"}]\n${child.text}`).join("\n\n"), signal);
-          this.check(); signal.throwIfAborted();
-          // A query may have refreshed the source while this model request was running.
-          if (!this.#records.includes(record)) return;
-          requireThat(text.trim(), "历史摘要为空。");
-          node.text = text.trim(); node.ready = true; this.files.save(record);
+      for (;;) {
+        this.check(); signal.throwIfAborted();
+        let pending: { record: HistoryRecord; node: HistoryNode; children: HistoryNode[] } | undefined;
+        for (const record of this.files.list()) {
+          const lookup = new Map(record.nodes.map(node => [node.id, node]));
+          const node = [...record.nodes].sort((a, b) => a.level - b.level).find(node => node.kind === "summary" && !node.ready && node.children.every(id => lookup.get(id)!.ready));
+          if (node) { pending = { record, node, children: node.children.map(id => lookup.get(id)!) }; break; }
         }
+        if (!pending) return;
+        const { record, node, children } = pending;
+        const text = await summarize(children.map(child => `[${child.from} — ${child.to}${child.completed ? "" : "；未完成"}]\n${child.text}`).join("\n\n"), signal);
+        this.check(); signal.throwIfAborted();
+        const committed = this.files.control(() => {
+          this.check(); signal.throwIfAborted();
+          const current = this.files.list().find(value => value.id === record.id);
+          if (!current || !completeHistorySummary(current, node.id, children, text)) return;
+          this.files.save(current); return current;
+        });
+        if (!committed) return;
+        this.#records = this.#records.map(value => value.host === this.files.host && value.record.id === committed.id ? { host: value.host, record: committed } : value);
       }
     };
-    const work = (this.#work ?? Promise.resolve()).catch(() => {}).then(run);
+    const work = (this.#work ?? Promise.resolve()).catch(() => {}).then(run).then(() => { this.#summaryError = undefined; }).catch(error => {
+      if (!signal.aborted && !this.#closed) this.#summaryError = String(error);
+      throw error;
+    });
     this.#work = work;
     return work.finally(() => { if (this.#work === work) this.#work = undefined; });
   }
-  async close() { this.#closed = true; await Promise.allSettled([this.#work, this.#refresh]); }
+  async close() { this.#closed = true; await Promise.allSettled([this.#work, this.#refresh]); this.#records = []; this.#loaded = false; }
 }

package/src/storage/agent-files.ts

@@ -5,7 +5,7 @@ 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, AgentSessionRef } from "../model/agent.js";
+import type { AgentDescriptor, AgentLaunch, AgentMessage, AgentStatus, AgentCycle, AgentSessionRef, AgentSessionReference } 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);
@@ -18,6 +18,11 @@ 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;
 }
+function dshSessionRef(v: unknown): Extract<AgentSessionReference, { host: "dsh" }> {
+  requireThat(object(v) && v.host === "dsh" && text(v.sessionId), "dsh 原生会话引用无效。");
+  fileId(v.sessionId as string);
+  return v as unknown as Extract<AgentSessionReference, { host: "dsh" }>;
+}
 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;
@@ -41,7 +46,7 @@ export function status(v: unknown): AgentStatus {
 }
 export class AgentFiles {
   #failure: unknown;
-  constructor(readonly root: string) {}
+  constructor(readonly root: string, readonly host: AgentSessionReference["host"] = "pi") {}
   check() { if (this.#failure) throw this.#failure; }
   fail(error: unknown) { this.#failure = error; }
   directory(id: string) { return join(this.root, fileId(id)); }
@@ -63,7 +68,8 @@ export class AgentFiles {
     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);
+    if (this.host === "pi") this.write(value.agentId, "session-ref.json", { file: null }, sessionRef, true);
+    else this.write(value.agentId, "native-session.json", { host: "dsh", sessionId: value.agentId }, dshSessionRef, true);
   }
   list() {
     if (!existsSync(this.root)) return [];
@@ -79,7 +85,14 @@ 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));
   }
+  reference(id: string): AgentSessionReference {
+    if (this.host === "pi") return { host: "pi", file: this.session(id) };
+    const ref = this.read(id, "native-session.json", dshSessionRef);
+    requireThat(ref.sessionId === id, "dsh 原生会话身份不匹配。");
+    return ref;
+  }
   session(id: string): string | null {
+    requireThat(this.host === "pi", "该宿主不使用 Pi 会话文件引用。");
     const ref = this.optional(id, "session-ref.json", sessionRef);
     requireThat(ref, "缺少原生会话引用；不导入旧记录，请重新 start。");
     return ref.file;
@@ -98,7 +111,7 @@ export class AgentFiles {
     try { mkdirSync(path, { mode: 0o700 }); }
     catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      throw Object.assign(new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关 Pi 后手动移除。"), { code: "PBOT_CONTROL_BUSY" });
+      throw Object.assign(new Error("子会话控制正在进行；稍后重试。崩溃遗留的 .control 需停止相关执行实例后手动移除。"), { code: "PBOT_CONTROL_BUSY" });
     }
     try { return work(); } finally { rmSync(path, { recursive: true }); }
   }

package/src/storage/history-files.ts

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

package/src/tools/agents/actions.ts

@@ -0,0 +1,47 @@
+import type { Static } from "typebox";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import type { AgentOptions, AgentOwner, AgentView } from "../../model/agent.js";
+import { markdownResult } from "../result.js";
+import type { agentParametersSchema, agentViewSchema } from "./contract.js";
+
+export type AgentInput = Omit<Static<typeof agentParametersSchema>, "thinking"> & { thinking?: string };
+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 async function executeAgent(service: AgentService, input: AgentInput, owner: AgentOwner, defaults: AgentOptions = {}) {
+  let value: AgentView & Partial<AgentOutput>;
+  switch (input.action) {
+    case "start": {
+      const { action: _action, ...supplied } = input;
+      value = await service.start({ ...defaults, ...supplied } as AgentOptions, owner); break;
+    }
+    case "list": return markdownResult({ agents: service.list(owner).map(agentOutput) }, "子会话列表");
+    case "send": value = service.send(input.agentId!, input.message!, input.delivery ?? "steer", owner); break;
+    case "rename": value = service.rename(input.agentId!, input.name!, owner); break;
+    case "resume": value = await service.resume(input.agentId!, input.message!, owner); break;
+    case "stop": value = service.stop(input.agentId!, owner); break;
+    case "status": value = service.status(input.agentId!, owner); break;
+    case "read": {
+      const page = await service.read(input.agentId!, owner, input.cycleId, input.offset, input.limit);
+      const data = agentOutput(page), output = markdownResult(data, "子会话报告");
+      return { ...output, details: { ...data, ...(page.cycle && page.cycle.state !== "running" ? { agentReadKeys: [page.agentId + ":" + page.cycle.cycleId] } : {}) } };
+    }
+  }
+  return markdownResult(agentOutput(value), "子会话状态");
+}

package/src/tools/agents/contract.ts

@@ -1,8 +1,11 @@
 import { Type } from "typebox";
+
+export const agentDescription = "独立专家会话，不继承父聊天历史。start 完成启动后返回，不等待工作完成；未提供 message/prompts/files 时只启动待命会话，不调用模型。完成自动通知，无需轮询。团队占用期间不能私人 send。send 继续对话，rename 改名，status/list 查看状态，status 返回最近周期且不读取报告正文。read 非阻塞读取报告；读取已结束周期会领取该周期的完成通知（包括部分读取），后续不再重复通知。nextOffset 非空时以返回的 cycle.cycleId 固定周期续读。state 是执行状态，cycle.state 是工作结果，queued 仅表示入队。stop 停止并保留历史，resume 携新 message 恢复，不重放旧工作。独立复核须 start 新上下文。子会话使用原生 CLI/MCP，按委派范围工作，不递归委派。每个父会话最多 50 个存活子会话，空闲也计入。";
+
 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 = {
+export const agentStartOptions = {
   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 按顺序合并为同一初始消息，不是多个执行轮次。" })),
@@ -24,12 +27,12 @@ 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 创建待命进程，禁止 agentId/delivery/分页字段；list 只接受 action；status/stop 只接受并必填 agentId；send 必填 agentId/message，仅可选 delivery；resume 必填 agentId/message；rename 必填 agentId/name；read 必填 agentId，仅可选 cycleId/offset/limit。禁止携带其他 action 的字段。",
+    description: "start 仅接受启动选项，可省略 message/prompts/files 创建待命会话，禁止 agentId/delivery/分页字段；list 只接受 action；status/stop 只接受并必填 agentId；send 必填 agentId/message，仅可选 delivery；resume 必填 agentId/message；rename 必填 agentId/name；read 必填 agentId，仅可选 cycleId/offset/limit。禁止携带其他 action 的字段。",
   }),
-  agentId: Type.Optional(id), ...options, ...page, delivery,
+  agentId: Type.Optional(id), ...agentStartOptions, ...page, delivery,
 }, { additionalProperties: false });
 export const agentActionSchema = Type.Union([
-  Type.Object({ action: Type.Literal("start"), ...options }, { additionalProperties: false }),
+  Type.Object({ action: Type.Literal("start"), ...agentStartOptions }, { 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 }),
@@ -45,7 +48,7 @@ const cycle = Type.Object({ cycleId: Type.String(), startedAt: Type.Number(), fi
 }, { 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。" }),
+  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() }), { description: "仅 read 返回：可读取的周期索引。" })),

package/src/tools/agents/dsh-contract.ts

@@ -0,0 +1,16 @@
+import { Type } from "typebox";
+import { agentActionSchema, agentParametersSchema, agentStartOptions } from "./contract.js";
+
+const options = Type.Omit(Type.Object(agentStartOptions), ["provider", "model", "thinking", "files", "tools", "noExtensions", "noPromptTemplates", "noContextFiles", "noSkills"]).properties;
+const native = {
+  provider: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "dsh 原生 provider route，默认继承父会话。" })),
+  model: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "该 dsh provider 的模型 ID，默认继承父会话。" })),
+  thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "该 dsh 模型的原生 reasoning effort ID，默认继承父会话；不转换 Pi 思考等级。" })),
+  files: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { maxItems: 32, description: "作为原生附件保存的文件；相对原工作区根目录。图片遵循宿主准入规则，其他文件保留原始字节供模型读取。" })),
+  tools: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, description: "原生能力工具名；不填写 run_code 传输名，不支持递归委派。省略时使用原生工具和 pbot_team_message。" })),
+  noSkills: Type.Optional(Type.Boolean({ description: "关闭该专家的模型技能目录和原生 skill 工具；不改变其他会话的技能配置。" })),
+};
+const omitted = ["noExtensions", "noPromptTemplates", "noContextFiles", "provider", "model", "thinking", "files", "tools", "noSkills"] as const;
+export const dshAgentParametersSchema = Type.Object({ ...Type.Omit(agentParametersSchema, omitted).properties, ...native }, { additionalProperties: false });
+export const dshAgentActionSchema = Type.Union(agentActionSchema.anyOf.map(row => row.properties.action.const === "start"
+  ? Type.Object({ action: Type.Literal("start"), ...options, ...native }, { additionalProperties: false }) : row));

package/src/tools/agents/dsh-tool.ts

@@ -0,0 +1,41 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { dshParameters, dshOutputSchema } from "../../integrations/dsh/schema.js";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import type { AgentOwner } from "../../model/agent.js";
+import { object, json } from "../../common/json.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { markdownFields } from "../../common/markdown.js";
+import { executeAgent, type AgentInput } from "./actions.js";
+import { agentDescription, agentResultSchema } from "./contract.js";
+import { dshAgentActionSchema, dshAgentParametersSchema } from "./dsh-contract.js";
+
+export function registerDshAgentTool(ctx: Context, agent: Agent, service: AgentService, owner: AgentOwner, check: () => void) {
+  const validators = new Map(dshAgentActionSchema.anyOf.map(row => [row.properties.action.const, schema(row)]));
+  const validOutput = schema(agentResultSchema);
+  ctx.tools.register({ name: "pbot_agent", description: agentDescription,
+    parameters: dshParameters(dshAgentParametersSchema),
+    output: {
+      schema: dshOutputSchema(agentResultSchema),
+      render: (_args, value) => [{ type: "text", text: "# 专家\n\n" + markdownFields(value) }],
+      presentationMeta: (args, value) => {
+        if (!object(args) || args.action !== "read" || !object(value) || !object(value.cycle) || value.cycle.state === "running") return {};
+        return json({ pbotAgentReadKeys: [String(value.agentId) + ":" + String(value.cycle.cycleId)] });
+      },
+    },
+    async execute(args, exec) {
+      check(); exec.signal.throwIfAborted();
+      requireThat(exec.agent === agent && object(args) && typeof args.action === "string", "专家工具会话或参数无效。");
+      const valid = validators.get(args.action);
+      requireThat(valid && valid(args), "dsh 专家参数无效或包含不支持的宿主选项。");
+      const selection = agent.model.current();
+      const output = await executeAgent(service, args as AgentInput, owner, selection ? {
+        provider: selection.provider, model: selection.model,
+        ...(selection.reasoningEffort && (!args.provider || args.provider === selection.provider) && (!args.model || args.model === selection.model)
+          ? { thinking: selection.reasoningEffort } : {}),
+      } : {});
+      requireThat(validOutput(output.structuredContent), "专家输出不符合契约。");
+      return output.structuredContent;
+    },
+  });
+}

package/src/tools/agents/tool.ts

@@ -1,61 +1,25 @@
-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 { markdownResult } 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 }),
-  };
-}
+import { executeAgent } from "./actions.js";
+import { agentDescription, agentActionSchema, agentParametersSchema, agentResultSchema } from "./contract.js";
 
 export function agentTool(service: AgentService, access: CallAccess) {
   const validators = new Map(agentActionSchema.anyOf.map(action => [action.properties.action.const, schema(action)]));
   return defineTool({ name: "pbot_agent", label: "子会话",
-    description: "独立 Pi 子会话，不继承父聊天历史。start 立即返回；未提供 message/prompts/files 时只启动待命进程，不调用模型。完成自动通知，无需轮询。团队占用期间不能私人 send。send 继续对话，rename 改名，status/list 查看状态，status 返回最近周期且不读取报告正文。read 非阻塞读取报告；读取已结束周期会领取该周期的完成通知（包括部分读取），后续不再重复通知。nextOffset 非空时以返回的 cycle.cycleId 固定周期续读。state 是进程状态，cycle.state 是工作结果，queued 仅表示入队。stop 停止并保留历史，resume 携新 message 恢复，不重放旧工作。独立复核须 start 新上下文。子会话使用原生 CLI/MCP，按委派范围工作，不递归委派。每个父会话最多 50 个存活子会话，空闲也计入。",
+    description: agentDescription,
     parameters: agentParametersSchema, outputSchema: agentResultSchema,
     async execute(_id, args, signal, _update, ctx) {
       access.check(); signal?.throwIfAborted();
       const valid = validators.get(args.action);
       requireThat(valid, "未知的子会话 action：" + args.action);
       requireThat(valid(args), "子会话 " + args.action + " 参数无效：" + JSON.stringify(valid.errors));
-      const input = args as Static<typeof agentParametersSchema>, owner = agentOwner(ctx);
-      let value: AgentView & Partial<AgentOutput>;
-      switch (input.action) {
-        case "start": {
-          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 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;
-        case "stop": value = service.stop(input.agentId!, owner); break;
-        case "status": value = service.status(input.agentId!, owner); break;
-        case "read": {
-          const page = service.read(input.agentId!, owner, input.cycleId, input.offset, input.limit);
-          const data = agentOutput(page), output = markdownResult(data, "子会话报告");
-          return { ...output, details: { ...data, ...(page.cycle && page.cycle.state !== "running" ? { agentReadKeys: [page.agentId + ":" + page.cycle.cycleId] } : {}) } };
-        }
-      }
-      return markdownResult(agentOutput(value), "子会话状态");
+      return executeAgent(service, args, agentOwner(ctx), {
+        ...(ctx.model ? { provider: ctx.model.provider, model: ctx.model.id } : {}),
+        ...(ctx.thinkingLevel ? { thinking: ctx.thinkingLevel } : {}),
+      });
     },
   });
 }

package/src/tools/history/actions.ts

@@ -0,0 +1,9 @@
+import type { HistoryLocation } from "../../model/history.js";
+import type { HistoryService } from "../../services/history/history-service.js";
+import type { HistoryInput } from "./contract.js";
+
+export async function executeHistory(service: HistoryService, args: HistoryInput, location: HistoryLocation, signal?: AbortSignal) {
+  signal?.throwIfAborted(); await service.refresh(location, signal); signal?.throwIfAborted();
+  return args.action === "search" ? service.search(args) :
+    { node: service.read(args.id!, args.offset, args.limit, args.childrenOffset, args.host), warnings: service.warnings };
+}