From f94645dfe57d34888271cf6db366bb90c8e88ec9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 19:26:37 +0100 Subject: [PATCH] docs: refresh session recall sanitization refs --- docs/concepts/delegate-architecture.md | 7 ++++--- docs/concepts/multi-agent.md | 4 +++- docs/concepts/session-tool.md | 10 ++++++++++ docs/gateway/protocol.md | 6 ++---- docs/platforms/android.md | 6 ++---- docs/platforms/mac/webchat.md | 7 ++----- docs/tools/index.md | 8 +++++--- docs/tools/multi-agent-sandbox-tools.md | 6 ++++-- docs/tools/subagents.md | 7 ++++++- docs/web/control-ui.md | 7 +------ docs/web/webchat.md | 2 +- 11 files changed, 40 insertions(+), 30 deletions(-) diff --git a/docs/concepts/delegate-architecture.md b/docs/concepts/delegate-architecture.md index 60e14e44bb7..a52d2a16092 100644 --- a/docs/concepts/delegate-architecture.md +++ b/docs/concepts/delegate-architecture.md @@ -284,9 +284,10 @@ The delegate's `AGENTS.md` defines its autonomous authority — what it may do w If you grant `sessions_history`, remember it is a bounded, safety-filtered recall view. OpenClaw redacts credential/token-like text, truncates long -content, and can replace oversized rows with -`[sessions_history omitted: message too large]` instead of returning a raw -transcript dump. +content, strips thinking tags / downgraded tool-call scaffolding / leaked model +control tokens / malformed MiniMax tool-call XML from assistant recall, and can +replace oversized rows with `[sessions_history omitted: message too large]` +instead of returning a raw transcript dump. ## Scaling pattern diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md index cbda319494b..510bd6fa267 100644 --- a/docs/concepts/multi-agent.md +++ b/docs/concepts/multi-agent.md @@ -24,7 +24,9 @@ Auth profiles are **per-agent**. Each agent reads from its own: ``` `sessions_history` is the safer cross-session recall path here too: it returns -a bounded, redacted view, not a raw transcript dump. +a bounded, sanitized view, not a raw transcript dump. Assistant recall strips +thinking tags, downgraded tool-call scaffolding, leaked model control tokens, +and malformed MiniMax tool-call XML before redaction/truncation. Main agent credentials are **not** shared automatically. Never reuse `agentDir` across agents (it causes auth/session collisions). If you want to share creds, diff --git a/docs/concepts/session-tool.md b/docs/concepts/session-tool.md index de55145abfb..9563e952ec6 100644 --- a/docs/concepts/session-tool.md +++ b/docs/concepts/session-tool.md @@ -30,6 +30,13 @@ counts, and timestamps. Filter by kind (`main`, `group`, `cron`, `hook`, By default, tool results are excluded -- pass `includeTools: true` to see them. The returned view is intentionally bounded and safety-filtered: +- assistant text is normalized before recall: + - thinking tags are stripped + - downgraded tool-call/result scaffolding such as `[Tool Call: ...]`, + `[Tool Result ...]`, and `[Historical context ...]` is stripped + - leaked model control tokens such as `<|assistant|>` / `<｜...｜>` are stripped + - malformed MiniMax tool-call XML such as `` / + `` is stripped - credential/token-like text is redacted before it is returned - long text blocks are truncated - very large histories can drop older rows or replace an oversized row with @@ -40,6 +47,9 @@ The returned view is intentionally bounded and safety-filtered: Both tools accept either a **session key** (like `"main"`) or a **session ID** from a previous list call. +If you need the exact byte-for-byte transcript, inspect the transcript file on +disk instead of treating `sessions_history` as a raw dump. + ## Sending cross-session messages `sessions_send` delivers a message to another session and optionally waits for diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index fb51f772fc3..b2db787e77e 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -317,10 +317,8 @@ Gateway exposes today. - chat execution still uses `chat.history`, `chat.send`, `chat.abort`, and `chat.inject`. - `chat.history` is display-normalized for UI clients: inline directive tags are - stripped from visible text, leaked reasoning / relevant-memories scaffolding, - leaked XML tool-call blocks, and leaked provider control tokens are also - stripped from visible assistant text, pure `NO_REPLY` assistant rows are - omitted, and oversized rows can be replaced with placeholders. + stripped from visible text, pure `NO_REPLY` assistant rows are omitted, and + oversized rows can be replaced with placeholders. #### Device pairing and device tokens diff --git a/docs/platforms/android.md b/docs/platforms/android.md index e8a26a2299a..519c39354ab 100644 --- a/docs/platforms/android.md +++ b/docs/platforms/android.md @@ -138,10 +138,8 @@ Pairing details: [Pairing](/channels/pairing). The Android Chat tab supports session selection (default `main`, plus other existing sessions): - History: `chat.history` (display-normalized; inline directive tags are - stripped from visible text; leaked reasoning / relevant-memories - scaffolding, leaked XML tool-call blocks, and leaked provider control tokens - are also stripped from visible assistant text; pure `NO_REPLY` assistant rows - are omitted; oversized rows can be replaced with placeholders) + stripped from visible text, pure `NO_REPLY` assistant rows are omitted, and + oversized rows can be replaced with placeholders) - Send: `chat.send` - Push updates (best-effort): `chat.subscribe` → `event:"chat"` diff --git a/docs/platforms/mac/webchat.md b/docs/platforms/mac/webchat.md index 8aed072a0e4..468fd887ddb 100644 --- a/docs/platforms/mac/webchat.md +++ b/docs/platforms/mac/webchat.md @@ -31,11 +31,8 @@ agent (with a session switcher for other sessions). - Data plane: Gateway WS methods `chat.history`, `chat.send`, `chat.abort`, `chat.inject` and events `chat`, `agent`, `presence`, `tick`, `health`. - `chat.history` returns display-normalized transcript rows: inline directive - tags are stripped from visible text; leaked reasoning / - relevant-memories scaffolding, leaked XML tool-call blocks, and leaked - provider control tokens are also stripped from visible assistant text; pure - `NO_REPLY` assistant rows are omitted; oversized rows can be replaced with - placeholders. + tags are stripped from visible text, pure `NO_REPLY` assistant rows are + omitted, and oversized rows can be replaced with placeholders. - Session: defaults to the primary session (`main`, or `global` when scope is global). The UI can switch between sessions. - Onboarding uses a dedicated session to keep first‑run setup separate. diff --git a/docs/tools/index.md b/docs/tools/index.md index a9c1059c414..cd6a348de47 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -129,9 +129,11 @@ Use `group:*` shorthands in allow/deny lists: | `group:nodes` | nodes | | `group:openclaw` | All built-in OpenClaw tools (excludes plugin tools) | -`sessions_history` returns a bounded, safety-filtered recall view. For very -large or sensitive transcripts, expect redaction, truncation, and possible -oversized-row placeholders instead of a raw transcript dump. +`sessions_history` returns a bounded, safety-filtered recall view. It strips +thinking tags, downgraded tool-call scaffolding, leaked model control tokens, +and malformed MiniMax tool-call XML from assistant text, then applies +redaction/truncation and possible oversized-row placeholders instead of acting +as a raw transcript dump. ### Provider-specific restrictions diff --git a/docs/tools/multi-agent-sandbox-tools.md b/docs/tools/multi-agent-sandbox-tools.md index da0e30ae885..d82e1f026ed 100644 --- a/docs/tools/multi-agent-sandbox-tools.md +++ b/docs/tools/multi-agent-sandbox-tools.md @@ -295,8 +295,10 @@ Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defau } ``` -`sessions_history` in this profile still returns a bounded, redacted recall -view rather than a raw transcript dump. +`sessions_history` in this profile still returns a bounded, sanitized recall +view rather than a raw transcript dump. Assistant recall strips thinking tags, +downgraded tool-call scaffolding, leaked model control tokens, and malformed +MiniMax tool-call XML before redaction/truncation. --- diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index d301ceaafad..893d59dfe34 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -261,6 +261,11 @@ Announce payloads include a stats line at the end (even when wrapped): `sessions_history` is the safer orchestration path: +- assistant recall is normalized first: + - thinking tags are stripped + - downgraded tool-call/result scaffolding and historical-context markers are stripped + - leaked model control tokens such as `<|assistant|>` are stripped + - malformed MiniMax tool-call XML is stripped - credential/token-like text is redacted - long blocks can be truncated - very large histories can drop older rows or replace an oversized row with @@ -276,7 +281,7 @@ By default, sub-agents get **all tools except session tools** and system tools: - `sessions_send` - `sessions_spawn` -`sessions_history` remains a bounded, redacted recall view here too; it is not +`sessions_history` remains a bounded, sanitized recall view here too; it is not a raw transcript dump. When `maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive `sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they can manage their children. diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 5a4f8470075..0cfa7ce61f6 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -116,12 +116,7 @@ Cron jobs panel notes: - `chat.send` is **non-blocking**: it acks immediately with `{ runId, status: "started" }` and the response streams via `chat` events. - Re-sending with the same `idempotencyKey` returns `{ status: "in_flight" }` while running, and `{ status: "ok" }` after completion. - `chat.history` responses are size-bounded for UI safety. When transcript entries are too large, Gateway may truncate long text fields, omit heavy metadata blocks, and replace oversized messages with a placeholder (`[chat.history omitted: message too large]`). -- `chat.history` also strips visible-text scaffolding from assistant output before rendering: - - inline directive tags such as `[[reply_to_*]]` and `[[audio_as_voice]]` - - leaked reasoning / relevant-memories blocks - - leaked XML tool-call scaffolding such as `` / `` - - leaked provider control tokens such as `<|assistant|>` and similar `<|...|>` / `<｜...｜>` markers - - assistant entries whose whole visible text is only `NO_REPLY` are omitted +- `chat.history` also strips display-only inline directive tags from visible assistant text (for example `[[reply_to_*]]` and `[[audio_as_voice]]`) and omits assistant entries whose whole visible text is only `NO_REPLY`. - `chat.inject` appends an assistant note to the session transcript and broadcasts a `chat` event for UI-only updates (no agent run, no channel delivery). - The chat header model and thinking pickers patch the active session immediately through `sessions.patch`; they are persistent session overrides, not one-turn-only send options. - Stop: diff --git a/docs/web/webchat.md b/docs/web/webchat.md index 0e86a941670..af0be1347a7 100644 --- a/docs/web/webchat.md +++ b/docs/web/webchat.md @@ -26,7 +26,7 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket. - The UI connects to the Gateway WebSocket and uses `chat.history`, `chat.send`, and `chat.inject`. - `chat.history` is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with `[chat.history omitted: message too large]`. -- `chat.history` is also display-normalized: inline delivery directive tags such as `[[reply_to_*]]` and `[[audio_as_voice]]`, leaked reasoning / relevant-memories scaffolding, leaked XML tool-call blocks, and leaked provider control tokens such as `<|assistant|>` are stripped from visible assistant text, and assistant entries whose whole visible text is only `NO_REPLY` are omitted. +- `chat.history` is also display-normalized: inline delivery directive tags such as `[[reply_to_*]]` and `[[audio_as_voice]]` are stripped from visible text, and assistant entries whose whole visible text is only `NO_REPLY` are omitted. - `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run). - Aborted runs can keep partial assistant output visible in the UI. - Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.