DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add canonical typed tool outputs

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-21 03:08:35 +08:00
parent 8500974fd4
commit 66c36e7325
173 changed files with 3298 additions and 954 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/web/tool-web/README.md
View File

@@ -13,6 +13,8 @@ Each tool is registered independently; a product that wants only one disables th
Both tools opt into concurrent scheduling because provider reads return content without mutating parent-agent state.
The normalized seam results are also the canonical tool values: `WebSearchResult` and `WebFetchResult`. Native renderers preserve the answer/source and fetched-body text below; provider search/body caps remain acquisition limits rather than presentation-only truncation.
## Config
| Key | Default | Meaning |

43
packages/web/tool-web/src/fetch.ts
View File

@@ -8,7 +8,6 @@
import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView } from '@deepseek-ai/dsh-tools'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import type { WebFetchBody, WebFetchResult } from '@deepseek-ai/dsh-web'
import { assertNever } from '@deepseek-ai/dsh-llm'
import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -91,16 +90,54 @@ export function applyWebFetchTool(ctx: Context, timeoutMs: number): void {
parameters: {
url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' },
},
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
url: { type: 'string', required: true },
statusCode: { type: 'integer', required: true },
body: {
required: true,
oneOf: [
{
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'html' },
content: { type: 'string', required: true },
},
},
{
type: 'object',
additionalProperties: false,
properties: {
kind: { type: 'string', required: true, const: 'text' },
content: { type: 'string', required: true },
},
},
],
},
truncated: { type: 'boolean', required: true },
},
},
render: (_args, value) => [{ type: 'text', text: formatFetchOutput(value) }],
},
timeoutMs,
// Provider reads do not mutate parent-agent state.
isConcurrencySafe: () => true,
async execute(args, exec): Promise<ContentBlock[]> {
async execute(args, exec) {
const input = parseFetchArgs(args)
const result = await ctx.web.fetch(
{ url: input.url },
exec.signal,
)
return [{ type: 'text', text: formatFetchOutput(result) }]
return {
url: result.url,
statusCode: result.statusCode,
body: { kind: result.body.kind, content: result.body.content },
truncated: result.truncated,
}
},
presentCall: presentFetchCall,
}))

39
packages/web/tool-web/src/search.ts
View File

@@ -8,7 +8,6 @@
import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView } from '@deepseek-ai/dsh-tools'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import type { WebSearchResult } from '@deepseek-ai/dsh-web'
import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -108,16 +107,50 @@ export function applyWebSearchTool(ctx: Context, maxResults: number, timeoutMs:
parameters: {
query: { type: 'string', required: true, description: 'The search query.' },
},
output: {
schema: {
type: 'object',
additionalProperties: false,
properties: {
content: { type: 'string' },
sources: {
type: 'array',
required: true,
items: {
type: 'object',
additionalProperties: false,
properties: {
url: { type: 'string', required: true },
title: { type: 'string' },
snippet: { type: 'string' },
publishedAt: { type: 'string' },
},
},
},
truncated: { type: 'boolean', required: true },
},
},
render: (_args, value) => [{ type: 'text', text: formatSearchOutput(value) }],
},
timeoutMs,
// Provider reads do not mutate parent-agent state.
isConcurrencySafe: () => true,
async execute(args, exec): Promise<ContentBlock[]> {
async execute(args, exec) {
const input = parseSearchArgs(args)
const result = await ctx.web.search(
{ query: input.query, maxResults },
exec.signal,
)
return [{ type: 'text', text: formatSearchOutput(result) }]
return {
...result.content !== undefined ? { content: result.content } : {},
sources: result.sources.map(source => ({
url: source.url,
...source.title !== undefined ? { title: source.title } : {},
...source.snippet !== undefined ? { snippet: source.snippet } : {},
...source.publishedAt !== undefined ? { publishedAt: source.publishedAt } : {},
})),
truncated: result.truncated,
}
},
presentCall: presentSearchCall,
}))

17
packages/web/tool-web/tests/integration.spec.ts
View File

