@deepseek-ai/dsh-tool-subagent 0.1.3-alpha.2 → 0.1.5-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent/README.md
-README.md: fc01b8417bc5d6d9a896954de62e64a7b8d276a7
-README.zh.md: e726ea6234bf1f6f24c6ee57d5f63050aa99719c
+README.md: 97bb9b143f003c830b68ffae9e25dee588a8fa67
+README.zh.md: 1804f8f5da2dcd8fbdd043d247e6c234ea090529

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-subagent` is the model-facing delegation tool: it turns one configured `ctx.subagents` provider into a tool the agent can call to start a child agent. Changing the provider changes the transport without changing the execution contract, so one composition can expose several delegation tools, each bound to a different backend. Calls wait for the child by default under `one-shot` policy, or start work in the background by default under `continuable` policy, which returns a durable child id the model can message later. An eligible instance can also let the model discover and select the child's LLM provider, model, and reasoning effort. The tool's descriptions adapt to whether the child inherits the parent's completed turns, and failed runs surface as errored tool results rather than partial success.
+Use this package to give an agent a named tool that delegates work to a configured child-agent backend. In `one-shot` mode, calls wait for the child by default; in `continuable` mode, they start a persistent child in the background and return an id for later messages. Supported backends can also expose approved child LLM providers, models, and reasoning effort for selection. Each instance can set child persona, tool access, and depth limits, while failed runs return errors instead of partial success.
 
 ## Table of Contents
 
@@ -44,7 +44,7 @@ Load the subagent service, an in-process or remote backend, and this tool; then
 |---|---|---|
 | `provider` | required | Provider name on `ctx.subagents` (e.g. `spawn`, `fork`, `acp`) |
 | `toolName` | `subagent` | Model-facing tool name; distinct for every loaded instance |
-| `modelSelectionSettings` | `false` | Sample the Host's exact-route authorization preference for each new top-level Session; valid only in Agent scope and requires provider `agentOptions` support |
+| `modelSelectionSettings` | `false` | Sample the Host's exact-route authorization preference for each top-level Session; a standing preset observes matching Sessions, while direct Agent setup passes its Session explicitly; requires provider `agentOptions` support |
 | `enableRunInBackground` | `true` | Expose `run_in_background`; disabling also rejects forced background calls |
 | `backgroundMode` | `one-shot` | Background policy: `one-shot` defaults calls to foreground; `continuable` defaults them to background and requires the provider's `prepareContinuable` capability |
 | `agentOptions` | — | Configured child `provider`, `model`, adapter-owned `reasoningEffort`, and positive `maxTokens` defaults; requires provider `agentOptions` support and overlays any provider-owned route defaults |
@@ -80,7 +80,7 @@ This section explains how the tool mirrors provider lifecycle and settles runs;
 
 ### Design concept
 
-One instance is one provider plus one tool name. The plugin mirrors provider lifecycle: it registers the tool when the named provider appears and disposes it when the provider leaves, so sibling load order and HMR replacement cannot strand a dangling tool. A numeric `maxDepth` or configured LLM selection the provider cannot enforce fails the mount instead of the first delegation. At most one instance in a tool scope may own model selection because `list_subagent_models` has a global name.
+One instance is one provider plus one tool name. The plugin mirrors provider lifecycle: it registers the tool when the named provider appears and disposes it when the provider leaves, so sibling load order and HMR replacement cannot strand a dangling tool. Direct Agent setup passes its unpublished Session explicitly and awaits installation before publication. A settings-backed standing preset receives each matching Agent from lifecycle events, selects policy from its Session, and installs through its Context. A numeric `maxDepth` or configured LLM selection the provider cannot enforce fails the mount instead of the first delegation. At most one instance in a tool scope may own model selection because `list_subagent_models` has a global name.
 
 ### Foreground settlement
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-subagent` 是面向模型的委派工具：它把一个已配置的 `ctx.subagents` 提供方变成 agent 可以调用来启动子 agent（智能体）的工具。更换提供方只会改变传输，不会改变执行约定，因此一个组合可以暴露多个委派工具，各自绑定不同的后端。`one-shot` 策略下，调用默认在前台等待子 agent；`continuable` 策略下，调用默认在后台启动工作，并返回模型之后可以发消息的持久化子 agent id。合适的实例还可让模型发现并选择子 agent 的 LLM 提供方、模型与推理等级。工具的描述会随子 agent 是否继承父级已完成轮次而调整，失败的运行以出错的工具结果呈现，而非部分成功。
+使用本包可为 agent 提供一个具名工具，把工作委派给已配置的子 agent 后端。`one-shot` 模式下，调用默认等待子 agent；`continuable` 模式下，调用默认在后台启动持久化子 agent，并返回可用于后续消息的 id。受支持的后端还可公开获准的子级 LLM 提供方、模型与推理等级供模型选择。每个实例均可设置子 agent 的 persona、工具权限与深度限制，失败的运行会返回错误，而非部分成功。
 
 ## 目录
 
@@ -44,7 +44,7 @@ kind: "package-reference"
 |---|---|---|
 | `provider` | 必填 | `ctx.subagents` 上的提供方名称（如 `spawn`、`fork`、`acp`） |
 | `toolName` | `subagent` | 面向模型的工具名称；每个已加载实例必须不同 |
-| `modelSelectionSettings` | `false` | 为每个新顶层 Session 读取宿主的精确路由授权偏好；只在 Agent 作用域内有效，并要求提供方支持 `agentOptions` |
+| `modelSelectionSettings` | `false` | 为每个顶层 Session 读取宿主的精确路由授权偏好；常驻 preset 观察匹配 Session，直接 Agent setup 则显式传入其 Session；要求提供方支持 `agentOptions` |
 | `enableRunInBackground` | `true` | 公开 `run_in_background`；禁用时也会拒绝强制后台调用 |
 | `backgroundMode` | `one-shot` | 后台策略：`one-shot` 默认前台调用；`continuable` 默认后台调用，并要求提供方具备 `prepareContinuable` 能力 |
 | `agentOptions` | — | 配置的子级 `provider`、`model`、适配器所有的 `reasoningEffort` 与正整数 `maxTokens` 默认值；要求提供方支持 `agentOptions`，并会覆盖提供方持有的路由默认值 |
@@ -80,7 +80,7 @@ kind: "package-reference"
 
 ### 设计理念
 
-一个实例就是一个提供方加一个工具名称。插件镜像提供方生命周期：具名提供方出现时注册工具，提供方离开时释放工具，因此同级加载顺序与 HMR 替换不会让工具悬空。提供方无法执行的数值型 `maxDepth` 或已配置 LLM 选择会在挂载时失败，而不是在首次委派时失败。每个工具作用域内最多一个实例可以拥有模型选择，因为 `list_subagent_models` 使用全局名称。
+一个实例就是一个提供方加一个工具名称。插件镜像提供方生命周期：具名提供方出现时注册工具，提供方离开时释放工具，因此同级加载顺序与 HMR 替换不会让工具悬空。直接 Agent setup 显式传入尚未发布的 Session，并在发布前等待安装完成。由设置控制的常驻 preset 从生命周期事件接收每个匹配 Agent，从其 Session 选择策略，并通过其 Context 安装。提供方无法执行的数值型 `maxDepth` 或已配置 LLM 选择会在挂载时失败，而不是在首次委派时失败。每个工具作用域内最多一个实例可以拥有模型选择，因为 `list_subagent_models` 使用全局名称。
 
 ### 前台结算
 

package/lib/index.js

@@ -359,7 +359,13 @@ function resolveDelegationRun(request, options) {
 	}
 	return { runInBackground: request.run_in_background ?? options.continuable };
 }
