@neuralmux/omp-superwhisper 1.0.1

package/README.md

@@ -0,0 +1,205 @@
+# @neuralmux/omp-superwhisper
+
+Superwhisper voice integration extension for [Oh My Pi](https://github.com/neuralmux/oh-my-pi).
+
+Get voice notifications when your AI coding tasks complete, and respond with your voice. Your voice response is sent back to OMP as the next prompt, creating a hands-free coding loop.
+
+## Requirements
+
+- [Oh My Pi](https://github.com/neuralmux/oh-my-pi) (`@oh-my-pi/pi-coding-agent`) installed
+- [Superwhisper](https://superwhisper.com) app for macOS
+
+## Installation
+
+### Via `omp plugin` (recommended)
+
+```bash
+# Local path — install directly from a local clone
+omp plugin install /workspaces/superwhisper-omp
+
+# Local development — symlink so edits are picked up live
+omp plugin link /workspaces/superwhisper-omp
+
+# From npm (once published)
+omp plugin install @neuralmux/omp-superwhisper
+
+# From a git repository
+omp plugin install github.com/neuralmux/pi-superwhisper
+```
+
+OMP installs the package into `~/.omp/plugins/node_modules/`, discovers
+`omp.extensions` from `package.json`, and wires extension modules into the
+runtime. Restart OMP to activate.
+
+### Manual (user-level)
+
+```bash
+mkdir -p ~/.omp/agent/extensions
+cp extensions/*.ts ~/.omp/agent/extensions/
+```
+
+### Manual (project-level)
+
+```bash
+mkdir -p .omp/extensions
+cp extensions/*.ts .omp/extensions/
+```
+
+## How It Works
+
+```
+You speak → OMP works → Extension notifies Superwhisper → You speak back → loop
+```
+
+1. **Task completes** → OMP fires `agent_end` with `stopReason: "stop"`
+2. **Extension extracts the response** → reads the last assistant text content
+3. **Extension notifies Superwhisper** → writes message to temp file, opens deeplink
+4. **Superwhisper shows notification** → displays summary with voice recording UI
+5. **You speak your response** → Superwhisper transcribes and writes to response file
+6. **Extension reads response** → polls the response file, sends back to OMP via `pi.sendUserMessage`
+7. **OMP continues** → processes your voice input as the next instruction
+
+## Events
+
+| OMP Event         | Superwhisper Status | Description                  |
+|-------------------|---------------------|------------------------------|
+| `agent_end` (stop)| `completed`         | Task finished                |
+
+OMP has no built-in permission popups or elicitation system, so only end-of-turn completions are surfaced today.
+
+## Using from Devcontainers / Docker
+
+When running OMP inside a devcontainer or Docker container, the extension cannot directly access the host's Superwhisper app. You need to run the **bridge daemon** on the macOS host to proxy communication.
+
+### 1. Start the bridge daemon on your macOS host
+
+**Quick start (foreground):**
+
+```bash
+bun run bin/superwhisper-bridge.ts
+```
+
+**Install as a background service (starts on login):**
+
+```bash
+bun run bin/install-bridge-service.ts
+```
+
+You'll see:
+
+```
+✓ Wrote ~/Library/LaunchAgents/com.superwhisper.bridge.plist
+✓ Service loaded: com.superwhisper.bridge.plist
+```
+
+The daemon is now running and will restart automatically on login.
+
+Check it's running:
+
+```bash
+launchctl list | grep superwhisper
+```
+
+View logs:
+
+```bash
+tail -f /tmp/superwhisper-bridge.log
+```
+
+**Uninstall the service:**
+
+```bash
+bun run bin/install-bridge-service.ts --uninstall
+```
+
+**Enable debug logging:**
+
+```bash
+bun run bin/install-bridge-service.ts --debug
+```
+
+### 2. Configure your devcontainer
+
+In your `.devcontainer/devcontainer.json` or `docker-compose.yml`, set the environment variable inside the container:
+
+```json
+{
+  "containerEnv": {
+    "SUPERWHISPER_BRIDGE_URL": "http://host.docker.internal:19550"
+  }
+}
+```
+
+Or in a `docker-compose.yml`:
+
+```yaml
+services:
+  dev:
+    environment:
+      - SUPERWHISPER_BRIDGE_URL=http://host.docker.internal:19550
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+### 3. That's it
+
+When the extension detects `SUPERWHISPER_BRIDGE_URL`, it automatically switches to bridge mode. All Superwhisper interactions (inbox delivery, message/response file I/O, deeplink wakes) are proxied through the host daemon.
+
+> **Note:** You need one bridge daemon per Mac. Multiple devcontainers can share the same daemon.
+
+## Controlling Superwhisper During a Session
+
+You can ask the agent to enable or disable Superwhisper voice notifications at any time during a session. The extension exposes a `superwhisper_toggle` tool the agent will use automatically when instructed.
+
+**Disable Superwhisper for the current session:**
+> "Disable Superwhisper" / "Turn off voice notifications" / "Stop Superwhisper"
+
+**Re-enable Superwhisper for the current session:**
+> "Enable Superwhisper" / "Turn voice notifications back on" / "Re-enable Superwhisper"
+
+The toggle is session-scoped — it only affects the current OMP session and resets when you start a new one.
+
+## Slash Commands
+
+```
+/superwhisper on       — enable voice notifications
+/superwhisper off      — disable voice notifications
+/superwhisper test     — send a test notification
+/superwhisper status   — show current state
+```
+
+## Environment Variables
+
+| Variable                    | Default | Description                                                          |
+|-----------------------------|---------|----------------------------------------------------------------------|
+| `SUPERWHISPER_DEBUG`        | unset   | Set to `1` to write debug logs to `/tmp/superwhisper-agent/debug.log`|
+| `SUPERWHISPER_SCHEME`       | auto    | Override deeplink scheme (`superwhisper` vs `superwhisper-debug`)    |
+| `SUPERWHISPER_BRIDGE_URL`   | unset   | Bridge daemon URL for devcontainer support (e.g. `http://host.docker.internal:19550`) |
+
+**Bridge daemon env vars** (set on the macOS host, not in the container):
+
+| Variable                    | Default | Description                                                          |
+|-----------------------------|---------|----------------------------------------------------------------------|
+| `SUPERWHISPER_BRIDGE_PORT`  | `19550` | Port for the bridge daemon to listen on                              |
+| `SUPERWHISPER_BRIDGE_HOST`  | `127.0.0.1` | Bind address for the bridge daemon                              |
+| `SUPERWHISPER_DEBUG`        | unset   | Set to `1` for verbose bridge daemon logging to stderr               |
+
+## Project Structure
+
+```
+extensions/
+  superwhisper.ts  # Extension entry — OMP loads this directly
+  host.ts          # HostOps abstraction (direct vs bridge mode)
+  constants.ts     # Constants and shared types
+  inbox.ts         # Inbox payload writes
+  message.ts       # AgentMessage helpers (extract text, summary, end-turn)
+  poll.ts          # Response file polling
+bin/
+  superwhisper-bridge.ts        # Host bridge daemon for devcontainer support
+  install-bridge-service.ts     # Launchd service installer
+  com.superwhisper.bridge.plist # Launchd plist template
+```
+
+## License
+
+MIT

package/bin/com.superwhisper.bridge.plist

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.superwhisper.bridge</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__BUN_PATH__</string>
+    <string>run</string>
+    <string>__SCRIPT_PATH__</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/superwhisper-bridge.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/superwhisper-bridge.err</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>SUPERWHISPER_DEBUG</key>
+    <string>__DEBUG__</string>
+  </dict>
+</dict>
+</plist>

package/bin/install-bridge-service.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+/**
+ * install-bridge-service — installs the superwhisper-bridge launchd service.
+ *
+ * Usage:
+ *   bun run bin/install-bridge-service.ts [--uninstall] [--debug]
+ *
+ * Installs ~/Library/LaunchAgents/com.superwhisper.bridge.plist and
+ * loads it with launchctl so the bridge daemon starts on login and
+ * stays running.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const LAUNCH_AGENTS_DIR = join(homedir(), "Library", "LaunchAgents")
+const PLIST_NAME = "com.superwhisper.bridge.plist"
+const PLIST_DEST = join(LAUNCH_AGENTS_DIR, PLIST_NAME)
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2)
+const uninstall = args.includes("--uninstall")
+const debug = args.includes("--debug")
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findBunPath(): string {
+  return process.execPath
+}
+
+function findScriptPath(): string {
+  return join(import.meta.dir, "superwhisper-bridge.ts")
+}
+
+function loadService(): void {
+  try {
+    Bun.spawnSync(["launchctl", "load", PLIST_DEST], { stdio: ["inherit", "inherit", "inherit"] })
+  } catch {
+    // launchctl load may fail if already loaded; try bootstrap
+    try {
+      const uid = (process as any).getuid?.() ?? 501
+      Bun.spawnSync(["launchctl", "bootstrap", `gui/${uid}`, PLIST_DEST], {
+        stdio: ["inherit", "inherit", "inherit"],
+      })
+    } catch {
+      console.log("⚠  Could not load the service — it may already be loaded, or you may need to log out and back in.")
+    }
+  }
+}
+
+function unloadService(): void {
+  try {
+    Bun.spawnSync(["launchctl", "unload", PLIST_DEST], { stdio: ["inherit", "inherit", "inherit"] })
+  } catch {
+    try {
+      const uid = (process as any).getuid?.() ?? 501
+      Bun.spawnSync(["launchctl", "bootout", `gui/${uid}`, PLIST_DEST], {
+        stdio: ["inherit", "inherit", "inherit"],
+      })
+    } catch {
+      // fine
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+if (uninstall) {
+  console.log("Uninstalling superwhisper-bridge launchd service...")
+
+  if (existsSync(PLIST_DEST)) {
+    unloadService()
+    unlinkSync(PLIST_DEST)
+    console.log(`✓ Removed ${PLIST_DEST}`)
+  } else {
+    console.log("Service plist not found — nothing to uninstall.")
+  }
+
+  console.log("Done.")
+  process.exit(0)
+}
+
+// --- Install ---
+
+const bunPath = findBunPath()
+const scriptPath = findScriptPath()
+const templatePath = join(import.meta.dir, "com.superwhisper.bridge.plist")
+
+if (!existsSync(scriptPath)) {
+  console.error(`✗ Bridge script not found at: ${scriptPath}`)
+  console.error("  Make sure bin/superwhisper-bridge.ts exists in the package.")
+  process.exit(1)
+}
+
+if (!existsSync(templatePath)) {
+  console.error(`✗ Plist template not found at: ${templatePath}`)
+  process.exit(1)
+}
+
+// Read template and substitute
+const template = readFileSync(templatePath, "utf8")
+const plist = template
+  .replace(/__BUN_PATH__/g, bunPath)
+  .replace(/__SCRIPT_PATH__/g, scriptPath)
+  .replace(/__DEBUG__/g, debug ? "1" : "")
+
+// Write plist
+mkdirSync(LAUNCH_AGENTS_DIR, { recursive: true })
+writeFileSync(PLIST_DEST, plist)
+console.log(`✓ Wrote ${PLIST_DEST}`)
+
+// Load service
+console.log("Loading service...")
+loadService()
+console.log(`✓ Service loaded: ${PLIST_NAME}`)
+
+// Done
+console.log()
+console.log("Bridge daemon is now running and will start automatically on login.")
+console.log()
+console.log("Check status:")
+console.log(`  launchctl list | grep superwhisper`)
+console.log()
+console.log("View logs:")
+console.log(`  tail -f /tmp/superwhisper-bridge.log`)
+console.log()
+console.log("Uninstall:")
+console.log(`  bun run ${join(import.meta.dir, "install-bridge-service.ts")} --uninstall`)

package/bin/superwhisper-bridge.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env bun
+/**
+ * superwhisper-bridge — HTTP daemon that runs on the macOS host.
+ *
+ * It acts as a proxy between OMP extensions running inside devcontainers (or
+ * any other isolated environment) and the Superwhisper macOS app. The daemon
+ * manages the inbox, message/response files, and deeplink wakes on the host
+ * filesystem so the containerized extension doesn't need host access.
+ *
+ * Usage:
+ *   bun run bin/superwhisper-bridge.ts [--port PORT]
+ *
+ * Environment:
+ *   SUPERWHISPER_BRIDGE_PORT  – port to listen on (default: 19550)
+ *   SUPERWHISPER_BRIDGE_HOST  – bind address   (default: 127.0.0.1)
+ *   SUPERWHISPER_SCHEME       – override scheme (default: auto-detect)
+ *   SUPERWHISPER_DEBUG        – enable debug logging
+ *
+ * API:
+ *   GET  /health                                     → { running, scheme, version }
+ *   POST /inbox            body: InboxPayload (JSON)  → { ok: bool }
+ *   GET  /session/:id/message                         → 200 text/plain | 404
+ *   PUT  /session/:id/message   body: text            → 204
+ *   DELETE /session/:id/message                       → 204
+ *   GET  /session/:id/response?timeout=MS             → 200 { kind, text? } | 408
+ *   DELETE /session/:id/response                      → 204
+ *   GET  /session/:id/disabled                        → { disabled: bool }
+ *   PUT  /session/:id/disabled                        → 204 (set disabled)
+ *   DELETE /session/:id/disabled                      → 204 (clear disabled)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs"
+import { $ } from "bun"
+
+// Re-use the existing extension modules for inbox and polling logic.
+import type { InboxPayload } from "../extensions/inbox"
+import { deliverAgentPayload } from "../extensions/inbox"
+import { waitForResponse } from "../extensions/poll"
+import { MESSAGE_DIR } from "../extensions/constants"
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const PORT = parseInt(process.env.SUPERWHISPER_BRIDGE_PORT || "19550", 10)
+const HOST = process.env.SUPERWHISPER_BRIDGE_HOST || "127.0.0.1"
+const DEBUG = !!process.env.SUPERWHISPER_DEBUG
+const VERSION = "1.0.0"
+
+function debugLog(level: string, msg: string) {
+  if (!DEBUG) return
+  const ts = new Date().toISOString()
+  process.stderr.write(`[${ts}] [${level}] [superwhisper-bridge] ${msg}\n`)
+}
+
+// ---------------------------------------------------------------------------
+// Scheme detection
+// ---------------------------------------------------------------------------
+
+let cachedScheme: string | null = process.env.SUPERWHISPER_SCHEME || null
+
+async function detectScheme(): Promise<string> {
+  if (cachedScheme) return cachedScheme
+  try {
+    await $`pgrep -f DerivedData.*superwhisper.app`.quiet()
+    cachedScheme = "superwhisper-debug"
+  } catch {
+    cachedScheme = "superwhisper"
+  }
+  return cachedScheme
+}
+
+async function checkRunning(): Promise<boolean> {
+  try {
+    await $`pgrep -x superwhisper`.quiet()
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function messagePath(sessionId: string) {
+  return `${MESSAGE_DIR}/${sessionId}-message.txt`
+}
+function responsePath(sessionId: string) {
+  return `${MESSAGE_DIR}/${sessionId}-response.txt`
+}
+function disabledPath(sessionId: string) {
+  return `${MESSAGE_DIR}/disabled-${sessionId}`
+}
+
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  })
+}
+
+function textResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  })
+}
+
+function emptyResponse(status = 204): Response {
+  return new Response(null, { status })
+}
+
+function corsHeaders(): Record<string, string> {
+  return {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET,PUT,POST,DELETE,OPTIONS",
+    "access-control-allow-headers": "content-type",
+  }
+}
+
+function extractSessionId(url: URL): string | null {
+  // /session/<id>/(message|response|disabled)
+  const m = url.pathname.match(/^\/session\/([^/]+)\/(message|response|disabled)/)
+  return m ? decodeURIComponent(m[1]) : null
+}
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+
+async function handleRequest(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const method = req.method.toUpperCase()
+
+  debugLog("info", `${method} ${url.pathname}${url.search}`)
+
+  if (method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: corsHeaders() })
+  }
+
+  try {
+    // ---- /health ----
+    if (url.pathname === "/health" && method === "GET") {
+      const scheme = await detectScheme()
+      const running = await checkRunning()
+      return jsonResponse({ running, scheme, version: VERSION })
+    }
+
+    // ---- /inbox ----
+    if (url.pathname === "/inbox" && method === "POST") {
+      let payload: InboxPayload
+      try {
+        payload = await req.json()
+      } catch {
+        return jsonResponse({ error: "invalid JSON" }, 400)
+      }
+      const scheme = await detectScheme()
+      // Override hookPid with the bridge's own PID so Superwhisper can
+      // validate it against running host processes. Container PIDs would
+      // otherwise be silently rejected.
+      payload.hookPid = process.pid
+      const ok = await deliverAgentPayload(payload, scheme)
+      return jsonResponse({ ok }, ok ? 200 : 500)
+    }
+
+    // ---- /session/:id/message ----
+    const sessionId = extractSessionId(url)
+    if (sessionId && url.pathname.endsWith("/message")) {
+      mkdirSync(MESSAGE_DIR, { recursive: true })
+
+      if (method === "GET") {
+        try {
+          const content = readFileSync(messagePath(sessionId), "utf8")
+          return textResponse(content)
+        } catch {
+          return jsonResponse({ error: "not found" }, 404)
+        }
+      }
+
+      if (method === "PUT") {
+        const body = await req.text()
+        writeFileSync(messagePath(sessionId), body)
+        return emptyResponse()
+      }
+
+      if (method === "DELETE") {
+        try { unlinkSync(messagePath(sessionId)) } catch {}
+        return emptyResponse()
+      }
+    }
+
+    // ---- /session/:id/response ----
+    if (sessionId && url.pathname.endsWith("/response")) {
+      mkdirSync(MESSAGE_DIR, { recursive: true })
+
+      if (method === "GET") {
+        const timeoutParam = url.searchParams.get("timeout")
+        const timeoutMs = timeoutParam ? parseInt(timeoutParam, 10) : 1_800_000
+
+        const rp = responsePath(sessionId)
+
+        // Long-poll: waitForResponse handles fs.watch + interval internally.
+        const result = await waitForResponse(rp, {
+          timeoutMs,
+          signal: undefined,
+        })
+
+        return jsonResponse(result)
+      }
+
+      if (method === "DELETE") {
+        try { unlinkSync(responsePath(sessionId)) } catch {}
+        return emptyResponse()
+      }
+    }
+
+    // ---- /session/:id/disabled ----
+    if (sessionId && url.pathname.endsWith("/disabled")) {
+      mkdirSync(MESSAGE_DIR, { recursive: true })
+
+      if (method === "GET") {
+        return jsonResponse({ disabled: existsSync(disabledPath(sessionId)) })
+      }
+
+      if (method === "PUT") {
+        writeFileSync(disabledPath(sessionId), "")
+        return emptyResponse()
+      }
+
+      if (method === "DELETE") {
+        try { unlinkSync(disabledPath(sessionId)) } catch {}
+        return emptyResponse()
+      }
+    }
+
+    // ---- 404 ----
+    return jsonResponse({ error: "not found" }, 404)
+  } catch (err) {
+    debugLog("error", `Request failed: ${err}`)
+    return jsonResponse({ error: "internal server error" }, 500)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+mkdirSync(MESSAGE_DIR, { recursive: true })
+
+const server = Bun.serve({
+  port: PORT,
+  hostname: HOST,
+  fetch(req) {
+    const res = handleRequest(req)
+    // Attach CORS headers to every response
+    return res.then((r) => {
+      for (const [k, v] of Object.entries(corsHeaders())) {
+        r.headers.set(k, v)
+      }
+      return r
+    })
+  },
+})
+
+console.log(`superwhisper-bridge v${VERSION} listening on http://${HOST}:${PORT}`)
+console.log(`Health check: http://${HOST}:${PORT}/health`)
+console.log(`Message dir:  ${MESSAGE_DIR}`)
+if (process.env.SUPERWHISPER_BRIDGE_URL) {
+  console.log(`⚠  SUPERWHISPER_BRIDGE_URL is set — this daemon should NOT be run with that variable.`)
+}
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  debugLog("info", "Shutting down...")
+  server.stop()
+  process.exit(0)
+})
+process.on("SIGTERM", () => {
+  debugLog("info", "Shutting down...")
+  server.stop()
+  process.exit(0)
+})

package/extensions/constants.ts

@@ -0,0 +1,4 @@
+export const LOG_PREFIX = "[omp-superwhisper]"
+export const MESSAGE_DIR = "/tmp/superwhisper-agent"
+export const POLL_INTERVAL_MS = 1_000
+export const POLL_TIMEOUT_MS = 30 * 60 * 1_000