@@ -12,7 +12,7 @@ import { AddressInfo } from 'node:net'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import ToolRegistry, { type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
import WebService from '@deepseek-ai/dsh-web'
import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
@@ -54,8 +54,7 @@ afterEach(async () => {
})
let counter = 0
type ToolResult = { isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }
function call(name: string, args: unknown): Promise<ToolResult> {
function call(name: string, args: unknown): Promise<ToolExecutionResult> {
return ctx.tools.execute({ callId: CallId(`call-${++counter}`), name, arguments: args })
}
@@ -63,7 +62,7 @@ describe('web_fetch integration over the real backend', () => {
it('fetches an html page and renders it to markdown', async () => {
const out = await call('web_fetch', { url: base })
expect(out.isError).toBe(false)
const text = out.content.map(b => b.text).join('')
const text = out.content.map(b => b.type === 'text' ? b.text : '').join('')
expect(text).toContain(`Fetched ${base}`)
expect(text).toContain('# Hello')
expect(text).toContain('World')
@@ -73,20 +72,20 @@ describe('web_fetch integration over the real backend', () => {
handler = (_req, res) => { res.writeHead(404, { 'content-type': 'text/plain' }); res.end('missing') }
const out = await call('web_fetch', { url: base })
expect(out.isError).toBe(false)
expect(out.content.map(b => b.text).join('')).toContain('HTTP 404')
expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('HTTP 404')
})
it('surfaces WEB_INVALID_URL as a structured tool error', async () => {
const out = await call('web_fetch', { url: 'ftp://example.com' })
expect(out.isError).toBe(true)
expect(out.error?.code).toBe('WEB_INVALID_URL')
expect(out.error?.info?.code).toBe('WEB_INVALID_URL')
})
it('surfaces a blocked cross-origin redirect as WEB_REDIRECT_BLOCKED', async () => {
handler = (_req, res) => { res.writeHead(302, { location: 'https://example.com/' }); res.end() }
const out = await call('web_fetch', { url: base })
expect(out.isError).toBe(true)
expect(out.error?.code).toBe('WEB_REDIRECT_BLOCKED')
expect(out.error?.info?.code).toBe('WEB_REDIRECT_BLOCKED')
})
})
@@ -98,7 +97,7 @@ describe('web_search integration over the real Exa provider', () => {
)))
const out = await call('web_search', { query: 'deepseek' })
expect(out.isError).toBe(false)
expect(out.content.map(b => b.text).join('')).toContain('[Result](https://result.test)')
expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('[Result](https://result.test)')
})
})
@@ -151,7 +150,7 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc
expect(out.isError).toBe(true)
// The outer tool-call deadline won: TOOL_TIMEOUT, owned by dsh-timeout-policy,
// NOT the provider's own WEB_FETCH_TIMEOUT (its 30s backstop never fired).
expect(out.error?.code).toBe('TOOL_TIMEOUT')
expect(out.error?.info?.code).toBe('TOOL_TIMEOUT')
const text = out.content.map(b => (b.type === 'text' ? b.text : '')).join('')
expect(text).toContain('timed out after 50ms')
})

