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.
This commit is contained in:
1 parent
a0766d7573
commit
b605b3dab2
5 files changed
+33
-15
No files matched your search
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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 投影:
|
||||
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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' })
|
||||
})
|
||||
Reference in new issue
Block a user