Skip to slide
068 / 221

CH 05 · Context Engineering and Memory · 08/18

Read as one page

Real code: OpenCode caps every tool result at the boundary

OpenCode is a full coding-agent harness. In its session runner, every local tool result passes through ToolOutput.truncate on the way into the session (step.ts lines 126 to 128: run the tool, then toolOutput.truncate). It caps the payload, says there is more, and leaves a path to the rest. OpenCode is built on the Effect library, so read yield* as "wait for this step", much like await.

const truncate = Effect.fnUntraced(function* (result: Result) {
  if (result.metadata?.truncated !== undefined) return result      // [1]
  const content = result.content
  const text = content.flatMap((item) => (item.type === "text" ? [item.text] : [])).join("\n")
  const limits = state.get()
  const lines = text.split("\n")
  if (text.endsWith("\n")) lines.pop()
  const totalBytes = Buffer.byteLength(text, "utf-8")
  if (lines.length <= limits.maxLines && totalBytes <= limits.maxBytes)   // [2]
    return { ...result, metadata: { ...result.metadata, truncated: false } }

  const kept: string[] = []
  let bytes = 0
  for (const line of lines.slice(0, limits.maxLines)) {
    const size = Buffer.byteLength(line, "utf-8") + (kept.length > 0 ? 1 : 0)
    if (bytes + size > limits.maxBytes) break                      // [3]
    kept.push(line)
    bytes += size
  }
  const file = path.join(directory, fileName())
  yield* fs.ensureDir(directory).pipe(Effect.orDie)
  yield* fs.writeFileString(file, text).pipe(Effect.orDie)         // [4]
  const shown = kept.length > 0 ? `lines 1-${kept.length}` : "0 lines"
  const marker = `[showing ${shown} of ${lines.length}; full output saved to ${file}]` // [5]
  // ... (22 lines: rebuild the content parts so they hold only the kept text, then add the marker)
  return {
    ...result,
    content: bounded,
    metadata: { ...result.metadata, truncated: true, outputPath: file },   // [6]
  }
})

Source: anomalyco/opencode, packages/core/src/tool-output.ts (MIT)

What to notice

  1. [1] If metadata.truncated is already true or false, this function returns the result unchanged. The shell tool sets that flag itself, through ShellResult.metadata. It keeps the tail of the command and points at its own log.
  2. [2] The fast path. Output under both limits (2,000 lines and 50 KiB by default, adjustable through the tool_output setting) goes through unchanged, marked truncated: false.
  3. [3] Whole lines are kept from the top until either limit would be crossed, so the model never sees half a line. Buffer.byteLength counts bytes.
  4. [4] The full text is written first, to a file named tool_<id> under OpenCode's data directory. Those files are deleted after seven days.
  5. [5] The marker names the kept lines and the path of the full output, which still includes the lines already shown. That path is outside the workspace, so the read tool must be allowed to open an external directory.
  6. [6] truncated and outputPath go into the metadata, so later code can tell a cut happened.

A stored tool result is sent again on later calls, so one oversized log taxes every turn after it. A naive cut (the first N characters, then nothing) hides the loss and throws the rest away. Here the model sees the cut, and the full text is one file read away. Choosing which fields matter still belongs inside each tool: this layer does not know their shape.

Read it yourself: open packages/core/test/tool-output.test.ts. "writes oversized text and returns a bounded preview" shows the marker. "skips results that report a truncation state" shows that truncated: false is left alone too. Then answer from the loop: a single 60 KiB line under the default limits leaves the model the marker and nothing else. The shell's own tail is in packages/core/src/shell.ts. ShellResult.metadata in packages/core/src/shell/result.ts copies that boolean onto metadata.truncated.

Finished this idea?

Your learning progress stays in this browser.