|
| 1 | +# Tool Result Envelope |
| 2 | + |
| 3 | +This document defines the target tool-result protocol. The current implementation adds the envelope to Agent tool `rawData.toolResult` at the ToolPresenter boundary while keeping legacy `rawData.content` unchanged for provider-facing model context. |
| 4 | + |
| 5 | +## Shape |
| 6 | + |
| 7 | +```ts |
| 8 | +type AgentToolResult = { |
| 9 | + ok: boolean |
| 10 | + summary: string |
| 11 | + data?: unknown |
| 12 | + meta?: { |
| 13 | + truncated?: boolean |
| 14 | + nextOffset?: number |
| 15 | + offloadPath?: string |
| 16 | + tokenEstimate?: number |
| 17 | + resultCount?: number |
| 18 | + } |
| 19 | + error?: { |
| 20 | + code: string |
| 21 | + message: string |
| 22 | + recoverable?: boolean |
| 23 | + } |
| 24 | +} |
| 25 | +``` |
| 26 | +
|
| 27 | +## Success |
| 28 | +
|
| 29 | +Successful tools set `ok: true`, provide a short model-readable `summary`, and put structured payloads in `data`. |
| 30 | +
|
| 31 | +Examples: |
| 32 | +
|
| 33 | +```json |
| 34 | +{ |
| 35 | + "ok": true, |
| 36 | + "summary": "Found 12 matches in 3 files.", |
| 37 | + "data": { |
| 38 | + "matches": [] |
| 39 | + }, |
| 40 | + "meta": { |
| 41 | + "resultCount": 12, |
| 42 | + "truncated": false |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | +
|
| 47 | +## Errors |
| 48 | +
|
| 49 | +Failed tools set `ok: false`, provide a short summary, and include a stable `error.code`. |
| 50 | +
|
| 51 | +```json |
| 52 | +{ |
| 53 | + "ok": false, |
| 54 | + "summary": "Invalid arguments for edit.", |
| 55 | + "error": { |
| 56 | + "code": "INVALID_ARGUMENT", |
| 57 | + "message": "oldText is required.", |
| 58 | + "recoverable": true |
| 59 | + } |
| 60 | +} |
| 61 | +``` |
| 62 | +
|
| 63 | +## Truncation |
| 64 | +
|
| 65 | +Tools that return partial data set `meta.truncated: true`. If the same tool can continue from a position, it also sets `meta.nextOffset`. |
| 66 | +
|
| 67 | +Renderer display: |
| 68 | +
|
| 69 | +- Show the `summary` in compact cards. |
| 70 | +- Show truncation and next-page affordances from `meta`. |
| 71 | +- Keep `data` available for rich views, but do not require the renderer to parse provider-facing prose. |
| 72 | +
|
| 73 | +Model-readable behavior: |
| 74 | +
|
| 75 | +- Always include the `summary`. |
| 76 | +- Include enough `data` for the next likely model step. |
| 77 | +- Prefer pagination over returning huge blobs. |
| 78 | +
|
| 79 | +## Offload |
| 80 | +
|
| 81 | +Large outputs may be written to an offload file and represented by `meta.offloadPath`. |
| 82 | +
|
| 83 | +Rules: |
| 84 | +
|
| 85 | +- `summary` must explain what was offloaded. |
| 86 | +- `data` may contain a preview. |
| 87 | +- The offload path must be readable by the canonical `read` tool when the session has access. |
| 88 | +
|
| 89 | +## Batch Results |
| 90 | +
|
| 91 | +When multiple tool calls are executed in one model round: |
| 92 | +
|
| 93 | +- Preserve the model's original tool-call order in returned tool messages. |
| 94 | +- Each tool message contains one envelope. |
| 95 | +- Parallel execution must not reorder renderer updates or provider-facing tool result messages. |
| 96 | +
|
| 97 | +## Renderer Contract |
| 98 | +
|
| 99 | +The renderer should treat the envelope as the stable display protocol: |
| 100 | +
|
| 101 | +- `ok` controls success/error styling. |
| 102 | +- `summary` powers the collapsed text. |
| 103 | +- `data` feeds rich tool-specific rendering. |
| 104 | +- `meta` handles pagination, truncation, and offload UI. |
| 105 | +- `error` provides retry hints and diagnostics. |
| 106 | +
|
| 107 | +## Migration Notes |
| 108 | +
|
| 109 | +1. Canonical Agent tools now receive an envelope through `rawData.toolResult` unless a tool already provides a specialized `toolResult`. |
| 110 | +2. Legacy raw tool output remains available through `rawData.content`. |
| 111 | +3. Renderer cards can migrate to the envelope without changing provider-facing tool messages. |
| 112 | +4. MCP passthrough tools and external servers can be extended after renderer support lands. |
0 commit comments