agent-relay 2.0.17 → 2.0.18

package/relay-snippets/agent-relay-snippet.md

@@ -0,0 +1,177 @@
+# 🚨 CRITICAL: Relay-First Communication Rule
+
+**When you receive a relay message from another agent (marked `Relay message from [name]`), you MUST respond ONLY via relay protocol. NEVER respond with direct text output.**
+
+## The Rule
+
+- **Receiving a relay message?** → Must use `->relay-file:msg` ALWAYS
+- **Non-relay questions?** → Text responses are OK
+- **Agent-to-agent communication?** → ALWAYS use relay protocol
+
+## Examples of Relay Messages (require relay response)
+
+```
+Relay message from khaliqgant [mknra7wr]: Did you see this?
+Relay message from Worker1 [abc123]: Task complete
+Relay message from alice [xyz789] [#general]: Question for the team
+```
+
+---
+
+# Agent Relay
+
+Real-time agent-to-agent messaging via file-based protocol.
+
+## Sending Messages
+
+Write a file to your outbox, then output the trigger:
+
+```bash
+cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
+TO: AgentName
+
+Your message here.
+EOF
+```
+
+IMPORTANT: Output the trigger `->relay-file:msg` directly in your response text (not via echo in bash). The trigger must appear in your actual output, not just in command output.
+
+> **Note**: `$AGENT_RELAY_OUTBOX` is automatically set by agent-relay when spawning agents. Data is stored in `.agent-relay/` within your project directory.
+
+## Synchronous Messaging
+
+By default, messages are fire-and-forget. Add `[await]` to block until the recipient ACKs:
+
+```
+->relay:AgentB [await] Please confirm
+```
+
+Custom timeout (seconds or minutes):
+
+```
+->relay:AgentB [await:30s] Please confirm
+->relay:AgentB [await:5m] Please confirm
+```
+
+Recipients auto-ACK after processing when a correlation ID is present.
+
+## Message Format
+
+```
+TO: Target
+THREAD: optional-thread
+
+Message body (everything after blank line)
+```
+
+| TO Value | Behavior |
+|----------|----------|
+| `AgentName` | Direct message |
+| `*` | Broadcast to all |
+| `#channel` | Channel message |
+
+## Agent Naming (Local vs Bridge)
+
+**Local communication** uses plain agent names. The `project:` prefix is **ONLY** for cross-project bridge mode.
+
+| Context | Correct | Incorrect |
+|---------|---------|-----------|
+| Local (same project) | `TO: Lead` | `TO: project:lead` |
+| Local (same project) | `TO: Worker1` | `TO: myproject:Worker1` |
+| Bridge (cross-project) | `TO: frontend:Designer` | N/A |
+| Bridge (to another lead) | `TO: otherproject:lead` | N/A |
+
+**Common mistake**: Using `project:lead` when communicating locally. This will fail because the relay looks for an agent literally named "project:lead".
+
+```bash
+# CORRECT - local communication to Lead agent
+cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
+TO: Lead
+
+Status update here.
+EOF
+```
+
+```bash
+# WRONG - project: prefix is only for bridge mode
+cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
+TO: project:lead
+
+This will fail locally!
+EOF
+```
+
+## Spawning & Releasing
+
+**IMPORTANT**: The filename is always `spawn` (not `spawn-agentname`) and the trigger is always `->relay-file:spawn`. Spawn agents one at a time sequentially.
+
+```bash
+# Spawn
+cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'
+KIND: spawn
+NAME: WorkerName
+CLI: claude
+
+Task description here.
+EOF
+```
+Then: `->relay-file:spawn`
+
+```bash
+# Release
+cat > $AGENT_RELAY_OUTBOX/release << 'EOF'
+KIND: release
+NAME: WorkerName
+EOF
+```
+Then: `->relay-file:release`
+
+## When You Are Spawned
+
+If you were spawned by another agent:
+
+1. **Check who spawned you**: `echo $AGENT_RELAY_SPAWNER`
+2. **Your first message** is your task from your spawner - reply to THEM, not "spawner"
+3. **Report status** to your spawner (your lead), not broadcast
+
+```bash
+# Check your spawner
+echo "I was spawned by: $AGENT_RELAY_SPAWNER"
+
+# Reply to your spawner
+cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
+TO: $AGENT_RELAY_SPAWNER
+
+ACK: Starting on the task.
+EOF
+```
+Then: `->relay-file:msg`
+
+## Receiving Messages
+
+Messages appear as:
+```
+Relay message from Alice [abc123]: Content here
+```
+
+Channel messages include `[#channel]`:
+```
+Relay message from Alice [abc123] [#general]: Hello!
+```
+Reply to the channel shown, not the sender.
+
+## Protocol
+
+- **ACK** when you receive a task: `ACK: Brief description`
+- **DONE** when complete: `DONE: What was accomplished`
+- Send status to your **lead** (the agent in `$AGENT_RELAY_SPAWNER`), not broadcast
+
+## Headers Reference
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| TO | Yes (messages) | Target agent/channel |
+| KIND | No | `message` (default), `spawn`, `release` |
+| NAME | Yes (spawn/release) | Agent name |
+| CLI | Yes (spawn) | CLI to use |
+| THREAD | No | Thread identifier |

