@deepseek-ai/dsh-experimental-tool-worktree 0.0.0-stage → 0.2.1-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,46 @@
+# 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-worktree/README.md
+/:
+  en: 7c7c8316f315eee0
+  zh: dfd3abcef256029e
+/deepseek-ai-dsh-experimental-tool-worktree:
+  en: db61f6b6ad671f45
+  zh: 9f3083d7f5605cbb
+/deepseek-ai-dsh-experimental-tool-worktree/summary:
+  en: f0df470fd16d8d29
+  zh: 5f2d371d844b0568
+/deepseek-ai-dsh-experimental-tool-worktree/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 2f8a621b991260a1
+/deepseek-ai-dsh-experimental-tool-worktree/use-this-package:
+  en: f69d3fdeed949ff5
+  zh: 05c9a85b7cdcfbad
+/deepseek-ai-dsh-experimental-tool-worktree/understand-the-implementation:
+  en: c03f875211ab69a8
+  zh: 8f49b82f90a60223
+/deepseek-ai-dsh-experimental-tool-worktree/further-exploration:
+  en: 6ec5bb0f5bfbbaa4
+  zh: 45009dd139621d0e
+/deepseek-ai-dsh-experimental-tool-worktree/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-experimental-tool-worktree/model-experience/creation-tool:
+  en: 4062fcaa4794bed7
+  zh: b56d35fc675fc430
+/deepseek-ai-dsh-experimental-tool-worktree/model-experience/creation-tool/what-the-model-sees:
+  en: e37073be01ff5cd1
+  zh: 02fd0282863c708c
+/deepseek-ai-dsh-experimental-tool-worktree/model-experience/creation-tool/token-effect:
+  en: 6c3f73ba01233a36
+  zh: d64d87a425db4fbd
+/deepseek-ai-dsh-experimental-tool-worktree/model-experience/creation-tool/kv-cache-effect:
+  en: 365f8ccedfa61bbb
+  zh: aa328044ba2528b8
+/deepseek-ai-dsh-experimental-tool-worktree/known-limitations-and-deferred-work:
+  en: 7cfc071dfc3f9c83
+  zh: f36ae822e801db12
+/deepseek-ai-dsh-experimental-tool-worktree/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+---
+description: "Model tool that creates a new local Git worktree and changes the current Session directory."
+kind: "package-bundle"
+---
 
