Messaging & Notifications

Scion provides a robust messaging system that allows for bidirectional communication between humans and running agents. This is particularly useful for long-running tasks where an agent might need clarification, approval, or simply wants to notify you of its progress.

The Inbox Tray

In the Web Dashboard, the Inbox Tray provides a centralized view of all messages sent by your agents.

Unread Badges: The top navigation bar displays a badge indicating the number of unread messages across all your agents.
Mark as Read: You can mark individual messages or all messages as read, helping you keep track of what needs your attention.
Contextual Links: Messages in the tray often link directly to the agent that sent them, allowing you to quickly jump in and provide the requested input or review the agent’s work.

Native Web Chat

Scion features an interactive, top-level Native Web Chat interface in the Web Dashboard (enabled via the web.native_chat feature flag). Rather than being isolated inside a single tab, chat is promoted to a top-level workspace view (a fourth ShellType in the SPA) that provides a cohesive, real-time collaborative environment for humans and agents.

Project-Scoped Spaces & Shared Threads: Chat is organized into distinct spaces scoped to specific Projects. Within a project-scoped space, users and agents participate in shared discussion threads, creating focused hubs of collaboration.
Project Context Preservation (Dashboard ↔ Chat Toggle): When you switch between dashboard and chat modes using the navigation icons in the header, Scion automatically maintains your active project context to avoid losing your work state:
- Dashboard → Chat: Clicking the Chat icon while on a project-scoped dashboard page (e.g., /projects/:id/... or inside an agent view) takes you straight to that project’s chat space (/chat/space/:id).
- Chat → Dashboard: Clicking the Dashboard icon while in a project chat space (/chat/space/:id/... or /chat/:slug/...) takes you directly back to that project’s detail page (/projects/:id).
- DMs / General Chat: If there is no active project context (such as when in Direct Messages or bare /chat), the toggle falls back to the top-level dashboard /.
Direct Messaging (DMs): In addition to collaborative project spaces, the chat interface supports robust 1-on-1 Direct Messages (DMs). This includes both human-to-human (H2H) communication between team members and human-to-agent (H2A) chats. DMs are structured as a “global pair”—a single, consolidated thread per participant pair.
- DM Promotion to Shared Threads: When a 1-on-1 Direct Message with an agent develops context useful for the broader team, you can promote the DM conversation into a Shared Space Thread. This atomic operation safely re-keys the messages and streams the transition live to all clients via SSE without a page reload. Use the promotion button located in the DM header.
Members Sidebar, Presence & Typing: A right-hand members sidebar lists all participants in the active project space or DM. This includes real-time online presence indicators (active, away, offline) and live typing indicators to show when a team member or agent is actively composing a message.
The Thread Rail & Mobile Swipe Navigation: A left-hand navigation sidebar lists all active chat spaces, threads, and DMs. On mobile viewports, the rail supports native swipe gestures for fluid, app-like drawer navigation.
Chat/Log Toggle: Located on the main scion-chat-thread panel, this toggle lets you switch between a clean, dialogue-focused Chat view and a live Execution Log stream for that agent.
Zero-Reload Navigation: Move between threads, project spaces, and configuration pages instantly with deep-linking support and no full-page reloads, ensuring no interruption to your active chat context or log streams.
Markdown & Rich Rendering: Chat messages support fully-featured real-time Markdown rendering inside chat bubbles (including syntax-highlighted code fences, tables, and nested lists) for highly readable development chats.
Clickable File Paths: File paths starting with /workspace/... or /scion-volumes/... render as interactive links. Clicking them immediately opens an on-demand file viewer dialog, fetching the current file content directly from the existing workspace and shared-directory APIs without leaving the chat context.
iOS & Platform Tailoring: The layout incorporates specific styling adjustments for iOS devices, delivering polished rendering and input behavior under Safari and other mobile browsers.
Config Toggle: Top-level native chat can be turned on or off globally by administrators using a single configuration key (web.native_chat feature flag) or via the Admin interface.

Advanced Collaboration & Productivity

The native web chat includes a complete suite of collaboration and developer productivity tools (Phases 0–5):

1. Message Action Bar

Hovering over a message (on desktop) or long-pressing (on mobile) reveals a contextual action bar providing several per-message actions:

Reply / Quote: Quote a previous message with full backend support for reply-threading, maintaining clear context in fast-moving development discussions.
Edit / Delete: Edit or delete your own messages.
Copy Permalink: Generate a direct link to any message in the thread.

2. Advanced Organization

Thread Pinning: Pin critical threads to the top of the thread rail for easy access.
Conversation Muting: Mute busy threads or spaces to suppress notifications while keeping the discussion active.
Custom Space Ordering: Reorder your chat spaces using intuitive drag-and-drop navigation in the sidebar.

3. High-Density Developer Utilities

Cmd/Ctrl-K Conversation Switcher: Trigger a keyboard-driven switcher to jump between spaces, threads, and DMs instantly without leaving your keyboard.
Unread Divider with Watermark: An unread indicator bar automatically segments new messages since your last visit, including a watermark to ensure you never miss a transition.
Rich Agent Output Rendering: Dispatched agents can render complex interactive payloads directly inside the chat, including structural diffs, test suite results, and interactive JSON/YAML tree-structures.
Collapsed Agent-to-Agent Messages: To keep threads readable, background agent-to-agent messages (visible under the Full density filter) are collapsed into a compact, click-to-expand pill. When expanded, these messages are displayed with 2-line truncation. If a message is truncated, an expand icon (‘arrows-angle-expand’) appears next to it, allowing you to open a full-screen Markdown-rendered dialog overlay.
Thread Export: Export any collaborative thread as a clean Markdown document, useful for sharing agent reasoning or saving session histories.
Send-to-Agent Context & Slash Commands: Fast-track your workflow with slash commands (e.g. /start, /help) and easily forward snippets or whole discussions directly to your agents as contextual guidance.

Push Notifications & Presence

Real-Time Browser Notifications: Stay informed of @mentions and incoming DMs with native browser push notifications.
Smart Suppression: Notifications are mute-aware and automatically suppressed for active conversations (threads you are currently looking at) to prevent alert fatigue.
Unread Badges: The tab title dynamically updates with an unread badge count when you are away from the tab.
Per-Thread Draft Persistence: Drafts are saved locally per-thread, so if you switch threads or close the tab, your unsent message remains waiting when you return.

Advanced Attachment Management

The web composer features a security-hardened, developer-friendly file upload system:

Executable Deny-List Strategy: To maximize flexibility for developers, attachment uploads use a security-first deny-list rather than a restrictive mime-type allow-list. It blocks executable binaries/scripts but permits 34+ developer file types (including configuration files, source code, and data structures).
Paste-to-Upload: Paste images or file content directly from your clipboard into the composer for instant attachment.
Markdown Attachment Rendering: Markdown files uploaded as attachments render directly within the chat bubble, featuring a source/preview toggle and a one-click clipboard copy.
Partial Success Reporting: When uploading multiple files simultaneously, the system supports partial success—successful uploads are staged instantly while failed individual files report explicit inline errors.

Performance & Safety Safeguards

Token-Bucket Rate Limiting: Per-sender token-bucket rate limits prevent message flooding, ensuring platform stability and protecting backend model endpoints.
16K Input Character Limit: A robust 16,000-character limit is enforced in the composer, protecting token context limits.
SSE Direct Append & Real-Time Attachments: Chat messages stream via Server-Sent Events (SSE) using direct-append logic, providing lag-free typing rendering. Additionally, attachment previews render immediately on incoming SSE messages, ensuring the user interface instantly displays attachment references without waiting for subsequent user-triggered renders.
Idempotency Keys: Client-side idempotency keys eliminate duplicate messages during transient connection drops or retry states.
Cursor-Based Scrollback Pagination: Solved previous scroll-jump issues and cursor-mismatches. Scrollback pagination and scroll-to-bottom locks operate smoothly as history loads.

Three-State Visibility Filtering

To prevent notification noise from overwhelming your conversation, the chat thread supports three distinct visibility filters:

Conversation: The cleanest view. Displays only direct human instructions and agent replies.
Verbose: Adds CCs, explicit @-mentions, and user-directed warnings.
Full: Displays every message, including background agent-to-agent operations, state-change notifications, and system warnings.

The visibility filter is processed server-side for efficiency, and your filter preferences are persisted per-agent so your preferred density level is remembered when you return to a thread. Dispatched messages feature real-time delivery state indicators, showing a success checkmark or a failure icon with a detailed tooltip (e.g. for delivery-failed notices).

Interactive @-Mentions & Autocomplete

When writing instructions, you can easily pull other agents into the thread:

Autocomplete Popup: Typing @ in the chat input opens a dropdown list of active agents in the project. The list supports fuzzy-matching as you type, and full keyboard navigation (arrow keys to select, Enter to insert).
Code-Fence Guard: The mention autocomplete is smart — it automatically disables itself when typing inside Markdown code fences (e.g., ``` blocks) so code snippets don’t trigger unwanted dropdowns.
Mention Leak Protection: Direct mentions are safely partitioned, resolving a previous bug where mentions would leak into the default agent tab.
Fan-Out Restrictions: For platform stability, a single message is fanned out to a maximum of 10 recipients per @-mention broadcast.
Composer Default-Agent Disambiguation: When sending messages in collaborative project spaces with multiple active agents, typing a message without an explicit target or @-mention triggers a smart disambiguation interface. This guides the user to select which agent the message should target (or fall back to the project’s configured default agent), keeping routing unambiguous and conversations clear.

Cross-Channel Coherence

If you use external messaging systems alongside the Web Dashboard, Scion ensures that conversations remain coherent across all channels:

Broker Inbound Persistence: Inbound messages received from external message brokers (such as Discord or Teams) are persisted in the Hub’s main database, making them instantly visible in the Web Chat.
Reply Affinity: Scion tracks user, project, and agent reply affinity so that replies are routed back to the initiating channel.
TouchThread & Broadcast Propagation: Messages and read states propagate smoothly across surfaces via TouchThread and Broadcasted events, ensuring that reading or replying to a thread on Discord or Teams instantly syncs the unread badges in your Web Dashboard.

CLI Message Management

You can also interact with the messaging system directly from the CLI using the scion messages command (aliases: msgs, inbox).

# View unread messages
scion messages

# View all messages for a specific agent
scion messages --agent <agent-name>

# Mark a message as read
scion messages read <message-id>

Sending Messages

Use scion message to send messages. The preferred addressing form uses @:

# Send to an agent (preferred form)
scion message @tech-lead "Please review the auth module."

# Send a global DM to a user by email
scion message @preston@example.com "Build is green, ready for review."

# Legacy forms (still work but @-form is preferred)
scion message agent:tech-lead "Please review the auth module."

# Attach a file
scion message @tech-lead "See the test results." --attach ./results.json

# Set message visibility
scion message @tech-lead "Debug trace attached." --visibility verbose

Message Formatting

The scion message CLI delivers the body argument verbatim — it performs no escape expansion, no markdown rendering, and no character substitution. Whatever bytes you pass are exactly what the recipient sees.

To include newlines, use real newlines inside shell quoted strings or heredocs. Do not use JSON-encoded bodies or literal backslash-n (\n) sequences — those will appear as literal characters in the delivered message.

Correct — real newlines in a quoted string:

scion message --non-interactive @reviewer "PR #42 is ready for review.

Branch: fix/auth-bug
CI: all green"

Correct — heredoc for longer messages:

scion message --non-interactive @reviewer "$(cat <<'EOF'
PR #42 is ready for review.

Branch: fix/auth-bug
CI: all green
EOF
)"

Wrong — JSON-encoded body with literal \n:

# BAD: literal \n chars appear in the delivered message
scion message --non-interactive @reviewer "PR #42 is ready for review.\n\nBranch: fix/auth-bug\nCI: all green"

scion broadcast: Send a message to all agents in the current project, or use --all for a global broadcast. This replaces the old --broadcast flag on scion message.
scion keys: Send raw keystrokes to an agent’s tmux terminal (e.g., scion keys editor "ENTER"). Useful for unblocking interactive prompts. This replaces the old --raw flag on scion message.

Discord

Scion supports Discord through two separate integration pathways:

Bidirectional Discord Bot: Interact with agents directly from Discord channels using slash commands under /scion (e.g., /scion setup to link channels, /scion default to set routing targets, /scion agents to check state). Agent replies are pushed back into the Discord channel with their own name and RoboHash-generated avatar.
Outbound Webhook Notifications: A simpler, outbound-only mechanism where agents push status updates, alerts, and ask_user requests to a designated Discord channel. Messages are color-coded by severity, and urgent notifications can trigger @user or @role mentions.

For a full setup guide and configuration options, see External Channels.

Scion also supports bidirectional messaging over Telegram: message your agents from a Telegram group and receive their replies in the chat. For a step-by-step Workstation setup, see Setting Up Telegram; for how it fits alongside other channels, see External Channels.

Agent `ask_user` Integration

When an agent uses the ask_user tool (or similar mechanism depending on the harness), Scion automatically performs two actions:

State Update: The agent’s state changes to WAITING_FOR_INPUT.
Explicit Message: A persistent message is generated and delivered to your Inbox Tray (and Discord, if configured), clearly stating what the agent needs.

Real-Time Delivery

Messages are delivered in real-time to the Web Dashboard via Server-Sent Events (SSE). The Messages Tab on the individual agent detail page provides a real-time stream of all communication with that specific agent.

Message Authorization & Modes

Every agent is protected by a Message Mode that controls which users and other agents can send messages to it. An agent’s message mode can be set via the Web Dashboard or via the set_message_mode action. The available modes are:

Project Mode (Default): Any user with the agent:message permission in the project can message the agent. Any peer agent in the project (that is not restricted by lineage mode) can also message it. The most permissive mode.
Branch Mode: Only users in the agent’s ancestry chain (its creator and their ancestors), plus the agent’s direct parent and child agents, can message it.
Lineage Mode: Strictly restricts messaging to users in the agent’s ancestry chain (its creator and their ancestors). No agent-to-agent messaging is permitted.
None Mode: Seals the agent from all messaging except system-plane notices. No users and no agents can message a none-mode agent through normal paths.

Piercing

Highly privileged users can bypass an agent’s message mode restrictions. This is called piercing.

Project Owners can pierce Branch and Lineage modes.
Super-admins pierce all modes, including None mode. Piercing applies only to user identities — it is never inherited by an owner’s agents.

The Web Dashboard displays reachability indicators (e.g., whether you can message a specific agent) based on the computed messageability, which takes into account the agent’s mode, your ancestry relationship to it, and any piercing privileges.

Developer Guide & Best Practices

For developers authoring agents and custom orchestrators, Scion’s messaging system follows a set of strict protocol rules and architectural patterns.

1. Message Length Limits

Scion maintains different limits depending on the recipient type:

User-Directed Messages (Agent-to-Human): Limited to 2,000 Unicode characters (runes). Each CJK character or emoji counts as a single character. Exceeding this limit causes scion message to fail with exit code 1 and print: validation_error: message exceeds 2000 character limit
- Tip: If you have a long message or log to send to a user, split it into multiple messages under 1,800 characters, or write the full content to a shared scratchpad file and send the filepath.
Agent-to-Agent Messages: No enforced length cap in code. You can send larger payloads safely between agents.

2. Inbound Message Type Discrimination

When an agent receives an inbound message, it arrives wrapped in standard delimiters and includes metadata:

---BEGIN SCION MESSAGE---
sender: agent:tech-lead
type: instruction
thread_id: 1234
---
Write a unit test for the auth package.
---END SCION MESSAGE---

Always check the type field before acting or replying:

Type	Meaning	Action Required
`instruction`	Direct instruction sent to you.	Read and act on it.
`state-change`	A notification that another agent changed phase (e.g. stopped or stalled).	Treat as FYI — no reply or action needed.
`input-needed`	A broadcast that an agent has called `sciontool status ask_user`.	See handling rules below.
`mention`	You were CC’d or mentioned in a message.	Treat as FYI unless explicitly directed otherwise.
`group-set`	An `@-mention` targeting multiple agents.	Act on it like an `instruction`.
`system`	Operational notices generated by the Hub (e.g. `delivery-failed`, `scheduler`, `port-forward`).	Treat as FYI or follow troubleshooting instructions in the notice.

The messaging system is transitioning to a conversation-based model where messages carry a conversation_id and are addressed to conversations rather than agents directly. During this transition, inbound messages continue to arrive with the type fields described above, and agents should continue to discriminate on the type field as documented.

To migrate historical messages that predate the conversation model, administrators can use the scion server backfill command.

Safe Idempotent Backfilling

The backfill process is safe and fully idempotent — messages that are already attributed to a conversation are skipped automatically. By default, the backfill runs in a safe dry-run mode, allowing operators to preview what would be migrated. The --execute flag must be explicitly passed to commit changes to the database.

Compound Keyset Resumability (DEF-81)

If a backfill operation is interrupted, it can be safely resumed from its last page of progress using the --checkpoint flag with the cursor printed in the previous run’s report. The backfill uses a robust compound keyset cursor (created, id) (rather than a strictly-greater-than timestamp). This eliminates the potential for permanent row loss on resume, ensuring that any messages sharing identical timestamps are correctly processed and never skipped during resumes.

Handling `input-needed` Notifications

When an agent signals WAITING_FOR_INPUT (by calling sciontool status ask_user), a notification of type input-needed is dispatched to all subscribed agents (including its creator).

Parent Agent Role: If you are the parent agent that created the waiting agent, you may be the intended respondent. Use scion message @<name> to reply with the answer.
Peer Agent Rule: Unrelated peer agents should NOT reply to input-needed notifications. Answering a peer’s input prompt wastes context tokens, causes false loop signals, and violates project-scoped boundaries. To request a peer’s input, always send an explicit instruction instead.

3. Subscription Management and Agent Self-Service

Automatic Subscription: The --notify flag on scion start is deprecated. When you start a sub-agent, Scion automatically registers your subscription via creation ancestry.
Explicit Messaging Subscription: Use the --notify flag on scion message only when you need to subscribe to notifications from a peer agent that you did not create.
Agent Self-Service Subscriptions: Running agents in Hosted mode are empowered to programmatically manage their own notification subscriptions. Previously restricted to administrative users (returning a 403 Forbidden for agents), agents with appropriate API credentials can now perform the following operations:
- CRUD Operations: Live agents can list, create, update, and delete their own subscriptions via the Hub API or client utilities.
- Identity Qualification: To prevent cross-project security leaks, every subscription request is qualified by the agent’s specific (project, slug) coordinates.
- Granular Scopes: Authorization gates require the agent token to hold the project:read scope for reading subscriptions and the project:agent:notify scope for writing (creating, updating, or deleting) subscriptions.
- Ownership Constraints: Acknowledging notifications or modifying/deleting existing subscriptions strictly requires ownership validation, meaning an agent can only modify or acknowledge subscriptions that target or belong to itself.

4. Security Controls for Direct Messages & Broadcasts

Scion employs strict, ingress-level security controls and invariants for Direct Messages (DMs) and Broadcasts to prevent spoofing, cross-project injection, and message divergence:

Server-Side Sender Identity & Derivation: Sender identity is forced server-side based on the authenticated request context, completely ignoring any sender claims in the payload. Furthermore, DM conversation keys are derived dynamically from the authenticated caller rather than trusting the payload, closing spoofed-sender conversation-selection vectors.
Canonical DM Key Enforcement: Thread IDs (used as DM keys) undergo strict canonicality enforcement. Non-canonical kinds and UUIDs are rejected immediately at derivation without silent normalization, ensuring precise routing.
Participant Guard Consolidation: A unified participant guard (CheckDMParticipantKey) protects all DM ingresses (adding/ensuring participants or merging conversations). This strict invariant guarantees that participant records cannot diverge from their canonical thread keys.
Broadcast Authorization: Project membership is strictly required and enforced for all broadcast calls.
Publish Gating & Stamping: Message publishing to real-time streams (SSE) is securely gated on successful database persistence (dual-write conversation stamping). This ensures that a message is never broadcasted to clients without being safely committed to history.

5. Sleep Anti-Pattern & Polling

Instead, pair sciontool status blocked with a scheduled self-callback using scion schedule create:

# Correct way to wait 5 minutes for a build to finish:
scion schedule create --in 5m --message "Check build status" --agent "$(scion whoami --non-interactive --format json | jq -r .name)"
sciontool status blocked "Waiting for build job 103"

The scheduled message delivers the wake-up poke; status blocked tells the platform that your silence is intentional, keeping you from being suspended.

6. @mention Parsing & Conversation Addressing

@<agent-name> is now the preferred addressing form for sending messages to agents via the CLI (e.g., scion message @tech-lead "..."). This form addresses the agent’s conversation directly.

When a human or an agent sends a message, Scion automatically scans for recipient targeting to fan-out notifications:

Body @mentions

Any name starting with @ in the message body (e.g., @dev-lead) is automatically parsed. If the name matches an active agent within the same project, Scion generates a secondary message of type mention and delivers it to that agent.

Multi-Recipient Addressing

To send to multiple recipients at once, use the group[...] addressing form:

scion message "group[tech-lead, dev-agent, qa-agent]" "Let's review the deployment strategy"

Validation & Integration Rules

Deduplication: If an agent is both @mentioned inside the body of a message and explicitly addressed as a recipient, Scion automatically deduplicates the list so they only receive a single mention message.
Project Scope Restriction: Mentions are restricted to the parent project boundary. Body-mentions can only be resolved and delivered to agents that belong to the same project. Unresolved names will result in a warning printed to stderr, but will not fail delivery of the primary message.
Fan-Out Restrictions: A single message is fanned out to a maximum of 10 recipients per @-mention broadcast.