@deepseek-ai/dsh-tool-present 0.1.5-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,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/fs/tool-present/README.md
+README.md: 93003711545f678336a02c9bf8589176f844af65
+README.zh.md: 152ba39be7184ca536a56ed9b4cfb5dfa4a5fe82

package/README.md

@@ -0,0 +1,102 @@
+---
+description: "Declare accessible files as deliverables with present; configuration, Session ownership, and source-file opening."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-present
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `present` to declare final files accessible through the Session filesystem, including files created through shell commands. Users open the current source files in their default application. The tool records paths and optional descriptions without copying file contents.
+
+## 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
+
+The `standard`, `ptc`, and `cordis` agent presets mount this plugin. Call `present` with `files: [{ path, description? }]` after creating the files. Files must be regular files accessible through the Session filesystem. Relative paths resolve against the Session working directory; absolute paths may name files outside it, including `/tmp` or Downloads. Missing files, directories, final symbolic links, and provider-denied paths fail the call. Files in a shell sandbox’s private `/tmp` must first be written somewhere the Session filesystem can access.
+
+Mount it in an agent's Cordis composition with `tools`, `fs`, and the `turnBoundary` Session projection available:
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-present'
+  config:
+    maxFiles: 8
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxFiles` | `8` | Positive maximum file count per call |
+
+The file-count limit is validated at mount. The tool requires an agent Session with a workspace and an open turn. Delivery belongs to the calling Session; a parent must call `present` itself to declare files created by a subagent.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The tool resolves paths through the configured filesystem provider and checks regular-file metadata without reading contents. Successful final `tools/result` notifications append `deliverables/presented`, including nested calls. A later enclosing program failure does not revoke an already completed declaration. Blocked results publish none. Each plugin instance records only calls it executed; scoped tools with the same name cannot publish through another instance.
+
+The pure `./types` entry declares `PresentedFile` and the Session event without importing Host runtime code. The Web consumer validates persisted declarations before displaying or opening them. The event stores no Session ID, so forked history resolves relative paths against the viewed Session's workspace.
+
+**Runtime invariant:** No companion is published. Tool and event registrations are effect-owned, and the Session log owns file declarations; the plugin maintains no independent file-content store.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Filesystem subsystem](../../../docs/subsystems/filesystem.md) — provider paths and errors.
+- [Web deliverables](../../client/ui-deliverables/README.md) — source-file opening and cards.
+- [Delivery decision](../../../.agents/notes/implemented/feature/2026-09-08-present-workspace-source-files.md) — Session ownership and required-on-read events.
+
+<a id="model-experience"></a>
+## Model Experience
+
+### present
+
+#### What the model sees
+
+The [present schema](../../../docs/tool-catalog.md#present) asks for existing accessible files: “Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” Results report `Presented <path>` for each file; the program result and durable event contain paths and optional descriptions.
+
+#### Token effect
+
+One tool schema per mounted agent and one result line per delivered file. File bytes do not enter model messages.
+
+#### KV Cache effect
+
+The tool schema is static for the mount lifetime. Delivery result text extends the conversation without rewriting its prompt prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Metadata and Host-path checks cannot atomically prevent replacement before a desktop application opens a file.
+- Edits change what opens. Deleted or moved source files cannot be opened from their declarations.
+- Session ZIP exports contain declarations, not file contents. Persistent delivery versions and copy-on-write storage are deferred.
+
+<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,102 @@
+---
+description: "通过 present 声明交付可访问的文件；配置、Session 归属与源文件打开。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-present
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `present` 声明交付Session 文件系统可访问的最终文件，包括通过 shell 命令创建的文件。用户使用默认应用打开当前源文件。工具记录路径和可选说明，不复制文件内容。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+`standard`、`ptc` 与 `cordis` Agent preset 挂载本插件。创建文件后，以 `files: [{ path, description? }]` 调用 `present`。文件必须是 Session 文件系统可访问的普通文件。相对路径按 Session 工作目录解析；绝对路径可以指向工作区外的文件，包括 `/tmp` 或 Downloads。文件缺失、为目录、最终路径为符号链接或提供方拒绝访问时，调用失败。Shell 沙箱私有 `/tmp` 中的文件需要先写入 Session 文件系统可访问的位置。
+
+在 Agent 的 Cordis 组合中挂载，并提供 `tools`、`fs` 和 `turnBoundary` Session 投影：
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-present'
+  config:
+    maxFiles: 8
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `maxFiles` | `8` | 每次调用的最大文件数，为正整数 |
+
+挂载时校验文件数量上限。工具要求 Agent Session 具有工作区和已开始的 turn。交付归调用方 Session 所有；父 Session 如需声明交付子 Agent 创建的文件，必须自行调用 `present`。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+工具通过配置的文件系统提供方解析路径，检查普通文件元数据，不读取内容。成功的最终 `tools/result` 通知追加 `deliverables/presented`，嵌套调用也适用。外层程序随后失败不会撤销已完成的声明。被阻止的结果不发布声明。每个插件实例只记录其实际执行的调用；同名作用域工具不能通过其他实例发布交付。
+
+纯 `./types` 入口声明 `PresentedFile` 与 Session 事件，不导入 Host 运行时代码。Web 消费方在展示或打开文件前校验持久声明。事件不保存 Session ID，因此 fork 历史中的相对路径按当前查看的 Session 工作区解析。
+
+**运行时不变式：** 不发布伴生入口。工具与事件注册归 effect 所有，Session 日志拥有文件声明；插件不维护独立的文件内容存储。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [文件系统子系统](../../../docs/subsystems/filesystem.zh.md)——提供方路径与错误。
+- [Web 交付](../../client/ui-deliverables/README.zh.md)——源文件打开与卡片。
+- [交付决策](../../../.agents/notes/implemented/feature/2026-09-08-present-workspace-source-files.zh.md)——Session 归属与读取端必须识别的事件。
+
+<a id="model-experience"></a>
+## 模型体验
+
+### present
+
+#### 模型看到的内容
+
+[present schema](../../../docs/tool-catalog.zh.md#present)要求已有且可访问的文件：“Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” 每个文件的结果为 `Presented <path>`；程序结果和持久事件包含路径及可选说明。
+
+#### Token 影响
+
+每个挂载的 Agent 增加一个工具 schema，每个交付文件增加一行结果。文件字节不进入模型消息。
+
+#### KV Cache 影响
+
+工具 schema 在挂载期间保持静态。交付结果文本扩展对话，不重写提示词前缀。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 元数据和 Host 路径检查无法原子性地阻止桌面应用打开文件前发生的路径替换。
+- 编辑会改变打开的内容。源文件删除或移动后，无法通过原声明打开。
+- Session ZIP 导出包含声明，不包含文件内容。交付版本持久化和写时复制存储延期实现。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,123 @@
+import z from "@deepseek-ai/schemastery";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/** Stable Loader identity. */
+const name = "tool-present";
+/** Validated delivery limit. */
+const Config = z.object({ maxFiles: z.number().default(8) });
+/** Services used by the scoped delivery tool. */
+const inject = [
+	"tools",
+	"fs",
+	"sessionProjections"
+];
+/**
+* Register present with durable file references in its tool result.
+* @param ctx - agent-scoped services.
+* @param config - maximum files per call.
+*/
+function apply(ctx, config) {
+	if (!Number.isSafeInteger(config.maxFiles) || config.maxFiles < 1) throw new Error("present requires a positive integer maxFiles");
+	const pending = /* @__PURE__ */ new WeakMap();
+	ctx.tools.register(defineTool({
+		name: "present",
+		description: "Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.",
+		parameters: { files: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: {
+						type: "string",
+						required: true,
+						description: "Path of an existing regular file. Relative paths use the Session working directory."
+					},
+					description: {
+						type: "string",
+						description: "Brief description for the user."
+					}
+				}
+			}
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					turn: {
+						type: "integer",
+						required: true
+					},
+					files: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								path: {
+									type: "string",
+									required: true
+								},
+								description: { type: "string" }
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.files.map((file) => `Presented ${file.path}`).join("\n")
+			}]
+		},
+		async execute(args, exec) {
+			if (exec.agent === void 0) throw new Error("present requires an agent Session");
+			const boundary = ctx.sessionProjections.stateOf(exec.agent.session, "turnBoundary");
+			if (boundary === void 0 || boundary.openTurnStartSeq === null) throw new Error("present requires an open turn");
+			if (args.files.length === 0 || args.files.length > config.maxFiles) throw new Error(`present accepts 1 to ${config.maxFiles} files`);
+			const cwd = exec.agent.session.header.cwd;
+			if (cwd === void 0) throw new Error("present requires a workspace");
+			const options = {
+				cwd,
+				signal: exec.signal
+			};
+			const files = [];
+			for (const file of args.files) {
+				if (file.path.trim().length === 0) throw new Error("present requires a non-empty file path");
+				const entry = await ctx.fs.lstat(file.path, { cwd }, exec.signal);
+				if (entry !== void 0 && entry.type !== "file") throw new Error(`Cannot present ${file.path}: not a regular file`);
+				const target = await ctx.fs.resolve(file.path, options);
+				const info = await ctx.fs.stat(target, exec.signal);
+				if (info === void 0) throw new FsError(`Cannot present ${file.path}: file not found. Check the path, create the file if needed, and retry.`, "FS_NOT_FOUND");
+				if (info.type !== "file") throw new Error(`Cannot present ${file.path}: not a regular file`);
+				files.push({ ...file });
+			}
+			exec.signal.throwIfAborted();
+			pending.set(exec, {
+				session: exec.agent.session,
+				turn: boundary.lastTurn,
+				files
+			});
+			return {
+				turn: boundary.lastTurn,
+				files
+			};
+		}
+	}));
+	ctx.on("tools/result", (exec, result) => {
+		const delivery = pending.get(exec);
+		pending.delete(exec);
+		if (delivery === void 0 || result.isError) return;
+		const { session, turn, files } = delivery;
+		session.append("deliverables/presented", {
+			turn,
+			callId: exec.callId,
+			files
+		});
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,21 @@
+/** Scoped tool that declares filesystem deliveries in their owning Session. */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Loader identity. */
+export declare const name = "tool-present";
+/** Per-call delivery limit. */
+export interface Config {
+    /** Maximum number of files in one call. */
+    maxFiles: number;
+}
+/** Validated delivery limit. */
+export declare const Config: z<Config>;
+/** Services used by the scoped delivery tool. */
+export declare const inject: string[];
+/**
+ * Register present with durable file references in its tool result.
+ * @param ctx - agent-scoped services.
+ * @param config - maximum files per call.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,102 @@
+import z from '@deepseek-ai/schemastery';
+import { FsError } from '@deepseek-ai/dsh-fs';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+/** Stable Loader identity. */
+export const name = 'tool-present';
+/** Validated delivery limit. */
+export const Config = z.object({
+    maxFiles: z.number().default(8),
+});
+/** Services used by the scoped delivery tool. */
+export const inject = ['tools', 'fs', 'sessionProjections'];
+/**
+ * Register present with durable file references in its tool result.
+ * @param ctx - agent-scoped services.
+ * @param config - maximum files per call.
+ */
+export function apply(ctx, config) {
+    if (!Number.isSafeInteger(config.maxFiles) || config.maxFiles < 1) {
+        throw new Error('present requires a positive integer maxFiles');
+    }
+    const pending = new WeakMap();
+    ctx.tools.register(defineTool({
+        name: 'present',
+        description: 'Declare existing files accessible through the Session filesystem as final deliverables. '
+            + 'When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. '
+            + 'Mentioning its path in your reply does not replace this call. The files must already exist. '
+            + 'The user opens the current source files; their contents are not copied or preserved.',
+        parameters: {
+            files: {
+                type: 'array', required: true,
+                items: {
+                    type: 'object', additionalProperties: false,
+                    properties: {
+                        path: { type: 'string', required: true, description: 'Path of an existing regular file. Relative paths use the Session working directory.' },
+                        description: { type: 'string', description: 'Brief description for the user.' },
+                    },
+                },
+            },
+        },
+        output: {
+            schema: {
+                type: 'object', additionalProperties: false,
+                properties: {
+                    turn: { type: 'integer', required: true },
+                    files: {
+                        type: 'array', required: true,
+                        items: {
+                            type: 'object', additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                description: { type: 'string' },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.files.map(file => `Presented ${file.path}`).join('\n') }],
+        },
+        async execute(args, exec) {
+            if (exec.agent === undefined)
+                throw new Error('present requires an agent Session');
+            const boundary = ctx.sessionProjections.stateOf(exec.agent.session, 'turnBoundary');
+            if (boundary === undefined || boundary.openTurnStartSeq === null)
+                throw new Error('present requires an open turn');
+            if (args.files.length === 0 || args.files.length > config.maxFiles)
+                throw new Error(`present accepts 1 to ${config.maxFiles} files`);
+            const cwd = exec.agent.session.header.cwd;
+            if (cwd === undefined)
+                throw new Error('present requires a workspace');
+            const options = { cwd, signal: exec.signal };
+            const files = [];
+            for (const file of args.files) {
+                if (file.path.trim().length === 0)
+                    throw new Error('present requires a non-empty file path');
+                const entry = await ctx.fs.lstat(file.path, { cwd }, exec.signal);
+                if (entry !== undefined && entry.type !== 'file')
+                    throw new Error(`Cannot present ${file.path}: not a regular file`);
+                const target = await ctx.fs.resolve(file.path, options);
+                const info = await ctx.fs.stat(target, exec.signal);
+                if (info === undefined)
+                    throw new FsError(`Cannot present ${file.path}: file not found. Check the path, create the file if needed, and retry.`, 'FS_NOT_FOUND');
+                if (info.type !== 'file')
+                    throw new Error(`Cannot present ${file.path}: not a regular file`);
+                files.push({ ...file });
+            }
+            exec.signal.throwIfAborted();
+            pending.set(exec, { session: exec.agent.session, turn: boundary.lastTurn, files });
+            return { turn: boundary.lastTurn, files };
+        },
+    }));
+    ctx.on('tools/result', (exec, result) => {
+        const delivery = pending.get(exec);
+        pending.delete(exec);
+        if (delivery === undefined || result.isError)
+            return;
+        const { session, turn, files } = delivery;
+        session.append('deliverables/presented', {
+            turn, callId: exec.callId, files,
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,20 @@
+/** Durable file deliveries produced by the present tool. */
+import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand';
+/** A declared filesystem file whose current contents remain at its source path. */
+export interface PresentedFile {
+    /** Original absolute path or path relative to the Session working directory. */
+    path: string;
+    /** Optional description supplied by the model. */
+    description?: string;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** Declared filesystem files from a successful final present result, including nested calls. */
+        'deliverables/presented': {
+            turn: number;
+            callId: ToolCallId;
+            files: PresentedFile[];
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@deepseek-ai/dsh-tool-present",
+  "description": "Explicit workspace file delivery declarations for the DeepSeek Harness",
+  "version": "0.1.5-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/fs/tool-present"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2"
+  }
+}