33
packages/web/tool-web/tests/tool-web.spec.ts
View File

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import ToolRegistry, { type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
import WebService from '@deepseek-ai/dsh-web'
import type { WebSearchProvider, WebSearchResult } from '@deepseek-ai/dsh-web'
import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
@@ -30,7 +30,7 @@ async function mountTools(opts: {
webConfig?: ConstructorParameters<typeof WebService>[1]
search?: WebSearchProvider
fetchProvider?: import('@deepseek-ai/dsh-web').WebFetchProvider
} = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>>; call: (name: string, args: unknown) => Promise<{ isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }> }> {
} = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>>; call: (name: string, args: unknown) => Promise<ToolExecutionResult> }> {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
@@ -39,7 +39,7 @@ async function mountTools(opts: {
if (opts.fetchProvider) ctx.web.registerFetchProvider(opts.fetchProvider)
const fiber = await ctx.plugin(ToolWeb, opts.config ?? {})
let counter = 0
const call = (name: string, args: unknown) => ctx.tools.execute({ callId: CallId(`call-${++counter}`), name, arguments: args }) as never
const call = (name: string, args: unknown) => ctx.tools.execute({ callId: CallId(`call-${++counter}`), name, arguments: args })
return { ctx, fiber, call }
}
@@ -196,7 +196,7 @@ describe('tool-web registration', () => {
// No provider is registered: the schema stays visible and execution reports
// the structured unavailability instead.
const out = await call('web_search', { query: 'q' })
expect(out.error?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
expect(out.error?.info?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
await fiber.dispose()
})
@@ -214,12 +214,13 @@ describe('tool-web execution through the real registry', () => {
it('executes web_search and formats the result', async () => {
const result: WebSearchResult = {
content: 'answer', truncated: false,
sources: [{ url: 'https://a.test', title: 'A', snippet: 'snip' }],
sources: [{ url: 'https://a.test', title: 'A', snippet: 'snip', publishedAt: '2026-07-20' }],
}
const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider(result) })
const out = await call('web_search', { query: 'q' })
expect(out.isError).toBe(false)
expect(out.content.map(b => b.text).join('')).toContain('[A](https://a.test)')
expect(out.value).toEqual(result)
expect(out.content.map(b => b.type === 'text' ? b.text : '').join('')).toContain('[A](https://a.test)')
await fiber.dispose()
})
@@ -227,7 +228,7 @@ describe('tool-web execution through the real registry', () => {
const { fiber, call } = await mountTools()
const out = await call('web_search', { query: 'q' })
expect(out.isError).toBe(true)
expect(out.error?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
expect(out.error?.info?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
await fiber.dispose()
})
@@ -236,7 +237,7 @@ describe('tool-web execution through the real registry', () => {
ctx.web.registerSearchProvider({ id: 'other', available: () => available, search: () => Promise.resolve({ sources: [], truncated: false }) })
const out = await call('web_search', { query: 'q' })
expect(out.isError).toBe(true)
expect(out.error?.code).toBe('WEB_PROVIDER_AMBIGUOUS')
expect(out.error?.info?.code).toBe('WEB_PROVIDER_AMBIGUOUS')
await fiber.dispose()
})
@@ -244,7 +245,7 @@ describe('tool-web execution through the real registry', () => {
const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider({ sources: [], truncated: false }) })
const out = await call('web_search', { query: 123 })
expect(out.isError).toBe(true)
expect(out.error?.code).toBe('INVALID_ARGS')
expect(out.error?.info?.code).toBe('INVALID_ARGS')
await fiber.dispose()
})
@@ -267,6 +268,12 @@ describe('tool-web execution through the real registry', () => {
const controller = new AbortController()
const out = await ctx.tools.execute({ callId: CallId('fetch-1'), name: 'web_fetch', arguments: { url: 'https://a.test' }, signal: controller.signal })
expect(out.isError).toBe(false)
expect(out.value).toEqual({
url: 'https://a.test',
statusCode: 200,
body: { kind: 'text', content: 'ok' },
truncated: false,
})
// The model schema exposes no timeout: the tool forwards only the url; the
// tool-call budget is owned by dsh-timeout-policy over exec.signal.
expect(seen.request).toEqual({ url: 'https://a.test' })
@@ -289,6 +296,12 @@ describe('tool-web execution through the real registry', () => {
// No signal on the execution: the tool passes `undefined`.
const out = await ctx.tools.execute({ callId: CallId('fetch-2'), name: 'web_fetch', arguments: { url: 'https://a.test' } })
expect(out.isError).toBe(false)
expect(out.value).toEqual({
url: 'https://a.test',
statusCode: 200,
body: { kind: 'text', content: 'ok' },
truncated: false,
})
expect(seen.passedSignal).toBe(false)
expect(seen.signal).toBeUndefined()
await fiber.dispose()
@@ -333,7 +346,7 @@ describe('searchMaxResults is plugin config', () => {
const { fiber, call } = await mountTools({ config: { searchMaxResults: 2 }, webConfig: { searchProvider: 'stub-search' }, search: provider })
const out = await call('web_search', { query: 'q' })
expect(out.isError).toBe(false)
const body = out.content.map(b => b.text).join('')
const body = out.content.map(b => b.type === 'text' ? b.text : '').join('')
expect(body).toContain('https://s1.test')
expect(body).not.toContain('https://s2.test')
expect(body).toContain('Showing the first 2 sources.')