personal-bot 0.2.4 → 0.2.5

package/lib/tools/agents/contract.js

@@ -0,0 +1,56 @@
+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]+$" });
+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 按顺序合并为同一初始消息，不是多个执行轮次。" })),
+    provider: Type.Optional(Type.String({ ...id, description: "Pi 模型提供方，默认继承主会话。" })),
+    model: Type.Optional(Type.String({ ...id, description: "子进程可用的 Pi 模型 ID，默认继承主会话。" })),
+    thinking: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh"), Type.Literal("max")], { description: "默认继承主会话思考级别。" })),
+    cwd: Type.Optional(Type.String({ minLength: 1, description: "执行目录，相对原工作区根目录；省略时使用工作区根目录。" })),
+    tools: Type.Optional(Type.Array(id, { minItems: 1, description: "按 Pi 原生规则选择工具，省略时沿用原生默认工具；MCP 工具遵循原生暴露设置。不提供递归委派；这不是宿主隔离。" })),
+    noExtensions: Type.Optional(Type.Boolean({ description: "默认 true，不发现其他扩展。" })),
+    noSkills: Type.Optional(Type.Boolean({ description: "关闭技能发现，默认 false。" })),
+    noPromptTemplates: Type.Optional(Type.Boolean({ description: "关闭提示模板发现，默认 false。" })),
+    noContextFiles: Type.Optional(Type.Boolean({ description: "关闭 Pi 原生上下文文件加载，默认 false。" })),
+};
+const page = {
+    cycleId: Type.Optional(Type.String({ ...id, description: "仅 read：省略时读取最近周期；按 nextOffset 续读时须固定为上页返回的 cycle.cycleId，避免切换到新周期。" })),
+    offset: Type.Optional(Type.Integer({ minimum: 0, description: "仅 read：报告正文的 UTF-16 字符偏移，默认 0；续读使用上页 nextOffset。" })),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000, description: "仅 read：最多返回的正文 UTF-16 字符数，默认 16000，不是消息数或 token 数。" })),
+};
+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 的字段。",
+    }),
+    agentId: Type.Optional(id), ...agentStartOptions, ...page, delivery,
+}, { additionalProperties: false });
+export const agentActionSchema = Type.Union([
+    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 }),
+    Type.Object({ action: Type.Literal("list") }, { additionalProperties: false }),
+    ...["stop", "status"].map(action => Type.Object({ action: Type.Literal(action), agentId: id }, { additionalProperties: false })),
+    Type.Object({ action: Type.Literal("read"), agentId: id, ...page }, { additionalProperties: false }),
+]);
+const cycle = Type.Object({ cycleId: Type.String(), startedAt: Type.Number(), finishedAt: Type.Optional(Type.Number()),
+    state: Type.Union([Type.Literal("running"), Type.Literal("completed"), Type.Literal("failed"), Type.Literal("cancelled"), Type.Literal("interrupted")], { description: "本周期的工作结果；completed 仍须核验实际交付。" }),
+    requestIds: Type.Array(Type.String()),
+    source: Type.Union([Type.Literal("parent"), Type.Literal("interactive"), Type.Literal("mixed")]), error: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+export const agentViewSchema = Type.Object({ agentId: Type.String(), name: Type.String(), cwd: Type.String(), createdAt: Type.Number(),
+    owned: Type.Boolean({ description: "是否属于当前父会话分支；false 时须回到所属分支操作。" }),
+    state: Type.Union([Type.Literal("starting"), Type.Literal("busy"), Type.Literal("idle"), Type.Literal("stopping"), Type.Literal("stopped"), Type.Literal("error")], { description: "执行状态；idle 不代表上轮工作成功，结果见 cycle.state。" }),
+    activity: Type.String(), cycle: Type.Optional(cycle), error: Type.Optional(Type.String()),
+    requestId: Type.Optional(Type.String()), messageStatus: Type.Optional(Type.Literal("queued", { description: "消息已入队，不代表模型已阅读或完成。" })),
+    cycles: Type.Optional(Type.Array(Type.Object({ cycleId: Type.String(), state: Type.String() }), { description: "仅 read 返回：可读取的周期索引。" })),
+    report: Type.Optional(Type.String({ description: "仅 read 返回：选定周期的报告正文片段。已结束周期的读取结果持久化后领取该周期通知，即使本页未读完。" })),
+    totalLength: Type.Optional(Type.Integer({ description: "仅 read 返回：完整报告的 UTF-16 字符数。" })),
+    nextOffset: Type.Optional(Type.Union([Type.Integer(), Type.Null()], { description: "仅 read 返回：null 表示本报告已读完；否则以相同 agentId、cycle.cycleId 和此 offset 继续。" })),
+}, { additionalProperties: false });
+export const agentResultSchema = Type.Union([agentViewSchema, Type.Object({ agents: Type.Array(agentViewSchema) }, { additionalProperties: false })]);

package/lib/tools/agents/dsh-contract.d.ts

@@ -0,0 +1,52 @@
+import { Type } from "typebox";
+export declare const dshAgentParametersSchema: Type.TObject<{
+    provider: Type.TOptional<Type.TString>;
+    model: Type.TOptional<Type.TString>;
+    thinking: Type.TOptional<Type.TString>;
+    files: Type.TOptional<Type.TArray<Type.TString>>;
+    tools: Type.TOptional<Type.TArray<Type.TString>>;
+    noSkills: Type.TOptional<Type.TBoolean>;
+    agentId: Type.TOptional<Type.TString>;
+    cwd: Type.TOptional<Type.TString>;
+    name: Type.TOptional<Type.TString>;
+    message: Type.TOptional<Type.TString>;
+    delivery: Type.TOptional<Type.TUnion<[Type.TLiteral<"steer">, Type.TLiteral<"followUp">]>>;
+    cycleId: Type.TOptional<Type.TString>;
+    prompts: Type.TOptional<Type.TArray<Type.TString>>;
+    action: Type.TUnion<[Type.TLiteral<"start">, Type.TLiteral<"send">, Type.TLiteral<"rename">, Type.TLiteral<"status">, Type.TLiteral<"list">, Type.TLiteral<"read">, Type.TLiteral<"stop">, Type.TLiteral<"resume">]>;
+    offset: Type.TOptional<Type.TInteger>;
+    limit: Type.TOptional<Type.TInteger>;
+}>;
+export declare const dshAgentActionSchema: Type.TUnion<(Type.TObject<{
+    name: Type.TOptional<Type.TString>;
+    message: Type.TOptional<Type.TString>;
+    files: Type.TOptional<Type.TArray<Type.TString>>;
+    prompts: Type.TOptional<Type.TArray<Type.TString>>;
+    provider: Type.TOptional<Type.TString>;
+    model: Type.TOptional<Type.TString>;
+    thinking: Type.TOptional<Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">, Type.TLiteral<"max">]>>;
+    cwd: Type.TOptional<Type.TString>;
+    tools: Type.TOptional<Type.TArray<Type.TString>>;
+    noExtensions: Type.TOptional<Type.TBoolean>;
+    noSkills: Type.TOptional<Type.TBoolean>;
+    noPromptTemplates: Type.TOptional<Type.TBoolean>;
+    noContextFiles: Type.TOptional<Type.TBoolean>;
+    action: Type.TLiteral<"start">;
+}> | Type.TObject<{
+    action: Type.TLiteral<"list">;
+}> | Type.TObject<{
+    action: Type.TLiteral<string>;
+    agentId: Type.TString;
+}> | Type.TObject<{
+    provider: Type.TOptional<Type.TString>;
+    model: Type.TOptional<Type.TString>;
+    thinking: Type.TOptional<Type.TString>;
+    files: Type.TOptional<Type.TArray<Type.TString>>;
+    tools: Type.TOptional<Type.TArray<Type.TString>>;
+    noSkills: Type.TOptional<Type.TBoolean>;
+    cwd: Type.TOptional<Type.TString>;
+    name: Type.TOptional<Type.TString>;
+    message: Type.TOptional<Type.TString>;
+    prompts: Type.TOptional<Type.TArray<Type.TString>>;
+    action: Type.TLiteral<"start">;
+}>)[]>;

package/lib/tools/agents/dsh-contract.js

@@ -0,0 +1,15 @@
+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"];
+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/lib/tools/agents/dsh-tool.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import type { AgentOwner } from "../../model/agent.js";
+export declare function registerDshAgentTool(ctx: Context, agent: Agent, service: AgentService, owner: AgentOwner, check: () => void): void;

package/lib/tools/agents/dsh-tool.js

@@ -0,0 +1,38 @@
+import { dshParameters, dshOutputSchema } from "../../integrations/dsh/schema.js";
+import { object, json } from "../../common/json.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { markdownFields } from "../../common/markdown.js";
+import { executeAgent } from "./actions.js";
+import { agentDescription, agentResultSchema } from "./contract.js";
+import { dshAgentActionSchema, dshAgentParametersSchema } from "./dsh-contract.js";
+export function registerDshAgentTool(ctx, agent, service, owner, check) {
+    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, 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/lib/tools/history/actions.d.ts

@@ -0,0 +1,70 @@
+import type { HistoryLocation } from "../../model/history.js";
+import type { HistoryService } from "../../services/history/history-service.js";
+import type { HistoryInput } from "./contract.js";
+export declare function executeHistory(service: HistoryService, args: HistoryInput, location: HistoryLocation, signal?: AbortSignal): Promise<{
+    matches: {
+        parents: string[];
+        snippet: string;
+        host: import("../../model/history.js").HistoryHost;
+        id: string;
+        kind: "session" | "exchange" | "summary";
+        sessionId: string;
+        name: string;
+        preview: string;
+        from: string;
+        to: string;
+        ready: boolean;
+        completed: boolean;
+    }[];
+    total: number;
+    nextOffset: number | null;
+    warnings: string[];
+} | {
+    node: {
+        text: string;
+        totalLength: number;
+        nextOffset: number | null;
+        parents: {
+            host: import("../../model/history.js").HistoryHost;
+            id: string;
+            kind: "session" | "exchange" | "summary";
+            sessionId: string;
+            name: string;
+            preview: string;
+            from: string;
+            to: string;
+            ready: boolean;
+            completed: boolean;
+        }[];
+        children: {
+            host: import("../../model/history.js").HistoryHost;
+            id: string;
+            kind: "session" | "exchange" | "summary";
+            sessionId: string;
+            name: string;
+            preview: string;
+            from: string;
+            to: string;
+            ready: boolean;
+            completed: boolean;
+        }[];
+        nextChildrenOffset: number | null;
+        source: {
+            host: import("../../model/history.js").HistoryHost;
+            sessionId: string;
+            entryIds: string[];
+        };
+        warnings: string[];
+        host: import("../../model/history.js").HistoryHost;
+        id: string;
+        kind: "session" | "exchange" | "summary";
+        sessionId: string;
+        name: string;
+        preview: string;
+        from: string;
+        to: string;
+        ready: boolean;
+        completed: boolean;
+    };
+    warnings: string[];
+}>;

package/lib/tools/history/actions.js

@@ -0,0 +1,7 @@
+export async function executeHistory(service, args, location, signal) {
+    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 };
+}

package/lib/tools/history/contract.d.ts

@@ -0,0 +1,81 @@
+import { Type, type Static } from "typebox";
+export declare const historyResultSchema: Type.TObject<{
+    matches: Type.TOptional<Type.TArray<Type.TObject<{
+        snippet: Type.TString;
+        parents: Type.TArray<Type.TString>;
+        host: Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>;
+        id: Type.TString;
+        kind: Type.TUnion<[Type.TLiteral<"session">, Type.TLiteral<"exchange">, Type.TLiteral<"summary">]>;
+        sessionId: Type.TString;
+        name: Type.TString;
+        preview: Type.TString;
+        from: Type.TString;
+        to: Type.TString;
+        ready: Type.TBoolean;
+        completed: Type.TBoolean;
+    }>>>;
+    total: Type.TOptional<Type.TInteger>;
+    nextOffset: Type.TOptional<Type.TUnion<[Type.TInteger, Type.TNull]>>;
+    node: Type.TOptional<Type.TObject<{
+        text: Type.TString;
+        totalLength: Type.TInteger;
+        nextOffset: Type.TUnion<[Type.TInteger, Type.TNull]>;
+        parents: Type.TArray<Type.TObject<{
+            host: Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>;
+            id: Type.TString;
+            kind: Type.TUnion<[Type.TLiteral<"session">, Type.TLiteral<"exchange">, Type.TLiteral<"summary">]>;
+            sessionId: Type.TString;
+            name: Type.TString;
+            preview: Type.TString;
+            from: Type.TString;
+            to: Type.TString;
+            ready: Type.TBoolean;
+            completed: Type.TBoolean;
+        }>>;
+        children: Type.TArray<Type.TObject<{
+            host: Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>;
+            id: Type.TString;
+            kind: Type.TUnion<[Type.TLiteral<"session">, Type.TLiteral<"exchange">, Type.TLiteral<"summary">]>;
+            sessionId: Type.TString;
+            name: Type.TString;
+            preview: Type.TString;
+            from: Type.TString;
+            to: Type.TString;
+            ready: Type.TBoolean;
+            completed: Type.TBoolean;
+        }>>;
+        nextChildrenOffset: Type.TUnion<[Type.TInteger, Type.TNull]>;
+        source: Type.TObject<{
+            host: Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>;
+            sessionId: Type.TString;
+            entryIds: Type.TArray<Type.TString>;
+        }>;
+        warnings: Type.TArray<Type.TString>;
+        host: Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>;
+        id: Type.TString;
+        kind: Type.TUnion<[Type.TLiteral<"session">, Type.TLiteral<"exchange">, Type.TLiteral<"summary">]>;
+        sessionId: Type.TString;
+        name: Type.TString;
+        preview: Type.TString;
+        from: Type.TString;
+        to: Type.TString;
+        ready: Type.TBoolean;
+        completed: Type.TBoolean;
+    }>>;
+    warnings: Type.TArray<Type.TString>;
+}>;
+export declare const historyDescription = "\u67E5\u8BE2\u5F53\u524D\u5DE5\u4F5C\u533A\u7684 Pi \u4E0E dsh \u5386\u53F2\u5F52\u6863\uFF0C\u53EF\u7528 host \u7B5B\u9009\u6765\u6E90\u3002search \u5BF9\u95EE\u7B54\u539F\u6587\u548C\u5404\u5C42\u6458\u8981\u505A\u4E0D\u533A\u5206\u5927\u5C0F\u5199\u7684\u8FDE\u7EED\u6587\u672C\u5339\u914D\uFF1B\u7701\u7565 query \u5217\u51FA\u4F1A\u8BDD\u3002\u5FD8\u8BB0\u539F\u8BCD\u65F6\u6362\u51E0\u7EC4\u8BCD\u67E5\u8BE2\u3002read \u8BFB\u53D6\u547D\u4E2D\u8282\u70B9\u5E76\u8FD4\u56DE\u7236\u5B50\u8282\u70B9\uFF1B\u6CBF parents/children \u7684 id \u5C55\u5F00\uFF0CnextOffset \u7EED\u8BFB\u6B63\u6587\uFF0CnextChildrenOffset \u7EED\u8BFB\u5B50\u8282\u70B9\u3002\u6458\u8981\u662F\u68C0\u7D22\u7EBF\u7D22\uFF0C\u91CD\u8981\u7ED3\u8BBA\u56DE\u5230 exchange \u539F\u6587\u6838\u5BF9\u3002\u5171\u4EAB\u524D\u7F00\u53EF\u80FD\u6709\u591A\u4E2A\u7236\u8282\u70B9\u3002\u67E5\u8BE2\u4E0D\u8C03\u7528\u6A21\u578B\uFF0C\u4E0D\u6062\u590D\u6216\u91CD\u653E\u65E7\u4EFB\u52A1\uFF1B\u53EA\u66F4\u65B0\u5F53\u524D\u5BBF\u4E3B\u7684\u539F\u751F\u5386\u53F2\u7D22\u5F15\u3002\u95EE\u7B54\u5F52\u6863\u4E0D\u4EE3\u66FF\u4E13\u5BB6\u7684\u5B8C\u6574\u5DE5\u5177\u65E5\u5FD7\u3002";
+export declare const historyParameters: Type.TObject<{
+    action: Type.TUnion<[Type.TLiteral<"search">, Type.TLiteral<"read">]>;
+    host: Type.TOptional<Type.TUnion<[Type.TLiteral<"pi">, Type.TLiteral<"dsh">]>>;
+    query: Type.TOptional<Type.TString>;
+    sessionId: Type.TOptional<Type.TString>;
+    from: Type.TOptional<Type.TString>;
+    to: Type.TOptional<Type.TString>;
+    id: Type.TOptional<Type.TString>;
+    offset: Type.TOptional<Type.TInteger>;
+    limit: Type.TOptional<Type.TInteger>;
+    childrenOffset: Type.TOptional<Type.TInteger>;
+}>;
+export type HistoryInput = Static<typeof historyParameters>;
+export declare function historyInput(value: unknown): HistoryInput;

package/lib/tools/history/contract.js

@@ -0,0 +1,32 @@
+import { Type } from "typebox";
+import { requireThat, schema } from "../../common/validation.js";
+const host = Type.Union([Type.Literal("pi"), Type.Literal("dsh")]);
+const nullableOffset = Type.Union([Type.Integer(), Type.Null()]);
+const node = Type.Object({ host, id: Type.String(), kind: Type.Union([Type.Literal("session"), Type.Literal("exchange"), Type.Literal("summary")]),
+    sessionId: Type.String(), name: Type.String(), preview: Type.String(), from: Type.String(), to: Type.String(), ready: Type.Boolean(), completed: Type.Boolean() });
+export const historyResultSchema = Type.Object({
+    matches: Type.Optional(Type.Array(Type.Object({ ...node.properties, snippet: Type.String(), parents: Type.Array(Type.String()) }))),
+    total: Type.Optional(Type.Integer()), nextOffset: Type.Optional(nullableOffset),
+    node: Type.Optional(Type.Object({ ...node.properties, text: Type.String(), totalLength: Type.Integer(), nextOffset: nullableOffset,
+        parents: Type.Array(node), children: Type.Array(node), nextChildrenOffset: nullableOffset,
+        source: Type.Object({ host, sessionId: Type.String({ description: "原始宿主会话 ID；来源不保存文件路径。" }), entryIds: Type.Array(Type.String()) }), warnings: Type.Array(Type.String()) })),
+    warnings: Type.Array(Type.String()),
+});
+export const historyDescription = "查询当前工作区的 Pi 与 dsh 历史归档，可用 host 筛选来源。search 对问答原文和各层摘要做不区分大小写的连续文本匹配；省略 query 列出会话。忘记原词时换几组词查询。read 读取命中节点并返回父子节点；沿 parents/children 的 id 展开，nextOffset 续读正文，nextChildrenOffset 续读子节点。摘要是检索线索，重要结论回到 exchange 原文核对。共享前缀可能有多个父节点。查询不调用模型，不恢复或重放旧任务；只更新当前宿主的原生历史索引。问答归档不代替专家的完整工具日志。";
+export const historyParameters = Type.Object({ action: Type.Union([Type.Literal("search"), Type.Literal("read")]),
+    host: Type.Optional(host), query: Type.Optional(Type.String()), sessionId: Type.Optional(Type.String()),
+    from: Type.Optional(Type.String({ description: "search：ISO 日期或时间，下界。" })),
+    to: Type.Optional(Type.String({ description: "search：ISO 日期或时间，上界。" })),
+    id: Type.Optional(Type.String({ description: "read 必填：返回的节点 id。" })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 24000, description: "search：最多 50 条，默认 20；read：字符数，默认 12000。" })),
+    childrenOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+const valid = schema(historyParameters);
+export function historyInput(value) {
+    requireThat(valid(value), "历史参数无效。");
+    const args = value;
+    requireThat(args.action !== "read" || args.id, "read 需要节点 id。");
+    requireThat(args.action !== "search" || (args.limit ?? 20) <= 50, "search limit 最多 50。");
+    return args;
+}

package/lib/tools/history/dsh-tool.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { HistoryService } from "../../services/history/history-service.js";
+export declare function registerDshHistoryTool(ctx: Context, agent: Agent, service: HistoryService, lifetime: AbortSignal, check: () => void): void;

package/lib/tools/history/dsh-tool.js

@@ -0,0 +1,22 @@
+import { dshParameters, dshOutputSchema } from "../../integrations/dsh/schema.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { json } from "../../common/json.js";
+import { markdownFields } from "../../common/markdown.js";
+import { historyDescription, historyInput, historyParameters, historyResultSchema } from "./contract.js";
+import { executeHistory } from "./actions.js";
+export function registerDshHistoryTool(ctx, agent, service, lifetime, check) {
+    const valid = schema(historyResultSchema);
+    ctx.tools.register({ name: "pbot_history", description: historyDescription, parameters: dshParameters(historyParameters),
+        output: { schema: dshOutputSchema(historyResultSchema), render: (_args, value) => [{ type: "text", text: "# 历史\n\n" + markdownFields(value) }] },
+        async execute(value, exec) {
+            check();
+            requireThat(exec.agent === agent, "历史工具不属于当前会话。");
+            const signal = AbortSignal.any([exec.signal, lifetime]);
+            const result = await executeHistory(service, historyInput(value), { host: "dsh", sessionId: agent.id }, signal);
+            check();
+            signal.throwIfAborted();
+            requireThat(valid(result), "历史输出不符合契约。");
+            return json(result);
+        },
+    });
+}

package/lib/tools/result.d.ts

@@ -0,0 +1,18 @@
+export declare function markdownResult(value: unknown, title: string): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: import("../common/json.js").Json;
+    structuredContent: import("../common/json.js").Json;
+};
+export declare function result(value: unknown, isError?: boolean, text?: string): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: import("../common/json.js").Json;
+    structuredContent: import("../common/json.js").Json;
+};

