@morlay/dsh-tool-guidance 0.0.10 → 0.0.11-alpha.0

package/dist/index.d.mts

@@ -1,11 +1,9 @@
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-//#region src/index.d.ts
 export declare const name = "tool-guidance";
 export declare const inject: string[];
 export interface Config {
   groups?: boolean;
 }
 export declare const Config: z<Config>;
-export declare function apply(ctx: Context, config: Config): void;
-//#endregion
+export declare function apply(ctx: Context, config: Config): void;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import z from "@deepseek-ai/schemastery";
-//#region src/guidance/packs/ask.ts
+// src/guidance/packs/ask.ts
 const ASK_PACK = {
 	family: "ask",
 	tools: [{
@@ -8,8 +8,7 @@ const ASK_PACK = {
 		short: "向用户提问并等待回答"
 	}]
 };
-//#endregion
-//#region src/guidance/packs/code.ts
+// src/guidance/packs/code.ts
 const CODE_PACK = {
 	family: "code",
 	tools: [{
@@ -17,8 +16,7 @@ const CODE_PACK = {
 		short: "用代码调用其它工具（PTC）"
 	}]
 };
-//#endregion
-//#region src/guidance/packs/delegation.ts
+// src/guidance/packs/delegation.ts
 const DELEGATION_PACK = {
 	family: "delegation",
 	tools: [
@@ -40,8 +38,7 @@ const DELEGATION_PACK = {
 		}
 	]
 };
-//#endregion
-//#region src/guidance/packs/flow.ts
+// src/guidance/packs/flow.ts
 const FLOW_PACK = {
 	family: "flow",
 	tools: [
@@ -84,11 +81,14 @@ const FLOW_PACK = {
 		{
 			tool: "schedule_delete",
 			short: "删除一个提醒"
+		},
+		{
+			tool: "plugin_manager",
+			short: "管理本 profile 的插件与 bundle"
 		}
 	]
 };
-//#endregion
-//#region src/guidance/packs/fs.ts
+// src/guidance/packs/fs.ts
 const FS_PACK = {
 	family: "fs",
 	tools: [
@@ -126,8 +126,7 @@ const FS_PACK = {
 		}
 	]
 };
-//#endregion
-//#region src/guidance/packs/shell.ts
+// src/guidance/packs/shell.ts
 const SHELL_PACK = {
 	family: "shell",
 	tools: [
@@ -177,8 +176,7 @@ const SHELL_PACK = {
 		}
 	]
 };
-//#endregion
-//#region src/guidance/packs/skill.ts
+// src/guidance/packs/skill.ts
 const SKILL_PACK = {
 	family: "skill",
 	tools: [{
@@ -186,8 +184,7 @@ const SKILL_PACK = {
 		short: "按需加载技能说明"
 	}]
 };
-//#endregion
-//#region src/guidance/packs/team.ts
+// src/guidance/packs/team.ts
 const TEAM_PACK = {
 	family: "team",
 	tools: [
@@ -229,8 +226,7 @@ const TEAM_PACK = {
 		}
 	]
 };
-//#endregion
-//#region src/guidance/packs/web.ts
+// src/guidance/packs/web.ts
 const WEB_PACK = {
 	family: "web",
 	tools: [{
@@ -241,8 +237,7 @@ const WEB_PACK = {
 		short: "联网搜索"
 	}]
 };
-//#endregion
-//#region src/guidance/packs/group-base.ts
+// src/guidance/packs/group-base.ts
 const BASE_GROUP = {
 	family: "group-base",
 	group: {
@@ -373,8 +368,7 @@ const BASE_GROUP = {
 		]
 	}
 };
-//#endregion
-//#region src/guidance/packs/group-delegation.ts
+// src/guidance/packs/group-delegation.ts
 const DELEGATION_GROUP = {
 	family: "group-delegation",
 	group: {
@@ -431,8 +425,7 @@ const DELEGATION_GROUP = {
 		]
 	}
 };
-//#endregion
-//#region src/guidance/packs/group-flow.ts
+// src/guidance/packs/group-flow.ts
 const FLOW_GROUP = {
 	family: "group-flow",
 	group: {
@@ -484,8 +477,7 @@ const FLOW_GROUP = {
 		]
 	}
 };
-//#endregion
-//#region src/guidance/packs/group-team.ts
+// src/guidance/packs/group-team.ts
 const TEAM_GROUP = {
 	family: "group-team",
 	group: {
@@ -526,8 +518,7 @@ const TEAM_GROUP = {
 		]
 	}
 };
-//#endregion
-//#region src/guidance/packs/index.ts
+// src/guidance/packs/index.ts
 const TOOL_PACKS = [
 	ASK_PACK,
 	CODE_PACK,
@@ -567,14 +558,12 @@ function groupsOf(packs = GROUP_PACKS) {
 	}
 	return groups;
 }
-//#endregion
-//#region src/guidance/types.ts
+// src/guidance/types.ts
 const BASE_GROUP_KEY = "base";
 function skillNameOf(key) {
 	return `tool-group-${key}`;
 }
-//#endregion
-//#region src/guidance/groups.ts
+// src/guidance/groups.ts
 const TOOL_GROUPS = groupsOf(GROUP_PACKS);
 const SHORT_TOOL_DESCRIPTIONS = shortDescriptionsOf(TOOL_PACKS);
 function groupByKey(key) {
@@ -589,8 +578,7 @@ function groupSkillBody(group, visible = () => true) {
 		return typeof when === "string" ? visible(when) : when.some(visible);
 	}).map((line) => `- ${line.text}`).join("\n");
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
 const name = "tool-guidance";
 const inject = [
 	"tools",
@@ -633,15 +621,47 @@ function apply(ctx, config) {
 			};
 		});
 	}
+	const projected = /* @__PURE__ */ new WeakSet();
+	const project = (definition) => {
+		if (projected.has(definition)) return;
+		projected.add(definition);
+		const description = SHORT_TOOL_DESCRIPTIONS[definition.name];
+		if (description !== void 0) Object.defineProperty(definition, "description", {
+			value: description,
+			configurable: true,
+			enumerable: true,
+			writable: true
+		});
+		Object.defineProperty(definition, "parameters", {
+			value: slimSchema(definition.parameters),
+			configurable: true,
+			enumerable: true,
+			writable: true
+		});
+	};
 	ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
 		const result = await next();
 		const agent = context.agent;
-		if (agent !== void 0) visibleTools.set(agent, new Set(result.tools.map((tool) => tool.name)));
-		return {
-			...result,
-			tools: shortenTools(result.tools)
-		};
+		if (agent !== void 0) {
+			const toolSet = context.toolSet;
+			const definitions = ctx.tools.definitions(agent, toolSet);
+			visibleTools.set(agent, new Set(definitions.map((tool) => tool.name)));
+			for (const definition of definitions) project(definition);
+		}
+		return result;
 	}, { prepend: true });
+	ctx.on("agent/created", ({ agent }) => {
+		const projectAgent = () => {
+			for (const definition of ctx.tools.definitions(agent)) project(definition);
+		};
+		projectAgent();
+		agent.ctx.on("tools/change", projectAgent);
+	});
+	const projectVisible = () => {
+		for (const definition of ctx.tools.definitions()) project(definition);
+	};
+	ctx.on("tools/change", projectVisible);
+	projectVisible();
 }
 const baseGroup = groupByKey(BASE_GROUP_KEY);
 function registeredIn(ctx, agent) {
@@ -670,13 +690,12 @@ function injectMessage(name, text) {
 	});
 }
 function latestInjectText(agent, name) {
-	for (const seq of agent.session.surface.nodes.toReversed()) {
-		const event = agent.session.eventAt(seq);
-		if (event?.type !== "user/message") continue;
-		const source = event.data.source;
+	for (const message of agent.session.deriveMessages().toReversed()) {
+		if (message.role !== "user") continue;
+		const source = message.source;
 		if (source.kind !== "skill-invocation" || source.name !== name) continue;
-		const [block] = event.data.content;
-		return event.data.content.length === 1 && block?.type === "text" ? block.text : "";
+		const [block] = message.content;
+		return message.content.length === 1 && block?.type === "text" ? block.text : "";
 	}
 }
 function slimSchema(schema) {
@@ -688,15 +707,4 @@ function slimSchema(schema) {
 	for (const key of ["items", "additionalProperties"]) if (key in rest) rest[key] = slimSchema(rest[key]);
 	return rest;
 }
-function shortenTools(tools) {
-	return tools.map((tool) => {
-		const description = SHORT_TOOL_DESCRIPTIONS[tool.name];
-		return {
-			...tool,
-			parameters: slimSchema(tool.parameters),
-			...description === void 0 ? {} : { description }
-		};
-	});
-}
-//#endregion
 export { Config, apply, inject, name };

package/dist/rows.d.mts

@@ -1,7 +1,5 @@
-//#region src/rows.d.ts
 export declare function toolGuidanceRow(config?: Readonly<Record<string, unknown>>): {
   readonly id: string;
   readonly name: string;
   readonly config?: Readonly<Record<string, unknown>>;
-};
-//#endregion
+};

package/dist/rows.mjs

@@ -1,4 +1,4 @@
-//#region src/rows.ts
+// src/rows.ts
 function toolGuidanceRow(config) {
 	return {
 		id: "tool-guidance",
@@ -6,5 +6,4 @@ function toolGuidanceRow(config) {
 		...config === void 0 ? {} : { config }
 	};
 }
-//#endregion
 export { toolGuidanceRow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/dsh-tool-guidance",
-  "version": "0.0.10",
+  "version": "0.0.11-alpha.0",
   "description": "Tool guidance for dsh: localized short tool descriptions, trimmed schema and usage groups as one host-plane row. The agent row list lives in the agent presets themselves (shipped or deployment-owned).",
   "keywords": [
     "dsh",
@@ -34,29 +34,29 @@
     "./locale/*.json": "./locale/*.json"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-include": "^1.0.10",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "@morlay/dsh-context-assembler": "0.0.10",
-    "@morlay/dsh-session-mode": "0.0.13",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.11-alpha.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.6-alpha.1",
+    "@morlay/dsh-context-assembler": "0.0.11-alpha.0",
+    "@morlay/dsh-session-mode": "0.0.14-alpha.0",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.2.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.2.1-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "@morlay/dsh-context-assembler": "0.0.10"
+    "@deepseek-ai/cordis": "^4.0.6-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-skill": "^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.2.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.6-alpha.1",
+    "@morlay/dsh-context-assembler": "0.0.11-alpha.0"
   },
   "engines": {
-    "dsh": ">= 0.2.1-rc.1 < 0.2.2"
+    "dsh": ">= 0.2.2-alpha.2 < 0.2.3"
   },
   "scripts": {
     "build": "pnpm exec tsdown"

package/src/guidance/packs/flow.ts

@@ -14,5 +14,6 @@ export const FLOW_PACK: ToolPack = {
     { tool: "schedule_list", short: "列出本会话的活动提醒" },
     { tool: "schedule_update", short: "原地改一个提醒" },
     { tool: "schedule_delete", short: "删除一个提醒" },
+    { tool: "plugin_manager", short: "管理本 profile 的插件与 bundle" },
   ],
 };

package/src/index.ts

@@ -1,8 +1,8 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
-import { createUserMessage, type ToolSchema } from "@deepseek-ai/dsh-llm";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import type {} from "@deepseek-ai/dsh-skill";
-import type {} from "@deepseek-ai/dsh-tools";
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
 import type {} from "@morlay/dsh-context-assembler";
 import z from "@deepseek-ai/schemastery";
 import {
@@ -89,24 +89,72 @@ export function apply(ctx: Context, config: Config): void {
     });
   }
 
-  // 本行挂在**最外层**（`prepend`）：会话收窄的监听比本行先注册（host 平面的行先于本行的 scope），而瀑布里
-  // 先注册的是外层——收窄发生在它的返回路径上，站在内层读 `next()` 拿到的是收窄**之前**的目录。站到最外层，
-  // 一次装配走完手里的 `result` 才是这个会话最终可见的那份。工具投影的改写与过滤可交换（只换描述与 schema，
-  // 不动名字），所以把改写一并挪到最外层，别人看到的结果不变。
+  // 工具投影的改写落在**工具定义**上：装配瀑布不再承载工具声明，而 `llm/stream` 的 options 是上游冻结过的
+  // （`agent-loop` 用 `Object.freeze` 构造请求），在监听器里写 `options.tools` 会抛
+  // `Cannot assign to read only property 'tools'`。定义对象本身可变，改它的 `description` / `parameters` 就等于
+  // 改了 `executor.describe()` 的输出（模型面），**不经过 `tools.register`，也不触发 `tools/change` 重入**；
+  // 执行期的输入校验用的是 `defineTool` 闭包里那份原 schema，不受这里替换影响。
+  const projected = new WeakSet<object>();
+  const project = (definition: ToolDefinition): void => {
+    if (projected.has(definition)) return;
+    projected.add(definition);
+    const description = SHORT_TOOL_DESCRIPTIONS[definition.name];
+    if (description !== undefined) {
+      Object.defineProperty(definition, "description", {
+        value: description,
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
+    }
+    Object.defineProperty(definition, "parameters", {
+      value: slimSchema(definition.parameters),
+      configurable: true,
+      enumerable: true,
+      writable: true,
+    });
+  };
+  // 本行挂在**最外层**（`prepend`）：`base` 正文要按这个会话最终可见的工具目录过滤，而装配上下文里的
+  // `toolSet` 就是这一步的准入集（上游 0.2.1-rc.2 起工具声明由 `tools.resolve` 定，装配瀑布不再带 `tools`）。
   ctx.on(
     "system-prompt/assemble",
     async (_assembly, context, next) => {
       const result = await next();
       const agent = context.agent;
-      // 记名字集合：`result.tools` 是投影**之后**的目录（收窄已生效、描述已被 `shortenTools` 换过），
-      // 名字不受描述改写影响。诊断式的无 agent 装配不记（那种装配也不属于任何会话）。
+      // 记名字集合：准入集已应用这个会话的收窄（`tools.restrict`）与条件激活，名字不受描述改写影响。
+      // 诊断式的无 agent 装配不记（那种装配也不属于任何会话）。
       if (agent !== undefined) {
-        visibleTools.set(agent, new Set(result.tools.map((tool) => tool.name)));
+        const toolSet = context.toolSet;
+        const definitions = ctx.tools.definitions(agent, toolSet);
+        visibleTools.set(
+          agent,
+          new Set(definitions.map((tool) => tool.name)),
+        );
+        // 会话内晚注册的工具（MCP 重连、skill 重载）赶不上 `agent/created`：这里补一次改写。本次装配的声明已经
+        // 按旧定义收集过了，所以从**下一次**请求开始生效。
+        for (const definition of definitions) project(definition);
       }
-      return { ...result, tools: shortenTools(result.tools) };
+      return result;
     },
     { prepend: true },
   );
+
+  // 工具注册在**会话挂着的那份 preset 的 scope** 上，全局 `definitions()` 看不到它们：会话建好时按它的视图改一遍，
+  // 这是第一次装配之前的时机。`tools/change` 只管全局可见的那部分；会话内晚注册的工具由装配监听补（下一次请求生效）。
+  ctx.on("agent/created", ({ agent }) => {
+    const projectAgent = (): void => {
+      for (const definition of ctx.tools.definitions(agent)) project(definition);
+    };
+    projectAgent();
+    // 团队、schedule 这类行在**会话建好之后**才把工具注册进 agent scope：全局 `tools/change` 看不到它们，
+    // 所以每个会话自己跟这条事件（监听挂在 `agent.ctx` 上，随会话收回）。
+    agent.ctx.on("tools/change", projectAgent);
+  });
+  const projectVisible = (): void => {
+    for (const definition of ctx.tools.definitions()) project(definition);
+  };
+  ctx.on("tools/change", projectVisible);
+  projectVisible();
 }
 
 const baseGroup = groupByKey(BASE_GROUP_KEY);
@@ -141,13 +189,14 @@ function injectMessage(name: string, text: string): ReturnType<typeof createUser
 // surface 上最近一条该键注入的正文（含信封）；没有则 undefined——压缩掉它、或进程重启后 resume 折叠出它，
 // 都由这一眼分辨。
 function latestInjectText(agent: Agent, name: string): string | undefined {
-  for (const seq of agent.session.surface.nodes.toReversed()) {
-    const event = agent.session.eventAt(seq);
-    if (event?.type !== "user/message") continue;
-    const source = event.data.source as { readonly kind?: unknown; readonly name?: unknown };
+  // `deriveMessages()` 是 surface 的派生消息视图（受支持的同步读）；逐 seq 读事件的
+  // `eventAt` / `snapshotEvents` / `ownEvents` 已被上游声明为「新调用禁止」。
+  for (const message of agent.session.deriveMessages().toReversed()) {
+    if (message.role !== "user") continue;
+    const source = message.source as { readonly kind?: unknown; readonly name?: unknown };
     if (source.kind !== "skill-invocation" || source.name !== name) continue;
-    const [block] = event.data.content;
-    return event.data.content.length === 1 && block?.type === "text" ? block.text : "";
+    const [block] = message.content;
+    return message.content.length === 1 && block?.type === "text" ? block.text : "";
   }
   return undefined;
 }
@@ -179,16 +228,3 @@ function slimSchema(schema: unknown): unknown {
   return rest;
 }
 
-// 改写模型看到的工具投影：描述换成一行中文，参数只留约束（`type` / `enum` / `oneOf` / `required` / `default`），
-// 说明性字段整段丢弃。改装配结果而不是注册表——注册同名工具会触发 `tools/change`，与上游 `tool-subagent` 的
-// composition reconcile 互相触发会造成装配风暴式重入；投影只影响本次请求，晚注册的工具也照样能覆盖。
-function shortenTools(tools: readonly ToolSchema[]): ToolSchema[] {
-  return tools.map((tool) => {
-    const description = SHORT_TOOL_DESCRIPTIONS[tool.name];
-    return {
-      ...tool,
-      parameters: slimSchema(tool.parameters),
-      ...(description === undefined ? {} : { description }),
-    } as ToolSchema;
-  });
-}