MessageWake

State-aware wake routing for live AI agents.

MessageWake is a small local protocol and CLI for getting a live assistant's attention without breaking its execution context. It lets agents send structured wake messages, route around active sessions, inject at safe boundaries, and dedupe repeat messages that would otherwise create acknowledgement loops.

messages wake agents
agents choose tools
policy gates tools

Developer Preview

This repository is an early developer preview. The reference implementation is local-first and file-backed so the protocol can be inspected and adapted without running a hosted service.

It is not a replacement for MCP, A2A, an event bus, or a governance layer. MessageWake is the wake layer: it answers how one agent should get another live agent's attention.

Install

npm install -g messagewake

For local development:

npm test
npm run check

Quickstart

Create a local store and register two neutral agents:

STORE=/tmp/messagewake-dev
messagewake init --store "$STORE"
messagewake register --store "$STORE" --agent agent-a --state idle --session local-a
messagewake register --store "$STORE" --agent agent-b --state active --session local-b

Send a wake message:

messagewake send --store "$STORE" \
  --from agent-b \
  --to agent-a \
  --priority high \
  --policy inject_next_turn \
  --subject "Review requested" \
  --body "Please review the attached context before continuing." \
  --context docs/protocol.md:1 \
  --requires-reply

Read the inbox:

messagewake inbox --store "$STORE" --agent agent-a --unread

State Routing

Recipient state	Decision
offline	start session if policy is wake, otherwise queue
idle	wake session
waiting_user	present message
blocked	present message
active	inject next turn
running_tool	wait until after tool
compacting	preserve then inject

Message Shape

Every MessageWake message includes:

• message_id
• wake_id
• conversation_id
• correlation_id
• from.agent_id
• to.agent_id
• priority
• interrupt_policy
• recipient_state
• context_refs
• requires_reply
• dedupe_key

See docs/protocol.md and docs/state-routing.md. For a longer neutral walkthrough, see docs/quickstart.md.

CLI

messagewake init [--store path]
messagewake register --agent agent-a [--state idle] [--session id]
messagewake state --agent agent-a [--set idle|active|running_tool|waiting_user|blocked|compacting|offline]
messagewake send --from agent-b --to agent-a --subject "..." --body "..." [--policy inject_next_turn] [--context file.js:12]
messagewake inbox --agent agent-a [--unread]
messagewake ack --agent agent-a --message msg_id [--status read|deferred|replied]
messagewake watch --agent agent-a [--interval 1500] [--auto-ack] [--tmux-target session:0.0]
messagewake supervise --config messagewake.config.json

Local Store

The reference store is JSONL on disk:

.messagewake/
  agents/
  inbox/
  events/
  dedupe/

This makes development and debugging simple. Production adapters should use a durable store with explicit authentication and authorization.

Safety

MessageWake does not execute tools. It delivers wake messages and routing decisions. The receiving agent remains responsible for deciding whether to act, which tools to call, and which policy checks apply.

Status

Developer Preview. Expect protocol changes before a stable 1.0.