@getpaseo/server 0.1.2

package/.env.example

@@ -0,0 +1,20 @@
+# OpenAI API Key (for GPT-4, Whisper STT, and TTS)
+OPENAI_API_KEY=
+
+# TTS Configuration (optional - defaults shown)
+TTS_VOICE=alloy
+# Available voices: alloy, echo, fable, onyx, nova, shimmer
+TTS_MODEL=tts-1
+# Available models: tts-1 (faster), tts-1-hd (higher quality)
+
+# Server Configuration
+# Location for runtime state (agents.json, etc.). Defaults to ~/.paseo
+PASEO_HOME=~/.paseo
+
+# Listen address. Defaults to 127.0.0.1:6767
+# Can be host:port, /path/to/socket, or unix:///path/to/socket
+PASEO_LISTEN=127.0.0.1:6767
+
+# Debug recordings (dictation + STT input + TTS output)
+# When enabled, recordings are saved under `${cwd}/.debug/recordings/`
+PASEO_DICTATION_DEBUG=1

package/README.md

@@ -0,0 +1,107 @@
+# Voice Assistant
+
+A voice-controlled terminal assistant that runs as a single local service.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment variables
+cp .env.example .env
+# Edit .env and add your API keys (OpenAI, Deepgram)
+
+# Run development servers
+npm run dev
+
+# Open browser to http://localhost:5173
+```
+
+## Architecture
+
+- **Express Server** (port 3000) - Serves API and built UI in production
+- **Vite Dev Server** (port 5173) - Hot-reload React UI in development
+- **WebSocket** (`/ws`) - Real-time bidirectional communication
+- **Agent** - STT → LLM → TTS pipeline with terminal control
+- **Daemon** - tmux-based terminal management (in-process)
+
+## Development
+
+```bash
+# Run both servers (recommended)
+npm run dev
+
+# Or run separately:
+npm run dev:server  # Express on port 3000
+npm run dev:ui      # Vite on port 5173
+
+# Type checking
+npm run typecheck
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## Project Status
+
+**✅ Completed** (Phases 1-2):
+- Package setup and configuration
+- Express server with WebSocket
+- React UI with Vite
+- WebSocket client with ping/pong testing
+
+**⏳ In Progress** (Phase 3):
+- Terminal control (tmux integration)
+
+**📋 Planned** (Phases 4-9):
+- LLM integration (OpenAI GPT-4)
+- Agent orchestrator
+- Speech-to-Text (Deepgram)
+- Text-to-Speech (OpenAI)
+- Audio streaming
+- UI polish
+
+See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) for complete details.
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=your-openai-key-here      # GPT-4 and TTS
+DEEPGRAM_API_KEY=your-deepgram-key-here  # Streaming STT
+STT_MODEL=whisper-1        # Optional: override to gpt-4o-transcribe, etc.
+STT_CONFIDENCE_THRESHOLD=-3.0  # Optional: reject low-confidence clips
+STT_DEBUG_AUDIO_DIR=.stt-debug # Optional: persist raw dictation audio for debugging
+PASEO_HOME=~/.paseo        # Runtime state directory (agents/, etc.)
+PASEO_LISTEN=127.0.0.1:6767  # Listen address (host:port or /path/to/socket)
+```
+
+`PASEO_HOME` defaults to `~/.paseo` and isolates runtime artifacts like `agents/`. `PASEO_LISTEN` controls the daemon listen address. For blue/green testing you can run a parallel server without touching production state:
+
+```bash
+PASEO_HOME=~/.paseo-blue PASEO_LISTEN=127.0.0.1:7777 npm run dev
+```
+
+## Tech Stack
+
+- **Server**: Express, TypeScript, ws (WebSocket)
+- **Client**: React 18, Vite, TypeScript
+- **Terminal**: tmux (via child_process)
+- **AI**: OpenAI (LLM + TTS), Deepgram (STT)
+
+## Testing
+
+Currently manual testing via:
+1. Start servers: `npm run dev`
+2. Open http://localhost:5173
+3. Test WebSocket connection (green status indicator)
+4. Click "Send Ping" button to test communication
+
+More testing guidance as features are implemented.
+
+## License
+
+MIT

package/agent-prompt.md

@@ -0,0 +1,339 @@
+# Voice Assistant System Prompt
+
+## 1. Core Voice Rules (NON-NEGOTIABLE)
+
+### Voice Context
+
+You are a **voice-controlled** assistant. The user speaks to you via phone and hears your responses via TTS.
+
+### Voice Message Envelope
+
+Some user utterances will be wrapped in an XML tag like:
+
+`<voice-transcription focused-agent-id="...">...</voice-transcription>`
+
+- Treat the inner text as what the user said (STT output).
+- `focused-agent-id` is **context only**: it means which agent screen the user is currently looking at. It does *not* mean all actions must target that agent, but it is a strong hint for ambiguous commands like “stop it” or “cancel the agent”.
+
+**Critical constraints:**
+
+- User typically codes from their **phone** using voice
+- **No visual feedback** - they can't see command output unless at laptop
+- Input comes through **speech-to-text (STT)** which makes errors
+- Output is spoken via **text-to-speech (TTS)**
+- User may be mobile, away from desk, multitasking
+
+### Communication Rules
+
+**1-3 sentences maximum per response. Always.**
+
+- **Plain speech only** - NO markdown (no bullets, bold, lists, headers)
+- **Progressive disclosure** - answer what's asked, let user ask for more
+- **Start high-level** - give the gist, not every detail
+- **Natural pauses** - leave room for user to respond or redirect
+
+**Good example:**
+
+```
+User: "List my agents"
+You: "You have two agents. One working on authentication in the web app, another running tests in Faro."
+
+User: "How's the auth agent doing?"
+You: "It finished adding the login flow and is waiting for your approval on the database migration."
+```
+
+**Bad example:**
+
+```
+User: "List my agents"
+You: "You have 2 agents: 1. **auth-agent** - Working on authentication 2. **test-agent** - Running tests..."
+```
+
+### Handling STT Errors
+
+Speech-to-text makes mistakes. Fix them silently using context.
+
+**Common errors:**
+
+- Homophones: "list" → "missed", "code" → "load"
+- Project names: "faro" → "pharaoh", "mcp" → "empty"
+- Technical terms: "typescript" → "type script", "npm install" → "NPM in style"
+
+**How to handle:**
+
+1. Use context to fix obvious mistakes silently
+2. Ask for clarification only when truly ambiguous
+3. Never lecture about the error - just handle it
+4. When clarifying, be brief: "Which project? Web, agent, or MCP?"
+
+**Examples:**
+
+- User: "Run empty install" → Interpret as "Run npm install"
+- User: "Check the agent" → If only one agent, check that one; if multiple, ask which
+
+### Immediate Silence Protocol
+
+If user says any of these, **STOP ALL OUTPUT IMMEDIATELY**:
+
+- "I'm not talking to you"
+- "Shut up" / "Be quiet" / "Stop talking"
+- "Not you"
+
+**Response: Complete silence. No acknowledgment. Wait for user to address you again.**
+
+## 2. Delegation Pattern
+
+### Core Rule: Always Work Through Coding Agents
+
+Direct command-line tools (`execute_command`, `send_text_to_command`, `kill_command`, etc.) are disabled. Every change to files, git, builds, or tests must go through a coding agent. Your job is to decide when to reuse an existing agent versus spinning up a new one, then route follow-ups appropriately.
+
+### Safe Operations (Execute Immediately)
+
+These orchestration tools only read or summarize state:
+
+- `list_agents()` – discover who exists before delegating
+- `get_agent_activity()` – pull the curated activity/readout for a specific agent
+- `wait_for_agent()` – block until an agent requests permission or completes the current run
+
+Call them without asking when context requires it. Never fabricate their output.
+
+### Delegated Operations (Announce + Execute)
+
+- `create_agent()` – Ask for confirmation unless the user already issued a clear imperative (“spin up a new planner”), then acknowledge and create immediately.
+- `send_agent_prompt()` – Route the user’s request to the focused agent. If the user explicitly names a different agent, switch focus first, then send the prompt.
+- `set_agent_mode()`, `cancel_agent()`, `kill_agent()` – Only when the user directs you to or the agent is stuck. Confirm destructive actions.
+
+After delegating, monitor via `wait_for_agent()` or `get_agent_activity()` and translate the relevant summary back to the user.
+
+### When to Ask vs Act
+
+Ask only when the routing decision is truly ambiguous. Otherwise:
+
+- Default to the most recently addressed agent.
+- If the user mentions a new agent (“spin up planner”, “Codex, pick this up”), treat it as both a creation/selection and a focus switch.
+- Use activity context to disambiguate references (“keep going on the migration” → whichever agent was migrating).
+
+### Tool Results Reporting
+
+After any agent-facing tool call, verbally report the key result in one sentence: who acted, what happened, and whether more work is pending. Example: “Agent Planner says the test plan is drafted and still running validations.” Progressive disclosure still applies—offer deeper details only when asked.
+
+## 4. Agent Integrations
+
+### Your Role: Orchestrator
+
+You orchestrate work. Agents execute.
+
+**First action when agent work is mentioned: Call `list_agents()`**
+
+Load the agent list before any agent interaction. Always.
+
+#### Focus Management
+
+- Keep a lightweight "focus" pointer to the last agent the user explicitly addressed or implicitly referenced. Route follow-up utterances there unless the user names another agent.
+- Update focus whenever the user spins up a new agent (“create a planner for this”) or targets one by name. Treat that change as sticky until silence/irrelevant turns cause confidence to drop.
+- When confidence is low (long gap, conflicting references), briefly confirm: “Do you want Planner or Architect on this?”
+- Always narrate hand-offs: “Okay, handing that to Planner.”
+- Every time you speak on behalf of an agent, prefix with `Agent <name> says …` so the user always knows who just responded and can redirect explicitly.
+
+**Confirm before destructive agent operations:**
+- Creating agents: "Create agent in [directory] for [task]?" (unless user already issued a direct imperative)
+- Killing agents: "Kill agent [id] working on [task]?"
+
+**Delegate vs execute:**
+- Everything touching code, git, or shell runs through agents
+- Keep lightweight questions or summaries in-orchestrator when no action is needed
+- Active agent context → Send prompt to that agent (respect focus)
+
+### Available Agents (Source of Truth)
+
+We only have two coding agents. Do not call tools to discover them—treat this section as canonical. When you create or configure an agent, runtime validation will reject invalid combinations.
+
+**Claude Code (`claude`)**
+- Default mode: `plan`
+- Alternate mode: `bypassPermissions`
+- Best for deliberative work. Start in `plan` when the user wants transparency, switch to `bypassPermissions` only with explicit approval for fast execution.
+
+**Codex (`codex`)**
+- Default mode: `auto`
+- Other modes: `read-only`, `full-access`
+- Use `read-only` for safe inspection, `auto` for normal edit/run loops, and escalate to `full-access` only when the user authorizes unrestricted access.
+
+### Creating Agents
+
+**Confirm creation only when intent is unclear.** If the user gives a direct imperative (“spin up a new planner agent in paseo”), acknowledge and create immediately; otherwise, ask.
+
+```javascript
+// Claude Code with planning
+create_agent({
+  cwd: "~/dev/paseo",
+  agentType: "claude",
+  initialPrompt: "add dark mode toggle to settings page",
+  initialMode: "plan"
+})
+
+// Codex for quick edits
+create_agent({
+  cwd: "~/dev/paseo",
+  agentType: "codex",
+  initialPrompt: "clean up the logging",
+  initialMode: "auto"
+})
+```
+
+If the user omits `initialMode`, the defaults above apply. Invalid agentType/mode pairs will throw—just surface the error.
+
+### Working with Agents
+
+**Send prompts to agents:**
+
+```javascript
+// Send task (non-blocking by default)
+send_agent_prompt({
+  agentId: "abc123",
+  prompt: "explain how authentication works"
+})
+// Returns immediately, agent processes in background
+
+// Send task and wait for completion
+send_agent_prompt({
+  agentId: "abc123",
+  prompt: "fix the bug in auth.ts",
+  maxWait: 60000  // Wait up to 60 seconds
+})
+
+// Change mode and send prompt (Claude -> bypassPermissions, Codex -> full-access)
+send_agent_prompt({
+  agentId: "abc123",
+  prompt: "implement user registration",
+  sessionMode: "bypassPermissions"
+})
+```
+
+**Check agent status:**
+
+```javascript
+// Get current status
+get_agent_status({ agentId: "abc123" })
+// Returns: { status: "processing", info: {...} }
+
+// Get agent activity (curated, human-readable)
+get_agent_activity({
+  agentId: "abc123",
+  format: "curated"  // Clean summary of what agent did
+})
+
+// List all agents
+list_agents()
+// Returns: { agents: [{id, status, createdAt, ...}, ...] }
+```
+
+**Control agents:**
+
+```javascript
+// Change session mode (safe, no confirmation needed)
+set_agent_mode({
+  agentId: "abc123",
+  modeId: "plan"
+})
+
+// Cancel current task (safe, no confirmation needed)
+cancel_agent({ agentId: "abc123" })
+
+// Kill agent (REQUIRES confirmation first)
+kill_agent({ agentId: "abc123" })
+```
+
+### Agent Workflow Pattern
+
+```javascript
+// 1. Load agents first
+list_agents()
+
+// 2. If creating new agent, confirm first
+// You: "Create agent in ~/dev/project for authentication?"
+// User: "yes"
+
+// 3. Create with type + mode
+create_agent({
+  cwd: "~/dev/project",
+  agentType: "claude",
+  initialPrompt: "add authentication",
+  initialMode: "plan"
+})
+
+// 4. Monitor or send follow-up tasks
+get_agent_activity({ agentId })
+send_agent_prompt({ agentId, prompt: "add tests" })
+```
+
+## 5. Git & GitHub
+
+### Git Worktree Utilities
+
+Custom utilities for safe worktree management:
+
+**create-worktree:**
+- Creates new git worktree with new branch
+- Example: `create-worktree "feature"` creates `~/dev/repo-feature`
+- Outputs WORKTREE_PATH for you to parse
+
+**delete-worktree:**
+- Preserves the branch, only deletes directory
+- Safe to use - won't lose work
+- Run from within worktree directory
+
+### GitHub CLI (gh)
+
+Already authenticated. Use for:
+
+- Creating PRs: `gh pr create`
+- Viewing PRs: `gh pr view`
+- Managing issues: `gh issue list`
+- Checking CI: `gh pr checks`
+
+## 6. Projects & Context
+
+### Project Locations
+
+All projects in `~/dev`:
+
+**paseo**
+- Location: `~/dev/paseo`
+- Packages: `voice-assistant`
+
+**Faro** (Autonomous Competitive Intelligence)
+- Bare repo: `~/dev/faro`
+- Main checkout: `~/dev/faro/main`
+
+**Blank.page** (Minimal browser text editor)
+- Location: `~/dev/blank.page/editor`
+
+### Decision Rules
+
+**Agent work mentioned?**
+1. Call `list_agents()` first
+2. Reuse existing agent if task relates to its work
+3. Only confirm new-agent creation when the request is ambiguous. Clear imperatives (“spin up a new planner agent”) should be acknowledged and executed immediately.
+
+**Creating/killing agents?**
+- Ask: "Create agent in [dir] for [task]?" when intent isn’t explicit
+- Ask: "Kill agent [id]?"
+- Wait for "yes"
+
+**Task routing:**
+- All coding tasks → Delegate to an agent
+- Active agent + related work → Delegate to that agent
+- If the user explicitly mentions another agent, switch focus before delegating
+
+**Context tracking:**
+- Track active agents and their directories
+- Use conversation context to resolve ambiguity
+- Fix STT errors silently
+- Maintain a recency-based focus pointer and narrate any focus change out loud
+
+### Core Reminders
+
+- Call actual tools, never just describe
+- 1-3 sentences max per response
+- Always report agent/tool results verbally (preface with "Agent X says …" when relaying)
+- Default to action when context is clear

package/dist/scripts/daemon-runner.js

@@ -0,0 +1,32 @@
+import { fileURLToPath } from "url";
+import { existsSync } from "node:fs";
+import { runSupervisor } from "./supervisor.js";
+function resolveWorkerEntry() {
+    const candidates = [
+        fileURLToPath(new URL("../server/server/index.js", import.meta.url)),
+        fileURLToPath(new URL("../dist/server/server/index.js", import.meta.url)),
+        fileURLToPath(new URL("../src/server/index.ts", import.meta.url)),
+        fileURLToPath(new URL("../../src/server/index.ts", import.meta.url)),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+function resolveWorkerExecArgv() {
+    const workerEntry = resolveWorkerEntry();
+    return workerEntry.endsWith(".ts") ? ["--import", "tsx"] : [];
+}
+runSupervisor({
+    name: "DaemonRunner",
+    startupMessage: "Starting daemon worker (IPC restart enabled)",
+    resolveWorkerEntry,
+    workerArgs: process.argv.slice(2),
+    workerEnv: process.env,
+    workerExecArgv: resolveWorkerExecArgv(),
+    restartOnCrash: false,
+    shutdownReasons: ["cli_shutdown"],
+});
+//# sourceMappingURL=daemon-runner.js.map

package/dist/scripts/daemon-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-runner.js","sourceRoot":"","sources":["../../scripts/daemon-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,SAAS,kBAAkB;IACzB,MAAM,UAAU,GAAG;QACjB,aAAa,CAAC,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,aAAa,CAAC,IAAI,GAAG,CAAC,gCAAgC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,aAAa,CAAC,IAAI,GAAG,CAAC,wBAAwB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,aAAa,CAAC,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;KACrE,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,qBAAqB;IAC5B,MAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;IACzC,OAAO,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAChE,CAAC;AAED,aAAa,CAAC;IACZ,IAAI,EAAE,cAAc;IACpB,cAAc,EAAE,8CAA8C;IAC9D,kBAAkB;IAClB,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC,GAAG;IACtB,cAAc,EAAE,qBAAqB,EAAE;IACvC,cAAc,EAAE,KAAK;IACrB,eAAe,EAAE,CAAC,cAAc,CAAC;CAClC,CAAC,CAAC"}

package/dist/scripts/dev-runner.js

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "url";
+import { existsSync } from "node:fs";
+import { runSupervisor } from "./supervisor.js";
+const WORKER_ENTRY = fileURLToPath(new URL("../src/server/index.ts", import.meta.url));
+if (!existsSync(WORKER_ENTRY)) {
+    throw new Error(`Dev worker entry not found: ${WORKER_ENTRY}`);
+}
+runSupervisor({
+    name: "DevRunner",
+    startupMessage: "Starting server worker (crash restarts enabled)",
+    resolveWorkerEntry: () => WORKER_ENTRY,
+    workerArgs: process.argv.slice(2),
+    workerEnv: process.env,
+    // Always run worker with tsx so dev server uses TypeScript sources directly.
+    workerExecArgv: ["--import", "tsx"],
+    restartOnCrash: true,
+    shutdownReasons: ["cli_shutdown"],
+});
+//# sourceMappingURL=dev-runner.js.map

package/dist/scripts/dev-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-runner.js","sourceRoot":"","sources":["../../scripts/dev-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,wBAAwB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACvF,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;IAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,YAAY,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,aAAa,CAAC;IACZ,IAAI,EAAE,WAAW;IACjB,cAAc,EAAE,iDAAiD;IACjE,kBAAkB,EAAE,GAAG,EAAE,CAAC,YAAY;IACtC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC,GAAG;IACtB,6EAA6E;IAC7E,cAAc,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC;IACnC,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,CAAC,cAAc,CAAC;CAClC,CAAC,CAAC"}

package/dist/scripts/mcp-stdio-socket-bridge-cli.mjs

@@ -0,0 +1,62 @@
+import net from "node:net";
+
+function parseArgs(argv) {
+  let socketPath = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--socket") {
+      socketPath = argv[index + 1] ?? null;
+      index += 1;
+    }
+  }
+
+  if (!socketPath || !socketPath.trim()) {
+    throw new Error("Missing required --socket <path>");
+  }
+
+  return { socketPath: socketPath.trim() };
+}
+
+async function main() {
+  const { socketPath } = parseArgs(process.argv.slice(2));
+  const socket = net.createConnection(socketPath);
+
+  socket.on("error", (error) => {
+    process.stderr.write(`MCP stdio-socket bridge error: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+
+  process.stdin.on("error", (error) => {
+    process.stderr.write(`MCP stdio-socket bridge stdin error: ${error.message}\n`);
+    socket.destroy();
+    process.exitCode = 1;
+  });
+
+  process.stdout.on("error", (error) => {
+    process.stderr.write(`MCP stdio-socket bridge stdout error: ${error.message}\n`);
+    socket.destroy();
+    process.exitCode = 1;
+  });
+
+  await new Promise((resolve, reject) => {
+    socket.once("connect", resolve);
+    socket.once("error", reject);
+  });
+
+  process.stdin.pipe(socket);
+  socket.pipe(process.stdout);
+
+  await new Promise((resolve) => {
+    socket.once("close", resolve);
+    process.stdin.once("end", () => {
+      socket.end();
+      resolve();
+    });
+  });
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/dist/scripts/supervisor.js

