* 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>
14 KiB
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 |
commandtruncated at 60 chars.description,url,queryalso 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.priorityexists 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 ofmetadata.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_updatemessages) - 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_endevent - 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:
lstool: hidden on low/medium- Directory reads: hidden on low/medium
globtool: hidden on low/mediumgreptool: 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