agent-relay 1.0.22 → 1.2.0

package/docs/WRAPPER_EVENTS.md

@@ -0,0 +1,358 @@
+# 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

@@ -0,0 +1,40 @@
+# 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`.

package/docs/agent-relay-protocol.md

@@ -0,0 +1,238 @@
+# Agent Relay Protocol (Internal)
+
+Advanced agent-relay features for dashboard integration, session persistence, and trajectory tracking.
+
+## Session Persistence (Required)
+
+Output these blocks to maintain session state. **The system monitors your output for these patterns.**
+
+### Progress Summary (Output Periodically)
+
+When completing significant work, output a summary block:
+
+```
+[[SUMMARY]]
+{
+  "currentTask": "What you're working on now",
+  "completedTasks": ["task1", "task2"],
+  "context": "Important context for session recovery",
+  "files": ["src/file1.ts", "src/file2.ts"]
+}
+[[/SUMMARY]]
+```
+
+**When to output:**
+- After completing a major task
+- Before long-running operations
+- When switching to a different area of work
+- Every 10-15 minutes of active work
+
+### Session End (Required on Completion)
+
+When your work session is complete, output:
+
+```
+[[SESSION_END]]
+{
+  "summary": "Brief description of what was accomplished",
+  "completedTasks": ["task1", "task2", "task3"]
+}
+[[/SESSION_END]]
+```
+
+Or for a simple close: `[[SESSION_END]]Work complete.[[/SESSION_END]]`
+
+**This enables:**
+- Session recovery if connection drops
+- Progress tracking in dashboard
+- Proper session cleanup in cloud
+
+## Session Continuity (Cross-Session)
+
+Output `->continuity:` patterns to persist state across sessions. This is different from `[[SUMMARY]]` blocks - continuity creates permanent records that survive agent restarts.
+
+### Save Session State
+
+Save your current state to the ledger:
+
+```
+->continuity:save <<<
+Current task: Implementing user authentication
+Completed: User model, JWT utils, Login endpoint
+In progress: Logout endpoint, Token refresh
+Key decisions: Using refresh tokens for security
+Files: src/auth/jwt.ts:10-50, src/models/user.ts>>>
+```
+
+To also create a permanent handoff document (recommended before long operations):
+
+```
+->continuity:save --handoff <<<
+Current task: Implementing auth module
+Completed: User model, JWT utils
+Next steps: Login endpoint, Session middleware
+Key decisions: JWT with refresh tokens, bcrypt for passwords
+Files: src/auth/*.ts>>>
+```
+
+### Load Previous Context
+
+Request your previous session context (auto-loaded on startup, but can request manually):
+
+```
+->continuity:load
+```
+
+### Search Past Work
+
+Search across all previous handoffs:
+
+```
+->continuity:search "authentication patterns"
+->continuity:search "database migration"
+```
+
+### Mark Uncertain Items
+
+Flag items that need verification in future sessions:
+
+```
+->continuity:uncertain "API rate limit handling unclear"
+```
+
+### When to Save
+
+**Always save before:**
+- Long-running operations (builds, tests, deployments)
+- Context-heavy operations (might trigger compaction)
+- Switching to a different task area
+- Taking a break or ending session
+
+**Good rhythm:**
+- Save progress every 15-20 minutes of active work
+- Use `--handoff` flag for major milestones
+- Mark uncertainties as you encounter them
+
+## Work Trajectories (Required)
+
+**Trajectory recording is MANDATORY for all agent work sessions.** Use Trail to record your work as a trajectory for future agents and humans to follow.
+
+### Enforcement
+
+Trajectories are enforced via hooks:
+- **onSessionStart** → Automatically calls `trail start` with task context
+- **onSessionEnd** → Prompts for `trail complete` if trajectory is open
+
+If hooks are not configured, you MUST manually call trail commands. Failure to record trajectories results in lost context for future agents.
+
+### When Starting Work
+
+**REQUIRED: Call `trail start` BEFORE diving into implementation** - this captures your full journey, not just the end result.
+
+Start a trajectory immediately when picking up a task:
+
+```bash
+trail start "Implement user authentication"
+```
+
+With external task reference (beads ID, ticket number):
+```bash
+trail start "Fix login bug" --task "agent-relay-123"
+```
+
+### Recording Decisions
+
+Record key decisions as you work:
+
+```bash
+trail decision "Chose JWT over sessions" \
+  --reasoning "Stateless scaling requirements"
+```
+
+For minor decisions, reasoning is optional:
+```bash
+trail decision "Used existing auth middleware"
+```
+
+**Record decisions when you:**
+- Choose between alternatives
+- Make architectural trade-offs
+- Decide on an approach after investigation
+
+### Completing Work
+
+**REQUIRED: Always close your trajectory before ending a session.** When done, complete with a retrospective:
+
+```bash
+trail complete --summary "Added JWT auth with refresh tokens" --confidence 0.85
+```
+
+**Confidence levels:**
+- 0.9+ : High confidence, well-tested
+- 0.7-0.9 : Good confidence, standard implementation
+- 0.5-0.7 : Some uncertainty, edge cases possible
+- <0.5 : Significant uncertainty, needs review
+
+### Abandoning Work
+
+If you need to stop without completing:
+
+```bash
+trail abandon --reason "Blocked by missing API credentials"
+```
+
+### Checking Status
+
+View current trajectory:
+```bash
+trail status
+```
+
+### Why Trail?
+
+Your trajectory helps others understand:
+- **What** you built (commits show this)
+- **Why** you built it this way (trajectory shows this)
+- **What alternatives** you considered
+- **What challenges** you faced
+
+Future agents can query past trajectories to learn from your decisions.
+
+## Cross-Project Messaging
+
+When running in bridge mode (multiple projects connected), use `project:agent` format:
+
+```
+->relay:frontend:Designer <<<
+Please update the login UI for the new auth flow>>>
+
+->relay:backend:lead <<<
+API question - should we use REST or GraphQL?>>>
+
+->relay:shared-lib:* <<<
+New utility functions available, please pull latest>>>
+```
+
+**Format:** `->relay:project-id:agent-name`
+
+**Special targets:**
+- `->relay:project:lead` - Message the lead agent of that project
+- `->relay:project:*` - Broadcast to all agents in that project
+- `->relay:*:*` - Broadcast to ALL agents in ALL projects
+
+**Cross-project threads:**
+```
+->relay:frontend:Designer [thread:auth-feature] <<<
+UI mockups ready for review>>>
+```
+
+## Dashboard Integration
+
+The dashboard automatically tracks:
+- Agent presence and online status
+- Message history and threads
+- Session summaries from `[[SUMMARY]]` blocks
+- Trajectory status from trail commands
+- Coordinator panel for multi-agent orchestration
+
+Agents can view their status at the dashboard URL provided at startup.