@qilin-agent/tool-workspace-dependencies 0.0.0-stage → 3.1.4

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,67 @@
+# 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/skill/tool-workspace-dependencies/README.md
+/:
+  en: 96f7fe2b814c798f
+  zh: 7ee4937b35eba80f
+/qilin-agent-tool-workspace-dependencies:
+  en: b310229aa35d9e94
+  zh: a952ca95d049dfe8
+/qilin-agent-tool-workspace-dependencies/summary:
+  en: e9ce608fa512599f
+  zh: 09fb6924aa46acd5
+/qilin-agent-tool-workspace-dependencies/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-tool-workspace-dependencies/use-this-package:
+  en: c4816a9cedf2f5d7
+  zh: e2889279b7a86757
+/qilin-agent-tool-workspace-dependencies/use-this-package/minimal-configuration:
+  en: e8ed32b430c875c3
+  zh: 0646e4e1b9279458
+/qilin-agent-tool-workspace-dependencies/use-this-package/payload-layout:
+  en: f92262be81174420
+  zh: 9823d4d5b8ad8375
+/qilin-agent-tool-workspace-dependencies/use-this-package/carrier-activation:
+  en: 7ec67f694bb22d05
+  zh: 3a297b7ad6f588b1
+/qilin-agent-tool-workspace-dependencies/understand-the-implementation:
+  en: 0121e57a754cb26f
+  zh: 2c8c7a36fe2b0603
+/qilin-agent-tool-workspace-dependencies/further-exploration:
+  en: 5042e4f62017d3e7
+  zh: 08c582d257a56a22
+/qilin-agent-tool-workspace-dependencies/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-schema/what-the-model-sees:
+  en: f8347f35b0296059
+  zh: 46bb4c8e52703807
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-schema/token-effect:
+  en: 615cce9c7fcb746d
+  zh: 837f23d49b53151f
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-schema/kv-cache-effect:
+  en: 4ee92571a5f8a71a
+  zh: b218ce5a939481dc
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-result:
+  en: f8ffc2b983f05ffc
+  zh: 8573891441963be4
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-result/what-the-model-sees:
+  en: c25c9db51e7d06da
+  zh: 94fbe03e91eb2382
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-result/token-effect:
+  en: 0efada793d1e65b1
+  zh: 3eed908f43174b88
+/qilin-agent-tool-workspace-dependencies/model-experience/tool-result/kv-cache-effect:
+  en: 42325f307b6c259d
+  zh: 658da42a5a6320d4
+/qilin-agent-tool-workspace-dependencies/known-limitations-and-deferred-work:
+  en: e8977bc1a21223de
+  zh: 9934bad01ad1585c
+/qilin-agent-tool-workspace-dependencies/known-limitations-and-deferred-work/dev-note:
+  en: 000d86d9a81c929a
+  zh: f1d501916e29e5ed

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+---
+description: "The load_workspace_dependencies tool: absolute paths into a bundled Python, Node.js, and pnpm payload, used in place or installed under the QiLin home."
+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-workspace-dependencies
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Deployments that ship their own script runtimes — a container image layer or a deployment-provided primary runtime — mount this tool so the agent can ask where the bundled Python, Node.js, and pnpm live instead of discovering a system interpreter. The tool returns absolute paths and recorded distribution versions; it changes neither `PATH` nor package-manager settings. The payload is either copied under the QiLin home on first use or used where it lies (read-only carriers).
+
+## 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 the plugin beside the tool registry with the payload directory. Configuration validation requires a nonempty `source` and rejects empty `root` values before activation; both paths must be absolute. The bundled Office skills (`@qilin-agent/skill-office`) call this tool by name for their default interpreter.
+
+### Minimal configuration
+
+```yaml
+- name: '@qilin-agent/tool-workspace-dependencies'
+  config:
+    source: /path/to/primary-runtime
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `source` | required | Absolute payload directory carrying `runtime.json` and `dependencies/`. |
+| `root` | unset | Absolute installation directory under the QiLin home. Set: the payload is copied there on the first call and reused while `runtime.json` is unchanged. Unset: the payload is validated and used in place; nothing is copied. |
+
+### Payload layout
+
+`runtime.json` records `desktopVersion`, `platform` (`win32`, `darwin`, or `linux`), `arch`, optional `payloadDigest`, top-level `python`, optional `node`/`pnpm` versions, and the complete `pythonPackages` distribution-version map. A pnpm entry requires Node.js. Python libraries, including numpy and pandas, appear only in `pythonPackages`. Entries live under `dependencies/`: `python/bin/python3` (`python/python.exe` on Windows) with `site-packages` beneath it, and, when declared, `node/bin/node` with `node/node_modules` and `pnpm/bin/pnpm.mjs`. A manifest whose platform or architecture differs from the running process is rejected.
+
+### Carrier activation
+
+The `sdk` profile mounts this tool and `@qilin-agent/skill-office` only when a carrier path exists. A deployment declares one of two environment variables; with neither set, both rows stay disabled and no payload is read.
+
+| Variable | Meaning |
+|---|---|
+| `QILIN_PRIMARY_RUNTIME` | Absolute path to a `primary-runtime/` payload directory. An empty string opts out even when a packaged carrier default exists. |
+| `QILIN_BUNDLED_PRIMARY_RUNTIME` | Carrier default supplied by a packaged carrier. Its `skill-office` `assetRoot` resolves to the sibling `office-skills/` directory and its Node executable to `<payload>/dependencies/node/bin/node`. |
+
+A carrier directory keeps the two resource trees side by side:
+
+```text
+<carrier>/
+  primary-runtime/
+    runtime.json
+    dependencies/python/…
+    dependencies/node/…
+    dependencies/pnpm/…
+  office-skills/
+    office-docx/SKILL.md
+    office-pptx/SKILL.md
+    office-xlsx/SKILL.md
+    scripts/check_office.py
+```
+
+The three Office workflows and their shared checker ship in this repository under [`packages/skill/skill-office/assets/`](../skill-office/assets); copy that tree to `<carrier>/office-skills/`. A container can copy both directories into an immutable image layer and set `QILIN_PRIMARY_RUNTIME` to the absolute `primary-runtime/` path; the tool then queries that payload in place. Profile patches can disable `skill-office` or replace its `assetRoot` independently of this tool, and a custom Python-only payload must either patch `skill-office.config.cli: false` or supply `skill-office.config.node`. Missing skill resources produce a startup warning; invalid or incomplete payloads fail the first tool call. Configuration changes require restarting the SDK process.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+`readPrimaryRuntime` and build smoke checks share `parsePrimaryRuntime`. It validates the flat manifest and rejects duplicate normalized distribution names. Legacy `components` metadata is normalized in memory, retaining its consistency checks; a missing legacy distribution map becomes empty. Mixed flat and legacy version fields are rejected. Reads do not rewrite metadata, and equivalent normalized manifests can reuse an installed payload. `workspaceDependencyPaths` derives the platform-specific entries. `installPrimaryRuntime` copies into a staging directory, requires declared interpreters and scripts to be files and package roots to be directories, and swaps it into place while retaining the previous tree on failure; `resolvePrimaryRuntime` verifies the same entries without copying. The tool memoizes the first successful preparation for the plugin's lifetime.
+
+| File | Responsibility |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Manifest validation, path derivation, in-place and installed preparation, tool registration. |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Office skills](../skill-office/README.md) — the workflows that call this tool for their interpreter.
+- [Tool registry](../../core/tools/README.md) — registration and schemas.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`load_workspace_dependencies` schema](../../../docs/tool-catalog.md#qilin-agenttool-workspace-dependencies).
+
+#### Token effect
+
+Fixed schema cost per request where the tool is visible; the description names the bundled Office libraries so the model can choose the interpreter without loading a skill first.
+
+#### KV Cache effect
+
+Prefix-stable while the tool definition and visibility are unchanged.
+
+### Tool result
+
+#### What the model sees
+
+One JSON object with absolute `python` and `pythonPackages` paths, `pythonDistributions` from `runtime.json`, and `node`, `nodePackages`, and `pnpm` when the payload declares them. Repeated calls return the same object.
+
+#### Token effect
+
+A few hundred characters per call; paths dominate.
+
+#### KV Cache effect
+
+Append-only tool result in the turn history; no prompt section is added.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- This repository ships no primary-runtime builder: the payload is always deployment-provided, and the shipped profiles read it only through `QILIN_PRIMARY_RUNTIME`.
+- Linux targets require glibc; musl payloads are not locked.
+- Windows payloads used in place must already be executable from their carrier; the in-place mode performs no permission repair.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+The carrier boundary is recorded in the [desktop and account alignment boundaries](../../../.agents/notes/implemented/architecture/2026-09-25-desktop-and-account-alignment-boundaries.md): this repository neither builds nor releases the desktop carrier, so the payload directory arrives from the deployment.
+
+</details>

package/README.zh.md

@@ -0,0 +1,147 @@
+---
+description: "load_workspace_dependencies 工具：返回随包 Python、Node.js 与 pnpm payload 的绝对路径，可原位使用或安装到 QiLin home 下。"
+kind: "package-reference"
+---
+
+# @qilin-agent/tool-workspace-dependencies
+
+[English](README.md) | 中文
+
+## 概述
+
+自带脚本运行时的部署——容器镜像层或部署方提供的 primary runtime——挂载本工具后，agent 可以直接询问随包 Python、Node.js 与 pnpm 的位置，而无需探测系统解释器。工具返回绝对路径与记录的发行版版本，既不修改 `PATH`，也不修改包管理器设置。payload 可以首次使用时复制到 QiLin home 下，也可以在原地使用（只读载体）。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将本插件与 payload 目录一同挂载到工具注册表旁。配置校验要求 `source` 非空，并在激活前拒绝空的 `root`；两个路径都必须为绝对路径。随包的 Office skills（`@qilin-agent/skill-office`）按名称调用本工具以取得默认解释器。
+
+### 最小配置
+
+```yaml
+- name: '@qilin-agent/tool-workspace-dependencies'
+  config:
+    source: /path/to/primary-runtime
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `source` | 必填 | 携带 `runtime.json` 与 `dependencies/` 的绝对 payload 目录。 |
+| `root` | 未设置 | QiLin home 下的绝对安装目录。设置后：首次调用时把 payload 复制到该处，并在 `runtime.json` 未变化时复用。未设置：校验并按原位使用 payload，不复制任何内容。 |
+
+### payload 布局
+
+`runtime.json` 记录 `desktopVersion`、`platform`（`win32`、`darwin` 或 `linux`）、`arch`、可选的 `payloadDigest`、顶层 `python`、可选的 `node`/`pnpm` 版本，以及完整的 `pythonPackages` 发行版版本映射。声明 pnpm 就必须声明 Node.js。Python 库（包括 numpy 与 pandas）只出现在 `pythonPackages` 中。具体条目位于 `dependencies/`：`python/bin/python3`（Windows 为 `python/python.exe`）及其下的 `site-packages`；声明时还有 `node/bin/node` 及 `node/node_modules` 和 `pnpm/bin/pnpm.mjs`。平台或架构与当前进程不一致的清单会被拒绝。
+
+### 载体启用
+
+`sdk` profile 仅在存在载体路径时挂载本工具与 `@qilin-agent/skill-office`。部署方声明下面两个环境变量之一；两者都未设置时，两行保持禁用，也不会读取任何 payload。
+
+| 环境变量 | 含义 |
+|---|---|
+| `QILIN_PRIMARY_RUNTIME` | `primary-runtime/` payload 目录的绝对路径。即使存在随包载体默认路径，空字符串也表示禁用。 |
+| `QILIN_BUNDLED_PRIMARY_RUNTIME` | 由打包载体提供的默认路径。其 `skill-office` 的 `assetRoot` 解析为同级的 `office-skills/` 目录，其 Node 可执行文件解析为 `<payload>/dependencies/node/bin/node`。 |
+
+载体目录把两棵资源树并排放置：
+
+```text
+<carrier>/
+  primary-runtime/
+    runtime.json
+    dependencies/python/…
+    dependencies/node/…
+    dependencies/pnpm/…
+  office-skills/
+    office-docx/SKILL.md
+    office-pptx/SKILL.md
+    office-xlsx/SKILL.md
+    scripts/check_office.py
+```
+
+三套 Office 工作流及其共享检查器随本仓提供，位于 [`packages/skill/skill-office/assets/`](../skill-office/assets)；把该目录树复制到 `<carrier>/office-skills/` 即可。容器可以把两个目录一起复制进不可变镜像层，并把 `QILIN_PRIMARY_RUNTIME` 设为 `primary-runtime/` 的绝对路径；此时工具原位查询该 payload。profile patch 可以独立于本工具禁用 `skill-office` 或替换其 `assetRoot`；自定义的纯 Python payload 必须把 `skill-office.config.cli` patch 为 `false`，或提供 `skill-office.config.node`。缺少 skill 资源会产生启动警告；无效或不完整的 payload 会在首次工具调用时失败。配置变更需要重启 SDK 进程。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部细节——点击展开</summary>
+
+`readPrimaryRuntime` 与构建期冒烟检查共用 `parsePrimaryRuntime`。该校验函数校验扁平清单，并拒绝归一化后重名的发行版。旧式 `components` 元数据在内存中归一化，保留其一致性检查；缺失的旧式发行版映射变为空映射。同时出现扁平与旧式版本字段会被拒绝。读取不重写元数据，归一化后等价的清单可以复用已安装的 payload。`workspaceDependencyPaths` 推导各平台的条目。`installPrimaryRuntime` 先复制到暂存目录，要求声明的解释器与脚本是文件、包根是目录，然后换入到位，并在失败时保留原有目录树；`resolvePrimaryRuntime` 校验同样的条目但不复制。工具在插件生命周期内记忆首次成功的准备结果。
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 清单校验、路径推导、原位与安装式准备、工具注册。 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Office skills](../skill-office/README.zh.md)——调用本工具取得解释器的工作流。
+- [工具注册表](../../core/tools/README.zh.md)——注册与 schema。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+模型看到生成的 [`load_workspace_dependencies` schema](../../../docs/tool-catalog.zh.md#qilin-agenttool-workspace-dependencies)。
+
+#### Token 影响
+
+在工具可见处每次请求的固定 schema 成本；描述中列出了随包的 Office 库，因此模型无需先加载 skill 即可选择解释器。
+
+#### KV Cache 影响
+
+只要工具定义与可见性不变，前缀保持稳定。
+
+### 工具结果
+
+#### 模型看到什么
+
+一个 JSON 对象，包含绝对的 `python` 与 `pythonPackages` 路径、来自 `runtime.json` 的 `pythonDistributions`，以及 payload 声明时的 `node`、`nodePackages` 和 `pnpm`。重复调用返回同一个对象。
+
+#### Token 影响
+
+每次调用几百个字符，以路径为主。
+
+#### KV Cache 影响
+
+工具结果只追加到本轮历史；不新增提示词区段。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 本仓不提供 primary-runtime 构建器：payload 始终由部署方提供，随附 profile 只通过 `QILIN_PRIMARY_RUNTIME` 读取它。
+- Linux 目标要求 glibc；musl payload 未纳入锁定。
+- 原位使用的 Windows payload 必须已在载体中可执行；原位模式不修复权限。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+载体边界记录在[桌面与账号对齐边界](../../../.agents/notes/implemented/architecture/2026-09-25-desktop-and-account-alignment-boundaries.zh.md)中：本仓既不构建也不发布桌面载体，因此 payload 目录由部署方提供。
+
+</details>

package/lib/index.js

@@ -0,0 +1,252 @@
+import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import z from "@qilin-agent/schemastery";
+import { defineTool } from "@qilin-agent/tools";
+//#region lib/types/index.js
+/** Model-facing query for a bundled Python, Node.js, and pnpm payload, in place or installed under the QiLin home. */
+/** Cordis plugin identity. */
+const name = "tool-workspace-dependencies";
+/** Registry the tool registers into. */
+const inject = ["tools"];
+/** Require a named payload source before the Loader activates the tool. */
+const Config = z.object({
+	source: z.string().min(1).required(),
+	root: z.string().min(1)
+});
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u;
+const PLATFORMS = [
+	"win32",
+	"darwin",
+	"linux"
+];
+function isVersion(value) {
+	return typeof value === "string" && VERSION.test(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDistributionMap(value) {
+	return isRecord(value) && Object.entries(value).every(([name, version]) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name) && typeof version === "string" && /^\d[\w.!+-]*$/u.test(version));
+}
+/**
+* Validate payload JSON and normalize legacy component fields to top-level versions.
+* @param value - Untrusted decoded runtime.json contents.
+* @returns Canonical metadata with one Python distribution map and no components field.
+* @throws For malformed or mixed formats, duplicate distribution names, or inconsistent legacy metadata.
+*/
+function parsePrimaryRuntime(value) {
+	if (!isRecord(value)) throw new Error("primary runtime: invalid metadata");
+	const legacy = value.components !== void 0;
+	const versions = legacy ? value.components : value;
+	if (!isRecord(versions) || legacy && [
+		"python",
+		"node",
+		"pnpm"
+	].some((key) => value[key] !== void 0)) throw new Error("primary runtime: invalid metadata");
+	const { desktopVersion, platform, arch, payloadDigest } = value;
+	const { python, node, pnpm } = versions;
+	const pythonPackages = value.pythonPackages === void 0 && legacy ? {} : value.pythonPackages;
+	if (typeof desktopVersion !== "string" || desktopVersion.length === 0 || typeof platform !== "string" || !PLATFORMS.includes(platform) || typeof arch !== "string" || !["x64", "arm64"].includes(arch) || !isVersion(python) || node !== void 0 && !isVersion(node) || pnpm !== void 0 && (!isVersion(pnpm) || node === void 0) || payloadDigest !== void 0 && (typeof payloadDigest !== "string" || !/^[a-f0-9]{64}$/u.test(payloadDigest)) || !isDistributionMap(pythonPackages)) throw new Error("primary runtime: invalid metadata");
+	const entries = Object.entries(pythonPackages);
+	const distributions = new Map(entries.map(([name, version]) => [name.toLowerCase().replace(/[-_.]+/gu, "-"), version]));
+	if (distributions.size !== entries.length) throw new Error("primary runtime: invalid metadata");
+	if (legacy) for (const name of ["numpy", "pandas"]) {
+		if (!isVersion(versions[name])) throw new Error("primary runtime: invalid metadata");
+		const version = distributions.get(name);
+		if (version !== void 0 && version !== versions[name]) throw new Error(`primary runtime: conflicting ${name} distribution version`);
+	}
+	return {
+		desktopVersion,
+		platform,
+		arch,
+		...payloadDigest === void 0 ? {} : { payloadDigest },
+		python,
+		...node === void 0 ? {} : { node },
+		...pnpm === void 0 ? {} : { pnpm },
+		pythonPackages
+	};
+}
+/**
+* Read and normalize build metadata without rewriting the source file.
+* @param root - Installed or bundled primary runtime directory.
+* @returns Validated top-level versions and target identifiers, including for legacy components manifests.
+*/
+async function readPrimaryRuntime(root) {
+	return parsePrimaryRuntime(JSON.parse(await readFile(join(root, "runtime.json"), "utf8")));
+}
+/**
+* Resolve platform-specific interpreter and library locations without changing the environment.
+* @param root - Absolute payload or installation directory.
+* @param manifest - Validated runtime metadata.
+* @returns Absolute paths for explicit script execution and recorded bundled Python versions.
+*/
+function workspaceDependencyPaths(root, manifest) {
+	const dependencies = join(root, "dependencies");
+	const windows = manifest.platform === "win32";
+	const node = manifest.node === void 0 ? {} : {
+		node: join(dependencies, "node", "bin", windows ? "node.exe" : "node"),
+		nodePackages: join(dependencies, "node", "node_modules")
+	};
+	const pnpm = manifest.pnpm === void 0 ? {} : { pnpm: join(dependencies, "pnpm", "bin", "pnpm.mjs") };
+	return {
+		python: join(dependencies, "python", ...windows ? ["python.exe"] : ["bin", "python3"]),
+		...node,
+		...pnpm,
+		pythonPackages: join(dependencies, "python", ...windows ? ["Lib"] : ["lib", `python${manifest.python.split(".").slice(0, 2).join(".")}`], "site-packages"),
+		pythonDistributions: manifest.pythonPackages
+	};
+}
+async function validatePayloadEntries(paths) {
+	for (const [path, kind] of [
+		[paths.python, "file"],
+		[paths.node, "file"],
+		[paths.pnpm, "file"],
+		[paths.pythonPackages, "directory"],
+		[paths.nodePackages, "directory"]
+	]) {
+		if (path === void 0) continue;
+		const entry = await stat(path);
+		if (!(kind === "file" ? entry.isFile() : entry.isDirectory())) throw new Error(`primary runtime: expected ${kind} at ${path}`);
+	}
+}
+async function exists(path) {
+	try {
+		if ((await lstat(path)).isSymbolicLink()) throw new Error(`primary runtime: installation path is a filesystem link: ${path}`);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+async function compatibleManifest(source) {
+	const manifest = await readPrimaryRuntime(source);
+	if (manifest.platform !== process.platform || manifest.arch !== process.arch) throw new Error("primary runtime: incompatible platform or architecture");
+	return manifest;
+}
+/**
+* Use a payload where it lies: validate its metadata and entries, copying nothing.
+* @param source - Payload directory, typically a read-only carrier.
+* @returns Paths into the payload itself.
+*/
+async function resolvePrimaryRuntime(source) {
+	const paths = workspaceDependencyPaths(source, await compatibleManifest(source));
+	await validatePayloadEntries(paths);
+	return paths;
+}
+/**
+* Install the application-owned payload locally, retaining a complete previous tree on copy failure.
+* @param source - Payload carried by the current installation.
+* @param root - Fixed primary runtime directory under the QiLin home.
+* @returns Paths into the installed payload; no PATH or package-manager configuration is changed.
+*/
+async function installPrimaryRuntime(source, root) {
+	const manifest = await compatibleManifest(source);
+	await mkdir(dirname(root), { recursive: true });
+	const previous = `${root}.previous`;
+	const previousExists = await exists(previous);
+	if (!await exists(root) && previousExists) await rename(previous, root);
+	if (await exists(join(root, "runtime.json")) && JSON.stringify(await readPrimaryRuntime(root)) === JSON.stringify(manifest)) {
+		const paths = workspaceDependencyPaths(root, manifest);
+		await validatePayloadEntries(paths);
+		return paths;
+	}
+	const staging = await mkdtemp(join(dirname(root), ".primary-runtime-"));
+	try {
+		await cp(source, staging, {
+			recursive: true,
+			dereference: true
+		});
+		await validatePayloadEntries(workspaceDependencyPaths(staging, manifest));
+		await rm(previous, {
+			recursive: true,
+			force: true
+		});
+		const replacing = await exists(root);
+		if (replacing) await rename(root, previous);
+		try {
+			await rename(staging, root);
+		} catch (error) {
+			if (replacing) await rename(previous, root);
+			throw error;
+		}
+		await rm(previous, {
+			recursive: true,
+			force: true
+		});
+	} finally {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+	return workspaceDependencyPaths(root, manifest);
+}
+/**
+* Register the read-only path query; the first invocation prepares (or merely validates) the payload.
+* @param ctx - Tool registry owner.
+* @param config - Payload location and optional installation directory.
+*/
+function apply(ctx, config) {
+	if (!isAbsolute(config.source) || config.root !== void 0 && !isAbsolute(config.root)) throw new Error("workspace dependencies: source and root must be absolute paths");
+	let preparation;
+	ctx.effect(() => async () => {
+		await preparation?.catch(() => void 0);
+	});
+	ctx.tools.register(defineTool({
+		name: "load_workspace_dependencies",
+		description: "Get absolute paths to bundled Python and library directories, plus bundled Python distribution versions. Node.js and pnpm paths are included when the payload provides them. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. When Node.js and pnpm paths are returned, run pnpm with that Node executable and pnpm script path. This does not change PATH or package-manager settings.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					python: {
+						type: "string",
+						required: true
+					},
+					node: {
+						type: "string",
+						description: "Absent when the payload ships no Node.js."
+					},
+					pnpm: {
+						type: "string",
+						description: "Absent when the payload ships no pnpm."
+					},
+					pythonPackages: {
+						type: "string",
+						required: true
+					},
+					nodePackages: {
+						type: "string",
+						description: "Absent when the payload ships no Node.js."
+					},
+					pythonDistributions: {
+						type: "object",
+						additionalProperties: true,
+						required: true,
+						description: "Bundled distribution names and versions recorded in runtime.json; excludes user-installed additions."
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value, void 0, 2)
+			}]
+		},
+		execute: () => {
+			preparation ??= (config.root === void 0 ? resolvePrimaryRuntime(config.source) : installPrimaryRuntime(config.source, config.root)).catch((error) => {
+				preparation = void 0;
+				throw error;
+			});
+			return preparation;
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "Load workspace dependencies",
+			kind: "read"
+		})
+	}));
+}
+//#endregion
+export { Config, apply, inject, installPrimaryRuntime, name, parsePrimaryRuntime, readPrimaryRuntime, resolvePrimaryRuntime, workspaceDependencyPaths };

