@deepseek-ai/dsh-tool-testkit 0.0.0-stage → 0.2.2-alpha.2

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,37 @@
+# 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/test-support/tool-testkit/README.md
+/:
+  en: 6c56a58c1397154b
+  zh: 7e37b4f4915f0a75
+/deepseek-ai-dsh-tool-testkit:
+  en: 6f5f9186228a4b87
+  zh: e05d9c94ad8a6c2e
+/deepseek-ai-dsh-tool-testkit/summary:
+  en: 36a296389a56ac64
+  zh: f1aecbfb8f0ce528
+/deepseek-ai-dsh-tool-testkit/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 1db86285abf6c499
+/deepseek-ai-dsh-tool-testkit/use-this-package:
+  en: 0489d9c434d64281
+  zh: 02e72be3ec225898
+/deepseek-ai-dsh-tool-testkit/understand-the-implementation:
+  en: 236c624cc2445cd1
+  zh: 60d9dbafe03332b9
+/deepseek-ai-dsh-tool-testkit/further-exploration:
+  en: db619f3ee3d024ef
+  zh: 02e35fcebaebd40e
+/deepseek-ai-dsh-tool-testkit/model-experience:
+  en: 478835c82631e8c3
+  zh: cb4f938bcaa046be
+/deepseek-ai-dsh-tool-testkit/model-experience/kv-cache-effect:
+  en: be3fa044c8f27bf0
+  zh: 35fdb79b58ba91f6
+/deepseek-ai-dsh-tool-testkit/known-limitations-and-deferred-work:
+  en: c21236a743177477
+  zh: 8cc8678c2133a8be
+/deepseek-ai-dsh-tool-testkit/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+---
+description: "Define test tools and invoke tool pipelines or selected executors in repository tests and benchmarks."
+kind: "package-library"
+---
 