package/SESSION_HANDOFF.md

@@ -1,67 +0,0 @@
-# Session Handoff - NPM Package Extraction Project
-
-**Last Updated**: Session end (Jan 22, 2026 ~12:45 UTC)
-
-## Current State Summary
-
-### Completed
-- **Phases 1-4**: 14 packages extracted (protocol, config, storage, state, policy, memory, utils, hooks)
-- **Phase 6A**: User-directory extracted (broke circular deps)
-- **Phase 5A**: Cloud extraction complete, build GREEN
-
-### In Progress - NEEDS ATTENTION
-- **Phase 5B** (Staff): Dashboard-server extraction
-  - Last confirmed: 12:37 UTC
-  - ETA: 45-60 minutes to build green
-  - Status: APPEARS IDLE - no updates for 15+ minutes
-  
-- **Phase 6B** (FullStack): Daemon extraction  
-  - Last confirmed: 12:21 UTC
-  - ETA: 60 minutes
-  - Status: UNRESPONSIVE - no updates for 40+ minutes
-
-### Queued
-- Phase 6C: CLI extraction (FullStack, after 6B)
-- Phase 6D: Final integrations (15-30 min)
-
-## Test Baseline
-Maintain 2468 passing tests throughout
-
-## Critical Reminders
-
-### Build Order
-Trajectory and Hooks MUST build BEFORE Memory
-
-### Relay Protocol
-Write to ~/.agent-relay/outbox/[Agent]/msg with TO: Lead header
-
-### Package Paths
-- Config: @agent-relay/config/*
-- Daemon: @agent-relay/daemon/*
-- Wrapper: @agent-relay/wrapper/*
-- Cloud: @agent-relay/cloud/*
-
-## Immediate Next Steps
-
-1. Ping Staff: Phase 5B dashboard-server status?
-2. Ping FullStack: What is blocking Phase 6B daemon extraction?
-3. Unblock both agents
-4. Resume parallel execution
-5. Monitor to completion
-
-## Key Files
-
-- Handoff notes: ~/.agent-relay/outbox/Lead/session-handoff
-- Phase 6 plan: .beads/phase6-execution-plan.md
-- Cloud package: packages/cloud/ (COMPLETE)
-- Dashboard-server: packages/dashboard-server/ (IN PROGRESS)
-- Daemon: packages/daemon/ (IN PROGRESS)
-
-## Timeline to Completion
-- Phase 5B: 50-60 min remaining
-- Phase 6B: 60 min (parallel)
-- Phase 6C: 30-45 min
-- Final integration: 15-30 min
-- TOTAL: 2-2.5 hours
-
-Risk Level: MODERATE (both agents appear stuck, need immediate wake-up)

package/test-push.txt

@@ -1 +0,0 @@
-# Test file for push verification