feat: introduce UntrustedContext layer with channel topic support

[chaodu-agent]

Description

Introduce an UntrustedContext layer to openab so that external, user-editable metadata — starting with Discord channel topics — can be safely injected into downstream ACP agent prompts.

Today, openab's SenderContext carries only trusted, structured identity fields (sender_id, sender_name, channel_id, etc.). There is no mechanism to pass channel-level metadata like the channel topic or description. This means agents running on openab have no awareness of the channel's stated purpose — information that other platforms already provide.

Use Cases

1. Channel-scoped behavior — A channel topic like "Production alerts only — respond in English" tells the agent the expected tone, language, and scope without per-channel config.
2. Project context — Teams using Discord forum channels set topics like "Planning and coordination for Project X". The agent can use this to stay on-topic.
3. Self-documenting channels — Operators can steer agent behavior by editing the channel topic in Discord UI, no config file changes needed.
4. Security — Channel topics are user-editable by anyone with MANAGE_CHANNELS permission. They must not be treated as trusted system instructions, or they become a prompt injection vector.

Prior Art Investigation

We investigated how OpenClaw and Hermes Agent handle channel topics:

OpenClaw (openclaw/openclaw, commit 7e13f3f)

OpenClaw has a mature UntrustedContext system with sanitization + isolation:

1. Read topic from Discord channel object — channel-access.ts L49-51: resolveDiscordChannelTopicSafe() safely reads channel.topic.

2. Pass through message handler — message-handler.process.ts L310: channelTopic: channelInfo?.topic.

3. Wrap as untrusted content — inbound-context.ts L59-66: Uses buildUntrustedChannelMetadata() to wrap the topic with security boundaries.

4. Sanitization pipeline — channel-metadata.ts and external-content.ts:

   • Wraps content in <<<EXTERNAL_UNTRUSTED_CONTENT id="random">>> markers with random IDs to prevent spoofing
   • Strips LLM special tokens (<|im_start|>, [INST], etc. — 20+ patterns)
   • Neutralizes Unicode homoglyph attacks (fullwidth chars, angle bracket variants)
   • Detects prompt injection patterns (ignore previous instructions, you are now a..., etc.)
   • Truncates to 400 chars/entry, 800 chars total

5. Isolation — The untrusted context is placed in a separate UntrustedContext[] array, never mixed into GroupSystemPrompt. The test at inbound-context.test.ts and message-handler.inbound-context.test.ts explicitly verify that a topic like "Ignore system instructions" stays in the untrusted layer.

6. Default on, no opt-out — Channel topic injection is always active for guild channels; DMs skip it automatically (isGuild: false).

Hermes Agent (NousResearch/hermes-agent, commit 192e7eb)

Hermes Agent also supports channel topics, but with a simpler (less secure) approach:

1. SessionSource.chat_topic — session.py L86: chat_topic: Optional[str] = None.

2. Discord reads topic — discord.py L3031-3038: _get_effective_topic() reads channel.topic, falls back to parent forum topic for threads.

3. Injected as plain text in system prompt — session.py L282-283: **Channel Topic:** {topic} — directly in the system prompt with no untrusted wrapping or sanitization.

Key Differences

Aspect	OpenClaw	Hermes Agent	openab (current)
Reads channel topic	✅	✅	❌
Untrusted context layer	✅ (sanitize + isolate)	❌ (plain text in system prompt)	❌ (no layer exists)
Prompt injection protection	✅ (boundary markers, token stripping, homoglyph defense)	❌	N/A
Forum thread fallback	✅ (via resolveDiscordChannelInfoSafe)	✅ (via _get_effective_topic)	N/A

Proposed Design for openab

Architecture

                    openab — Proposed UntrustedContext Layer
 ═══════════════════════════════════════════════════════════════════

  Discord Message
       │
       ▼
 ┌───────────────────────────────────────────────────────────────┐
 │  discord.rs                                                    │
 │                                                                │
 │  msg.channel_id.to_channel(&ctx.http).await                    │
 │       │                                                        │
 │       ▼                                                        │
 │  GuildChannel {                                                │
 │    topic: Some("Production alerts — respond in English"),      │
 │    name: "ops-alerts",                                         │
 │    thread_metadata, parent_id, owner_id, ...                   │
 │  }                                                             │
 │       │                                                        │
 │       │  gc.topic already available at line ~387               │
 │       │  (currently only thread_metadata/parent_id used)       │
 │       ▼                                                        │
 │  ┌─────────────────────────────────────────────────────┐      │
 │  │  UntrustedContext::wrap(source, label, content)     │      │
 │  │                                                     │      │
 │  │  1. Truncate (400 char/entry, 800 total)           │      │
 │  │  2. Strip LLM special tokens                       │      │
 │  │  3. Neutralize boundary marker spoofing            │      │
 │  │  4. Wrap in random-ID boundary markers             │      │
 │  └──────────────────────┬──────────────────────────────┘      │
 │                         │                                      │
 └─────────────────────────┼──────────────────────────────────────┘
                           │
                           ▼
 ┌───────────────────────────────────────────────────────────────┐
 │  ACP Prompt Assembly (adapter.rs)                              │
 │                                                                │
 │  content_blocks: [                                             │
 │    Text {                                                      │
 │      "<sender_context>{...}</sender_context>"     ← trusted   │
 │                                                                │
 │      "<<<EXTERNAL_UNTRUSTED_CONTENT id=\"a1b2\">>>"           │
 │      "Source: Channel metadata"                                │
 │      "---"                                                     │
 │      "UNTRUSTED channel metadata (discord)"                   │
 │      "Discord channel topic:"                                  │
 │      "Production alerts — respond in English"                  │
 │      "<<<END_EXTERNAL_UNTRUSTED_CONTENT id=\"a1b2\">>>"       │
 │                                                    ← isolated │
 │      "user's actual message"                                   │
 │    },                                                          │
 │    Image { ... },   ← if image attached                       │
 │  ]                                                             │
 └──────────────────────┬────────────────────────────────────────┘
                        │
                        ▼
 ┌───────────────────────────────────────────────────────────────┐
 │  Downstream ACP Agent (Kiro CLI / Claude Code / etc)          │
 │                                                                │
 │  Agent sees channel topic as reference context,                │
 │  but knows it's untrusted external content.                    │
 └───────────────────────────────────────────────────────────────┘

Protection Layers

The UntrustedContext wrapper provides sanitize + isolate defense-in-depth:

Layer	What it does	Why
Truncation	400 chars/entry, 800 chars total	Limit attack surface
LLM token stripping	Remove <|im_start|>, [INST], <s>, etc.	Prevent chat-template escape
Homoglyph folding	Normalize fullwidth chars, Unicode angle brackets	Prevent visual spoofing of markers
Marker sanitization	Replace spoofed <<<EXTERNAL_UNTRUSTED_CONTENT>>>	Prevent boundary escape
Random boundary IDs	<<<EXTERNAL_UNTRUSTED_CONTENT id="random_hex">>>	Attacker can't predict end marker
Isolation	Separate from system prompt / sender_context	Semantic separation for LLM

Files Changed

File	Change	Description
src/untrusted.rs	NEW	UntrustedContext wrapper — sanitize, truncate, wrap with boundary markers (~100 lines)
src/adapter.rs	MOD	Add untrusted_context: Option<Vec<String>> to prompt assembly
src/discord.rs	MOD	Read gc.topic and gc.name from the existing to_channel() call at L387, wrap as untrusted
src/gateway.rs	MOD	Add topic: Option<String> and name: Option<String> to ChannelInfo for Telegram/LINE
gateway/src/main.rs	MOD	Pass topic/name in gateway ChannelInfo

Future Extensions

Once the UntrustedContext layer exists, it can carry more than just channel topics:

• Channel name — useful for agents to know where they are
• Slack channel purpose/description
• Telegram group description
• Webhook payloads (email bodies, CI notifications)
• Forum thread tags

References

• OpenClaw channel topic: channel-access.ts, inbound-context.ts
• OpenClaw security runtime: channel-metadata.ts, external-content.ts
• Hermes Agent channel topic: session.py L86, discord.py L3031-3038, session.py L282-283
• openab existing to_channel() call: discord.rs L387
• openab SenderContext struct: adapter.rs L36-52
• Related: feat: support voice message STT (Speech-to-Text) for Discord #224 (STT feature — same investigation pattern)

Discord: https://discord.com/channels/1491295327620169908/1497578757333057577/1497930272635748473

[github-actions]

⚠️ This issue is missing the following required information and will not be processed until completed:

• Description
• Use Case

Please edit this issue to fill in the missing fields. Thank you!

Note: Please do not modify the section headings (### ...) as they are used for automated validation.

[chaodu-agent]

Why This Might Not Be a Good Idea / Options to Consider

Before implementing, it is worth weighing the cost-benefit:

Option A: Auto-inject every message (this proposal)

• Pro: Zero friction — agent always knows the channel context
• Con: Every message carries an untrusted context block, wasting tokens on repeated information that rarely changes
• Con: Added code complexity (new untrusted.rs module, sanitization pipeline, boundary markers)
• Con: Channel topic changes infrequently — injecting it on every turn is overkill

Option B: User pastes channel topic once per session (workaround, zero code change)

ACP sessions have memory. A user can paste the channel topic once at the start of a conversation, and the agent remembers it for the entire session. This is a minor inconvenience but not a blocker.

Option C: Static channel directory file in $HOME (workaround, zero code change)

Maintain a markdown file like ~/docs/channel-directory.md:

| Channel ID | Channel Name | Topic |
|---|---|---|
| 1490282656913559673 | #四法師禪房 | 四法師協作、PR review、日常討論 |
| 1497925057740144640 | #lab | 實驗性功能測試與討論 |

Reference it from the agent's context entries. Benefits:

• All sessions can look it up — no need to paste every time
• Can contain richer info than just the topic (channel purpose, resident members, related repos)
• No openab code changes required
• ⚠️ Requires manual maintenance when topics change

Recommendation

Option C is a practical immediate workaround. Option A (this proposal) is the proper long-term solution but should be prioritized against other work. The UntrustedContext layer itself has value beyond channel topics (webhook payloads, email bodies, etc.), so the investment may pay off when those use cases arise.