feat: add canonical typed tool outputs

docs/user/develop/basic/index.i18n.yaml

@@ -2,5 +2,5 @@
 # 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
-index.md: d7d657ff7b8cb9001dd5e9c3af658a7a3c45b5b7
-index.zh.md: 7a134f7aaed470b87ee8ca8978dd39593de2651b
+index.md: 5a9f8dfb8f2d87dfbd2ba30b4d09d002ae9b635c
+index.zh.md: 08aca87cbc02d1b0dfbe6fe2d92b3f6e87075097

docs/user/develop/basic/index.md

@@ -138,8 +138,12 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }

docs/user/develop/basic/index.zh.md

@@ -138,8 +138,12 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }

docs/user/develop/basic/tool.i18n.yaml

@@ -2,5 +2,5 @@
 # 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
-tool.md: 17adbfc5f7eb804856dfe39b4d2b4a65374b6414
-tool.zh.md: 8857e16ca836dfa5b158a68581bd3c715dcb1ac5
+tool.md: 7b211cfef54306f7c316dc08da1df759dcbf1b06
+tool.zh.md: 214b35b28de0c647737bc8297b13b4997947b52e

docs/user/develop/basic/tool.md

@@ -20,9 +20,13 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'The name to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       // args is inferred as { name: string }.
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
@@ -107,33 +111,45 @@ export const tool = defineTool({
   name: 'example',
   description: 'Return an example result.',
   parameters: {},
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args: inferred from parameters
     // exec: ToolExecution context
 
-    // Return a ContentBlock array.
+    // Return the value declared by output.schema.
     void args
     void exec
-    return [{ type: 'text', text: 'result here' }]
+    return 'result here'
   },
 })
 ```
 
 ### Return value
 
-`execute` returns a `ContentBlock[]` that becomes the tool result visible to the model:
+`execute` returns the lossless JSON value declared by `output.schema`. `output.render(args, value)` separately turns that validated value into the Native/model-facing content:
 
 ```ts ignore-check
-// Text result
-return [{ type: 'text', text: 'file content here...' }]
-
-// Multiple blocks
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+output: {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      path: { type: 'string', required: true },
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.content }],
+},
+async execute(args) {
+  return { path: args.path, content: await readFile(args.path, 'utf8') }
+}
 ```
 
+The canonical value is available to execution-time programmatic callers and is not persisted in `tool/result`; the rendered content and optional `presentationMeta` are the replayable projections. A body value that does not satisfy the schema, or is not lossless JSON, becomes an `INVALID_TOOL_OUTPUT` failure.
+
 ### Argument validation
 
 Before calling `execute`, `defineTool` validates model-generated arguments. Invalid input raises `ToolArgsError`; the framework turns it into an `isError` result so the model can correct its call.
@@ -148,6 +164,10 @@ A tool can define UI presentation methods for terminal and ACP clients:
 defineTool({
   name: 'bash',
   // ...
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   presentCall(args) {
     return {
       card: 'terminal',
@@ -196,13 +216,24 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Directory path' },
       extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          files: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
+    },
     async execute(args) {
       const entries = await readdir(args.path, { withFileTypes: true })
       let files = entries.filter(e => e.isFile())
       if (args.extension) {
         files = files.filter(f => f.name.endsWith(args.extension!))
       }
-      return [{ type: 'text', text: `Found ${files.length} files.` }]
+      return { count: files.length, files: files.map(file => file.name) }
     },
   }))
 }

docs/user/develop/basic/tool.zh.md

@@ -20,9 +20,13 @@ export function apply(ctx: Context) {
     parameters: {
       name: { type: 'string', required: true, description: 'The name to greet' },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       // args is inferred as { name: string }.
-      return [{ type: 'text', text: `Hello, ${args.name}!` }]
+      return `Hello, ${args.name}!`
     },
   }))
 }
@@ -107,33 +111,45 @@ export const tool = defineTool({
   name: 'example',
   description: 'Return an example result.',
   parameters: {},
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   async execute(args, exec) {
     // args: inferred from parameters
     // exec: ToolExecution context
 
-    // Return a ContentBlock array.
+    // Return the value declared by output.schema.
     void args
     void exec
-    return [{ type: 'text', text: 'result here' }]
+    return 'result here'
   },
 })
 ```
 
 ### 返回值
 
-`execute` 必须返回一个 `ContentBlock[]`，告诉模型 tool 的执行结果：
+`execute` 返回由 `output.schema` 声明的无损 JSON 值。`output.render(args, value)` 会将经过校验的值另外转换为 Native／模型可见的内容：
 
 ```ts ignore-check
-// Text result
-return [{ type: 'text', text: 'file content here...' }]
-
-// Multiple blocks
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+output: {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      path: { type: 'string', required: true },
+      content: { type: 'string', required: true },
+    },
+  },
+  render: (_args, value) => [{ type: 'text', text: value.content }],
+},
+async execute(args) {
+  return { path: args.path, content: await readFile(args.path, 'utf8') }
+}
 ```
 
+执行期间的程序化调用方可以使用规范值，但 `tool/result` 不会持久化该值；渲染后的内容和可选的 `presentationMeta` 才是可回放的投影。工具主体返回的值若不满足 schema 或不是无损 JSON，就会变为 `INVALID_TOOL_OUTPUT` 失败。
+
 ### 参数校验
 
 `defineTool` 在调用 `execute` 之前会自动校验模型生成的参数。如果参数不合法，会抛出 `ToolArgsError`，框架将其转换为 `isError` 结果返回给模型，让模型自行修正。
@@ -148,6 +164,10 @@ Tool 可以定义 UI 渲染方法，用于在终端或 ACP 客户端中展示 to
 defineTool({
   name: 'bash',
   // ...
+  output: {
+    schema: { type: 'string' },
+    render: (_args, value) => [{ type: 'text', text: value }],
+  },
   presentCall(args) {
     return {
       card: 'terminal',
@@ -196,13 +216,24 @@ export function apply(ctx: Context) {
       path: { type: 'string', required: true, description: 'Directory path' },
       extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          count: { type: 'integer', required: true },
+          files: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
+    },
     async execute(args) {
       const entries = await readdir(args.path, { withFileTypes: true })
       let files = entries.filter(e => e.isFile())
       if (args.extension) {
         files = files.filter(f => f.name.endsWith(args.extension!))
       }
-      return [{ type: 'text', text: `Found ${files.length} files.` }]
+      return { count: files.length, files: files.map(file => file.name) }
     },
   }))
 }

docs/user/develop/practice/index.i18n.yaml

@@ -2,5 +2,5 @@
 # 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
-index.md: 0261b49b071167f7c2a33f78bbc1959cc6f1879f
-index.zh.md: 5819344430fcbde31bf825e9815120983e44e3f6
+index.md: e197d499d7f5bd9911ea60bebf584251cd4ed915
+index.zh.md: 8b8d08f9d0c6d0ca8d95fbaa3281c98b7a600fe4

docs/user/develop/practice/index.md

@@ -132,9 +132,13 @@ export function apply(ctx: Context) {
     parameters: {
       input: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       const result = await ctx.myCap.execute({ input: args.input })
-      return [{ type: 'text', text: result.output }]
+      return result.output
     },
   }))
 }

docs/user/develop/practice/index.zh.md

@@ -132,9 +132,13 @@ export function apply(ctx: Context) {
     parameters: {
       input: { type: 'string', required: true },
     },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
     async execute(args) {
       const result = await ctx.myCap.execute({ input: args.input })
-      return [{ type: 'text', text: result.output }]
+      return result.output
     },
   }))
 }