package/lib/types/index.d.ts

@@ -0,0 +1,86 @@
+/** Model-facing query for a bundled Python, Node.js, and pnpm payload, in place or installed under the QiLin home. */
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+/** Cordis plugin identity. */
+export declare const name = "tool-workspace-dependencies";
+/** Registry the tool registers into. */
+export declare const inject: string[];
+/** Payload location and optional installation directory. */
+export interface Config {
+    /** Payload directory carrying `runtime.json` and `dependencies/`. */
+    readonly source: string;
+    /**
+     * Installation directory under the QiLin home. When set, the payload is copied there on the
+     * first call (the copy-on-first-use behavior); when omitted, the payload is used in place without copying,
+     * which suits read-only carriers such as container image layers.
+     */
+    readonly root?: string;
+}
+/** Require a named payload source before the Loader activates the tool. */
+export declare const Config: z<Config>;
+/** Canonical build metadata, independent of user-installed packages; legacy files are normalized on read. */
+export interface PrimaryRuntimeManifest {
+    readonly desktopVersion: string;
+    readonly platform: string;
+    readonly arch: string;
+    /** Locked payload identity; absent only in installations made before payload hashing. */
+    readonly payloadDigest?: string;
+    /** Bundled Python interpreter version. */
+    readonly python: string;
+    /** Absent when the payload ships no Node.js. */
+    readonly node?: string;
+    /** Bundled pnpm version; requires a bundled Node.js executable. */
+    readonly pnpm?: string;
+    /** All recorded Python distribution versions; empty for legacy files without a distribution map. */
+    readonly pythonPackages: Readonly<Record<string, string>>;
+}
+/** Absolute entry points and bundled versions; pnpm runs through the returned Node executable. */
+export interface WorkspaceDependencies {
+    readonly python: string;
+    readonly node?: string;
+    readonly pnpm?: string;
+    readonly pythonPackages: string;
+    readonly nodePackages?: string;
+    /** Locked distribution versions; excludes packages users add to the installed environment. */
+    readonly pythonDistributions: Readonly<Record<string, string>>;
+}
+/**
+ * Validate payload JSON and normalize legacy component fields to top-level versions.
+ * @param value - Untrusted decoded runtime.json contents.
+ * @returns Canonical metadata with one Python distribution map and no components field.
+ * @throws For malformed or mixed formats, duplicate distribution names, or inconsistent legacy metadata.
+ */
+export declare function parsePrimaryRuntime(value: unknown): PrimaryRuntimeManifest;
+/**
+ * Read and normalize build metadata without rewriting the source file.
+ * @param root - Installed or bundled primary runtime directory.
+ * @returns Validated top-level versions and target identifiers, including for legacy components manifests.
+ */
+export declare function readPrimaryRuntime(root: string): Promise<PrimaryRuntimeManifest>;
+/**
+ * Resolve platform-specific interpreter and library locations without changing the environment.
+ * @param root - Absolute payload or installation directory.
+ * @param manifest - Validated runtime metadata.
+ * @returns Absolute paths for explicit script execution and recorded bundled Python versions.
+ */
+export declare function workspaceDependencyPaths(root: string, manifest: PrimaryRuntimeManifest): WorkspaceDependencies;
+/**
+ * Use a payload where it lies: validate its metadata and entries, copying nothing.
+ * @param source - Payload directory, typically a read-only carrier.
+ * @returns Paths into the payload itself.
+ */
+export declare function resolvePrimaryRuntime(source: string): Promise<WorkspaceDependencies>;
+/**
+ * Install the application-owned payload locally, retaining a complete previous tree on copy failure.
+ * @param source - Payload carried by the current installation.
+ * @param root - Fixed primary runtime directory under the QiLin home.
+ * @returns Paths into the installed payload; no PATH or package-manager configuration is changed.
+ */
+export declare function installPrimaryRuntime(source: string, root: string): Promise<WorkspaceDependencies>;
+/**
+ * Register the read-only path query; the first invocation prepares (or merely validates) the payload.
+ * @param ctx - Tool registry owner.
+ * @param config - Payload location and optional installation directory.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@qilin-agent/tool-workspace-dependencies",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "The load_workspace_dependencies tool: absolute paths into a bundled Python, Node.js, and pnpm payload",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/skill/tool-workspace-dependencies"
+  },
+  "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"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/kylin-plugin-include": "~1.0.8",
+    "@qilin-agent/kylin-plugin-loader": "~1.0.4"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  }
 }