personal-bot 0.2.4 → 0.2.6

package/lib/extension/dsh/management.js

@@ -0,0 +1,217 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { extractSessionEventText } from "@deepseek-ai/dsh-session-query";
+import { Type } from "typebox";
+import { json } from "../../common/json.js";
+import { requireThat, schema } from "../../common/validation.js";
+import { packageVersion } from "../../common/version.js";
+import { historyInput } from "../../tools/history/contract.js";
+import { executeHistory } from "../../tools/history/actions.js";
+import { pbotReadRemote } from "../../ui/dsh/remote.js";
+const requestSchema = Type.Object({ parentSessionId: Type.String({ minLength: 1 }), input: Type.Optional(Type.Unknown()) }, { additionalProperties: false });
+const expertSchema = Type.Object({ agentId: Type.String({ minLength: 1 }), offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })), seq: Type.Optional(Type.Integer({ minimum: 0 })),
+    textOffset: Type.Optional(Type.Integer({ minimum: 0 })), textLimit: Type.Optional(Type.Integer({ minimum: 2, maximum: 24000 })),
+    format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("json")])) }, { additionalProperties: false });
+const teamSchema = Type.Object({ teamId: Type.String({ minLength: 1 }), 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 })) }, { additionalProperties: false });
+const validRequest = schema(requestSchema), validExpert = schema(expertSchema), validTeam = schema(teamSchema);
+export function dshStatus(workspaces, workspace) {
+    workspace.check();
+    const agents = workspace.agents.list(workspace.owner);
+    return json({ host: "dsh", release: packageVersion, workspaceRoot: workspace.root, sessionId: workspace.agent.id,
+        model: workspace.agent.model.current() ?? null, python: workspaces.python.status,
+        controlError: workspace.controlError ?? null, history: workspace.history.status,
+        agents, teams: workspace.teams.list(workspace.owner, agents) });
+}
+/** Native Remote owns transport and access checks. These workspace reads do not admit or cancel execution. */
+let PbotManagement = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _snapshot_decorators;
+    let _expert_decorators;
+    let _team_decorators;
+    let _history_decorators;
+    return class PbotManagement extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _snapshot_decorators = [Remote];
+            _expert_decorators = [Remote];
+            _team_decorators = [Remote];
+            _history_decorators = [Remote];
+            __esDecorate(this, null, _snapshot_decorators, { kind: "method", name: "snapshot", static: false, private: false, access: { has: obj => "snapshot" in obj, get: obj => obj.snapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _expert_decorators, { kind: "method", name: "expert", static: false, private: false, access: { has: obj => "expert" in obj, get: obj => obj.expert }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _team_decorators, { kind: "method", name: "team", static: false, private: false, access: { has: obj => "team" in obj, get: obj => obj.team }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _history_decorators, { kind: "method", name: "history", static: false, private: false, access: { has: obj => "history" in obj, get: obj => obj.history }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        workspaces = __runInitializers(this, _instanceExtraInitializers);
+        constructor(ctx, workspaces) {
+            super(ctx, "pbotManagement", { namespace: "pbot" });
+            this.workspaces = workspaces;
+        }
+        async workspace(request, signal) {
+            signal.throwIfAborted();
+            requireThat(validRequest(request), "管理查询参数无效。");
+            const args = request;
+            const agent = this.ctx.agents.get(SessionId(args.parentSessionId));
+            requireThat(agent, "父会话未加载或已关闭，请在原生会话页面重新打开。");
+            const workspace = await this.workspaces.get(agent);
+            signal.throwIfAborted();
+            workspace.check();
+            return { workspace, input: args.input, signal: AbortSignal.any([signal, workspace.lifetime.signal]) };
+        }
+        async snapshot(request, signal) {
+            const { workspace, input } = await this.workspace(request, signal);
+            requireThat(input === undefined, "工作区状态查询不接受额外参数。");
+            return dshStatus(this.workspaces, workspace);
+        }
+        async expert(request, signal) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const current = await this.workspace(request, signal), { workspace, input } = current;
+                requireThat(validExpert(input), "专家记录查询参数无效。");
+                const args = input;
+                const view = workspace.agents.status(args.agentId, workspace.owner);
+                const observation = __addDisposableResource(env_1, await this.ctx.sessionQuery.observeSession(SessionId(view.agentId), { projectionMode: "none", signal: current.signal }), false);
+                workspace.check();
+                current.signal.throwIfAborted();
+                const header = observation.header;
+                requireThat(header.id === view.agentId && header.cwd === view.cwd && header.parentSession === workspace.agent.id &&
+                    header.origin === "subagent" && !header.isSeeded, "原生专家记录的身份或归属不匹配。");
+                const events = observation.events;
+                if (args.seq !== undefined) {
+                    const event = events.find(value => value.seq === args.seq);
+                    requireThat(event, "原生记录位置不存在。");
+                    const text = (args.format === "text" ? extractSessionEventText(event) : "") || JSON.stringify(event, null, 2), offset = args.textOffset ?? 0;
+                    requireThat(offset <= text.length, "原生记录分页位置超出范围。");
+                    let end = Math.min(text.length, offset + (args.textLimit ?? 12000));
+                    if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1]))
+                        end--;
+                    return json({ agent: view, cursor: observation.cursor, seq: event.seq, offset, text: text.slice(offset, end),
+                        totalLength: text.length, nextOffset: end < text.length ? end : null });
+                }
+                const limit = args.limit ?? 30, offset = args.offset ?? Math.max(0, events.length - limit);
+                requireThat(offset <= events.length, "原生记录分页位置超出范围。");
+                return json({ agent: view, header, cursor: observation.cursor, total: events.length, offset,
+                    nextOffset: offset + limit < events.length ? offset + limit : null,
+                    events: events.slice(offset, offset + limit).map(event => ({ seq: event.seq, type: event.type, time: event.time,
+                        ...(event.type === "user/message" ? { source: event.data.source.kind } : {}), preview: extractSessionEventText(event).slice(0, 800) })) });
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        }
+        async team(request, signal) {
+            const { workspace, input } = await this.workspace(request, signal);
+            requireThat(validTeam(input), "团队记录查询参数无效。");
+            const args = input;
+            return json({ team: workspace.teams.status(args.teamId, workspace.owner, workspace.agents.list(workspace.owner)),
+                page: workspace.teams.read(args.teamId, { kind: "user", owner: workspace.owner }, args) });
+        }
+        async history(request, signal) {
+            const current = await this.workspace(request, signal), { workspace, input } = current;
+            const result = await executeHistory(workspace.history, historyInput(input), { host: "dsh", sessionId: workspace.agent.id }, current.signal);
+            workspace.check();
+            current.signal.throwIfAborted();
+            return json(result);
+        }
+    };
+})();
+export { PbotManagement };
+export function registerDshManagement(ctx, workspaces) {
+    ctx.typert.register({ package: pbotReadRemote.package, face: "host", schemas: [],
+        model: { services: [], events: [], objects: [] }, invocations: pbotReadRemote.descriptors });
+    return new PbotManagement(ctx, workspaces);
+}

