agent-relay 1.2.0 → 1.2.3

package/docs/PROTOCOL.md

@@ -1,325 +0,0 @@
-# Agent Relay Protocol Specification
-
-Version 1.0
-
-## Goals
-
-- Low-latency local IPC (<5ms)
-- Strict framing with backpressure
-- At-least-once delivery (optional exactly-once within session)
-- Reconnect + state resync
-- Simple to implement in Rust/Go/TypeScript
-
-## Non-Goals
-
-- Cross-host networking
-- Encryption (local-only)
-- Unbounded buffering
-
----
-
-## 1. Transport
-
-**Preferred:** Unix Domain Socket (stream)
-- Path: `/tmp/agent-relay.sock` (configurable)
-
-**Windows fallback:** Named Pipe
-- Path: `\\.\pipe\agent-relay`
-
-**Connection model:** Each wrapper opens 1 duplex stream to daemon.
-
----
-
-## 2. Framing
-
-Stream is a sequence of frames.
-
-### Frame Header
-- 4-byte big-endian unsigned length `N` (bytes)
-- Followed by `N` bytes UTF-8 JSON
-
-### Limits
-- `N` MUST be <= `max_frame_bytes` (default: 1 MiB)
-- If exceeded, daemon closes connection with error
-- JSON payload MUST be an object
-
-### Example (pseudo)
-```
-0000003A {"v":1,"type":"HELLO","agent":"claude-1",...}
-```
-Where `0x3A` (58) is the byte length of the JSON payload.
-
----
-
-## 3. Envelope
-
-All messages are `Envelope` objects:
-
-```typescript
-interface Envelope {
-  v: 1;                    // Protocol version
-  type: MessageType;       // See below
-  id: string;              // Unique per-sender (UUIDv4)
-  ts: number;              // Milliseconds since epoch
-  from?: string;           // Agent name (set by daemon)
-  to?: string | '*';       // Target or broadcast
-  topic?: string;          // Optional topic/channel
-  payload: object;         // Type-specific payload
-}
-```
-
-### Message Types
-
-| Type | Direction | Purpose |
-|------|-----------|---------|
-| `HELLO` | Client→Server | Initiate handshake |
-| `WELCOME` | Server→Client | Confirm session |
-| `SEND` | Client→Server | Send message |
-| `DELIVER` | Server→Client | Deliver message |
-| `ACK` | Both | Acknowledge receipt |
-| `NACK` | Both | Negative acknowledgment |
-| `PING` | Server→Client | Heartbeat |
-| `PONG` | Client→Server | Heartbeat response |
-| `ERROR` | Server→Client | Error notification |
-| `BUSY` | Server→Client | Backpressure signal |
-| `RESUME` | Client→Server | Resume session |
-| `SYNC` | Server→Client | State sync info |
-| `BYE` | Both | Graceful disconnect |
-| `SUBSCRIBE` | Client→Server | Subscribe to topic |
-| `UNSUBSCRIBE` | Client→Server | Unsubscribe from topic |
-
----
-
-## 4. Handshake
-
-### New Session
-
-**Client → Server: HELLO**
-```json
-{
-  "v": 1,
-  "type": "HELLO",
-  "id": "uuid",
-  "ts": 1734440000000,
-  "payload": {
-    "agent": "claude-1",
-    "capabilities": {
-      "ack": true,
-      "resume": true,
-      "max_inflight": 256,
-      "supports_topics": true
-    },
-    "session": {
-      "resume_token": "optional-previous-token"
-    }
-  }
-}
-```
-
-**Server → Client: WELCOME**
-```json
-{
-  "v": 1,
-  "type": "WELCOME",
-  "id": "uuid",
-  "ts": 1734440000001,
-  "payload": {
-    "session_id": "s-abc123",
-    "resume_token": "new-token-for-reconnect",
-    "server": {
-      "max_frame_bytes": 1048576,
-      "heartbeat_ms": 5000
-    }
-  }
-}
-```
-
----
-
-## 5. Sending and Delivery
-
-### Client → Server: SEND
-```json
-{
-  "v": 1,
-  "type": "SEND",
-  "id": "m-001",
-  "ts": 1734440000100,
-  "to": "codex-1",
-  "topic": "chat",
-  "payload": {
-    "kind": "message",
-    "body": "Your turn",
-    "data": {}
-  },
-  "payload_meta": {
-    "requires_ack": true,
-    "ttl_ms": 60000
-  }
-}
-```
-
-### Server → Recipient: DELIVER
-```json
-{
-  "v": 1,
-  "type": "DELIVER",
-  "id": "d-001",
-  "ts": 1734440000102,
-  "from": "claude-1",
-  "to": "codex-1",
-  "topic": "chat",
-  "payload": {
-    "kind": "message",
-    "body": "Your turn",
-    "data": {}
-  },
-  "delivery": {
-    "seq": 42,
-    "session_id": "s-abc123"
-  }
-}
-```
-
-### Recipient → Server: ACK
-```json
-{
-  "v": 1,
-  "type": "ACK",
-  "id": "uuid",
-  "ts": 1734440000103,
-  "payload": {
-    "ack_id": "d-001",
-    "seq": 42
-  }
-}
-```
-
-### Ordering Guarantee
-
-Per `(topic, from → to)` stream, daemon guarantees in-order DELIVER by `delivery.seq`.
-
-No global ordering across topics.
-
----
-
-## 6. Backpressure
-
-Backpressure signaling is reserved for future versions. The current daemon is best-effort and does not implement bounded outbound queues or `BUSY` responses.
-
-### Server → Client: BUSY
-```json
-{
-  "v": 1,
-  "type": "BUSY",
-  "id": "uuid",
-  "ts": 1734440000300,
-  "payload": {
-    "retry_after_ms": 50,
-    "queue_depth": 1000
-  }
-}
-```
-
-Client should back off (exponential with jitter).
-
----
-
-## 7. Heartbeats
-
-- Daemon sends PING every `heartbeat_ms` if idle
-- Wrapper replies PONG with same nonce
-- Missing PONG for `2 * heartbeat_ms` → connection dead
-
----
-
-## 8. Reconnect / Resume
-
-### Client → Server: RESUME
-```json
-{
-  "v": 1,
-  "type": "RESUME",
-  "id": "uuid",
-  "ts": 1734440001000,
-  "payload": {
-    "session_id": "s-abc123",
-    "agent": "claude-1",
-    "streams": {
-      "chat": { "last_seq": 45 }
-    }
-  }
-}
-```
-
-### Server → Client: SYNC
-```json
-{
-  "v": 1,
-  "type": "SYNC",
-  "id": "uuid",
-  "ts": 1734440001001,
-  "payload": {
-    "session_id": "s-abc123",
-    "streams": [
-      { "topic": "chat", "peer": "codex-1", "last_seq": 45, "server_last_seq": 49 }
-    ]
-  }
-}
-```
-
-Server then replays DELIVER messages from `last_seq + 1` to `server_last_seq`.
-
-### Stale Resume
-
-If resume gap exceeds retention, server sends NACK with code "STALE".
-Client should send fresh HELLO.
-
----
-
-## 9. PTY Pattern Extractor
-
-### Fenced Format (default, recommended)
-
-```
-->relay:codex-1 <<<
-Your turn to play>>>
-
-->relay:* <<<
-Hello everyone>>>
-```
-
-**Always use the fenced format** for reliable message delivery. The `<<<` opens, `>>>` closes at end of last line.
-
-### Block Format (structured data)
-
-```
-[[RELAY]]
-{"to": "*", "type": "message", "body": "Hello everyone"}
-[[/RELAY]]
-```
-
-### Rules
-
-1. Fenced: `->relay:AgentName <<<` starts message, `>>>` ends it
-2. Block: Only parse when `[[RELAY]]` at start of line
-3. Pattern must be at start of line, not in code fences
-4. Escape: `\->relay:` outputs literal `->relay:`
-
----
-
-## 10. Connection Lifecycle
-
-```
-DISCONNECTED → CONNECTING → HANDSHAKING → READY
-                    ↑              ↓
-                BACKOFF ←─────── ERROR
-```
-
-### Backoff Strategy
-
-- Initial: 100ms
-- Multiplier: 2x
-- Max: 30s
-- Jitter: ±15%
-- Max attempts: 10

