@yinaoxiong/paseo-server 0.0.0-stage → 0.11.2-personal.1

package/.env.example

@@ -0,0 +1,31 @@
+# OpenAI API Key (for GPT-4, Whisper STT, and TTS)
+OPENAI_API_KEY=
+
+# Optional: point speech-to-text and text-to-speech at different OpenAI-compatible
+# endpoints. Each falls back to OPENAI_API_KEY / OPENAI_BASE_URL when unset.
+# STT covers composer dictation + voice mode STT; TTS covers voice mode TTS.
+OPENAI_STT_API_KEY=
+OPENAI_STT_BASE_URL=
+OPENAI_TTS_API_KEY=
+OPENAI_TTS_BASE_URL=
+
+# 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
+
+# Enable verbose Claude SDK stream logging (trace-level per-token logs)
+PASEO_CLAUDE_DEBUG=1

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# Voice Assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/build-info.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "upstreamVersion": "0.11.2",
+  "revision": 1,
+  "version": "0.11.2-personal.1",
+  "appVersion": "0.11.2",
+  "androidVersionCode": 11002001,
+  "iosBuildNumber": "11002999",
+  "sourceSha": "f6d461e8aed966e668ec4dd7c5e574877fde0937",
+  "lockSha256": "2c24d71c5c42c035bf12fda1d893f203fd2e659e8477953995cb55f870d3b861",
+  "nodeVersion": "v24.21.0",
+  "npmVersion": "11.19.0",
+  "platform": "linux",
+  "arch": "x64",
+  "signature": "unsigned",
+  "githubRunId": "37967635075",
+  "githubRunAttempt": "1",
+  "marker": "v0112-all-1884",
+  "packageName": "@yinaoxiong/paseo-server",
+  "desktopVersion": "0.11.2+personal.1"
+}

package/dist/scripts/dev-runner.js

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "url";
+import dotenv from "dotenv";
+dotenv.config({
+    path: fileURLToPath(new URL("../.env", import.meta.url)),
+    quiet: true,
+});
+const daemonRunnerEntry = fileURLToPath(new URL("./supervisor-entrypoint.ts", import.meta.url));
+const supervisorArgs = [...process.execArgv, daemonRunnerEntry, "--dev", ...process.argv.slice(2)];
+const supervisor = spawn(process.execPath, supervisorArgs, {
+    stdio: "inherit",
+    env: {
+        ...process.env,
+        PASEO_LOG_FORMAT: process.env.PASEO_LOG_FORMAT ?? "pretty",
+    },
+});
+function exitCodeForSignal(signal) {
+    return signal === "SIGINT" ? 130 : 1;
+}
+function forwardSignal(signal) {
+    if (supervisor.exitCode !== null || supervisor.signalCode !== null || supervisor.killed) {
+        return;
+    }
+    supervisor.kill(signal);
+}
+// The supervisor handles SIGINT/SIGTERM itself and needs time to drain the
+// worker gracefully. Keep this wrapper alive until the supervisor exits so npm
+// does not release the shell while the daemon is still logging final shutdown.
+process.on("SIGINT", () => forwardSignal("SIGINT"));
+process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+supervisor.on("error", (error) => {
+    throw error;
+});
+supervisor.on("exit", (code, signal) => {
+    process.exit(code ?? (signal ? exitCodeForSignal(signal) : 1));
+});
+//# sourceMappingURL=dev-runner.js.map

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-entrypoint.js