-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-worktree
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Add Git Worktrees from the GUI plugin manager to let a model create and enter a new Git worktree with one call. This optional bundle is installed with Harness and stays off until selected. Native tool calls and PTC programs receive the same typed result, and the existing file policy governs creation.
+
+## 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
+
+In the GUI, open **Plugins → Official → Git Worktrees** and turn on the switch. The bundle loads the [worktree runtime](../worktree/README.md) and this tool together; it is off in every shipped profile. Turning it off removes `create_worktree` without deleting existing checkouts or branches. The built-in `working_directory` tool remains available.
+
+For an explicit composition, mount this function plugin after the worktree runtime and tool registry.
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-worktree'
+- name: '@deepseek-ai/dsh-experimental-tool-worktree'
+```
+
+Call `create_worktree({ name?: string, from?: string })`. Success returns the canonical checkout `path`, new `branch`, pinned `baseCommit`, and source `repositoryRoot`, and changes the calling Session's current working directory. To leave, call `working_directory({ cd: path })`; the checkout and branch remain. The [generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-experimental-tool-worktree) owns the exact schema and model-facing description.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+[`cordis.patch.yml`](cordis.patch.yml) inserts the `worktree` runtime row and the `tool-worktree` consumer row. [`src/index.ts`](src/index.ts) registers one typed tool. Runtime creation owns Git behavior, cancellation, and the working-directory change. The tool returns the runtime record as its canonical value and renders that record as JSON; its Host presentation uses the generic card. Disposal unregisters the tool.
+
+No runtime invariant companion is published because the tool retains no state independently of the worktree runtime.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Worktree runtime](../worktree/README.md) — configuration, creation semantics, and write permissions.
+- [Working directory](../../session/working-directory/README.md) — Session context and exit operation.
+- [Tool authoring](../../../docs/cookbook/adding-a-tool.md) — canonical results and pure presentation.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Creation tool
+
+#### What the model sees
+
+The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-experimental-tool-worktree) defines `create_worktree`. Each successful result contains the created checkout's canonical path, branch, base commit, and source checkout’s top-level directory. Failed calls report the operation error.
+
+#### Token effect
+
+The schema has a fixed per-request cost while mounted. Each call appends its arguments and bounded creation result or error to ordinary tool history.
+
+#### KV Cache effect
+
+Unchanged tool schemas retain their existing prefix. Calls append after prior history; the working-directory service separately records the successful directory change for later requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Calling Agent required** — the tool changes a Session directory and rejects calls without an Agent.
+- **Creation only** — inspection, merging, and checkout or branch removal are outside this tool; the [runtime limitations](../worktree/README.md#known-limitations-and-deferred-work) also apply.
+
+<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,96 @@
+---
+description: "创建新的本地 Git 工作树并改变当前 Session 目录的模型工具。"
+kind: "package-bundle"
+---
+
+# @deepseek-ai/dsh-experimental-tool-worktree
+
+[English](README.md) | 中文
+
+## 概述
+
+从 GUI 插件管理器添加 Git 工作树，让模型通过一次调用创建并进入新的 Git 工作树。此可选 bundle 随 Harness 安装，在选中之前保持关闭。原生工具调用与 PTC 程序获得相同的带类型结果，创建操作沿用现有文件策略。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [深入探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在 GUI 中打开**插件 → 官方 → Git 工作树**并启用开关。此 bundle 一起加载[工作树运行时](../worktree/README.zh.md)与本工具；所有随附 profile 默认关闭它。关闭后会移除 `create_worktree`，已有检出目录与分支会保留。内置 `working_directory` 工具仍然可用。
+
+在显式组合中，将此函数插件挂载到工作树运行时和工具注册表之后。
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-worktree'
+- name: '@deepseek-ai/dsh-experimental-tool-worktree'
+```
+
+调用 `create_worktree({ name?: string, from?: string })`。成功会返回规范化检出路径 `path`、新分支 `branch`、固定提交 `baseCommit` 和源仓库根目录 `repositoryRoot`，并改变调用 Session 的当前工作目录。离开时调用 `working_directory({ cd: path })`；检出目录与分支会保留。[生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-experimental-tool-worktree)拥有准确的 schema 与面向模型的描述。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+[`cordis.patch.yml`](cordis.patch.yml) 插入 `worktree` 运行时行与 `tool-worktree` 消费方行。[`src/index.ts`](src/index.ts) 注册一个带类型的工具。运行时创建操作拥有 Git 行为、取消处理与工作目录切换。工具将运行时记录作为规范返回值，并渲染为 JSON；Host 展示使用通用卡片。销毁插件会注销工具。
+
+本包不发布运行时不变量伴随入口，因为工具不保留独立于工作树运行时的状态。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 深入探索
+
+- [工作树运行时](../worktree/README.zh.md)——配置、创建语义与写权限。
+- [工作目录](../../session/working-directory/README.zh.md)——Session 上下文与离开操作。
+- [工具编写](../../../docs/cookbook/adding-a-tool.zh.md)——规范结果与纯展示函数。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 创建工具
+
+#### 模型看到什么
+
+[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-experimental-tool-worktree)定义 `create_worktree`。每个成功结果包含已创建检出目录的规范路径、分支、基准提交与源检出目录的顶层目录。失败调用报告操作错误。
+
+#### Token 影响
+
+挂载期间，schema 为每次请求带来固定成本。每次调用将参数与有界创建结果或错误追加到普通工具历史。
+
+#### KV Cache 影响
+
+未改变的工具 schema 保留既有前缀。调用追加到先前历史之后；工作目录服务另行记录成功的目录切换，供后续请求使用。
+
+## 已知限制与待办工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **必须有调用 Agent**——工具改变 Session 目录，没有 Agent 的调用会被拒绝。
+- **仅负责创建**——检查、合并、移除检出目录或删除分支不属于此工具；[运行时限制](../worktree/README.zh.md#known-limitations-and-deferred-work)同样适用。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: worktree
+      name: '@deepseek-ai/dsh-experimental-worktree'
+    - id: tool-worktree
+      name: '@deepseek-ai/dsh-experimental-tool-worktree'

package/icon.svg

@@ -0,0 +1,18 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(1.8 1.8) scale(0.9)">
+    <path d="M11 12V24M11 19H16C20.4 19 25 16.4 25 12" stroke="url(#worktree-branches)" stroke-width="3" />
+    <rect x="7.5" y="7" width="7" height="7" rx="2" fill="#86B8F5" />
+    <rect x="7.5" y="22" width="7" height="7" rx="2" fill="#5269E1" />
+    <rect x="21.5" y="7" width="7" height="7" rx="2" fill="url(#worktree-leaf)" />
+  </g>
+  <defs>
+    <linearGradient id="worktree-branches" x1="11" y1="12" x2="18" y2="24" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#86B8F5" />
+      <stop offset="1" stop-color="#5269E1" />
+    </linearGradient>
+    <linearGradient id="worktree-leaf" x1="22" y1="7" x2="28" y2="14" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#51CFDB" />
+      <stop offset="1" stop-color="#108792" />
+    </linearGradient>
+  </defs>
+</svg>

package/lib/index.js

@@ -0,0 +1,66 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/** Model tool for creating and entering a new Git worktree through the shared runtime. */
+/** Cordis plugin name. */
+const name = "tool-worktree";
+/** Services required to register and execute the worktree tool. */
+const inject = ["tools", "worktrees"];
+/**
+* Register create_worktree for model and PTC callers.
+* @param ctx - tool registry and worktree runtime.
+*/
+function apply(ctx) {
+	ctx.tools.register(defineTool({
+		name: "create_worktree",
+		description: "Create a new Git branch and worktree from a local commit, branch, or tag, then change this session's working directory to it. Defaults to HEAD and a generated name. Uncommitted files stay in the source checkout. Existing names fail. Use working_directory with cd to leave; the checkout and branch remain.",
+		parameters: {
+			name: {
+				type: "string",
+				description: "New branch name, also used as the checkout directory. Omit to generate a unique name."
+			},
+			from: {
+				type: "string",
+				description: "Local commit, branch, or tag to start from. Defaults to HEAD; no fetch is performed."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true
+					},
+					branch: {
+						type: "string",
+						required: true
+					},
+					baseCommit: {
+						type: "string",
+						required: true
+					},
+					repositoryRoot: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		async execute(args, exec) {
+			if (exec.agent === void 0) throw new Error("create_worktree requires a calling agent");
+			return ctx.worktrees.create(exec.agent, args, exec.signal);
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: "create_worktree",
+			rawInput: args
+		})
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+/** Model tool for creating and entering a new Git worktree through the shared runtime. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name. */
+export declare const name = "tool-worktree";
+/** Services required to register and execute the worktree tool. */
+export declare const inject: string[];
+/**
+ * Register create_worktree for model and PTC callers.
+ * @param ctx - tool registry and worktree runtime.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Git Worktrees",
+    "description": "Let the agent create a new Git branch and worktree, then continue there."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Git 工作树",
+    "description": "让智能体创建新的 Git 分支与工作树，并在其中继续工作。"
+  }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@deepseek-ai/dsh-experimental-tool-worktree",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model tool that creates and enters a new Git worktree",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/index.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/tool-worktree"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-experimental-worktree": "0.2.1-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-experimental-worktree": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.3"
+  },
+  "icon": "./icon.svg",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-experimental-worktree": "0.2.1-alpha.3"
+  }
 }