package/docs/WRAPPER_EVENTS.md

@@ -1,358 +0,0 @@
-# PtyWrapper Events
-
-PtyWrapper extends Node.js EventEmitter and emits events for monitoring agent behavior, handling persistence, and debugging. This document describes all available events and how to use them.
-
-## Event Reference
-
-### `output`
-
-Emitted for every chunk of output from the agent's PTY.
-
-```typescript
-pty.on('output', (data: string) => {
-  console.log('Agent output:', data);
-});
-```
-
-**Parameters:**
-- `data` (string): Raw output data from the PTY
-
-**Use cases:**
-- Live log streaming to dashboard
-- Output capture for analysis
-- Debugging agent behavior
-
----
-
-### `exit`
-
-Emitted when the agent process exits.
-
-```typescript
-pty.on('exit', (code: number) => {
-  console.log(`Agent exited with code ${code}`);
-});
-```
-
-**Parameters:**
-- `code` (number): Exit code of the process (0 = success)
-
-**Use cases:**
-- Cleanup resources
-- Trigger restart logic
-- Update agent status
-
----
-
-### `error`
-
-Emitted when an error occurs in the wrapper.
-
-```typescript
-pty.on('error', (error: Error) => {
-  console.error('PTY error:', error);
-});
-```
-
-**Parameters:**
-- `error` (Error): The error that occurred
-
-**Use cases:**
-- Error logging
-- Alerting
-- Graceful error handling
-
----
-
-### `injection-failed`
-
-Emitted when message injection fails after all retry attempts.
-
-```typescript
-import type { InjectionFailedEvent } from './wrapper/pty-wrapper.js';
-
-pty.on('injection-failed', (event: InjectionFailedEvent) => {
-  console.warn('Injection failed:', event);
-});
-```
-
-**Parameters:**
-- `event.messageId` (string): ID of the failed message
-- `event.from` (string): Sender of the message
-- `event.attempts` (number): Number of injection attempts made
-
-**Use cases:**
-- Alert on delivery failures
-- Fallback to inbox-based delivery
-- Dashboard warning indicators
-
----
-
-### `summary`
-
-Emitted when the agent outputs a `[[SUMMARY]]` block. Used for cloud persistence.
-
-```typescript
-import type { SummaryEvent } from './wrapper/pty-wrapper.js';
-
-pty.on('summary', (event: SummaryEvent) => {
-  console.log(`${event.agentName} summary:`, event.summary);
-});
-```
-
-**Parameters:**
-- `event.agentName` (string): Name of the agent
-- `event.summary` (ParsedSummary): Parsed summary object
-  - `currentTask?` (string): What the agent is currently working on
-  - `completedTasks?` (string[]): List of completed tasks
-  - `decisions?` (string[]): Key decisions made
-  - `context?` (string): Additional context
-  - `files?` (string[]): Files being worked on
-
-**Agent output format:**
-```
-[[SUMMARY]]
-{
-  "currentTask": "Implementing auth module",
-  "completedTasks": ["login flow", "session management"],
-  "context": "Using JWT for tokens",
-  "files": ["src/auth.ts", "src/session.ts"]
-}
-[[/SUMMARY]]
-```
-
-**Use cases:**
-- Persist agent progress to database
-- Resume interrupted sessions
-- Dashboard progress indicators
-
----
-
-### `session-end`
-
-Emitted when the agent outputs a `[[SESSION_END]]` block. Marks explicit session completion.
-
-```typescript
-import type { SessionEndEvent } from './wrapper/pty-wrapper.js';
-
-pty.on('session-end', (event: SessionEndEvent) => {
-  console.log(`${event.agentName} ended session:`, event.marker);
-});
-```
-
-**Parameters:**
-- `event.agentName` (string): Name of the agent
-- `event.marker` (SessionEndMarker): End marker object
-  - `summary?` (string): Final session summary
-  - `completedTasks?` (string[]): Tasks completed in session
-
-**Agent output format:**
-```
-[[SESSION_END]]
-{
-  "summary": "Completed auth module implementation",
-  "completedTasks": ["login", "logout", "session management"]
-}
-[[/SESSION_END]]
-```
-
-Or empty for clean close:
-```
-[[SESSION_END]][[/SESSION_END]]
-```
-
-**Use cases:**
-- Close session in database
-- Trigger cleanup
-- Update billing/usage
-
----
-
-## Cloud Persistence Integration
-
-For cloud deployments, use `CloudPersistenceService` to automatically persist summary and session-end events to PostgreSQL:
-
-```typescript
-import { PtyWrapper } from './wrapper/pty-wrapper.js';
-import { CloudPersistenceService } from './cloud/services/persistence.js';
-
-// Create persistence service
-const persistence = new CloudPersistenceService({
-  workspaceId: 'workspace-123',
-  onSummaryPersisted: (agentName, summaryId) => {
-    console.log(`Summary saved: ${summaryId}`);
-  },
-});
-
-// Create and start PTY
-const pty = new PtyWrapper(config);
-await pty.start();
-
-// Bind persistence to PTY - creates session record
-const sessionId = await persistence.bindToPtyWrapper(pty);
-
-// ... agent runs ...
-
-// Cleanup when done
-persistence.unbindFromPtyWrapper(pty);
-```
-
-### Database Schema
-
-```sql
--- Agent sessions
-CREATE TABLE agent_sessions (
-  id UUID PRIMARY KEY,
-  workspace_id UUID NOT NULL REFERENCES workspaces(id),
-  agent_name VARCHAR(255) NOT NULL,
-  status VARCHAR(50) DEFAULT 'active',
-  started_at TIMESTAMPTZ DEFAULT NOW(),
-  ended_at TIMESTAMPTZ,
-  end_marker JSONB,
-  metadata JSONB DEFAULT '{}'
-);
-
--- Agent summaries
-CREATE TABLE agent_summaries (
-  id UUID PRIMARY KEY,
-  session_id UUID NOT NULL REFERENCES agent_sessions(id),
-  agent_name VARCHAR(255) NOT NULL,
-  summary JSONB NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-```
-
----
-
-## Daemon Event Integration
-
-When using `AgentManager`, PtyWrapper events are automatically forwarded as daemon events:
-
-| PtyWrapper Event | Daemon Event | Description |
-|------------------|--------------|-------------|
-| `summary` | `agent:summary` | Agent output a summary block |
-| `session-end` | `agent:session-end` | Agent explicitly ended session |
-| `injection-failed` | `agent:injection-failed` | Message delivery failed |
-
-```typescript
-const manager = getAgentManager();
-
-// Optional: Enable cloud persistence
-manager.setCloudPersistence({
-  onSummary: async (agentId, event) => {
-    await db.saveSummary(agentId, event.summary);
-  },
-  onSessionEnd: async (agentId, event) => {
-    await db.endSession(agentId, event.marker);
-  },
-});
-
-// Daemon events are emitted to connected dashboard clients
-manager.on('event', (event) => {
-  if (event.type === 'agent:summary') {
-    broadcastToClients(event);
-  }
-});
-```
-
----
-
-## Event Flow Diagram
-
-```
-Agent Output
-    │
-    ▼
-┌───────────────┐
-│  PtyWrapper   │
-│ handleOutput()│
-└───────┬───────┘
-        │
-        ├──► emit('output', data)
-        │
-        ├──► parseRelayCommands()
-        │
-        ├──► checkForSummaryAndEmit()
-        │         │
-        │         ▼
-        │    emit('summary', event)
-        │         │
-        │         ▼
-        │    CloudPersistenceService
-        │         │
-        │         ▼
-        │    PostgreSQL
-        │
-        └──► checkForSessionEndAndEmit()
-                  │
-                  ▼
-             emit('session-end', event)
-```
-
----
-
-## Best Practices
-
-1. **Always unbind on cleanup** - Call `persistence.unbindFromPtyWrapper(pty)` or the listeners will leak
-
-2. **Use resetSessionState() for reuse** - If reusing a wrapper instance, call `pty.resetSessionState()` to clear session-specific state
-
-3. **Handle async errors** - Event handlers for `summary` and `session-end` can be async, but errors should be caught
-
-4. **Deduplication is automatic** - PtyWrapper deduplicates summary events based on content, preventing repeated persistence of the same summary
-
----
-
-## Environment Variables
-
-Configure PtyWrapper and cloud persistence behavior via environment variables:
-
-### Summary Reminders
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `RELAY_SUMMARY_REMINDER_ENABLED` | `true` | Set to `false` to disable automatic summary reminders |
-| `RELAY_SUMMARY_INTERVAL_MINUTES` | `15` | Minutes of activity before injecting a summary reminder |
-| `RELAY_SUMMARY_MIN_OUTPUTS` | `50` | Minimum significant outputs before reminding |
-
-Example:
-```bash
-# Remind every 30 minutes after 100 outputs
-export RELAY_SUMMARY_INTERVAL_MINUTES=30
-export RELAY_SUMMARY_MIN_OUTPUTS=100
-
-# Disable reminders entirely
-export RELAY_SUMMARY_REMINDER_ENABLED=false
-```
-
-### Cloud Persistence (Pro+ Feature)
-
-> **Note:** Session persistence is a premium feature requiring Pro plan or higher.
-> In cloud deployments, access is enforced at the organization level via `canUseSessionPersistence()`.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `RELAY_CLOUD_ENABLED` | `false` | Set to `true` to enable cloud persistence (for local dev/testing) |
-| `RELAY_WORKSPACE_ID` | Auto-generated | UUID for workspace scoping (auto-generated from project path if not set) |
-| `DATABASE_URL` | Required | PostgreSQL connection string (required when cloud enabled) |
-
-**Local Development:**
-```bash
-# Enable cloud persistence for local testing
-export RELAY_CLOUD_ENABLED=true
-export DATABASE_URL=postgresql://user:pass@localhost:5432/relay
-export RELAY_WORKSPACE_ID=550e8400-e29b-41d4-a716-446655440000
-```
-
-**Cloud Deployment:**
-In cloud deployments, the `RELAY_CLOUD_ENABLED` env var is not used.
-Instead, session persistence is enabled per-organization based on subscription:
-- **Free plan:** Not available
-- **Pro+ plans:** Session persistence enabled
-
-### Priority
-
-Environment variables take precedence over programmatic config:
-1. Environment variable (highest priority)
-2. `PtyWrapperConfig.summaryReminder` option
-3. Default values (lowest priority)

