Skip to content

cos-agent-runner.md

Latest commit

 

History

History
45 lines (34 loc) · 2.19 KB

cos-agent-runner.md

File metadata and controls

45 lines (34 loc) · 2.19 KB

CoS Agent Runner

Isolated PM2 process for spawning Claude CLI agents, preventing orphaned processes when portos-server restarts.

Problem

When multiple CoS agents are running and the main portos-server restarts (due to code changes, crashes, or manual restart), child processes spawned via child_process.spawn() become orphaned. The parent loses track of them because the activeAgents Map is in memory.

Solution

A separate portos-cos PM2 process that:

  1. Runs independently from portos-server
  2. Manages agent spawning via HTTP/Socket.IO bridge
  3. Doesn't restart when portos-server restarts
  4. Maintains its own state file for PID tracking

Architecture

┌─────────────────┐     HTTP/Socket.IO    ┌─────────────────┐
│  portos-server  │ ──────────────────►   │   portos-cos    │
│    (5555)       │     spawn/terminate   │     (5558)      │
│                 │ ◄──────────────────   │                 │
│  subAgentSpawner│     events/output     │  cos-runner     │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                                   │ spawn
                                                   ▼
                                          ┌───────────────┐
                                          │  Claude CLI   │
                                          │   Processes   │
                                          └───────────────┘

Features

  • Process Isolation: Agent processes survive server restarts
  • State Persistence: PIDs tracked in state file for recovery
  • Bridge Communication: HTTP/Socket.IO for cross-process messaging
  • Orphan Detection: Automatic cleanup of orphaned agent processes

Related Features