From b605b3dab2d4e5138a96d65e27e1537af3fe1f5a Mon Sep 17 00:00:00 2001 From: sjw1231 Date: Thu, 5 Nov 2026 17:28:45 +0800 Subject: [PATCH] feat(present): give present failures structured error codes A missing agent Session or open turn throws ToolContextUnavailableError, an empty path or out-of-range file count throws ToolArgsError, and a directory or final symlink throws FsError FS_NOT_REGULAR_FILE. --- .../tool-present/README.i18n.yaml | 4 +-- packages/deliverables/tool-present/README.md | 2 +- .../deliverables/tool-present/README.zh.md | 2 +- .../deliverables/tool-present/src/index.ts | 14 +++++----- .../tool-present/tests/present.spec.ts | 26 ++++++++++++++++--- 5 files changed, 33 insertions(+), 15 deletions(-) diff --git a/packages/deliverables/tool-present/README.i18n.yaml b/packages/deliverables/tool-present/README.i18n.yaml index 7de5647086..d5b2ce4e60 100644 --- a/packages/deliverables/tool-present/README.i18n.yaml +++ b/packages/deliverables/tool-present/README.i18n.yaml @@ -15,8 +15,8 @@ en: d152484eb41ac6b4 zh: 09388d293f9be9cb /deepseek-ai-dsh-tool-present/use-this-package: - en: d1a1e22686f9041d - zh: 8053a913199195fa + en: aecb160dd6ee85ba + zh: 148288a2e92236fa /deepseek-ai-dsh-tool-present/understand-the-implementation: en: 6e73ca41dddc096e zh: b59fdfa3f3cc47e1 diff --git a/packages/deliverables/tool-present/README.md b/packages/deliverables/tool-present/README.md index 7439bda570..031cf546d4 100644 --- a/packages/deliverables/tool-present/README.md +++ b/packages/deliverables/tool-present/README.md @@ -29,7 +29,7 @@ Shared output and file-link guidance comes from [`dsh-deliverable-file-reference `present` validates paths against the Session's current working directory and records absolute paths, so later directory changes do not redirect delivered files. -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. +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 with `FsError` codes such as `FS_NOT_FOUND`, `FS_NOT_REGULAR_FILE`, and `FS_PERMISSION_DENIED`; an empty path or a file count outside 1 to `maxFiles` reports `ToolArgsError` (`INVALID_ARGS`), and a call without an agent Session or open turn reports `ToolContextUnavailableError` (`TOOL_CONTEXT_UNAVAILABLE`). 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: diff --git a/packages/deliverables/tool-present/README.zh.md b/packages/deliverables/tool-present/README.zh.md index 40b81571aa..08410efe05 100644 --- a/packages/deliverables/tool-present/README.zh.md +++ b/packages/deliverables/tool-present/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" `present` 按 Session 的当前工作目录校验路径并记录绝对路径,因此后续目录切换不会让已交付文件指向其他位置。 -`standard`、`ptc` 与 `cordis` Agent preset 挂载本插件。创建文件后,以 `files: [{ path, description? }]` 调用 `present`。文件必须是 Session 文件系统可访问的普通文件。相对路径按 Session 工作目录解析;绝对路径可以指向工作区外的文件,包括 `/tmp` 或 Downloads。文件缺失、为目录、最终路径为符号链接或提供方拒绝访问时,调用失败。Shell 沙箱私有 `/tmp` 中的文件需要先写入 Session 文件系统可访问的位置。 +`standard`、`ptc` 与 `cordis` Agent preset 挂载本插件。创建文件后,以 `files: [{ path, description? }]` 调用 `present`。文件必须是 Session 文件系统可访问的普通文件。相对路径按 Session 工作目录解析;绝对路径可以指向工作区外的文件,包括 `/tmp` 或 Downloads。文件缺失、为目录、最终路径为符号链接或提供方拒绝访问时,调用以 `FsError` 失败,错误码如 `FS_NOT_FOUND`、`FS_NOT_REGULAR_FILE` 与 `FS_PERMISSION_DENIED`;路径为空或文件数量不在 1 到 `maxFiles` 之间时报告 `ToolArgsError`(`INVALID_ARGS`),缺少 agent Session 或打开的 turn 时报告 `ToolContextUnavailableError`(`TOOL_CONTEXT_UNAVAILABLE`)。Shell 沙箱私有 `/tmp` 中的文件需要先写入 Session 文件系统可访问的位置。 在 Agent 的 Cordis 组合中挂载,并提供 `tools`、`fs` 和 `turnBoundary` Session 投影: diff --git a/packages/deliverables/tool-present/src/index.ts b/packages/deliverables/tool-present/src/index.ts index 393a95d8c8..fac6ab0378 100644 --- a/packages/deliverables/tool-present/src/index.ts +++ b/packages/deliverables/tool-present/src/index.ts @@ -3,7 +3,7 @@ import type {} from '@deepseek-ai/dsh-working-directory' import type { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' import { FsError } from '@deepseek-ai/dsh-fs' -import { defineTool, type ToolExecution } from '@deepseek-ai/dsh-tools' +import { ToolArgsError, ToolContextUnavailableError, defineTool, type ToolExecution } from '@deepseek-ai/dsh-tools' import type {} from '@deepseek-ai/dsh-agent' import type { Session } from '@deepseek-ai/dsh-session' import type { PresentedFile } from './types.ts' @@ -76,21 +76,21 @@ export function apply(ctx: Context, config: Config): void { 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') + if (exec.agent === undefined) throw new ToolContextUnavailableError('present requires an agent Session') const boundary = ctx.agents.turnBoundaryOf(exec.agent.session) - if (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`) + if (boundary.openTurnStartSeq === null) throw new ToolContextUnavailableError('present requires an open turn') + if (args.files.length === 0 || args.files.length > config.maxFiles) throw new ToolArgsError([`present accepts 1 to ${config.maxFiles} files`]) const cwd = await ctx.workingDirectory.ensure(exec.agent, exec.signal) const options = { cwd, signal: exec.signal } const files: PresentedFile[] = [] for (const file of args.files) { - if (file.path.trim().length === 0) throw new Error('present requires a non-empty file path') + if (file.path.trim().length === 0) throw new ToolArgsError(['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`) + if (entry !== undefined && entry.type !== 'file') throw new FsError(`Cannot present ${file.path}: not a regular file`, 'FS_NOT_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`) + if (info.type !== 'file') throw new FsError(`Cannot present ${file.path}: not a regular file`, 'FS_NOT_REGULAR_FILE') files.push({ ...file, path: ctx.fs.processPath(target) }) } exec.signal.throwIfAborted() diff --git a/packages/deliverables/tool-present/tests/present.spec.ts b/packages/deliverables/tool-present/tests/present.spec.ts index 18da272027..6492740c99 100644 --- a/packages/deliverables/tool-present/tests/present.spec.ts +++ b/packages/deliverables/tool-present/tests/present.spec.ts @@ -140,9 +140,19 @@ describe('present', () => { const { root, owner, execute } = await setup() await writeFile(join(root, 'large'), 'four') await symlink(tmpdir(), join(root, 'outside')) - for (const files of [[], [{ path: '' }], [{ path: 'missing' }], [{ path: '.' }], [{ path: 'outside' }], [{ path: 'large' }, { path: 'large' }, { path: 'large' }]]) { + const invalidArgs = { name: 'ToolArgsError', code: 'INVALID_ARGS' } + const notRegular = { name: 'FsError', code: 'FS_NOT_REGULAR_FILE' } + for (const [files, info] of [ + [[], invalidArgs], + [[{ path: '' }], invalidArgs], + [[{ path: 'missing' }], { name: 'FsError', code: 'FS_NOT_FOUND' }], + [[{ path: '.' }], notRegular], + [[{ path: 'outside' }], notRegular], + [[{ path: 'large' }, { path: 'large' }, { path: 'large' }], invalidArgs], + ] as const) { const result = await execute(files) expect(result.isError, JSON.stringify(files)).toBe(true) + expect(result.error?.info, JSON.stringify(files)).toEqual(info) } expect(owner.session.snapshotEvents().some(event => event.type === 'deliverables/presented')).toBe(false) }) @@ -163,9 +173,13 @@ it('validates deployment limits before registering the tool', async () => { it('requires an agent, an open turn, and a workspace', async () => { const { ctx, owner, execute } = await setup() const detached = await executeToolFixture(ctx, { signal: new AbortController().signal, callId: ToolCallId('detached'), name: 'present', arguments: { files: [{ path: 'a' }] } }) + const contextUnavailable = { name: 'ToolContextUnavailableError', code: 'TOOL_CONTEXT_UNAVAILABLE' } expect(detached.isError).toBe(true) + expect(detached.error?.info).toEqual(contextUnavailable) owner.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - expect((await execute([{ path: 'a' }])).isError).toBe(true) + const closed = await execute([{ path: 'a' }]) + expect(closed.isError).toBe(true) + expect(closed.error?.info).toEqual(contextUnavailable) const noWorkspace = await agent(ctx, undefined) noWorkspace.session.append('turn/start', { turn: 1 }) const absent = await executeToolFixture(ctx, { signal: new AbortController().signal, callId: ToolCallId('no-workspace'), name: 'present', arguments: { files: [{ path: 'a' }] }, agent: noWorkspace }) @@ -188,7 +202,9 @@ it('refuses a final symlink to an ordinary file', async () => { const { root, execute } = await setup() await writeFile(join(root, 'source'), 'source') await symlink(join(root, 'source'), join(root, 'link')) - expect((await execute([{ path: 'link' }])).isError).toBe(true) + const result = await execute([{ path: 'link' }]) + expect(result.isError).toBe(true) + expect(result.error?.info).toEqual({ name: 'FsError', code: 'FS_NOT_REGULAR_FILE' }) }) @@ -197,5 +213,7 @@ it('refuses a file replaced by a directory after inspecting its final component' await writeFile(join(root, 'source'), 'source') const directory = await ctx.fs.stat(await ctx.fs.resolve(root)) vi.spyOn(ctx.fs, 'stat').mockResolvedValueOnce(directory) - expect((await execute([{ path: 'source' }])).isError).toBe(true) + const result = await execute([{ path: 'source' }]) + expect(result.isError).toBe(true) + expect(result.error?.info).toEqual({ name: 'FsError', code: 'FS_NOT_REGULAR_FILE' }) })