package/lib/extension/dsh/workspace.d.ts

@@ -0,0 +1,48 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { AgentOwner } from "../../model/agent.js";
+import { DshAgents } from "../../integrations/dsh/dsh-agents.js";
+import { AgentService } from "../../services/agents/agent-service.js";
+import { TeamService } from "../../services/agents/team-service.js";
+import { DshAgentRuntime } from "./agent-runtime.js";
+import { DshHistoryWork } from "./history.js";
+import type { HistoryService } from "../../services/history/history-service.js";
+import { PythonEnvironmentService } from "../../services/workspace/python-environment-service.js";
+export declare const dshDependencies: string[];
+export declare class DshWorkspace {
+    #private;
+    readonly ctx: Context;
+    readonly root: string;
+    readonly agent: Agent;
+    readonly python: PythonEnvironmentService;
+    readonly component: AbortSignal;
+    private readonly historyWork;
+    private readonly releaseHistory;
+    readonly lifetime: AbortController;
+    readonly host: DshAgents;
+    readonly agents: AgentService;
+    readonly teams: TeamService;
+    readonly history: HistoryService;
+    readonly owner: AgentOwner;
+    constructor(ctx: Context, root: string, agent: Agent, python: PythonEnvironmentService, component: AbortSignal, historyWork: DshHistoryWork, releaseHistory: () => Promise<void>);
+    check: () => void;
+    get controlError(): string | undefined;
+    open(): Promise<void>;
+    expert(id: string): DshAgentRuntime;
+    close(): Promise<void>;
+}
+/** The execution component owns Python; closing one Session must not undo its activation. */
+export declare class DshWorkspaces {
+    #private;
+    readonly ctx: Context;
+    readonly python: PythonEnvironmentService;
+    constructor(ctx: Context);
+    private history;
+    open(agent: Agent): Promise<DshWorkspace>;
+    get(agent: Agent): Promise<DshWorkspace>;
+    preparePython(): Promise<{
+        directory: string;
+        python: string;
+    }>;
+    close(): Promise<void>;
+}

