feat: return typed values from Code Mode

2026-07-21 04:34:14 +08:00
parent 66c36e7325
commit c1d7b0df81
50 changed files with 2155 additions and 580 deletions
@@ -6,10 +6,10 @@
 */

 import { parse } from 'node:path'
-import { inspect } from 'node:util'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { CodeBindingFunction, CodeRunResult, CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { defineTool } from './schema.ts'
 import type { ToolDefinition, ToolRegistry } from './index.ts'
@@ -62,10 +62,7 @@ export class CodeRunFailedError extends HarnessError {
 */
 const SUMMARY_MAX_CHARS = 200

-/** Bounded inspect for rendering a program's completion value into the model-facing text. */
-const INSPECT_OPTIONS = { depth: 4, maxArrayLength: 100, maxStringLength: 10_000 } as const
-
-/** Join a result's text blocks; a non-text block becomes a placeholder (an MVP limitation, stated in the SDK instructions). */
+/** Join Native content for the bounded durable sub-dispatch summary; non-text blocks become diagnostic placeholders. */
 function textOf(content: ContentBlock[]): string {
  return content
    .map((block) => {
@@ -88,32 +85,26 @@ function summarize(text: string, cwd: string | undefined): string {
 }

 /**
- * JSON-normalize one binding call's argument into TWO independent parses of the same canonical
- * text: `dispatched` goes to the tool, `logged` to the `tool/code-dispatch` event — identical
- * by construction (the runtime's structured-clone boundary is wider than JSON; the session log
- * accepts only JSON), and separate objects, so a tool mutating its args can neither desync the
- * log from what was dispatched nor re-poison the append.
+ * Snapshot one binding call's argument as lossless JSON, then clone it into
+ * independent dispatch/log values so a tool mutation cannot desynchronize the
+ * durable event from what was called.
 */
 function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unknown } {
-  if (value === undefined) {
-    throw new Error('tool arguments must be JSON-serializable (call the tool with an arguments object, e.g. `{}`)')
-  }
-  let text: string | undefined
+  let snapshot: JsonValue | undefined
  try {
-    text = JSON.stringify(value)
+    snapshot = snapshotJsonValue(value) as JsonValue | undefined
  } catch (error: unknown) {
-    throw new Error(`tool arguments must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`)
+    throw new Error(`tool arguments must be lossless JSON: ${error instanceof Error ? error.message : String(error)}`)
  }
-  // JSON.stringify's lib type claims `string`, but a bare function or symbol
-  // root really yields `undefined` at runtime — the guard is live.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (text === undefined) throw new Error('tool arguments must be JSON-serializable (got a value JSON cannot represent)')
-  return { dispatched: JSON.parse(text) as unknown, logged: JSON.parse(text) as unknown }
+  if (snapshot === undefined) {
+    throw new Error('tool arguments must be lossless JSON (call the tool with an arguments object, e.g. `{}`)')
+  }
+  return { dispatched: structuredClone(snapshot), logged: structuredClone(snapshot) }
 }

 /** Render one present program completion value for the model-facing result text. */
 function renderValue(value: JsonValue): string {
-  return typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS)
+  return typeof value === 'string' ? value : JSON.stringify(value, null, 2)
 }

 /** The run_code result's `meta` payload (JSON-serializable; `presentResult` narrows it back). */
@@ -203,7 +194,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
      // would be narrowed away by control flow analysis.
      const runOver = (): boolean => runController.signal.aborted

-      const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise<unknown> => {
+      const binding = (name: string): CodeBindingFunction => async (rawArgs: unknown): Promise<JsonValue> => {
        if (runOver()) {
          throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`)
        }
@@ -234,7 +225,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
            isError: result.isError,
            resultSummary: summarize(text, exec.agent.session.header.cwd),
          })
-          return { text, isError: result.isError }
+          return result.isError
+            ? { isError: true as const, message: result.error.message }
+            : { isError: false as const, value: result.value }
        })
        // A budget expiry or outer cancel that lands while this call was in
        // flight already aborted the dispatch; stop the program now rather
@@ -242,11 +235,11 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
        if (runOver()) {
          throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`)
        }
-        // A failed tool call REJECTS — real code signals failure by throwing,
-        // so try/catch and Promise.all short-circuiting behave as models
-        // expect (the error text is the tool's model-facing result text).
-        if (outcome.isError) throw new Error(outcome.text)
-        return outcome.text
+        // The worker turns a binding rejection into ToolCallError and adds
+        // only the binding name. Native content and internal error metadata
+        // stay outside the program-facing failure contract.
+        if (outcome.isError) throw new Error(outcome.message)
+        return outcome.value
      }

      // Null-prototype + defineProperty, mirroring the worker-side namespace
@@ -283,12 +276,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
          const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : ''
          throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`)
        }
-        // The runtime seam is wider than JSON until PR 3 makes this boundary
-        // lossless. The registry immediately snapshots and rejects any value
-        // that does not satisfy the declared JSON output.
        return {
          logs: result.logs,
-          ...result.value !== undefined ? { result: result.value as JsonValue } : {},
+          ...result.value !== undefined ? { result: result.value } : {},
        }
      } finally {
        exec.signal?.removeEventListener('abort', onOuterAbort)
@@ -23,6 +23,7 @@ import { assertSupportedJsonSchema, validateJsonSchemaValue } from './json-schem
 import type { JsonSchemaNode } from './json-schema.ts'
 import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts'
 import { renderToolsSdk } from './ts-types.ts'
+import type { ToolSdkSchema } from './ts-types.ts'

 export {
  defineTool,
@@ -550,7 +551,7 @@ export class ToolRegistry extends Service {
        // Regenerate from the calling scope's visible tools in stable order.
        text: (context) => {
          this.requireCodeRuntime()
-          return renderToolsSdk(this.schemas(context.scope).filter(schema => schema.name !== RUN_CODE_NAME))
+          return renderToolsSdk(this.sdkSchemas(context.scope))
        },
      })
    }
@@ -815,6 +816,16 @@ export class ToolRegistry extends Service {
    return [...this.view(scope).visible.values()].map(definition => this.schemaOf(definition, true))
  }

+  /** Project visible callable tools onto the generated Code Mode SDK contract. */
+  private sdkSchemas(scope?: ScopeKey): ToolSdkSchema[] {
+    return [...this.view(scope).visible.values()]
+      .filter(definition => definition.name !== RUN_CODE_NAME)
+      .map((definition): ToolSdkSchema => ({
+        ...this.schemaOf(definition, true),
+        output: structuredClone(definition.output.schema),
+      }))
+  }
+
  /** Project one definition onto the model-facing schema fields. */
  private schemaOf(definition: ToolDefinition, detachParameters: boolean): ToolSchema {
    const { name, description, parameters } = definition
@@ -8,7 +8,13 @@

 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import { assertSupportedJsonSchema } from './json-schema.ts'
-import type { JsonSchemaScalar } from './json-schema.ts'
+import type { JsonSchemaNode, JsonSchemaScalar } from './json-schema.ts'
+
+/** Internal Code Mode projection: the model-facing schema plus the canonical output schema. */
+export interface ToolSdkSchema extends ToolSchema {
+  /** Validated canonical value returned by the tool binding. */
+  output: JsonSchemaNode
+}

 /** Property names that are valid bare TS identifiers; anything else is quoted. */
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
@@ -107,8 +113,8 @@ const SDK_INSTRUCTIONS = `## Writing code for run_code

 Pass \`run_code\` the body of an async TypeScript function (erasable syntax only — no \`enum\` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:

- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's text output as a string. Tool arguments must be JSON-serializable.
- A FAILED tool call rejects with an \`Error\` carrying the tool's error text — \`try/catch\` it to handle and continue.
+- Call tools as \`await tools.name(args)\` — quoted access for exotic names: \`tools["my-tool"](args)\`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
+- A FAILED tool call rejects with \`ToolCallError\`, whose \`toolName\` identifies the failed tool and whose \`message\` is human-readable — \`try/catch\` it to handle and continue.
 - Calls execute sequentially, even under \`Promise.all\`.
 - Emit results with \`return\` and/or \`console.log(...)\`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.

@@ -123,16 +129,24 @@ The available tools:`
 *   `run_code` itself).
 * @returns the complete section text.
 */
-export function renderToolsSdk(schemas: ToolSchema[]): string {
+export function renderToolsSdk(schemas: ToolSdkSchema[]): string {
  const sorted = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
-  const members: string[] = []
+  const argsMembers: string[] = []
+  const outputMembers: string[] = []
  for (const schema of sorted) {
-    members.push(...docLines(schema.description, 1))
-    members.push(`${pad(1)}${renderKey(schema.name)}(args: ${jsonSchemaToTs(schema.parameters, 1)}): Promise<string>;`)
+    argsMembers.push(...docLines(schema.description, 1))
+    argsMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.parameters, 1)};`)
+    outputMembers.push(`${pad(1)}${renderKey(schema.name)}: ${jsonSchemaToTs(schema.output, 1)};`)
  }
-  const declaration = members.length > 0
-    ? `declare const tools: {\n${members.join('\n')}\n}`
-    : 'declare const tools: {}'
+  const argsMap = `interface ToolArgsMap {${argsMembers.length > 0 ? `\n${argsMembers.join('\n')}\n` : ''}}`
+  const outputMap = `interface ToolOutputMap {${outputMembers.length > 0 ? `\n${outputMembers.join('\n')}\n` : ''}}`
+  const declaration = [
+    argsMap,
+    outputMap,
+    'type ToolName = keyof ToolOutputMap',
+    ['declare class ToolCallError extends Error {', '  readonly name: "ToolCallError";', '  readonly toolName: ToolName;', '}'].join('\n'),
+    ['declare const tools: {', '  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;', '}'].join('\n'),
+  ].join('\n\n')
  const jsonValue = 'type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }'
  return `${SDK_INSTRUCTIONS}\n\n\`\`\`ts\n${jsonValue}\n\n${declaration}\n\`\`\``
 }