DeepSeek Harness 工具结果、审计与 UI Presentation：一个 value 的多种投影

dsh-b4-result/
└── result-projection-demo.ts

node --import tsx E:/coding/rex-hugo/.tmp-research/dsh-b4-result/result-projection-demo.ts

const noteTool = defineTool({
  name: 'note',
  description: 'Return a structured note (canonical object value).',
  parameters: {
    title: { type: 'string', required: true, description: 'Note title' },
  },
  output: {
    schema: {
      type: 'object',
      additionalProperties: false,
      properties: {
        title: { type: 'string', required: true },
        lines: { type: 'array', required: true, items: { type: 'string' } },
      },
    },
    render: (_args, value) => {
      const v = value as { title: string; lines: string[] }
      return [{ type: 'text', text: `# ${v.title}\n${v.lines.map((l) => `- ${l}`).join('\n')}` }]
    },
    presentationMeta: (_args, value) => {
      const v = value as { title: string; lines: string[] }
      return { lineCount: v.lines.length, title: v.title }
    },
  },
  async execute(args) {
    return { title: args.title, lines: ['line one', 'line two'] }
  },
  presentCall(args): ToolCallView | undefined {
    return { card: 'generic', title: `Read note ${args.title}`, kind: 'read' }
  },
  presentResult(_args, result): ToolResultView | undefined {
    return { card: 'generic', title: `Note completed`, content: result.content }
  },
})

=== A: execution-local result (tools/result) ===
{"events":["result:success"],"isError":false,"value":{"title":"Demo","lines":["line one","line two"]},"content":[{"type":"text","text":"# Demo\n- line one\n- line two"}],"meta":{"lineCount":2,"title":"Demo"}}
=== A: UI views (pure projections) ===
{"callView":{"card":"generic","title":"Read note Demo","kind":"read"},"resultView":{"card":"generic","title":"Note completed","content":[{"type":"text","text":"# Demo\n- line one\n- line two"}]}}

=== C: durable session log (events) ===
{"type":"turn/start","seq":0,"data":{"turn":0}}
{"type":"tool/call","seq":1,"data":{"turn":0,"step":0,"callId":"b4-logged-call","name":"note","arguments":"{\"title\":\"Demo\"}"}}
{"type":"tool/result","seq":2,"data":{"turn":0,"step":0,"message":{...tool-result message...},"meta":{"lineCount":2,"title":"Demo"}}}
=== C: checks ===
{"callArgsIsRawString":true,"resultHasNoValueField":true,"transcriptHasNoToolCall":true,"transcriptRoleAndSource":[{"role":"user","source":{"kind":"tool","callId":"b4-logged-call"}}]}

/** Successful canonical tool execution, including its Native/model projection. */
export interface ToolExecutionSuccess {
  readonly isError: false
  /** Execution-local canonical value; deliberately omitted from durable events. */
  readonly value: JsonValue
  readonly content: ContentBlock[]
  readonly error?: never
  readonly meta?: JsonValue
  readonly additionalContexts?: UserMessage[]
  /** The agent loop stops after committing this successful result batch. */
  readonly concludesTurn?: true
}

/** Failed canonical tool execution; failures never carry a successful value. */
export interface ToolExecutionFailure {
  readonly isError: true
  readonly error: ToolFailure
  readonly value?: never
  readonly content: ContentBlock[]
  readonly meta?: JsonValue
  readonly additionalContexts?: UserMessage[]
  readonly concludesTurn?: never
}

/** The discriminated, execution-local outcome of one tool call. */
export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure

  /**
   * The model requested one tool invocation: `name` with the raw `arguments`
   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
   * call with its `tool/result`.
   */
  'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
  /**
   * A completed tool call's model-facing result, optional internal failure
   * identity, and optional tool-private `meta` presentation payload. `meta` is
   * opaque to the core (the producing tool owns its shape and reads it back in
   * `presentResult`) but MUST be JSON-serializable: `Session.append`
   * runtime-validates all event data with `isJsonValue`, so a non-serializable
   * `meta` is rejected at the source, and the durable log reproduces the
   * identical card on replay. Absent
   * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time
   * contextual diff here).
   */
  'tool/result': {
    turn: number
    step: number
    message: ToolResultMessage
    error?: { name: string; code: string }
    meta?: JsonValue
  }

    case 'tool/result': {
      return event.data.message
    }

/**
 * Post-dispatch decision: accept, replace one projection, attach context for the
 * next request, or block by turning corrective feedback into an error result.
 */
export type PostToolDecision =
  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: UserMessage[] }
  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: UserMessage[] }
  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: UserMessage[] }

=== B1: accept content replace ===
{"events":["result:success"],"isError":false,"value":{"title":"Demo","lines":["line one","line two"]},"content":[{"type":"text","text":"redacted summary"}],"meta":{"lineCount":2,"title":"Demo"}}
=== B2: accept value replace ===
{"events":["result:success"],"isError":false,"value":{"title":"Replaced","lines":["x"]},"content":[{"type":"text","text":"# Replaced\n- x"}],"meta":{"lineCount":1,"title":"Replaced"}}
=== B3: block with feedback ===
{"events":["result:error"],"isError":true,"content":[{"type":"text","text":"blocked by result policy"}],"error":{"message":"blocked by result policy"}}
=== B4: value replace on failed result ===
{"events":["result:error"],"isError":true,"content":[{"type":"text","text":"Error: tools/post-execute cannot replace the value of a failed result"}],"error":{"message":"tools/post-execute cannot replace the value of a failed result"}}

  /**
   * Optional: how to present the PENDING state of one call in a UI, derived from
   * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
   * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
   * or `undefined` (or omit the method) to fall back to a generic presentation
   * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
   * call it during live streaming AND a session-log replay, so it must depend
   * only on `args`.
   */
  presentCall?(args: unknown): ToolCallView | undefined
  /**
   * Optional: how to present the COMPLETED state, given the same `args` and the
   * durable result projection (`content`, failure state, and optional `meta`). Returns a
   * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
   * pending title and render the raw result content. Pure and side-effect-free
   * for the same replay reason.
   */
  presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined