OpenACP/docs/dev/message-format-reference.md
Rex DEV ce15c30d2b
fix(formatting): always show plan regardless of verbosity (#81)
* fix(formatting): wire rawInput + display* fields through both adapters

- Add rawInput, displaySummary, displayTitle, displayKind to Discord
  adapter tool call/update meta construction (were missing after reset)
- Add displaySummary, displayTitle, displayKind to Telegram adapter
  (rawInput was already present)
- Update existing tests to pass "high" for full-detail assertions
  (default changed to "medium" which returns compact output)

Entire-Checkpoint: e0737b6c7432

* fix(formatting): preserve display* on tool edit, cleanup duplication

- Store displaySummary/displayTitle/displayKind in ToolCallState
  so they survive from tool_call to tool_call_update edit
- Merge with ?? fallback: update fields take precedence over stored
- Telegram formatToolUpdate delegates to formatToolCall (like Discord)
- Remove unused STATUS_ICONS/KIND_ICONS imports from platform formatters

Entire-Checkpoint: 5afc4b23e3ed

* fix(formatting): always show plan regardless of verbosity level

Plan messages were hidden when displayVerbosity was set to "low".
Removed "plan" from HIDDEN_ON_LOW set and added low verbosity
handling in Discord/Telegram formatPlan to show summary count.

Entire-Checkpoint: 25f61b05a8f3

* fix(telegram): handle low verbosity in PlanCard formatPlanCard

PlanCard uses its own formatPlanCard() instead of the shared
formatPlan() from formatting.ts. The low verbosity case was
missing, causing it to fall through to high detail mode.

Entire-Checkpoint: ad8701fddbdc

* fix(formatting): plan always shows full entries regardless of verbosity

Remove verbosity branching from formatPlan โ€” plan always renders
the full entry list with status icons. Previously low/medium showed
only a summary count. Also fix Telegram PlanCard formatPlanCard
which had the same issue.

Entire-Checkpoint: ec946aa88fa1

* docs: add consolidated tool card design spec

Entire-Checkpoint: 41ede6b49d70

* docs: update tool card spec with review decisions (v2)

Entire-Checkpoint: c49386e3cfc2

* docs: update tool card verbosity tiers โ€” full list on all levels (v3)

Entire-Checkpoint: 075290d470e5

* docs: viewer links shown on all verbosity levels (v4)

Entire-Checkpoint: cbc26f5db2c4

* docs: add grep to noise filter rules

Entire-Checkpoint: 2b8dbb47e518

* docs: add consolidated tool card implementation plan

Entire-Checkpoint: 2baf2ed990bc

* feat(formatting): add grep to noise filter, change glob to hide

Entire-Checkpoint: 5d880ff51b85

* feat: add ToolCardState for consolidated tool card

Entire-Checkpoint: 31469436e6e5

* feat(discord): add renderToolCard formatter

Entire-Checkpoint: 1c21fec9dc31

* feat(telegram): add renderToolCard formatter

Add renderToolCard() to Telegram formatting that renders tool card snapshots
as HTML (bold headers, escaped labels, anchor viewer links, plan section,
usage footer). Add corresponding tests covering all output behaviors.

Entire-Checkpoint: 643c26444277

* feat(discord): wire ToolCard into ActivityTracker

Entire-Checkpoint: 018413b14f8d

* feat(telegram): wire ToolCard into ActivityTracker

Entire-Checkpoint: 22d59ca7c6f5

* refactor: delete deprecated platform ToolCallTrackers

Entire-Checkpoint: c5c4b3ac6239

* docs: update message format reference for consolidated tool card

Entire-Checkpoint: f211f739e728

* fix(tool-card): guard empty render, fix falsy usage check, make destroy terminal

- Skip send/edit when renderToolCard returns empty string (prevents API
  errors for sessions that end with no tool calls)
- Fix tokensUsed check from falsy to != null in both Discord and Telegram
  renderToolCard so tokensUsed=0 is not silently hidden
- Set finalized=true in ToolCardState.destroy() to make it terminal and
  prevent post-destroy mutations

Entire-Checkpoint: de056e6643c9

* fix(tool-card): put viewer links on new line for better readability

Entire-Checkpoint: 4ce2b139ecbd

* fix(tool-card): always show usage stats, use formatUsage with verbosity

- sendUsage() no longer skips when no tool content โ€” standalone usage
  message is sent for text-only responses
- renderToolCard uses formatUsage() so progress bar and cost appear
  according to verbosity (high verbosity shows progress bar + %)
- Separator line only rendered when there are tool entries above it
- Update test to assert standalone usage message behavior

Entire-Checkpoint: b55f5bc768c0

* fix(telegram): edit thinking message instead of sending new ones

Entire-Checkpoint: 4f47ffddcdb4

* fix(formatting): recognize Terminal tool name, show command in summary

Entire-Checkpoint: 1c66813043ae

* fix(formatting): show play icon for Terminal tool with no command

Entire-Checkpoint: 46c93d01eee8

---------

Co-authored-by: Leo Agent <bigbearman078@mgail.com>
2026-03-27 18:30:31 +07:00

14 KiB
Raw Permalink Blame History

Message Format Reference

How each message type is formatted across verbosity levels and platforms.


1. Visibility Matrix

Which message types are shown at each verbosity level:

Message Type Low Medium High
text Show Show Show
thought Hidden Show Show
tool_call Show* Show Show
tool_update Show* Show Show
plan Show Show Show
usage Hidden Show Show
error Show Show Show
attachment Show Show Show
system_message Show Show Show
session_end Show Show Show
mode_change Show Show Show
config_update Show Show Show
model_update Show Show Show
user_replay Show Show Show
resource Show Show Show
resource_link Show Show Show

* tool_call has noise filtering: ls is hidden (except high), directory reads are hidden (except high), glob is collapsed on low.


2. ToolCall Formatting

2.1 Tool-Specific Formats (formatToolSummary โ€” medium/high)

Tool Format Example
read ๐Ÿ“– Read {filePath}{(N lines)} ๐Ÿ“– Read src/main.ts (50 lines)
edit โœ๏ธ Edit {filePath} โœ๏ธ Edit src/main.ts
write ๐Ÿ“ Write {filePath} ๐Ÿ“ Write src/new-file.ts
bash โ–ถ๏ธ Run: {command} โ–ถ๏ธ Run: pnpm test
grep ๐Ÿ” Grep "{pattern}" in {path} ๐Ÿ” Grep "TODO" in src/
glob ๐Ÿ” Glob {pattern} ๐Ÿ” Glob **/*.test.ts
agent ๐Ÿง  Agent: {description} ๐Ÿง  Agent: Find message formatting code
webfetch ๐ŸŒ Fetch {url} ๐ŸŒ Fetch https://example.com/api
websearch ๐ŸŒ Search "{query}" ๐ŸŒ Search "vitest mock guide"
(default) ๐Ÿ”ง {name} ๐Ÿ”ง CustomTool

command truncated at 60 chars. description, url, query also truncated at 60 chars.

2.2 Tool-Specific Formats (formatToolTitle โ€” low)

Tool Format Example
read {filePath} src/main.ts
edit {filePath} src/main.ts
write {filePath} src/new-file.ts
bash {command} pnpm test
grep "{pattern}" in {path} "TODO" in src/
glob {pattern} **/*.test.ts
agent {description} Find message formatting code
webfetch {url} https://example.com/api
websearch {query} vitest mock guide
(default) {name} CustomTool

2.3 Icon Resolution (resolveToolIcon)

Priority: status icon > displayKind/kind icon > ๐Ÿ”ง default.

Status Icons:

Status Icon
pending โณ
in_progress ๐Ÿ”„
completed โœ…
failed โŒ
cancelled ๐Ÿšซ
running ๐Ÿ”„
done โœ…
error โŒ

Kind Icons:

Kind Icon
read ๐Ÿ“–
edit โœ๏ธ
write โœ๏ธ
delete ๐Ÿ—‘๏ธ
execute โ–ถ๏ธ
command โ–ถ๏ธ
bash โ–ถ๏ธ
search ๐Ÿ”
web ๐ŸŒ
fetch ๐ŸŒ
agent ๐Ÿง 
think ๐Ÿง 
install ๐Ÿ“ฆ
move ๐Ÿ“ฆ
other ๐Ÿ› ๏ธ

2.4 Noise Filtering

Rule Action Effect
Tool name is ls hide Hidden on low/medium
Read on directory (path ends /) hide Hidden on low/medium
Tool name is glob hide Hidden on low/medium
Tool name is grep hide Hidden on low/medium

3. Plan Formatting

Source data:

{ type: "plan", entries: PlanEntry[] }
// PlanEntry = { content: string; status: "pending" | "in_progress" | "completed"; priority }

Note: Plan is now rendered inline within the Consolidated Tool Card (see Section 9), positioned between completed and running tools. It is no longer a standalone message.

Per verbosity:

Verbosity Output
Low Full list with status icons
Medium Full list with status icons
High Full list with status icons

Regardless of verbosity, plan always shows all entries in full (no summary collapse).

Example:

๐Ÿ“‹ Plan
โœ… 1. Set up project structure
โœ… 2. Create database schema
๐Ÿ”„ 3. Implement API endpoints
โฌœ 4. Write tests
โฌœ 5. Deploy to staging

Plan status icons:

Status Base/Discord Telegram
completed โœ… โœ…
in_progress ๐Ÿ”„ ๐Ÿ”„
pending โฌœ โฌœ

Note: PlanEntry.priority exists in the type but is not rendered anywhere.


4. Usage Formatting

Source data:

{ type: "usage", metadata: { tokensUsed, contextSize, cost } }
Verbosity Output
Low Hidden
Medium ๐Ÿ“Š 12.5K tokens ยท $0.05
High ๐Ÿ“Š 12.5K / 200K tokens + progress bar + ๐Ÿ’ฐ $0.05

High verbosity example:

๐Ÿ“Š 12,500 / 200,000 tokens
โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 6%
๐Ÿ’ฐ $0.05

Shows โš ๏ธ instead of ๐Ÿ“Š when usage >= 85% (Discord/Telegram).


5. Other Message Types

Type Format
text Raw text (plain/markdown/html per platform)
thought Hidden on low. Shown on medium/high.
error โŒ Error: {text}
system_message Raw text
session_end Done ({reason})
mode_change ๐Ÿ”„ Mode: {modeId}
config_update โš™๏ธ Config updated
model_update ๐Ÿค– Model: {modelId}
resource ๐Ÿ“„ Resource: {name} ({uri})
resource_link ๐Ÿ”— {name}: {uri}
notification {emoji} {sessionName}\n{summary}

Notification emojis:

Type Icon
completed โœ…
error โŒ
permission ๐Ÿ”
input_required ๐Ÿ’ฌ
budget_warning โš ๏ธ
(default) โ„น๏ธ

6. Platform-Specific Differences

6.1 Discord (Markdown)

{icon} **{label}**
[View filename](file_url)
[View diff โ€” filename](diff_url)

// High only:
**Input:**
```json
{rawInput}

Output:

{content}

- Max content: 500 chars (input/output in high mode)
- Max message: 1800 chars per chunk (splitMessage)
- Viewer links always shown

### 6.2 Telegram (HTML)

```html
{icon} <b>{escaped_label}</b>
๐Ÿ“„ <a href="url">View filename</a>
๐Ÿ“ <a href="url">View diff โ€” filename</a>

<!-- High only: -->
<b>Input:</b>
<pre>{escaped_input}</pre>
<b>Output:</b>
<pre>{escaped_content}</pre>
  • Max content: 3800 chars (input/output in high mode)
  • Max message: 3800 chars per chunk (splitMessage)
  • HTML escaping applied (&, <, >)
  • Markdown-to-HTML conversion for links, bold, italic, code

6.3 Slack (Block Kit)

Type Block Type Format
text section mrkdwn text (markdown converted)
thought context ๐Ÿ’ญ _{text}_ (500 char limit)
tool_call context ๐Ÿ”ง `{name}` + input JSON code block
tool_update context {icon} \{name}` โ€” {status}`
plan divider + section ๐Ÿ“‹ *Plan*\n{text}
usage context ๐Ÿ“Š in: X ยท out: Y ยท $Z
error section โš ๏ธ *Error:* {text}
session_end divider + context โœ… Session ended โ€” {reason}

Known issue: Slack Plan uses message.text (empty string) instead of metadata.entries. Plan content will be blank.


7. Data Flow

AgentEvent (ACP subprocess)
    โ†“
MessageTransformer.transform()         โ†’ OutgoingMessage { type, text, metadata }
    โ†“
ToolCardState (consolidation buffer)    โ†’ buffers tool_call + tool_update events
    โ†“
ToolCardRenderer.render()               โ†’ single consolidated embed per prompt turn
    โ†“
MessagingAdapter.sendMessage()
    โ†“
shouldDisplay(content, verbosity)       โ†’ noise filter + HIDDEN_ON_LOW check
    โ†“
dispatchMessage(content, verbosity)     โ†’ switch(content.type)
    โ†“
handleXxx()                             โ†’ platform-specific handler
    โ†“
renderer.renderXxx() / formatXxx()      โ†’ RenderedMessage { body, format }
    โ†“
Platform send (Telegram HTML, Discord MD, Slack Blocks)

Consolidated Tool Card: Single auto-updating embed/message per prompt turn replaces per-tool messages + standalone PlanCard. Card becomes immutable on session_end.


8. Files Reference

File Role
src/core/types.ts AgentEvent, OutgoingMessage, PlanEntry types
src/core/message-transformer.ts AgentEvent โ†’ OutgoingMessage mapping
src/core/adapter-primitives/format-types.ts Icons, ToolCallMeta, ViewerLinks types
src/core/adapter-primitives/message-formatter.ts formatToolSummary, formatToolTitle, resolveToolIcon, evaluateNoise
src/core/adapter-primitives/format-utils.ts progressBar, formatTokens, truncateContent, splitMessage
src/core/adapter-primitives/messaging-adapter.ts Message dispatch, visibility, noise filtering
src/core/adapter-primitives/rendering/renderer.ts BaseRenderer (plain text defaults)
src/core/adapter-primitives/primitives/tool-card-state.ts ToolCard shared state, debounce logic (500ms + immediate first render)
src/plugins/discord/formatting.ts Discord markdown formatting
src/plugins/telegram/formatting.ts Telegram HTML formatting
src/plugins/slack/formatter.ts Slack Block Kit formatting

9. Consolidated Tool Card

Overview

The Consolidated Tool Card is a single auto-updating embed/message per prompt turn that replaces both:

  • Per-tool messages (individual tool_call/tool_update messages)
  • Standalone PlanCard (now rendered inline)

Behavior:

  • One embed per session per prompt turn
  • Auto-updates as tools run (debounced at 500ms; immediate first render)
  • Becomes immutable on session_end event
  • Renders sequentially: completed tools โ†’ running tools โ†’ plan โ†’ usage footer
  • Verbosity controls noise filtering: low/medium hide noise tools, high shows all

Structure

Header:

๐Ÿ”ง Tools (3/5 completed)

Completed Tools Section:

โœ… Read src/main.ts (50 lines)
โœ… Grep "TODO" in src/

Running Tools Section:

๐Ÿ”„ Edit src/main.ts

Plan Section (inline, always full entries):

๐Ÿ“‹ Plan
โœ… 1. Set up project structure
โœ… 2. Create database schema
๐Ÿ”„ 3. Implement API endpoints
โฌœ 4. Write tests

Usage Footer:

๐Ÿ“Š 12.5K tokens ยท $0.05

Noise Filtering

Same rules as Section 2.4 apply:

  • ls tool: hidden on low/medium
  • Directory reads: hidden on low/medium
  • glob tool: hidden on low/medium
  • grep tool: hidden on low/medium

On high verbosity, all tools show (no filtering).

Update Strategy

  • Debounce: 500ms between renders (batches rapid tool events)
  • First render: Immediate (not debounced)
  • Immutability: On session_end, card stops updating and becomes read-only
  • Card lifecycle: Created on first tool_call, destroyed with session