Module: Opencode::ToolPart

Defined in:
lib/opencode/tool_part.rb

Overview

Canonical shape of a tool part in an assistant reply.

A tool part starts ‘pending` and transitions through `running` to a terminal `completed` or `error`. The complete representation carries seven fields, all string-keyed so views read consistent keys whether the part came from a live streaming event or a post-stream message poll:

"type"     => "tool"
"tool"     => "edit"
"status"   => "completed"
"title"    => "Edited /INDEX.md"
"input"    => { ... }   # full args the agent passed, deep-stringified
"metadata" => { ... }   # tool-specific output: diff, preview, stdout, etc.
"output"   => "Edited successfully."
"error"    => "..."     # only when status == "error", truncated to 200 chars

The shape is produced two ways:

1. Opencode::Reply#apply_tool_state — live, mid-stream, merging
   incoming event state into an in-memory record (previous values
   survive when the new event omits a field).

2. Opencode::ResponseParser.build_tool_summary — post-stream, built
   fresh from a complete OpenCode message returned by
   /session/:id/message during recovery / final-exchange polling.

Existence reason: the two paths used to drift. ResponseParser stripped ‘metadata` and whitelisted `input` to a fixed key list, so `parts_json` saved on finalize had strictly less data than the streaming DOM had shown. The visible symptom was “I saw the diff while streaming and it disappeared when the turn finished”. This class is the single source of truth that prevents that drift.

Constant Summary collapse

MAX_ERROR_LEN = 
200
INVALID_TOOL = 
"invalid"

Class Method Summary collapse

Class Method Details

.from_message_part(part) ⇒ Object

Build a fresh canonical tool-part hash from one OpenCode message part (the shape that arrives through /session/:id/message). Used by ResponseParser for recovery and final-exchange polling.



46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/opencode/tool_part.rb', line 46

def from_message_part(part)
  state = state_of(part)
  build_canonical(
    tool: part[:tool] || part["tool"],
    status: state_value(state, :status),
    title: state_value(state, :title),
    input: state_value(state, :input),
    metadata: state_value(state, :metadata),
    output: state_value(state, :output),
    error: state_value(state, :error)
  )
end

.merge_streaming_state(record, part) ⇒ Object

Merge an incoming ‘message.part.updated` event state into an existing record. Used by Reply#apply_tool_state during streaming.

Fields the event omits (or that arrive empty) leave the record’s previous value intact. Mid-tool events are partial by design.

In addition to the canonical render fields (status, title, input, metadata, output, error), this also persists ‘callID` and `messageID` from the incoming state. Those identifiers are needed by downstream lookups (e.g. matching an ask-user reply event back to the originating tool part by callID) and would otherwise be silently dropped on the way into Reply.parts JSON.

Returns the (mutated) record for chaining.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/opencode/tool_part.rb', line 73

def merge_streaming_state(record, part)
  state = state_of(part)

  tool = part[:tool] || part["tool"]
  # Preserve original tool name if OpenCode later renames to "invalid"
  # mid-session — we want to keep rendering the original name.
  record["tool"] = tool if tool.present? && tool != INVALID_TOOL

  status = state_value(state, :status)
  record["status"] = status if status

  title = state_value(state, :title)
  record["title"] = title if title.present?

  input = state_value(state, :input)
  record["input"] = stringify_deep(input) if input.present?

  metadata = state_value(state, :metadata)
  record["metadata"] = stringify_deep(metadata) if metadata.present?

  output = state_value(state, :output)
  record["output"] = output if output.present?

  error = state_value(state, :error)
  record["error"] = error.to_s.truncate(MAX_ERROR_LEN) if error.present?

  # callID and messageID moved from state.* to the part's top level
  # somewhere in opencode v1.15.x. Read top-level first, fall back
  # to state.* for any older versions that may still be in flight.
  # Without this, merge_pending_question_into_existing_tool_part
  # (which searches @parts by callID) silently no-ops, and the
  # question form renders with no questions or routing IDs.
  call_id = part[:callID] || part["callID"] || state_value(state, :callID)
  record["callID"] = call_id if call_id.present?

  message_id = part[:messageID] || part["messageID"] || state_value(state, :messageID)
  record["messageID"] = message_id if message_id.present?

  record
end