@deepseek-ai/dsh-experimental-tool-subagent-oar 0.0.0-stage → 0.2.2-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,52 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/tool-subagent-oar/README.md
+/:
+  en: 85780a9fcc4720e5
+  zh: ff5b2d870cf3b73f
+/deepseek-ai-dsh-experimental-tool-subagent-oar:
+  en: 520d9dc51e2b0142
+  zh: 8f332776243107a9
+/deepseek-ai-dsh-experimental-tool-subagent-oar/summary:
+  en: 8adbaf2511d2c47f
+  zh: 1495f6bdb84a30ea
+/deepseek-ai-dsh-experimental-tool-subagent-oar/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 8d1e20b826450ffe
+/deepseek-ai-dsh-experimental-tool-subagent-oar/use-this-package:
+  en: 045000a545e143bb
+  zh: db19a60804c8d561
+/deepseek-ai-dsh-experimental-tool-subagent-oar/use-this-package/when-to-choose-it:
+  en: 368805e5bcffeb0a
+  zh: 9340ff5074ada9e1
+/deepseek-ai-dsh-experimental-tool-subagent-oar/use-this-package/minimal-configuration:
+  en: 5b2b33c1d0fae20a
+  zh: 26bff1e013e2bfcd
+/deepseek-ai-dsh-experimental-tool-subagent-oar/understand-the-implementation:
+  en: 3e8a9fffa9c5afd0
+  zh: 932b6d0b682208ba
+/deepseek-ai-dsh-experimental-tool-subagent-oar/further-exploration:
+  en: a796236202b695f5
+  zh: 8e76361f31517714
+/deepseek-ai-dsh-experimental-tool-subagent-oar/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-experimental-tool-subagent-oar/model-experience/external-delegation-tool:
+  en: 8febbb031aa0452d
+  zh: da3f9011631652da
+/deepseek-ai-dsh-experimental-tool-subagent-oar/model-experience/external-delegation-tool/what-the-model-sees:
+  en: 2e0f5274092f794b
+  zh: 83a14e5f7018717f
+/deepseek-ai-dsh-experimental-tool-subagent-oar/model-experience/external-delegation-tool/token-effect:
+  en: 60d7ffec7f4dc858
+  zh: 09f286978df6b4ec
+/deepseek-ai-dsh-experimental-tool-subagent-oar/model-experience/external-delegation-tool/kv-cache-effect:
+  en: 7c1ac0b007b2f0ce
+  zh: 2332a07c6f8bcbdc
+/deepseek-ai-dsh-experimental-tool-subagent-oar/known-limitations-and-deferred-work:
+  en: 5157ca8c4aa1a865
+  zh: 47ad253d87a02838
+/deepseek-ai-dsh-experimental-tool-subagent-oar/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 8ec3e73528ddb1a6

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+---
+description: "Expose one external subagent tool that selects a configured runtime for each task."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-experimental-tool-subagent-oar
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use one `subagent_oar` tool to choose a configured external agent for each standalone text task. Configuration fixes the available runtime aliases and their providers; the model selects an alias without changing native arguments or permissions. Each task uses independent context and returns a child id, with a later completion notice delivered to the parent.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this tool beside configured external providers, such as [OAR provider instances](../subagent-oar/README.md). Declare the tool and provider packages as dependencies of your composition.
+
+### When to choose it
+
+Choose this tool when one model-facing entry should select among independent, one-shot providers. It rejects providers that inherit the parent conversation or support continuation. Use the [shared subagent tool](../../subagent/tool-subagent/README.md) for continuable child agents or broader child configuration.
+
+### Minimal configuration
+
+With `oar-codex` and `oar-claude` already registered, mount this row in the composition:
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-tool-subagent-oar'
+  config:
+    providers:
+      codex: oar-codex
+      claude: oar-claude
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `providers` | required | Nonempty map from model-visible runtime aliases to registered provider names |
+| `toolName` | `subagent_oar` | Tool name; every mounted instance needs a distinct name |
+
+The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-tool-subagent-oar) owns accepted fields and validation. A call requires `runtime`, `description`, and `prompt`; optional `cwd` selects the child directory, with relative paths resolved from the parent's current directory. The prompt must contain the context the child needs. Native installation, authentication, model settings, and permissions belong to the selected provider.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+[`src/index.ts`](src/index.ts) builds the runtime enum from the configured aliases and registers one tool. Each call resolves its provider and starts an activation through the shared subagent service, which owns capacity, parent lifetime, cancellation, terminal recording, and completion delivery. The tool's call card uses the task description and submitted arguments. Disposing the plugin removes its tool registration; the activation manager retains ownership of accepted children.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Subagent service](../../subagent/subagent/README.md) — provider registration and activation ownership.
+- [OAR provider](../subagent-oar/README.md) — native runtime setup and permission configuration.
+- [Subagent subsystem](../../../docs/subsystems/subagent.md) — parent completion notices and retained results.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### External delegation tool
+
+#### What the model sees
+
+The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-experimental-tool-subagent-oar) owns the description and argument schema. The `runtime` enum contains the configured aliases. After acceptance, the tool returns `started subagent <id>`, where `<id>` identifies the child. The shared subagent service later supplies the child's answer or failure notice.
+
+#### Token effect
+
+Each mounted instance adds one tool schema. The acknowledgement and completion notice append to the parent context; the provider owns the child's independent context and token use.
+
+#### KV Cache effect
+
+Changing the configured aliases, tool name, or registration changes the tool schema in later requests. Acknowledgements and completion notices append after the reusable parent prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+The tool's choices and execution capabilities are fixed by its configured providers.
+
+- **One-shot providers only:** child context is independent, and the tool exposes no follow-up, resume, structured output, or per-call native permission override.
+- **Provider availability:** a selected provider that is absent or unloaded fails at call time; its configured alias remains in the schema until this tool's configuration changes.
+- **Provider-owned work:** runtime setup, startup cancellation, process cleanup, and answer selection follow the selected provider's documented behavior. Removing this tool does not revoke accepted activations.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,111 @@
+---
+description: "提供一个外部子智能体工具，为每个任务选择已配置的运行时。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-tool-subagent-oar
+
+[English](README.md) | 中文
+
+## 概述
+
+使用一个 `subagent_oar` 工具，为每个独立文本任务选择已配置的外部智能体。配置固定可用的运行时别名及其提供方；模型选择别名，不能更改原生参数或权限。每个任务使用独立上下文并返回子任务 id，完成通知稍后送达父智能体。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待完善事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在已配置的外部提供方旁挂载此工具，例如 [OAR 提供方实例](../subagent-oar/README.zh.md)。在组合中将工具包和提供方包声明为依赖。
+
+### 适用场景
+
+当一个模型可见入口需要在独立的单次提供方之间选择时，使用此工具。它拒绝继承父对话或支持继续执行的提供方。需要可继续的子智能体或更多子任务配置时，请使用[共享子智能体工具](../../subagent/tool-subagent/README.zh.md)。
+
+### 最小配置
+
+在 `oar-codex` 和 `oar-claude` 已注册的情况下，在组合中挂载此行：
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-tool-subagent-oar'
+  config:
+    providers:
+      codex: oar-codex
+      claude: oar-claude
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `providers` | 必填 | 从模型可见运行时别名映射到已注册提供方名称的非空映射 |
+| `toolName` | `subagent_oar` | 工具名称；每个挂载实例需要不同名称 |
+
+[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-tool-subagent-oar)定义接受的字段和校验规则。调用要求提供 `runtime`、`description` 和 `prompt`；可选的 `cwd` 选择子任务目录，相对路径从父智能体的当前目录解析。提示必须包含子任务需要的上下文。原生安装、认证、模型设置和权限由所选提供方负责。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部细节 — 点击展开</summary>
+
+[`src/index.ts`](src/index.ts)根据配置的别名构建运行时枚举，并注册一个工具。每次调用解析其提供方，并通过共享子智能体服务启动激活；该服务负责容量、父智能体生命周期、取消、最终记录和完成通知交付。工具调用卡片使用任务描述和提交的参数。释放插件会移除其工具注册；激活管理器继续负责已接受的子任务。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [子智能体服务](../../subagent/subagent/README.zh.md) — 提供方注册和激活所有权。
+- [OAR 提供方](../subagent-oar/README.zh.md) — 原生运行时配置和权限配置。
+- [子智能体子系统](../../../docs/subsystems/subagent.zh.md) — 父智能体完成通知和保留结果。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 外部委派工具
+
+#### 模型看到什么
+
+[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-experimental-tool-subagent-oar)定义描述和参数 schema。`runtime` 枚举包含配置的别名。接受任务后，工具返回 `started subagent <id>`，其中 `<id>` 标识子任务。共享子智能体服务稍后提供子任务的答复或失败通知。
+
+#### Token 影响
+
+每个挂载实例添加一个工具 schema。确认和完成通知追加到父上下文；提供方负责子任务的独立上下文和 token 使用。
+
+#### KV Cache 影响
+
+修改配置的别名、工具名称或注册会改变后续请求中的工具 schema。确认和完成通知追加在可复用的父请求前缀之后。
+
+## 已知限制与待完善事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+工具的选项和执行能力由已配置的提供方固定。
+
+- **仅支持单次提供方：** 子任务上下文独立，工具不提供后续输入、恢复、结构化输出或按调用覆盖原生权限的功能。
+- **提供方可用性：** 选择的提供方不存在或已卸载时，调用会失败；其配置的别名会保留在 schema 中，直到此工具的配置改变。
+- **提供方负责的工作：** 运行时配置、启动取消、进程清理和答复选择遵循所选提供方的文档行为。移除此工具不会撤销已接受的激活。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,99 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/** One delegation tool selects a configured external provider for each task. */
+const name = "experimental-tool-subagent-oar";
+const inject = ["tools", "subagents"];
+const Config = z.object({
+	providers: z.dict(z.string().min(1)).required(),
+	toolName: z.string().min(1).default("subagent_oar")
+});
+/**
+* Register a tool that selects one configured external provider per task.
+* @param ctx - shared tool registry and managed subagent service.
+* @param config - runtime choices and the model-facing tool name.
+*/
+function apply(ctx, config) {
+	const providers = new Map(Object.entries(config.providers));
+	if (providers.size === 0 || [...providers.keys()].some((runtime) => runtime.trim().length === 0)) throw new Error("subagent_oar: providers must contain at least one non-empty runtime alias");
+	const toolName = config.toolName ?? "subagent_oar";
+	ctx.tools.register(defineTool({
+		name: toolName,
+		description: "Delegate a self-contained task to a configured external agent. Choose its runtime for each call. The child works in its own context and does not see this conversation. This tool returns a child id; a later completion notice includes its final answer. The child does not accept follow-up messages. Start independent tasks together and continue useful work while they run. When only waiting for their results remains, end your turn instead of polling.",
+		parameters: {
+			runtime: {
+				type: "string",
+				required: true,
+				enum: [...providers.keys()],
+				description: "Configured external runtime for this task."
+			},
+			description: {
+				type: "string",
+				required: true,
+				description: "A short description of the delegated task, for display."
+			},
+			prompt: {
+				type: "string",
+				required: true,
+				description: "The complete, self-contained task. Include all context the external agent needs."
+			},
+			cwd: {
+				type: "string",
+				description: "Initial child working directory. Relative paths use your current directory; omission inherits it."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "activation"
+					},
+					subagentId: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `started subagent ${value.subagentId}`
+			}]
+		},
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			const parent = exec.agent;
+			if (parent === void 0) throw new Error("subagent_oar requires a calling agent");
+			const providerName = providers.get(args.runtime);
+			const provider = ctx.subagents.getProvider(providerName);
+			if (provider !== void 0 && (provider.prepareContinuable !== void 0 || provider.inheritsParentContext)) throw new Error("subagent_oar requires a one-shot provider with independent conversation context");
+			return {
+				kind: "activation",
+				subagentId: (await ctx.subagents.startActivation({
+					provider: providerName,
+					label: args.description,
+					request: {
+						parent,
+						prompt: [{
+							type: "text",
+							text: args.prompt
+						}],
+						...args.cwd === void 0 ? {} : { cwd: args.cwd }
+					},
+					signal: exec.signal,
+					delivery: "parent"
+				})).childId
+			};
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: args.description,
+			rawInput: args
+		})
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,20 @@
+/** One delegation tool selects a configured external provider for each task. */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "experimental-tool-subagent-oar";
+export declare const inject: string[];
+/** Deployment-owned runtime choices exposed by the external delegation tool. */
+export interface Config {
+    /** Model-visible runtime aliases mapped to registered subagent provider names. */
+    providers: Record<string, string>;
+    /** Model-facing tool name (default subagent_oar). */
+    toolName?: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Register a tool that selects one configured external provider per task.
+ * @param ctx - shared tool registry and managed subagent service.
+ * @param config - runtime choices and the model-facing tool name.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OAR-Subagenten-Tool",
+    "description": "Wählen Sie für jede eigenständige Aufgabe einen konfigurierten externen Agenten aus."
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OAR subagent tool",
+    "description": "Choose a configured external agent for each standalone task."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Herramienta subagente OAR",
+    "description": "Elija un agente externo configurado para cada tarea independiente."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Outil de sous-agent OAR",
+    "description": "Choisissez un agent externe configuré pour chaque tâche autonome."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OAR サブエージェントツール",
+    "description": "独立したタスクごとに、設定済みの外部エージェントを選択します。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Ferramenta de subagente OAR",
+    "description": "Escolha um agente externo configurado para cada tarefa autônoma."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Инструмент субагента OAR",
+    "description": "Выберите настроенный внешний агент для каждой отдельной задачи."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OAR 子智能体工具",
+    "description": "为每个独立任务选择已配置的外部智能体。"
+  }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@deepseek-ai/dsh-experimental-tool-subagent-oar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Delegate standalone tasks to configured external subagent providers",
+  "version": "0.2.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/tool-subagent-oar"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-subagent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.7-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-subagent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tool-testkit": "0.2.2-alpha.3"
+  }
 }