-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-tool-testkit
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this package to define content-producing test tools and exercise tool execution without running an Agent turn. Tests and benchmarks import its helpers as a development dependency. Callers own the Cordis context, plugin composition, and teardown.
+
+## 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
+
+Add `@deepseek-ai/dsh-tool-testkit` to the consuming package's `devDependencies`. Define a fixture when the test needs rendered content without a domain-specific result value:
+
+```ts
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tool-testkit'
+
+const tool = defineContentToolFixture({
+  name: 'echo',
+  description: 'Return a test message.',
+  parameters: {},
+  execute: async () => [{ type: 'text', text: 'hello' }],
+})
+```
+
+Register the returned definition through the caller's tool registry. Use `executeToolFixture` for an already-parsed invocation, or `executeModelToolFixture` to pass one JSON-encoded call through the selected executor. The latter requires the caller to mount that executor and rejects arguments that cannot be JSON-encoded or an executor response without a result. See [`src/index.ts`](src/index.ts) for invocation fields.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+[`src/index.ts`](src/index.ts) adapts content blocks into a tool's canonical JSON value and delegates execution to the production pipeline or registry. It creates no context and owns no plugin registrations.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Tools package](../../core/tools/README.md) — tool definitions, registry, and execution policy.
+- [Testing policy](../../../docs/testing.md) — choosing verification for production behavior.
+- [Test-support group map](../README.md) — sibling test utilities.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as these test helpers do not assemble or send model requests.
+
+#### KV Cache effect
+
+None; the package itself sends no provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Content-array values are test fixtures; product tools declare domain-owned output schemas.
+- Direct pipeline execution omits model-batch scheduling. Both execution helpers omit root Session logging; use an Agent turn when verifying the recorded conversation.
+- Plugin composition and context disposal remain caller-owned.
+
+<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,91 @@
+---
+description: "在仓库测试和基准测试中定义测试工具，并调用工具流水线或选定的执行器。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-tool-testkit
+
+[English](README.md) | 中文
+
+## 概述
+
+使用本包定义生成内容的测试工具，并在不运行 Agent 回合的情况下测试工具执行。测试和基准测试将这些辅助函数作为开发依赖导入。调用方负责 Cordis context、插件组合和资源清理。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将 `@deepseek-ai/dsh-tool-testkit` 加入消费包的 `devDependencies`。测试只需要渲染内容而不需要领域结果值时，可以定义以下 fixture：
+
+```ts
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tool-testkit'
+
+const tool = defineContentToolFixture({
+  name: 'echo',
+  description: 'Return a test message.',
+  parameters: {},
+  execute: async () => [{ type: 'text', text: 'hello' }],
+})
+```
+
+通过调用方的工具注册表注册返回的定义。使用 `executeToolFixture` 执行已解析的调用，或使用 `executeModelToolFixture` 将一次 JSON 编码的调用交给选定的执行器。后者要求调用方挂载该执行器，并在参数无法编码为 JSON 或执行器响应缺少结果时拒绝。调用字段见 [`src/index.ts`](src/index.ts)。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+[`src/index.ts`](src/index.ts) 将内容块适配为工具的规范 JSON 值，并将执行委托给生产流水线或注册表。它不创建 context，也不持有插件注册。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [工具包](../../core/tools/README.zh.md)——工具定义、注册表和执行策略。
+- [测试策略](../../../docs/testing.zh.md)——为生产行为选择验证方式。
+- [test-support 分组地图](../README.zh.md)——同组测试工具。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，这些测试辅助函数不组装或发送模型请求。
+
+#### KV Cache 影响
+
+无；本包自身不发送 provider 请求。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 内容数组值仅用于测试 fixture；产品工具声明领域自己的输出 schema。
+- 直接执行流水线不包含模型批次调度。两种执行辅助函数都不记录根 Session 日志；验证会话记录时应运行 Agent 回合。
+- 插件组合和 context 释放仍由调用方负责。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,68 @@
+import { ToolExecutionPipeline } from "@deepseek-ai/dsh-tools/pipeline";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/** Canonical tool-definition fixtures for repository tests. @module @deepseek-ai/dsh-tool-testkit */
+const CONTENT_VALUE_SCHEMA = {
+	type: "array",
+	items: { type: "json" }
+};
+/**
+* Define a test fixture that deliberately uses its content blocks as the
+* canonical JSON value. Product tools must declare domain-owned DTOs instead.
+* @param options - ordinary fixture fields plus a content-producing body.
+* @returns a registry-ready tool with an explicit JSON-array output contract.
+* @internal
+*/
+function defineContentToolFixture(options) {
+	const execute = options.execute;
+	return defineTool({
+		...options,
+		output: {
+			schema: CONTENT_VALUE_SCHEMA,
+			render: (_args, value) => value
+		},
+		async execute(args, exec) {
+			return await execute(args, exec);
+		}
+	});
+}
+/**
+* Exercise invocation stages directly, preserving parsed and nested test inputs.
+* Use executeModelToolFixture for a complete single-call batch.
+* @param ctx - context owning the tool definitions and execution policy.
+* @param input - parsed invocation, including nested identity when testing a composite.
+* @returns the settled capability result.
+* @internal
+*/
+async function executeToolFixture(ctx, input) {
+	const pipeline = new ToolExecutionPipeline(ctx);
+	const prepared = await pipeline.prepare(input);
+	const outcome = prepared.kind === "dispatch" ? await pipeline.dispatch(prepared.exec) : prepared;
+	return pipeline.complete(prepared.exec, outcome);
+}
+/**
+* Run one raw call through the selected executor without root Session logging.
+* @param ctx - context owning the selected executor.
+* @param input - JSON arguments, optional Agent supplying scoped tools and tool context, and optional step admission.
+* @returns the single settled result.
+* @internal
+*/
+async function executeModelToolFixture(ctx, input) {
+	const args = JSON.stringify(input.arguments);
+	if (args === void 0) throw new TypeError("Model tool fixture arguments must encode as JSON");
+	const outcome = (await ctx.tools.execute({
+		calls: [{
+			type: "tool-call",
+			id: input.callId,
+			name: input.name,
+			arguments: args
+		}],
+		signal: input.signal,
+		...input.agent === void 0 ? {} : { agent: input.agent },
+		...input.toolSet === void 0 ? {} : { toolSet: input.toolSet }
+	})).results[0];
+	if (outcome === void 0) throw new Error("Executor omitted the model tool fixture result");
+	return outcome.result;
+}
+//#endregion
+export { defineContentToolFixture, executeModelToolFixture, executeToolFixture };

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/** Canonical tool-definition fixtures for repository tests. @module @deepseek-ai/dsh-tool-testkit */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { DefineToolOptions, InferArgs, ParameterSchemaSpec, ToolDefinition, ToolExecutionInput, ToolExecutionResult, ToolRunContext } from '@deepseek-ai/dsh-tools';
+declare const CONTENT_VALUE_SCHEMA: {
+    readonly type: "array";
+    readonly items: {
+        readonly type: "json";
+    };
+};
+/** Options for a fixture whose canonical value is its rendered content array. */
+export type ContentToolFixtureOptions<S extends ParameterSchemaSpec> = Omit<DefineToolOptions<S, typeof CONTENT_VALUE_SCHEMA>, 'output' | 'execute'> & {
+    /** Produce the fixture's content blocks as its canonical test value. */
+    execute(args: InferArgs<S>, exec: ToolRunContext): Promise<ContentBlock[]>;
+};
+/**
+ * Define a test fixture that deliberately uses its content blocks as the
+ * canonical JSON value. Product tools must declare domain-owned DTOs instead.
+ * @param options - ordinary fixture fields plus a content-producing body.
+ * @returns a registry-ready tool with an explicit JSON-array output contract.
+ * @internal
+ */
+export declare function defineContentToolFixture<const S extends ParameterSchemaSpec>(options: ContentToolFixtureOptions<S>): ToolDefinition;
+/**
+ * Exercise invocation stages directly, preserving parsed and nested test inputs.
+ * Use executeModelToolFixture for a complete single-call batch.
+ * @param ctx - context owning the tool definitions and execution policy.
+ * @param input - parsed invocation, including nested identity when testing a composite.
+ * @returns the settled capability result.
+ * @internal
+ */
+export declare function executeToolFixture(ctx: Context, input: ToolExecutionInput): Promise<ToolExecutionResult>;
+/**
+ * Run one raw call through the selected executor without root Session logging.
+ * @param ctx - context owning the selected executor.
+ * @param input - JSON arguments, optional Agent supplying scoped tools and tool context, and optional step admission.
+ * @returns the single settled result.
+ * @internal
+ */
+export declare function executeModelToolFixture(ctx: Context, input: Pick<ToolExecutionInput, 'callId' | 'name' | 'arguments' | 'signal' | 'agent' | 'toolSet'>): Promise<ToolExecutionResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@deepseek-ai/dsh-tool-testkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Tool definition and execution fixtures for tests and benchmarks",
+  "version": "0.2.2-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/test-support/tool-testkit"
+  },
+  "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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2"
+  }
 }