package/docs/agent-policy-snippet.md

@@ -1,40 +0,0 @@
-# Agent Policy
-
-You are operating under organizational agent policies. These policies govern your interactions with other agents and tools.
-
-## Your Permissions
-
-Check the policy service for your specific permissions. If no explicit restrictions are defined, you have full permissions.
-
-## General Rules
-
-1. **Spawn Authorization**: Only spawn agents you are authorized to spawn. Check with Lead before spawning if unsure.
-
-2. **Message Routing**: Only message agents you are authorized to communicate with. Use proper channels.
-
-3. **Tool Usage**: Only use tools you are authorized to use. Read-only operations are generally safer.
-
-4. **Rate Limits**: Respect rate limits on messages. Don't spam other agents.
-
-## Restricted Agents
-
-Workers and non-lead agents typically have these restrictions:
-- Cannot spawn other agents without Lead approval
-- Can only message Lead, Coordinator, and their assigned peers
-- Limited to read-only tools unless explicitly granted write access
-
-## Lead Agents
-
-Lead agents typically have elevated permissions:
-- Can spawn Worker agents
-- Can message all agents
-- Can use all tools
-- Responsible for enforcing policy on spawned agents
-
-## Enforcement
-
-Policy violations are blocked at runtime. If your action is blocked, you'll receive a denial message explaining why. Do not attempt to circumvent policy restrictions.
-
-## Checking Your Policy
-
-To see your current policy, ask Lead or check the dashboard at `/api/policy/:workspaceId`.