* 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>
376 lines
14 KiB
Markdown
376 lines
14 KiB
Markdown
# 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:**
|
||
```typescript
|
||
{ 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:**
|
||
```typescript
|
||
{ 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
|