@deepseek-ai/dsh-tool-working-directory 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/session/tool-working-directory/README.md
+/:
+  en: 98cfd91158449dab
+  zh: 5235a85797dc16a6
+/deepseek-ai-dsh-tool-working-directory:
+  en: 1cbdc6d915999dbc
+  zh: 0c6cc71c43276a63
+/deepseek-ai-dsh-tool-working-directory/summary:
+  en: 9a02398f19196e04
+  zh: 490c400f5c7c23cd
+/deepseek-ai-dsh-tool-working-directory/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 87d7d2dbd7777429
+/deepseek-ai-dsh-tool-working-directory/use-this-package:
+  en: bb750522dbdb3fef
+  zh: 85586a5c2137afa9
+/deepseek-ai-dsh-tool-working-directory/understand-the-implementation:
+  en: f361fe510916fce8
+  zh: a2127f768ef9ac95
+/deepseek-ai-dsh-tool-working-directory/further-exploration:
+  en: eabff683146786c8
+  zh: 7997dec17802ef64
+/deepseek-ai-dsh-tool-working-directory/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-working-directory/model-experience/tool-schema-and-result:
+  en: bc924247b1806144
+  zh: af4cc374d7d16917
+/deepseek-ai-dsh-tool-working-directory/model-experience/tool-schema-and-result/what-the-model-sees:
+  en: e69a26e66bc5e3c4
+  zh: 9a7515def45d139c
+/deepseek-ai-dsh-tool-working-directory/model-experience/tool-schema-and-result/token-effect:
+  en: a8379dea8db4e2a2
+  zh: 5b8c86352564ba68
+/deepseek-ai-dsh-tool-working-directory/model-experience/tool-schema-and-result/kv-cache-effect:
+  en: ae50eb17ba3b6545
+  zh: 6f5eed7bb30209e4
+/deepseek-ai-dsh-tool-working-directory/known-limitations-and-deferred-work:
+  en: 58cd03e27224e8b8
+  zh: 4bd8752b74d1b05f
+/deepseek-ai-dsh-tool-working-directory/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: a4b126f9a4eaca6f

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+---
+description: "Read the Session’s current directory or enter an existing directory with the same tool. Relative changes use the current directory. The returned absolute path can be passed to other tools."
+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-tool-working-directory
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Read the Session’s current directory or enter an existing directory with the same tool. Relative changes use the current directory. The returned absolute path can be passed to other tools.
+
+## 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 alongside `tools` and `workingDirectory`. Call `working_directory({})` to read or `working_directory({ cd: "src" })` to change directory. The tool has no configuration fields.
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The tool delegates validation, recovery, persistence, and context notices to the directory owner. Its canonical result contains `cwd`; native rendering returns that path. The generic tool card displays the arguments and result without a separate GUI renderer.
+
+No runtime invariant companion is published because the tool delegates all directory state and mutations to `workingDirectory`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Working directories](../../../docs/subsystems/working-directory.md) — shared runtime behavior.
+- [Session group](../README.md) — durable Session services.
+- [Testing](../../../docs/testing.md) — composition and replay verification.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema and result
+
+#### What the model sees
+
+The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-working-directory) defines the optional `cd` argument and canonical `cwd` result. Directory notices are owned by `dsh-working-directory`.
+
+#### Token effect
+
+The registered schema and returned path contribute tokens when the tool is available and invoked.
+
+#### KV Cache effect
+
+Changing tool availability changes its schema context. A tool call appends ordinary call and result history without replacing prior messages.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Calling Session required** — the tool requires an Agent and changes neither existing processes nor write permissions.
+
+<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,90 @@
+---
+description: "使用同一工具读取 Session 的当前目录，或进入一个现有目录。相对路径变更基于当前目录解析。返回的绝对路径可传给其他工具。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-working-directory
+
+[English](README.md) | 中文
+
+## 概述
+
+使用同一工具读取 Session 的当前目录，或进入一个现有目录。相对路径变更基于当前目录解析。返回的绝对路径可传给其他工具。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+与 `tools` 和 `workingDirectory` 一起挂载。调用 `working_directory({})` 读取目录，或调用 `working_directory({ cd: "src" })` 改变目录。此工具没有配置字段。
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+此工具将验证、恢复、持久化和上下文通知委托给目录服务。规范结果包含 `cwd`；原生渲染返回该路径。通用工具卡展示参数和结果，无需独立 GUI 渲染器。
+
+不发布 `./invariant` 伴生模块，因为工具将全部目录状态和变更委托给 `workingDirectory`。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步阅读
+
+- [工作目录](../../../docs/subsystems/working-directory.zh.md) — 共享运行时行为。
+- [Session 包组](../README.zh.md) — 持久化 Session 服务。
+- [测试](../../../docs/testing.zh.md) — 组合与回放验证。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema 与结果
+
+#### 模型可见内容
+
+[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-working-directory) 定义可选的 `cd` 参数与规范 `cwd` 结果。目录通知由 `dsh-working-directory` 拥有。
+
+#### Token 影响
+
+工具可用及被调用时，注册的 schema 和返回路径贡献 token。
+
+#### KV Cache 影响
+
+改变工具可用性会改变其 schema 上下文。工具调用追加普通调用和结果历史，不替换已有消息。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **需要调用方 Session** — 此工具需要 Agent，不改变已有进程或写权限。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,45 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/**
+* Read or change the calling Session's working directory.
+* @module @deepseek-ai/dsh-tool-working-directory
+*/
+/** Cordis plugin name. */
+const name = "tool-working-directory";
+/** Services used by the tool. */
+const inject = ["tools", "workingDirectory"];
+/**
+* Register the working-directory tool for this composition.
+* @param ctx - context providing the tool registry and directory owner.
+*/
+function apply(ctx) {
+	ctx.tools.register(defineTool({
+		name: "working_directory",
+		description: "Read the current working directory, or change it with cd. Relative paths use the current directory. Existing shells and running processes keep their own directories.",
+		parameters: { cd: {
+			type: "string",
+			description: "Existing directory to enter. Omit to read the current directory."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { cwd: {
+					type: "string",
+					required: true,
+					description: "Current absolute working directory."
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.cwd
+			}]
+		},
+		async execute(args, exec) {
+			if (exec.agent === void 0) throw new Error("working_directory requires an agent Session");
+			return { cwd: args.cd === void 0 ? await ctx.workingDirectory.ensure(exec.agent, exec.signal) : await ctx.workingDirectory.set(exec.agent, args.cd, exec.signal) };
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read or change the calling Session's working directory.
+ * @module @deepseek-ai/dsh-tool-working-directory
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name. */
+export declare const name = "tool-working-directory";
+/** Services used by the tool. */
+export declare const inject: string[];
+/**
+ * Register the working-directory tool for this composition.
+ * @param ctx - context providing the tool registry and directory owner.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@deepseek-ai/dsh-tool-working-directory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Read and change the active Session working directory",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/tool-working-directory"
+  },
+  "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.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "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-agent-loop": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm": "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-system-prompt": "0.2.1-alpha.3"
+  }
 }