@qilin-agent/tool-working-directory 0.0.0-stage → 3.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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: 3614603639d0b7e5
+/qilin-agent-tool-working-directory:
+  en: 314feb2ff5e94a32
+  zh: 65fb2c8bad738b87
+/qilin-agent-tool-working-directory/summary:
+  en: 9a02398f19196e04
+  zh: af829ecc71225ad3
+/qilin-agent-tool-working-directory/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 9f0336825ccdaacd
+/qilin-agent-tool-working-directory/use-this-package:
+  en: bb750522dbdb3fef
+  zh: 6e498c24c7ad557e
+/qilin-agent-tool-working-directory/understand-the-implementation:
+  en: 89bbb00f9a795dbc
+  zh: 672c4374edc21e62
+/qilin-agent-tool-working-directory/further-exploration:
+  en: 7889612b1e9c9549
+  zh: 65b74a3d8471ade7
+/qilin-agent-tool-working-directory/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-tool-working-directory/model-experience/tool-schema-and-result:
+  en: bc924247b1806144
+  zh: af4cc374d7d16917
+/qilin-agent-tool-working-directory/model-experience/tool-schema-and-result/what-the-model-sees:
+  en: a625e5cf6a9f7185
+  zh: 1db8cb09ae88203d
+/qilin-agent-tool-working-directory/model-experience/tool-schema-and-result/token-effect:
+  en: a8379dea8db4e2a2
+  zh: cdd9b7c6b7fe9bae
+/qilin-agent-tool-working-directory/model-experience/tool-schema-and-result/kv-cache-effect:
+  en: 8a3ea858b739464c
+  zh: 432f48203586282e
+/qilin-agent-tool-working-directory/known-limitations-and-deferred-work:
+  en: faad28f483bfb52b
+  zh: 16027ea8cb6c3420
+/qilin-agent-tool-working-directory/known-limitations-and-deferred-work/dev-note:
+  en: 0a1253c6f7b5e8b9
+  zh: 9f56528562c7c914

package/README.md

@@ -1,3 +1,78 @@
-# 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.
+# @qilin-agent/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: '@qilin-agent/tool-working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+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.
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Session group](../README.md) — durable Session services.
+- [Tool catalog](../../../docs/tool-catalog.md) — the model-facing tool schemas.
+- [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#qilin-agenttool-working-directory) defines the optional `cd` argument and canonical `cwd` result. Directory notices are owned by `@qilin-agent/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 in the request; a directory change itself adds no schema tokens.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Directory changes are per Session** — existing shells, background jobs, and sandbox grants keep their own directories; the tool does not move them.
+
+<a id="dev-note"></a>
+### Dev Note
+
+None.

package/README.zh.md

@@ -0,0 +1,78 @@
+---
+description: "用同一个工具读取 Session 当前目录或进入既有目录。相对路径基于当前目录解析。返回的绝对路径可传给其他工具。"
+kind: "package-reference"
+---
+
+# @qilin-agent/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: '@qilin-agent/tool-working-directory'
+```
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+本工具把校验、恢复、持久化与上下文通知全部委托给目录所有者。其规范结果包含 `cwd`；原生渲染返回该路径。通用工具卡片展示参数与结果，不需要单独的 GUI 渲染器。
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [Session 组](../README.zh.md) — 持久 Session 服务。
+- [工具目录](../../../docs/tool-catalog.zh.md) — 面向模型的工具 schema。
+- [测试](../../../docs/testing.zh.md) — 组合与回放验收。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema 与结果
+
+#### 模型看到什么
+
+[工具目录](../../../docs/tool-catalog.zh.md#qilin-agenttool-working-directory)定义了可选参数 `cd` 与规范结果 `cwd`。目录通知由 `@qilin-agent/working-directory` 持有。
+
+#### token 影响
+
+工具可用并被调用时，注册的 schema 与返回路径计入 token。
+
+#### KV Cache 影响
+
+工具可用性变化会改变请求中的 schema；目录变更本身不增加 schema token。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **目录变更按 Session 隔离** —— 既有 shell、后台任务与沙箱授权保持各自目录，本工具不会移动它们。
+
+<a id="dev-note"></a>
+### 开发备注
+
+无。

package/lib/index.js

@@ -0,0 +1,45 @@
+import { defineTool } from "@qilin-agent/tools";
+//#region lib/types/index.js
+/**
+* Read or change the calling Session's working directory.
+* @module @qilin-agent/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 @qilin-agent/tool-working-directory
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** 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,43 @@
 {
   "name": "@qilin-agent/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": "3.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/tool-working-directory"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "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": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/working-directory": "3.1.5",
+    "@qilin-agent/tools": "3.1.5"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/tools": "3.1.5",
+    "@qilin-agent/working-directory": "3.1.5"
+  }
 }