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

376 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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