package/lib/tools/result.js

@@ -0,0 +1,10 @@
+import { json } from "../common/json.js";
+import { markdownFields } from "../common/markdown.js";
+export function markdownResult(value, title) {
+    return result(value, false, "# " + title + "\n\n" + markdownFields(json(value)));
+}
+export function result(value, isError = false, text) {
+    const data = json(value);
+    return { content: [{ type: "text", text: text ?? JSON.stringify(data) }],
+        details: data, structuredContent: data, ...(isError ? { isError: true } : {}) };
+}

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

@@ -0,0 +1,24 @@
+import type { Static } from "typebox";
+import type { TeamService } from "../../services/agents/team-service.js";
+import type { AgentService } from "../../services/agents/agent-service.js";
+import type { TeamActor } from "../../model/team.js";
+import type { AgentOwner } from "../../model/agent.js";
+import type { teamParametersSchema, teamMessageParametersSchema } from "./contract.js";
+export declare function executeTeam(service: TeamService, agents: AgentService, input: Static<typeof teamParametersSchema>, owner: AgentOwner): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: import("../../common/json.js").Json;
+    structuredContent: import("../../common/json.js").Json;
+};
+export declare function executeTeamMessage(service: TeamService, input: Static<typeof teamMessageParametersSchema>, actor: TeamActor, requestId: string): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: import("../../common/json.js").Json;
+    structuredContent: import("../../common/json.js").Json;
+};