package/lib/extension/dsh/workspace.js

@@ -0,0 +1,290 @@
+import { realpath } from "node:fs/promises";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import { DshAgents } from "../../integrations/dsh/dsh-agents.js";
+import { dshResources, dshExpertTools } from "../../integrations/dsh/resources.js";
+import { AgentService } from "../../services/agents/agent-service.js";
+import { TeamService } from "../../services/agents/team-service.js";
+import { registerDshAgentTool } from "../../tools/agents/dsh-tool.js";
+import { registerDshTeamTool, registerDshTeamMessageTool } from "../../tools/teams/dsh-tool.js";
+import { DshAgentRuntime } from "./agent-runtime.js";
+import { DshAgentEvents } from "./agent-events.js";
+import { registerDshFileEvents } from "./files.js";
+import { DshHistoryWork, registerDshHistoryEvents } from "./history.js";
+import { registerDshHistoryTool } from "../../tools/history/dsh-tool.js";
+import { activatePython } from "../../integrations/python-activation.js";
+import { PythonEnvironmentService } from "../../services/workspace/python-environment-service.js";
+import { requireThat } from "../../common/validation.js";
+export const dshDependencies = ["agents", "sessions", "sessionPersistence", "sessionQuery", "llm", "tools", "systemPrompt", "skills", "fs", "attachments", "workingDirectory", "approval"];
+export class DshWorkspace {
+    ctx;
+    root;
+    agent;
+    python;
+    component;
+    historyWork;
+    releaseHistory;
+    lifetime = new AbortController();
+    host;
+    agents;
+    teams;
+    history;
+    owner;
+    #experts = new Map();
+    #scope;
+    #events;
+    #closing;
+    constructor(ctx, root, agent, python, component, historyWork, releaseHistory) {
+        this.ctx = ctx;
+        this.root = root;
+        this.agent = agent;
+        this.python = python;
+        this.component = component;
+        this.historyWork = historyWork;
+        this.releaseHistory = releaseHistory;
+        this.history = historyWork.service;
+        this.owner = { sessionId: agent.id, leaf: null, branch: [] };
+        this.host = new DshAgents(ctx, agent, {
+            setup: (d, _directory, generation) => async (agentCtx, child) => {
+                for (const key of ["noExtensions", "noPromptTemplates", "noContextFiles"])
+                    requireThat(d.options[key] === undefined, "dsh 不支持宿主选项：" + key);
+                await agentCtx.plugin({ name: "pbot-expert", inject: dshDependencies, apply: async (scope) => {
+                        const runtime = new DshAgentRuntime(scope, child, d, generation, this.agents.files, this.teams, { check: this.check, release: () => this.host.release(d.agentId, generation) });
+                        this.#experts.set(d.agentId, runtime);
+                        scope.effect(() => () => { if (this.#experts.get(d.agentId) === runtime)
+                            this.#experts.delete(d.agentId); });
+                        await dshResources(scope, child, root, "general-purpose", () => python.status, runtime.check);
+                        const teamTool = dshExpertTools(scope, child, d.options);
+                        if (teamTool)
+                            registerDshTeamMessageTool(scope, child, this.teams, runtime.actor, runtime.check);
+                        registerDshFileEvents(scope, child, root, true, runtime.check);
+                        runtime.initialize(teamTool);
+                    } });
+                return { commit: this.check };
+            },
+            ready: (child, generation) => {
+                const runtime = this.#experts.get(child.id);
+                requireThat(runtime?.generation === generation, "专家执行组件未就绪。");
+                runtime.start();
+            },
+            stopping: async (child, generation) => { const runtime = this.#experts.get(child.id); if (runtime?.generation === generation)
+                await runtime.stop(); },
+        }, this.lifetime.signal);
+        this.agents = new AgentService(root, dshHomePath("pbot", "subagents"), this.host);
+        this.teams = new TeamService(root, this.agents.files, this.agents.teamFiles);
+    }
+    check = () => { this.component.throwIfAborted(); this.lifetime.signal.throwIfAborted(); };
+    get controlError() { return this.#events?.error; }
+    async open() {
+        this.check();
+        this.#scope = await this.agent.ctx.plugin({ name: "pbot-coordinator", inject: dshDependencies, apply: async (ctx) => {
+                await dshResources(ctx, this.agent, this.root, "coordinator", () => this.python.status, this.check);
+                registerDshFileEvents(ctx, this.agent, this.root, false, this.check);
+                registerDshAgentTool(ctx, this.agent, this.agents, this.owner, this.check);
+                registerDshTeamTool(ctx, this.agent, this.teams, this.agents, this.owner, this.check);
+                registerDshTeamMessageTool(ctx, this.agent, this.teams, () => ({ kind: "coordinator", owner: this.owner }), this.check);
+                registerDshHistoryTool(ctx, this.agent, this.history, this.lifetime.signal, this.check);
+                registerDshHistoryEvents(ctx, this.agent, this.historyWork, this.check);
+                this.#events = new DshAgentEvents(ctx, this.agent, this.agents, this.teams, this.owner, this.check);
+                this.#events.start();
+            } });
+        this.check();
+    }
+    expert(id) {
+        this.check();
+        const view = this.agents.status(id, this.owner), runtime = this.#experts.get(id);
+        requireThat(view.owned, "专家不属于当前父会话。");
+        requireThat(view.alive, "专家已停止；需要明确恢复后才能对话。");
+        requireThat(view.state !== "starting", "专家尚未就绪，请等待启动或恢复完成。");
+        requireThat(runtime?.generation === view.generation, "原生专家由其他执行实例持有；当前组件不能接管对话。");
+        return runtime;
+    }
+    close() {
+        if (this.#closing)
+            return this.#closing;
+        this.lifetime.abort();
+        this.#closing = (async () => {
+            const errors = [];
+            try {
+                await this.#events?.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                this.teams.pauseAll(this.owner, "父会话或执行组件关闭");
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await this.agents.close(this.owner);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await this.host.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            this.teams.dispose();
+            try {
+                await this.#scope?.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await this.releaseHistory();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            if (errors.length)
+                throw new AggregateError(errors, "dsh 工作区关闭失败；请核对执行资源和控制记录。");
+        })();
+        return this.#closing;
+    }
+}
+/** The execution component owns Python; closing one Session must not undo its activation. */
+export class DshWorkspaces {
+    ctx;
+    python = new PythonEnvironmentService(process.cwd());
+    #parents = new Map();
+    #parentEffects = new Map();
+    #histories = new Map();
+    #lifetime = new AbortController();
+    #restorePython;
+    #preparing;
+    #closing;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async history(root) {
+        this.#lifetime.signal.throwIfAborted();
+        let entry = this.#histories.get(root);
+        if (entry && entry.users === 0) {
+            await entry.work.close();
+            this.#lifetime.signal.throwIfAborted();
+            if (this.#histories.get(root) === entry)
+                this.#histories.delete(root);
+            return this.history(root);
+        }
+        if (!entry) {
+            entry = { work: new DshHistoryWork(this.ctx, root), users: 0 };
+            this.#histories.set(root, entry);
+        }
+        const owned = entry;
+        owned.users++;
+        let released = false;
+        return { work: owned.work, release: async () => {
+                if (released)
+                    return;
+                released = true;
+                if (--owned.users === 0) {
+                    try {
+                        await owned.work.close();
+                    }
+                    finally {
+                        if (this.#histories.get(root) === owned)
+                            this.#histories.delete(root);
+                    }
+                }
+            } };
+    }
+    async open(agent) {
+        this.#lifetime.signal.throwIfAborted();
+        requireThat(this.ctx.agents.roots().includes(agent) && agent.session.header.origin !== "subagent", "专家不拥有协调者管理入口。");
+        const current = this.#parents.get(agent);
+        if (current)
+            return current;
+        const opening = (async () => {
+            const root = await realpath(agent.session.header.cwd ?? process.cwd());
+            this.#lifetime.signal.throwIfAborted();
+            const history = await this.history(root);
+            let workspace;
+            try {
+                workspace = new DshWorkspace(this.ctx, root, agent, this.python, this.#lifetime.signal, history.work, history.release);
+                const owned = workspace;
+                const dispose = agent.ctx.effect(() => async () => {
+                    this.#parents.delete(agent);
+                    this.#parentEffects.delete(agent);
+                    await owned.close();
+                });
+                this.#parentEffects.set(agent, dispose);
+                await workspace.open();
+                this.#lifetime.signal.throwIfAborted();
+                return workspace;
+            }
+            catch (error) {
+                try {
+                    const dispose = this.#parentEffects.get(agent);
+                    if (dispose)
+                        await dispose();
+                    else if (workspace)
+                        await workspace.close();
+                    else
+                        await history.release();
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], "dsh 工作区装配与清理均未完成。");
+                }
+                throw error;
+            }
+        })();
+        this.#parents.set(agent, opening);
+        try {
+            return await opening;
+        }
+        catch (error) {
+            this.#parents.delete(agent);
+            throw error;
+        }
+    }
+    async get(agent) {
+        this.#lifetime.signal.throwIfAborted();
+        requireThat(this.ctx.agents.get(agent.id) === agent, "父会话已关闭。");
+        const workspace = await this.open(agent);
+        workspace.check();
+        return workspace;
+    }
+    preparePython() {
+        this.#lifetime.signal.throwIfAborted();
+        if (this.#preparing)
+            return this.#preparing;
+        this.#preparing = (async () => {
+            const result = await this.python.setup(this.#lifetime.signal);
+            this.#lifetime.signal.throwIfAborted();
+            if (!this.#restorePython)
+                this.#restorePython = activatePython(result.directory);
+            return result;
+        })().finally(() => { this.#preparing = undefined; });
+        return this.#preparing;
+    }
+    close() {
+        if (this.#closing)
+            return this.#closing;
+        this.#lifetime.abort();
+        this.#closing = (async () => {
+            try {
+                const opened = await Promise.allSettled(this.#parents.values());
+                const closed = await Promise.allSettled(opened.filter(v => v.status === "fulfilled").map(v => v.value.close()));
+                const effects = await Promise.allSettled([...this.#parentEffects.values()].map(dispose => dispose()));
+                const histories = await Promise.allSettled([...this.#histories.values()].map(value => value.work.close()));
+                await this.python.close();
+                const errors = [...new Set([...closed, ...effects, ...histories].flatMap(value => value.status === "rejected" ? [value.reason] : []))];
+                if (errors.length)
+                    throw new AggregateError(errors, "部分 dsh 工作区未能完成关闭。");
+            }
+            finally {
+                this.#parents.clear();
+                this.#parentEffects.clear();
+                this.#histories.clear();
+                this.#restorePython?.();
+                this.#restorePython = undefined;
+            }
+        })();
+        return this.#closing;
+    }
+}

package/lib/integrations/agent-resources.d.ts

@@ -0,0 +1 @@
+export declare function agentText(agent: "coordinator" | "general-purpose", root: string): Promise<string>;

package/lib/integrations/agent-resources.js

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

package/lib/integrations/dsh/dsh-agents.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent, AgentSetup } from "@deepseek-ai/dsh-agent";
+import type { AgentDescriptor, AgentSessionReference } from "../../model/agent.js";
+import type { AgentHost } from "../../services/agents/agent-service.js";
+/** Native handles belong to the execution component, independently of browser observers. */
+export declare class DshAgents implements AgentHost {
+    #private;
+    readonly ctx: Context;
+    readonly parent: Agent;
+    readonly composition: {
+        setup(d: AgentDescriptor, directory: string, generation: string): AgentSetup;
+        ready(agent: Agent, generation: string): void;
+        stopping(agent: Agent, generation: string): Promise<void>;
+    };
+    readonly lifetime: AbortSignal;
+    readonly kind = "dsh";
+    constructor(ctx: Context, parent: Agent, composition: {
+        setup(d: AgentDescriptor, directory: string, generation: string): AgentSetup;
+        ready(agent: Agent, generation: string): void;
+        stopping(agent: Agent, generation: string): Promise<void>;
+    }, lifetime: AbortSignal);
+    available(): void;
+    alive(id: string): boolean;
+    private reference;
+    validateSession(d: AgentDescriptor, reference: AgentSessionReference): Promise<void>;
+    launch(d: AgentDescriptor, directory: string, generation: string, reference: AgentSessionReference, resume: boolean, signal: AbortSignal): Promise<void>;
+    release(id: string, generation: string): Promise<void>;
+    report(d: AgentDescriptor, reference: AgentSessionReference, position: string): Promise<string>;
+    close(): Promise<void>;
+}