agent-relay 2.0.17 → 2.0.19

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

@@ -0,0 +1,101 @@
+# Agent Relay Protocol (Internal)
+
+Advanced features for session continuity and trajectory tracking.
+
+## Session Continuity
+
+Save your state for session recovery using file-based format (same as messaging):
+
+```bash
+cat > $AGENT_RELAY_OUTBOX/continuity << 'EOF'
+KIND: continuity
+ACTION: save
+
+Current task: Implementing user authentication
+Completed: User model, JWT utils
+In progress: Login endpoint
+Key decisions: Using refresh tokens
+Files: src/auth/*.ts
+EOF
+```
+Then: `->relay-file:continuity`
+
+### When to Save
+
+- Before long-running operations (builds, tests)
+- When switching task areas
+- Every 15-20 minutes of active work
+- Before ending session
+
+### Load Previous Context
+
+Context auto-loads on startup. To manually request:
+
+```bash
+cat > $AGENT_RELAY_OUTBOX/load << 'EOF'
+KIND: continuity
+ACTION: load
+EOF
+```
+Then: `->relay-file:load`
+
+### Mark Uncertainties
+
+Flag items needing future verification:
+
+```bash
+cat > $AGENT_RELAY_OUTBOX/uncertain << 'EOF'
+KIND: continuity
+ACTION: uncertain
+
+API rate limit handling unclear
+EOF
+```
+Then: `->relay-file:uncertain`
+
+## Work Trajectories
+
+Record your work as a trajectory for future agents.
+
+### Starting Work
+
+```bash
+trail start "Implement user authentication"
+trail start "Fix login bug" --task "agent-relay-123"
+```
+
+### Recording Decisions
+
+```bash
+trail decision "Chose JWT over sessions" --reasoning "Stateless scaling"
+trail decision "Used existing auth middleware"
+```
+
+### Completing Work
+
+```bash
+trail complete --summary "Added JWT auth" --confidence 0.85
+```
+
+Confidence: 0.9+ (high), 0.7-0.9 (good), 0.5-0.7 (some uncertainty), <0.5 (needs review)
+
+### Abandoning Work
+
+```bash
+trail abandon --reason "Blocked by missing credentials"
+```
+
+## Cross-Project Messaging
+
+In bridge mode, use `project:agent` format:
+
+```
+TO: frontend:Designer
+
+Please update the login UI.
+```
+
+Special targets:
+- `project:lead` - Lead agent of that project
+- `project:*` - Broadcast to project
+- `*:*` - Broadcast to all projects

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/scripts/postinstall.js

@@ -73,6 +73,36 @@ function getRelayPtyBinaryName() {
   return `relay-pty-${targetPlatform}-${targetArch}`;
 }
 
+/**
+ * Re-sign a binary with ad-hoc signature on macOS.
+ * This is required because macOS code signature validation can fail
+ * when binaries are copied/downloaded, causing SIGKILL on execution.
+ *
+ * The codesign tool is always available on macOS (part of the system).
+ * This is a common solution for npm packages distributing native binaries.
+ * Similar approach is used by esbuild, swc, and other Rust/Go tools.
+ *
+ * @param {string} binaryPath - Path to the binary to sign
+ * @returns {boolean} - Whether signing succeeded
+ */
+function resignBinaryForMacOS(binaryPath) {
+  if (os.platform() !== 'darwin') {
+    return true; // Only needed on macOS
+  }
+
+  try {
+    // codesign is always available on macOS as a system utility
+    execSync(`codesign --force --sign - "${binaryPath}"`, { stdio: 'pipe' });
+    return true;
+  } catch (err) {
+    // This shouldn't happen on a normal macOS system, but handle gracefully
+    warn(`Failed to re-sign binary: ${err.message}`);
+    warn('The binary may fail to execute due to code signature issues.');
+    warn('You can manually fix this by running: codesign --force --sign - ' + binaryPath);
+    return false;
+  }
+}
+
 /**
  * Install the relay-pty binary for the current platform
  */
@@ -103,6 +133,9 @@ function installRelayPtyBinary() {
       const sourceStats = fs.statSync(sourcePath);
       const targetStats = fs.statSync(targetPath);
       if (sourceStats.size === targetStats.size) {
+        // Re-sign even if already installed to ensure signature is valid
+        // This fixes issues where previous installs have invalid signatures
+        resignBinaryForMacOS(targetPath);
         info('relay-pty binary already installed');
         return true;
       }
@@ -115,7 +148,14 @@ function installRelayPtyBinary() {
   try {
     fs.copyFileSync(sourcePath, targetPath);
     fs.chmodSync(targetPath, 0o755);
-    success(`Installed relay-pty binary for ${os.platform()}-${os.arch()}`);
+
+    // Re-sign the binary on macOS to prevent code signature validation failures
+    // Without this, macOS may SIGKILL the process immediately on execution
+    if (resignBinaryForMacOS(targetPath)) {
+      success(`Installed relay-pty binary for ${os.platform()}-${os.arch()}`);
+    } else {
+      warn(`Installed relay-pty binary but signing failed - may not work on macOS`);
+    }
     return true;
   } catch (err) {
     warn(`Failed to install relay-pty binary: ${err.message}`);

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)