@@ -0,0 +1,176 @@
+import { fileURLToPath } from "url";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { acquirePidLock, PidLockError, releasePidLock, startPidLockHeartbeat, updatePidLock, } from "../src/server/pid-lock.js";
+import { resolvePaseoHome } from "../src/server/paseo-home.js";
+import { daemonLogPath } from "../src/server/daemon-instance.js";
+import { PRIVATE_FILE_MODE } from "../src/server/private-files.js";
+import { loadPersistedConfig } from "../src/server/persisted-config.js";
+import { runSupervisor } from "./supervisor.js";
+import { resolveSupervisorLogFile } from "./supervisor-log-config.js";
+process.title = "Paseo Supervisor";
+function parseConfig(argv) {
+    let devMode = false;
+    const workerArgs = [];
+    for (const arg of argv) {
+        if (arg === "--dev") {
+            devMode = true;
+            continue;
+        }
+        if (arg === "--reclaim-stale-pid-lock") {
+            throw new Error("--reclaim-stale-pid-lock was removed: stop the existing supervisor before starting another.");
+        }
+        workerArgs.push(arg);
+    }
+    return { devMode, workerArgs };
+}
+function resolveWorkerEntry() {
+    const candidates = [
+        fileURLToPath(new URL("../server/server/daemon-worker.js", import.meta.url)),
+        fileURLToPath(new URL("../dist/server/server/daemon-worker.js", import.meta.url)),
+        fileURLToPath(new URL("../src/server/daemon-worker.ts", import.meta.url)),
+        fileURLToPath(new URL("../../src/server/daemon-worker.ts", import.meta.url)),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+function resolveDevWorkerEntry() {
+    const candidate = fileURLToPath(new URL("../src/server/daemon-worker.ts", import.meta.url));
+    if (!existsSync(candidate)) {
+        throw new Error(`Dev worker entry not found: ${candidate}`);
+    }
+    return candidate;
+}
+function resolveWorkerExecArgv(workerEntry, devMode) {
+    const execArgv = workerEntry.endsWith(".ts") ? ["--import", "tsx"] : [];
+    if (!devMode) {
+        return execArgv;
+    }
+    const devArgs = [
+        "--heapsnapshot-near-heap-limit=3",
+        "--max-old-space-size=3072",
+        "--report-on-fatalerror",
+        "--report-directory=/tmp/paseo-reports",
+    ];
+    const inspectArg = process.env.PASEO_NODE_INSPECT ?? "--inspect";
+    if (inspectArg !== "0" && inspectArg !== "false" && inspectArg !== "off") {
+        devArgs.push(inspectArg);
+    }
+    return [...devArgs, ...execArgv];
+}
+function resolvePackagedNodeEntrypointRunnerPath(currentScriptPath) {
+    const packageMarker = `${path.sep}node_modules${path.sep}@getpaseo${path.sep}server${path.sep}`;
+    const markerIndex = currentScriptPath.lastIndexOf(packageMarker);
+    if (markerIndex === -1) {
+        return null;
+    }
+    const appRoot = currentScriptPath.slice(0, markerIndex);
+    const runnerPath = path.join(appRoot, "dist", "daemon", "node-entrypoint-runner.js");
+    return existsSync(runnerPath) ? runnerPath : null;
+}
+async function main() {
+    const config = parseConfig(process.argv.slice(2));
+    const workerEntry = config.devMode ? resolveDevWorkerEntry() : resolveWorkerEntry();
+    const workerExecArgv = resolveWorkerExecArgv(workerEntry, config.devMode);
+    const workerEnv = { ...process.env };
+    const packagedNodeEntrypointRunner = process.env.ELECTRON_RUN_AS_NODE === "1"
+        ? resolvePackagedNodeEntrypointRunnerPath(fileURLToPath(import.meta.url))
+        : null;
+    const paseoHome = resolvePaseoHome(workerEnv);
+    const persistedConfig = loadPersistedConfig(paseoHome);
+    const supervisorLogFile = resolveSupervisorLogFile(paseoHome, persistedConfig, workerEnv);
+    try {
+        await acquirePidLock(paseoHome, null, {
+            ownerPid: process.pid,
+        });
+    }
+    catch (error) {
+        if (error instanceof PidLockError) {
+            failStartup(error.message, error.message);
+        }
+        throw error;
+    }
+    let lockReleased = false;
+    let requestSupervisorShutdown = null;
+    const stopLockHeartbeat = startPidLockHeartbeat(paseoHome, {
+        ownerPid: process.pid,
+        onError: (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`PID lock heartbeat failed: ${message}\n`);
+            if (error instanceof PidLockError) {
+                requestSupervisorShutdown?.("pid_lock_ownership_lost");
+            }
+        },
+    });
+    const releaseLock = async () => {
+        if (lockReleased) {
+            return;
+        }
+        lockReleased = true;
+        stopLockHeartbeat();
+        await releasePidLock(paseoHome, {
+            ownerPid: process.pid,
+        });
+    };
+    const supervisor = runSupervisor({
+        name: "DaemonRunner",
+        startupMessage: "Starting daemon worker (IPC restart and crash restart enabled)",
+        resolveWorkerEntry: () => workerEntry,
+        workerArgs: config.workerArgs,
+        workerEnv,
+        workerExecArgv,
+        resolveWorkerSpawnSpec: packagedNodeEntrypointRunner
+            ? (resolvedWorkerEntry) => ({
+                command: process.execPath,
+                args: [
+                    packagedNodeEntrypointRunner,
+                    "node-script",
+                    resolvedWorkerEntry,
+                    ...config.workerArgs,
+                ],
+                env: {
+                    ...workerEnv,
+                    ELECTRON_RUN_AS_NODE: "1",
+                },
+            })
+            : undefined,
+        restartOnCrash: true,
+        logFile: supervisorLogFile,
+        onWorkerReady: async ({ listen, serverId }) => {
+            await updatePidLock(paseoHome, { listen, serverId }, { ownerPid: process.pid });
+        },
+        onWorkerExit: () => updatePidLock(paseoHome, { listen: null, serverId: null }, { ownerPid: process.pid }),
+        onSupervisorExit: releaseLock,
+    });
+    requestSupervisorShutdown = supervisor.requestShutdown;
+}
+// The supervisor opens its log only after config and the PID lock succeed. A background
+// launch discards stderr, so earlier failures also go to the log the launcher points at.
+function failStartup(detail, summary) {
+    process.stderr.write(`${detail}\n`);
+    try {
+        const logPath = daemonLogPath(resolvePaseoHome(process.env));
+        mkdirSync(path.dirname(logPath), { recursive: true });
+        appendFileSync(logPath, `${JSON.stringify({
+            level: "fatal",
+            time: new Date().toISOString(),
+            pid: process.pid,
+            name: "DaemonRunner",
+            msg: summary,
+        })}\n`, { mode: PRIVATE_FILE_MODE });
+    }
+    catch {
+        // stderr already carries the failure.
+    }
+    process.exit(1);
+}
+void main().catch((error) => {
+    if (error instanceof Error)
+        failStartup(error.stack ?? error.message, error.message);
+    failStartup(String(error), String(error));
+});
+//# sourceMappingURL=supervisor-entrypoint.js.map

package/dist/scripts/supervisor-log-config.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+const DEFAULT_DAEMON_LOG_FILENAME = "daemon.log";
+const DEFAULT_LOG_ROTATE_SIZE = "10m";
+const DEFAULT_LOG_ROTATE_MAX_FILES = 3;
+export function resolveSupervisorLogFile(paseoHome, persistedConfig, env = process.env) {
+    const configuredFile = persistedConfig.log?.file;
+    const configuredPath = configuredFile?.path;
+    const envRotateSize = env.PASEO_LOG_ROTATE_SIZE?.trim();
+    const envRotateMaxFiles = parseOptionalPositiveInteger(env.PASEO_LOG_ROTATE_COUNT);
+    let logPath = path.join(paseoHome, DEFAULT_DAEMON_LOG_FILENAME);
+    if (configuredPath) {
+        logPath = path.isAbsolute(configuredPath)
+            ? configuredPath
+            : path.resolve(paseoHome, configuredPath);
+    }
+    return {
+        path: logPath,
+        rotate: {
+            maxSize: configuredFile?.rotate?.maxSize ?? envRotateSize ?? DEFAULT_LOG_ROTATE_SIZE,
+            maxFiles: configuredFile?.rotate?.maxFiles ?? envRotateMaxFiles ?? DEFAULT_LOG_ROTATE_MAX_FILES,
+        },
+    };
+}
+function parseOptionalPositiveInteger(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value.trim(), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+//# sourceMappingURL=supervisor-log-config.js.map