OpenCode to Takopi Event Mapping

This document describes how OpenCode JSON events are translated to Takopi's normalized event model. The OpenCode runner shipped in Takopi v0.5.0.

Event Translation

StartedEvent

Emitted on the first step_start event that contains a sessionID.

OpenCode: {"type":"step_start","sessionID":"ses_XXX",...}
Takopi:   StartedEvent(engine="opencode", resume=ResumeToken(engine="opencode", value="ses_XXX"))

ActionEvent

Tool usage is translated to action events. Note: opencode run --format json currently only emits tool_use events when the tool finishes (status == "completed"). Pending/running tool states exist in the schema but are not emitted by the CLI JSON stream.

Started phase (when tool is pending/running, if emitted by the JSON stream):

OpenCode: {"type":"tool_use","part":{"tool":"bash","state":{"status":"pending",...}}}
Takopi:   ActionEvent(engine="opencode", action=Action(kind="command"), phase="started")

Completed phase (when tool finishes):

OpenCode: {"type":"tool_use","part":{"tool":"bash","state":{"status":"completed","metadata":{"exit":0}}}}
Takopi:   ActionEvent(engine="opencode", action=Action(kind="command"), phase="completed", ok=True)

CompletedEvent

Emitted on step_finish with reason="stop" or on error events.

Success:

OpenCode: {"type":"step_finish","part":{"reason":"stop","tokens":{...},"cost":0.001}}
Takopi:   CompletedEvent(engine="opencode", ok=True, answer="<accumulated text>", usage={...})

If step_finish omits reason, Takopi treats a clean process exit as successful completion and emits CompletedEvent(ok=True) with the accumulated usage.

Error:

OpenCode: {"type":"error","error":{"name":"APIError","data":{"message":"API rate limit exceeded"}}}
Takopi:   CompletedEvent(engine="opencode", ok=False, error="API rate limit exceeded")

Tool Kind Mapping

OpenCode Tool	Takopi ActionKind
`bash`, `shell`	`command`
`edit`, `write`, `multiedit`	`file_change`
`read`	`tool`
`glob`	`tool`
`grep`	`tool`
`websearch`, `web_search`	`web_search`
`webfetch`, `web_fetch`	`web_search`
`todowrite`, `todoread`	`note`
`task`	`tool`
(other)	`tool`

Usage Accumulation

Token usage is accumulated across all step_finish events and reported in the final CompletedEvent.usage:

{
  "total_cost_usd": 0.001,
  "tokens": {
    "input": 22443,
    "output": 118,
    "reasoning": 0,
    "cache_read": 21415,
    "cache_write": 0
  }
}

2.6 KiB Raw Blame History