-function apply(ctx, config) {
+/**
+* Install one delegation-tool composition.
+* @param ctx - Context that owns the registrations.
+* @param config - delegation-tool configuration.
+* @param session - unpublished Session supplied by a direct Agent setup; omit for a standing composition.
+*/
+function apply(ctx, config, session) {
 	if (config.maxDepth !== "provider-managed") assertSubagentMaxDepth(config.maxDepth);
 	if (config.toolFilter !== void 0 && config.toolFilter.allow === void 0 && config.toolFilter.deny === void 0) throw new Error("tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter");
 	const backgroundEnabled = config.enableRunInBackground !== false;
@@ -579,32 +585,33 @@ function apply(ctx, config) {
 	}
 	const settings = ctx.get("subagentModelSelection");
 	if (settings === void 0) throw new Error("tool-subagent: `modelSelectionSettings` requires @deepseek-ai/dsh-tool-subagent/model-selection-settings in the Host scope");
-	const compositionScope = scopeOf(ctx);
-	if (compositionScope === void 0) throw new Error("tool-subagent: `modelSelectionSettings` requires an Agent or preset scope");
-	const selectForAgent = (agent) => {
-		const freshSession = agent.session.firstLiveSeq === 0 && agent.session.eventAt(SessionSeq(0))?.type !== "session/end-seed";
-		let allowedModels = subagentModelSelectionPolicy(ctx.sessionProjections, agent.session);
+	const selectForSession = (target) => {
+		const freshSession = target.firstLiveSeq === 0 && target.eventAt(SessionSeq(0))?.type !== "session/end-seed";
+		let allowedModels = subagentModelSelectionPolicy(ctx.sessionProjections, target);
 		if (allowedModels === void 0) {
-			const parentId = agent.session.header.origin === "subagent" ? agent.session.header.parentSession : void 0;
+			const parentId = target.header.origin === "subagent" ? target.header.parentSession : void 0;
 			if (parentId !== void 0) {
-				const parent = ctx.get("agents")?.get(parentId);
-				allowedModels = parent === void 0 ? void 0 : subagentModelSelectionPolicy(ctx.sessionProjections, parent.session);
+				const sessions = ctx.get("sessions");
+				if (sessions === void 0) throw new Error("tool-subagent: child model-selection inheritance requires the Session registry");
+				const parent = sessions.get(parentId);
+				allowedModels = parent === void 0 ? void 0 : subagentModelSelectionPolicy(ctx.sessionProjections, parent);
 			} else if (freshSession) {
 				const current = settings.current();
 				allowedModels = current.enabled ? current.allowedModels : void 0;
 			}
 		}
-		if (allowedModels !== void 0) recordSubagentModelSelection(ctx.sessionProjections, agent.session, allowedModels);
+		if (allowedModels !== void 0) recordSubagentModelSelection(ctx.sessionProjections, target, allowedModels);
 		return allowedModels === void 0 ? void 0 : { routes: allowedModels };
 	};
-	const agent = ctx.agent;
-	if (agent !== void 0) {
-		install(ctx, selectForAgent(agent));
+	if (session !== void 0) {
+		install(ctx, selectForSession(session));
 		return;
 	}
+	const compositionScope = scopeOf(ctx);
+	if (compositionScope === void 0) throw new Error("tool-subagent: standing `modelSelectionSettings` requires a scoped preset Context");
 	const agents = ctx.get("agents");
-	/* v8 ignore next -- Agent and preset scopes are minted only by the Agent registry. */
-	if (agents === void 0) throw new Error("tool-subagent: scoped model-selection settings require the Agent registry");
+	/* v8 ignore next -- shipped preset compositions always include the Agent registry. */
+	if (agents === void 0) throw new Error("tool-subagent: standing `modelSelectionSettings` requires the Agent registry");
 	const scopedInstalls = /* @__PURE__ */ new WeakMap();
 	const installing = /* @__PURE__ */ new WeakSet();
 	const belongsToComposition = (candidate) => scopeChainOf(scopeOf(candidate.ctx)).includes(compositionScope);
@@ -613,7 +620,7 @@ function apply(ctx, config) {
 		installing.add(candidate);
 		let fiber;
 		try {
-			const policy = selectForAgent(candidate);
+			const policy = selectForSession(candidate.session);
 			fiber = candidate.ctx.inject([
 				"tools",
 				"subagents",
@@ -646,6 +653,7 @@ function apply(ctx, config) {
 		removeScoped(disposed);
 	});
 	ctx.on("tools/change", reconcileComposedAgents);
+	reconcileComposedAgents();
 }
 //#endregion
 export { Config, apply, inject, name };

package/lib/model-selection-settings.js

@@ -45,7 +45,7 @@ const SUBAGENT_MODEL_SELECTION_SETTINGS_SCHEMA = z.object({
 	enabled: z.boolean().default(false),
 	allowedModels: z.array(AllowedModelRouteSchema).default([])
 });
-/** Singleton settings owner read by delegation tools when an Agent is published. */
+/** Singleton settings owner read when delegation tools are composed for a Session. */
 var SubagentModelSelectionConfig = class extends Service {
 	static Config = z.object({
 		enabled: z.boolean().default(false),
@@ -74,7 +74,7 @@ var SubagentModelSelectionConfig = class extends Service {
 		});
 	}
 	/**
-	* Read a detached selection preference for the next eligible Agent publication.
+	* Read a detached selection preference for the next eligible Session composition.
 	* @returns the enabled state and exact allowed routes.
 	*/
 	current() {

package/lib/types/index.d.ts

@@ -10,6 +10,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session } from '@deepseek-ai/dsh-session';
 export declare const name = "tool-subagent";
 export declare const inject: string[];
 /** Config: which registered provider this tool delegates to, plus child defaults. */
@@ -22,8 +23,8 @@ export interface Config {
      */
     toolName?: string;
     /**
-     * Sample the Host `subagent-model-selection` user setting for each new
-     * top-level session and inherit that decision in its child sessions.
+     * Sample the Host `subagent-model-selection` setting for each new top-level
+     * Session and inherit that decision in its child Sessions.
      */
     modelSelectionSettings?: boolean;
     /**
@@ -70,5 +71,11 @@ export interface Config {
     maxDepth?: number | 'provider-managed';
 }
 export declare const Config: z<Config>;
-export declare function apply(ctx: Context, config: Config): void;
+/**
+ * Install one delegation-tool composition.
+ * @param ctx - Context that owns the registrations.
+ * @param config - delegation-tool configuration.
+ * @param session - unpublished Session supplied by a direct Agent setup; omit for a standing composition.
+ */
+export declare function apply(ctx: Context, config: Config, session?: Session): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/model-selection-settings.d.ts

@@ -4,7 +4,7 @@ import z from '@deepseek-ai/schemastery';
 import { type AllowedModelRoute } from './model-selection.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        /** User preference sampled when a new Agent receives its delegation tools. */
+        /** User preference sampled when a new Session receives delegation tools. */
         subagentModelSelection: SubagentModelSelectionConfig;
     }
 }
@@ -26,13 +26,13 @@ export interface Config {
     /** Initial route list inherited when the user document does not override it. */
     allowedModels?: AllowedModelRoute[];
 }
-/** Singleton settings owner read by delegation tools when an Agent is published. */
+/** Singleton settings owner read when delegation tools are composed for a Session. */
 export declare class SubagentModelSelectionConfig extends Service {
     static Config: z<Config>;
     private source;
     constructor(ctx: Context, config?: Config);
     /**
-     * Read a detached selection preference for the next eligible Agent publication.
+     * Read a detached selection preference for the next eligible Session composition.
      * @returns the enabled state and exact allowed routes.
      */
     current(): SubagentModelSelectionSettings;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent",
   "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,17 +37,17 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
@@ -56,22 +56,22 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-subagent-spawn-in-process": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tool-jobs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-jobs-local": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tool-jobs": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-jobs-local": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-alpha.1"
   }
 }