agent-relay 1.1.0 → 1.2.3

package/dist/bridge/spawner.js

@@ -10,6 +10,19 @@ import { getProjectPaths } from '../utils/project-namespace.js';
 import { resolveCommand } from '../utils/command-resolver.js';
 import { PtyWrapper } from '../wrapper/pty-wrapper.js';
 import { selectShadowCli } from './shadow-cli.js';
+import { AgentPolicyService } from '../policy/agent-policy.js';
+/**
+ * Get a minimal relay reminder.
+ * Agents already have full relay docs via CLAUDE.md - this is just a brief reminder.
+ * Loading full docs (400+ lines) overwhelms agents and causes "meandering".
+ */
+function getMinimalRelayReminder() {
+    return `# Quick Relay Reference
+- Send: \`->relay:Name <<<message>>>\`
+- ACK tasks, send DONE when complete
+- Use \`trail start/decision/complete\` for trajectories
+- Output \`[[SESSION_END]]..[[/SESSION_END]]\` when done`;
+}
 export class AgentSpawner {
     activeWorkers = new Map();
     agentsPath;
@@ -18,6 +31,10 @@ export class AgentSpawner {
     logsDir;
     workersPath;
     dashboardPort;
+    onAgentDeath;
+    cloudPersistence;
+    policyService;
+    policyEnforcementEnabled = false;
     constructor(projectRoot, _tmuxSession, dashboardPort) {
         const paths = getProjectPaths(projectRoot);
         this.projectRoot = paths.projectRoot;
@@ -28,19 +45,111 @@ export class AgentSpawner {
         this.dashboardPort = dashboardPort;
         // Ensure logs directory exists
         fs.mkdirSync(this.logsDir, { recursive: true });
+        // Initialize policy service if enforcement is enabled
+        if (process.env.AGENT_POLICY_ENFORCEMENT === '1') {
+            this.policyEnforcementEnabled = true;
+            this.policyService = new AgentPolicyService({
+                projectRoot: this.projectRoot,
+                workspaceId: process.env.WORKSPACE_ID,
+                strictMode: process.env.AGENT_POLICY_STRICT === '1',
+            });
+            console.log('[spawner] Policy enforcement enabled');
+        }
+    }
+    /**
+     * Set cloud policy fetcher for workspace-level policies
+     */
+    setCloudPolicyFetcher(fetcher) {
+        if (this.policyService) {
+            // Recreate policy service with cloud fetcher
+            this.policyService = new AgentPolicyService({
+                projectRoot: this.projectRoot,
+                workspaceId: process.env.WORKSPACE_ID,
+                cloudFetcher: fetcher,
+                strictMode: process.env.AGENT_POLICY_STRICT === '1',
+            });
+        }
+    }
+    /**
+     * Get the policy service (for external access to policy checks)
+     */
+    getPolicyService() {
+        return this.policyService;
     }
     /**
      * Set the dashboard port (for nested spawn API calls).
      * Called after the dashboard server starts and we know the actual port.
      */
     setDashboardPort(port) {
+        console.log(`[spawner] Dashboard port set to ${port} - nested spawns now enabled`);
         this.dashboardPort = port;
     }
+    /**
+     * Set callback for agent death notifications.
+     * Called when an agent exits unexpectedly (non-zero exit code).
+     */
+    setOnAgentDeath(callback) {
+        this.onAgentDeath = callback;
+    }
+    /**
+     * Set cloud persistence handler for forwarding PtyWrapper events.
+     * When set, 'summary' and 'session-end' events from spawned agents
+     * are forwarded to the handler for cloud persistence (PostgreSQL/Redis).
+     *
+     * Note: Enable via RELAY_CLOUD_ENABLED=true environment variable.
+     */
+    setCloudPersistence(handler) {
+        this.cloudPersistence = handler;
+        console.log('[spawner] Cloud persistence handler set');
+    }
+    /**
+     * Bind cloud persistence event handlers to a PtyWrapper.
+     * Returns the listener references for cleanup.
+     */
+    bindCloudPersistenceEvents(name, pty) {
+        if (!this.cloudPersistence)
+            return {};
+        const summaryListener = async (event) => {
+            try {
+                await this.cloudPersistence.onSummary(name, event);
+            }
+            catch (err) {
+                console.error(`[spawner] Cloud persistence summary error for ${name}:`, err);
+            }
+        };
+        const sessionEndListener = async (event) => {
+            try {
+                await this.cloudPersistence.onSessionEnd(name, event);
+            }
+            catch (err) {
+                console.error(`[spawner] Cloud persistence session-end error for ${name}:`, err);
+            }
+        };
+        pty.on('summary', summaryListener);
+        pty.on('session-end', sessionEndListener);
+        return { summary: summaryListener, sessionEnd: sessionEndListener };
+    }
+    /**
+     * Unbind all tracked listeners from a PtyWrapper.
+     */
+    unbindListeners(pty, listeners) {
+        if (!listeners)
+            return;
+        if (listeners.output) {
+            pty.off('output', listeners.output);
+        }
+        if (listeners.summary) {
+            pty.off('summary', listeners.summary);
+        }
+        if (listeners.sessionEnd) {
+            pty.off('session-end', listeners.sessionEnd);
+        }
+    }
     /**
      * Spawn a new worker agent using node-pty
      */
     async spawn(request) {
-        const { name, cli, task, team } = request;
+        const { name, cli, task, team, spawnerName } = request;
         const debug = process.env.DEBUG_SPAWN === '1';
         // Check if worker already exists
         if (this.activeWorkers.has(name)) {
@@ -50,6 +159,22 @@ export class AgentSpawner {
                 error: `Worker ${name} already exists`,
             };
         }
+        // Policy enforcement: check if the spawner is authorized to spawn this agent
+        if (this.policyEnforcementEnabled && this.policyService && spawnerName) {
+            const decision = await this.policyService.canSpawn(spawnerName, name, cli);
+            if (!decision.allowed) {
+                console.warn(`[spawner] Policy blocked spawn: ${spawnerName} -> ${name}: ${decision.reason}`);
+                return {
+                    success: false,
+                    name,
+                    error: `Policy denied: ${decision.reason}`,
+                    policyDecision: decision,
+                };
+            }
+            if (debug) {
+                console.log(`[spawner:debug] Policy allowed spawn: ${spawnerName} -> ${name} (source: ${decision.policySource})`);
+            }
+        }
         try {
             // Parse CLI command
             const cliParts = cli.split(' ');
@@ -76,13 +201,19 @@ export class AgentSpawner {
                 console.log(`[spawner:debug] Spawning ${name} with: ${command} ${args.join(' ')}`);
             // Create PtyWrapper config
             // Use dashboardPort for nested spawns (API-based, works in non-TTY contexts)
-            // Fall back to callbacks only if no dashboardPort is set
+            // Fall back to callbacks only if no dashboardPort is not set
+            // Note: Spawned agents CAN spawn sub-workers intentionally - the parser is strict enough
+            // to avoid accidental spawns from documentation text (requires line start, PascalCase, known CLI)
+            // Use request.cwd if specified, otherwise use projectRoot
+            const agentCwd = request.cwd || this.projectRoot;
+            // Log whether nested spawning will be enabled for this agent
+            console.log(`[spawner] Spawning ${name}: dashboardPort=${this.dashboardPort || 'none'} (${this.dashboardPort ? 'nested spawns enabled' : 'nested spawns disabled'})`);
             const ptyConfig = {
                 name,
                 command,
                 args,
                 socketPath: this.socketPath,
-                cwd: this.projectRoot,
+                cwd: agentCwd,
                 logsDir: this.logsDir,
                 dashboardPort: this.dashboardPort,
                 // Shadow agent configuration
@@ -109,20 +240,52 @@ export class AgentSpawner {
                 onExit: (code) => {
                     if (debug)
                         console.log(`[spawner:debug] Worker ${name} exited with code ${code}`);
+                    // Get the agentId and clean up listeners before removing from active workers
+                    const worker = this.activeWorkers.get(name);
+                    const agentId = worker?.pty?.getAgentId?.();
+                    if (worker?.listeners) {
+                        this.unbindListeners(worker.pty, worker.listeners);
+                    }
                     this.activeWorkers.delete(name);
-                    this.saveWorkersMetadata();
+                    try {
+                        this.saveWorkersMetadata();
+                    }
+                    catch (err) {
+                        console.error(`[spawner] Failed to save metadata on exit:`, err);
+                    }
+                    // Notify if agent died unexpectedly (non-zero exit)
+                    if (code !== 0 && code !== null && this.onAgentDeath) {
+                        this.onAgentDeath({
+                            name,
+                            exitCode: code,
+                            agentId,
+                            resumeInstructions: agentId
+                                ? `To resume this agent's work, use: --resume ${agentId}`
+                                : undefined,
+                        });
+                    }
                 },
             };
             // Create and start the pty wrapper
             const pty = new PtyWrapper(ptyConfig);
+            // Track listener references for proper cleanup
+            const listeners = {};
             // Hook up output events for live log streaming
-            pty.on('output', (data) => {
+            const outputListener = (data) => {
                 // Broadcast to any connected WebSocket clients via global function
                 const broadcast = global.__broadcastLogOutput;
                 if (broadcast) {
                     broadcast(name, data);
                 }
-            });
+            };
+            pty.on('output', outputListener);
+            listeners.output = outputListener;
+            // Bind cloud persistence events (if enabled) and store references
+            const cloudListeners = this.bindCloudPersistenceEvents(name, pty);
+            if (cloudListeners.summary)
+                listeners.summary = cloudListeners.summary;
+            if (cloudListeners.sessionEnd)
+                listeners.sessionEnd = cloudListeners.sessionEnd;
             await pty.start();
             if (debug)
                 console.log(`[spawner:debug] PTY started, pid: ${pty.pid}`);
@@ -131,18 +294,37 @@ export class AgentSpawner {
             if (!registered) {
                 const error = `Worker ${name} failed to register within 30s`;
                 console.error(`[spawner] ${error}`);
-                pty.kill();
+                await pty.kill();
                 return {
                     success: false,
                     name,
                     error,
                 };
             }
+            // Build the full message: minimal relay reminder + policy instructions (if any) + task
+            let fullMessage = task || '';
+            // Prepend a brief relay reminder (agents have full docs via CLAUDE.md)
+            // Note: Previously loaded full 400+ line docs which overwhelmed agents
+            const relayReminder = getMinimalRelayReminder();
+            if (relayReminder) {
+                fullMessage = `${relayReminder}\n\n---\n\n${fullMessage}`;
+                if (debug)
+                    console.log(`[spawner:debug] Prepended relay reminder for ${name}`);
+            }
+            // Prepend policy instructions if enforcement is enabled
+            if (this.policyEnforcementEnabled && this.policyService) {
+                const policyInstruction = await this.policyService.getPolicyInstruction(name);
+                if (policyInstruction) {
+                    fullMessage = `${policyInstruction}\n\n${fullMessage}`;
+                    if (debug)
+                        console.log(`[spawner:debug] Prepended policy instructions to task for ${name}`);
+                }
+            }
             // Send task via relay message if provided (not via direct PTY injection)
             // This ensures the agent is ready to receive before processing the task
-            if (task && task.trim()) {
+            if (fullMessage && fullMessage.trim()) {
                 if (debug)
-                    console.log(`[spawner:debug] Will send task via relay: ${task.substring(0, 50)}...`);
+                    console.log(`[spawner:debug] Will send task via relay: ${fullMessage.substring(0, 50)}...`);
                 // If we have dashboard API, send task as relay message
                 if (this.dashboardPort) {
                     // Wait a moment for the agent's relay client to be ready
@@ -153,7 +335,7 @@ export class AgentSpawner {
                             headers: { 'Content-Type': 'application/json' },
                             body: JSON.stringify({
                                 to: name,
-                                message: task,
+                                message: fullMessage,
                                 from: '__spawner__',
                             }),
                         });
@@ -165,19 +347,19 @@ export class AgentSpawner {
                         else {
                             console.warn(`[spawner] Failed to send task via relay: ${result.error}`);
                             // Fall back to direct injection
-                            pty.write(task + '\r');
+                            pty.write(fullMessage + '\r');
                         }
                     }
                     catch (err) {
                         console.warn(`[spawner] Relay send failed, falling back to direct injection: ${err.message}`);
-                        pty.write(task + '\r');
+                        pty.write(fullMessage + '\r');
                     }
                 }
                 else {
                     // No dashboard API available - use direct injection as fallback
                     if (debug)
                         console.log(`[spawner:debug] No dashboard API, using direct injection`);
-                    pty.write(task + '\r');
+                    pty.write(fullMessage + '\r');
                 }
             }
             // Track the worker
@@ -190,6 +372,7 @@ export class AgentSpawner {
                 pid: pty.pid,
                 pty,
                 logFile: pty.logPath,
+                listeners, // Store for cleanup
             };
             this.activeWorkers.set(name, workerInfo);
             this.saveWorkersMetadata();
@@ -334,13 +517,13 @@ export class AgentSpawner {
             return false;
         }
         try {
-            // Stop the pty process gracefully
-            worker.pty.stop();
-            // Wait for graceful shutdown
-            await sleep(2000);
+            // Unbind all listeners first to prevent memory leaks
+            this.unbindListeners(worker.pty, worker.listeners);
+            // Stop the pty process gracefully (handles auto-save internally)
+            await worker.pty.stop();
             // Force kill if still running
             if (worker.pty.isRunning) {
-                worker.pty.kill();
+                await worker.pty.kill();
             }
             this.activeWorkers.delete(name);
             this.saveWorkersMetadata();
@@ -349,7 +532,8 @@ export class AgentSpawner {
         }
         catch (err) {
             console.error(`[spawner] Failed to release ${name}:`, err.message);
-            // Still remove from tracking
+            // Still unbind and remove from tracking
+            this.unbindListeners(worker.pty, worker.listeners);
             this.activeWorkers.delete(name);
             this.saveWorkersMetadata();
             return false;

package/dist/bridge/types.d.ts

@@ -37,6 +37,10 @@ export interface SpawnRequest {
     task: string;
     /** Optional team name to organize agents under */
     team?: string;
+    /** Working directory for the agent (defaults to detected workspace) */
+    cwd?: string;
+    /** Name of the agent requesting the spawn (for policy enforcement) */
+    spawnerName?: string;
     /** Shadow execution mode (subagent = no extra process) */
     shadowMode?: 'subagent' | 'process';
     /** Primary agent to shadow (if this agent is a shadow) */
@@ -48,12 +52,20 @@ export interface SpawnRequest {
     /** When the shadow should speak (default: ['EXPLICIT_ASK']) */
     shadowSpeakOn?: Array<'SESSION_END' | 'CODE_WRITTEN' | 'REVIEW_REQUEST' | 'EXPLICIT_ASK' | 'ALL_MESSAGES'>;
 }
+/** Policy decision details */
+export interface PolicyDecision {
+    allowed: boolean;
+    reason: string;
+    policySource: 'repo' | 'local' | 'workspace' | 'default';
+}
 export interface SpawnResult {
     success: boolean;
     name: string;
     /** PID of the spawned process (for pty-based workers) */
     pid?: number;
     error?: string;
+    /** Policy decision details if spawn was blocked by policy */
+    policyDecision?: PolicyDecision;
 }
 export interface WorkerInfo {
     name: string;