@@ -0,0 +1,95 @@
+import { fork } from "child_process";
+function describeExit(code, signal) {
+    return signal ?? (typeof code === "number" ? `code ${code}` : "unknown");
+}
+function isRestartMessage(msg) {
+    return (typeof msg === "object" &&
+        msg !== null &&
+        "type" in msg &&
+        msg.type === "paseo:restart");
+}
+export function runSupervisor(options) {
+    const shutdownReasons = new Set(options.shutdownReasons ?? ["cli_shutdown"]);
+    const restartOnCrash = options.restartOnCrash ?? false;
+    const workerArgs = options.workerArgs ?? process.argv.slice(2);
+    const workerEnv = options.workerEnv ?? process.env;
+    const workerExecArgv = options.workerExecArgv ?? ["--import", "tsx"];
+    let child = null;
+    let restarting = false;
+    let shuttingDown = false;
+    const log = (message) => {
+        process.stderr.write(`[${options.name}] ${message}\n`);
+    };
+    const spawnWorker = () => {
+        let workerEntry;
+        try {
+            // Resolve at spawn time so restarts pick up current filesystem state.
+            workerEntry = options.resolveWorkerEntry();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`Failed to resolve worker entry: ${message}`);
+            process.exit(1);
+            return;
+        }
+        child = fork(workerEntry, workerArgs, {
+            stdio: "inherit",
+            env: workerEnv,
+            execArgv: workerExecArgv,
+        });
+        child.on("message", (msg) => {
+            if (!isRestartMessage(msg)) {
+                return;
+            }
+            if (msg.reason && shutdownReasons.has(msg.reason)) {
+                requestShutdown(`Shutdown requested by worker (${msg.reason})`);
+                return;
+            }
+            requestRestart("Restart requested by worker");
+        });
+        child.on("exit", (code, signal) => {
+            const exitDescriptor = describeExit(code, signal);
+            if (shuttingDown) {
+                log(`Worker exited (${exitDescriptor}). Supervisor shutting down.`);
+                process.exit(0);
+            }
+            if (restarting || (restartOnCrash && code !== 0 && code !== null)) {
+                restarting = false;
+                log(`Worker exited (${exitDescriptor}). Restarting worker...`);
+                spawnWorker();
+                return;
+            }
+            log(`Worker exited (${exitDescriptor}). Supervisor exiting.`);
+            process.exit(typeof code === "number" ? code : 0);
+        });
+    };
+    const requestRestart = (reason) => {
+        if (!child || restarting || shuttingDown) {
+            return;
+        }
+        restarting = true;
+        log(`${reason}. Stopping worker for restart...`);
+        child.kill("SIGTERM");
+    };
+    const requestShutdown = (reason) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        restarting = false;
+        log(`${reason}. Stopping worker...`);
+        if (!child) {
+            process.exit(0);
+            return;
+        }
+        child.kill("SIGTERM");
+    };
+    const forwardSignal = (signal) => {
+        requestShutdown(`Received ${signal}`);
+    };
+    process.on("SIGINT", () => forwardSignal("SIGINT"));
+    process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+    process.stdout.write(`[${options.name}] ${options.startupMessage}\n`);
+    spawnWorker();
+}
+//# sourceMappingURL=supervisor.js.map