package/lib/tools/teams/actions.js

@@ -0,0 +1,38 @@
+import { teamMessagesMarkdown } from "../../integrations/team-context.js";
+import { markdownResult, result } from "../result.js";
+export function executeTeam(service, agents, input, owner) {
+    const views = agents.list(owner);
+    service.recover(owner);
+    let id = input.teamId;
+    switch (input.action) {
+        case "create":
+            id = service.create(owner, { name: input.name, brief: input.brief, members: input.members }, views).teamId;
+            break;
+        case "list": return markdownResult({ teams: service.list(owner, views) }, "团队列表");
+        case "read": {
+            const page = service.read(id, { kind: "coordinator", owner }, input);
+            return result(page, false, teamMessagesMarkdown(page));
+        }
+        case "run":
+            service.run(id, owner, { instruction: input.instruction, mode: input.mode,
+                ...(input.rounds === undefined ? {} : { rounds: input.rounds }),
+                ...(input.maxConcurrent === undefined ? {} : { maxConcurrent: input.maxConcurrent }),
+                ...(input.timeoutSeconds === undefined ? {} : { timeoutSeconds: input.timeoutSeconds }) }, views);
+            break;
+        case "pause":
+            service.pause(id, owner);
+            break;
+        case "close":
+            service.close(id, owner, views);
+            break;
+    }
+    return markdownResult(service.status(id, owner, views), "团队状态");
+}
+export function executeTeamMessage(service, input, actor, requestId) {
+    if (input.action === "read") {
+        const page = service.read(input.teamId, actor, input);
+        return result(page, false, teamMessagesMarkdown(page));
+    }
+    const message = service.post(input.teamId, actor, requestId, input.text, input.replyTo);
+    return markdownResult({ teamId: input.teamId, seq: message.seq, status: "stored" }, "团队消息已保存");
+}