@stibbons/pi-opensuperwhisper 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Holzmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# pi-opensuperwhisper
 
-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.
+Answer [pi](https://github.com/badlogic/pi-mono) and [oh-my-pi](https://github.com/can1357/oh-my-pi) agents from the [OpenSuperWhisper](https://github.com/my-monkeys/OpenSuperWhisper) panel on macOS.
+
+When a run is finished and waiting for you, OpenSuperWhisper's Agents panel opens with the agent's last message. Dictate (or type) your reply there. It shows up in the session as a normal user message and starts the next run. You don't have to go back to the terminal.
+
+## Install
+
+pi:
+
+```bash
+pi install npm:@stibbons/pi-opensuperwhisper
+```
+
+oh-my-pi:
+
+```bash
+omp plugin install @stibbons/pi-opensuperwhisper
+```
+
+There's nothing to configure. Turn the panel on or off in OpenSuperWhisper's own settings.
+
+## Requirements
+
+- macOS with OpenSuperWhisper running. On any other platform the extension does nothing.
+- **The "Claude Code" agent kind must be enabled in OpenSuperWhisper.** OpenSuperWhisper doesn't know pi or oh-my-pi yet, so the extension identifies itself as Claude Code. For the same reason the panel labels these requests "Claude Code". This is temporary until OpenSuperWhisper gets its own pi agent kind.
+- The interactive terminal UI. In print, json and rpc modes the extension does nothing.
+
+## How it behaves
+
+- **Panel opens** when the run is fully settled: on pi after `agent_settled`, on oh-my-pi after a terminal `agent_end` once nothing else is queued. It doesn't open while the agent will still continue on its own (retries, compaction, queued follow-ups), after you abort a run with Esc or Ctrl+C, after a run that ended in an error, in oh-my-pi subagent sessions, or when the last message has no visible text. The panel shows only the message's text, without thinking or tool calls.
+- **Your reply** is sent as the next user message, without the panel's "The user answered by voice…" prefix.
+- **"Let it stop", or the panel timing out,** leaves the agent idle with no side effects.
+- **The terminal always wins.** Typing in the terminal, starting a new run, switching or resuming sessions, or quitting cancels the panel request. Exactly one run happens, even if a panel reply arrives at the same moment.
+- **Fails open.** If OpenSuperWhisper isn't running, its files are missing or stale, or anything goes wrong, the extension does nothing and logs nothing. It never blocks the agent or the terminal.
+- **No network.** The extension only talks to the local OpenSuperWhisper app.
+
+## How it works
+
+The extension uses OpenSuperWhisper's own Claude Code integration path. It finds the running app through `~/Library/Application Support/fr.my-monkey.opensuperwhisper/agents/` (`app.pid`, `app.executable`), then runs `<app> agent-hook stop` with a Claude Code–style Stop request on stdin and `CLAUDE_PROJECT_DIR` set. If you answer, the app prints the reply on stdout. Cancelling a request kills that process, and the app closes the panel within about a second.
+
+## Development
+
+The package ships TypeScript source; there's no build step. pi loads it through jiti, oh-my-pi through Bun.
+
+```bash
+bun install
+bun test           # behaviour tests against a fake agent-hook script
+bun run typecheck  # tsc --noEmit
+```
+
+Try it against the real app from a checkout:
+
+```bash
+pi -e ./src/index.ts
+omp -e ./src/index.ts
+```
+
+See [docs/WHAT.md](docs/WHAT.md) for the design and [docs/WHY.md](docs/WHY.md) for the motivation.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@stibbons/pi-opensuperwhisper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Answer pi and oh-my-pi agents from the OpenSuperWhisper panel on macOS",
+  "license": "MIT",
+  "author": "Daniel Holzmann <daniel@danielholzmann.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dVelopment/pi-opensuperwhisper.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "oh-my-pi",
+    "omp",
+    "opensuperwhisper",
+    "voice",
+    "macos"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@types/bun": "1.4.3",
+    "typescript": "7.0.2"
+  }
+}

package/src/app.ts

@@ -0,0 +1,29 @@
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Finds the running OpenSuperWhisper app through its agent registry (`app.pid`, `app.executable`).
+ * Returns the app executable, or nothing when the files are missing or malformed, the pid is
+ * dead, or the executable is missing or not runnable.
+ */
+export function locateApp(agentsDir: string): string | undefined {
+  try {
+    const pid = readFileSync(join(agentsDir, "app.pid"), "utf8").trim();
+    if (!/^[1-9]\d*$/.test(pid) || !isAlive(Number(pid))) return undefined;
+    const executable = readFileSync(join(agentsDir, "app.executable"), "utf8").trim();
+    if (!statSync(executable).isFile()) return undefined;
+    accessSync(executable, constants.X_OK);
+    return executable;
+  } catch {
+    return undefined;
+  }
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

package/src/hook.ts

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+
+/** The Claude Code–style Stop payload `agent-hook stop` reads from stdin. */
+export interface StopRequest {
+  hook_event_name: "Stop";
+  session_id: string;
+  cwd: string;
+  last_assistant_message: string;
+  stop_hook_active: false;
+}
+
+export interface StopHook {
+  /** Resolves with the hook's stdout when it exits 0, or nothing on any failure. */
+  readonly stdout: Promise<string | undefined>;
+  /** Stops the hook (SIGTERM). Safe to call after it has exited. */
+  kill(): void;
+}
+
+/**
+ * Spawns `<executable> agent-hook stop` without blocking, writes the Stop request to its stdin
+ * and collects its stdout. `CLAUDE_PROJECT_DIR` makes the app accept the request as Claude Code.
+ */
+export function runStopHook(executable: string, request: StopRequest): StopHook {
+  const { promise, resolve } = Promise.withResolvers<string | undefined>();
+  const child = spawn(executable, ["agent-hook", "stop"], {
+    env: { ...process.env, CLAUDE_PROJECT_DIR: request.cwd },
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+  let stdout = "";
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdout += chunk;
+  });
+  child.on("error", () => resolve(undefined));
+  child.on("close", (code) => resolve(code === 0 ? stdout : undefined));
+  // The hook may exit before reading stdin; a broken pipe must not crash the host.
+  child.stdin.on("error", () => {});
+  child.stdin.end(JSON.stringify(request));
+  return {
+    stdout: promise,
+    kill: () => {
+      child.kill("SIGTERM");
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentEndEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { locateApp } from "./app.ts";
+import { runStopHook, type StopHook } from "./hook.ts";
+import { type AssistantMessageLike, extractText, parseReply } from "./message.ts";
+
+export interface ExtensionOptions {
+  /** OpenSuperWhisper's agent registry directory (holds `app.pid` and `app.executable`). */
+  agentsDir: string;
+  platform: NodeJS.Platform;
+  /** Safety net: kill a hook that outlives the app's own maximum wait (590 s). */
+  hardKillMs: number;
+}
+
+const DEFAULT_OPTIONS: ExtensionOptions = {
+  agentsDir: join(homedir(), "Library", "Application Support", "fr.my-monkey.opensuperwhisper", "agents"),
+  platform: process.platform,
+  hardKillMs: 600_000,
+};
+
+export function createExtension(overrides: Partial<ExtensionOptions> = {}): (pi: ExtensionAPI) => void {
+  const options = { ...DEFAULT_OPTIONS, ...overrides };
+  return (pi) => {
+    // At most one pending panel request per session. Bumping the generation orphans any reply
+    // still in flight, so typed input racing a panel reply produces exactly one run.
+    let pending: StopHook | undefined;
+    let generation = 0;
+
+    function cancelPending(): void {
+      generation++;
+      pending?.kill();
+      pending = undefined;
+    }
+
+    /** Opens the panel for a settled run, unless a guard says the user shouldn't be asked. */
+    function requestReply(ctx: ExtensionContext, message: AssistantMessageLike | undefined, sessionId: string): void {
+      cancelPending();
+      if (options.platform !== "darwin" || ctx.mode !== "tui") return;
+      if (!message || message.stopReason === "aborted" || message.stopReason === "error") return;
+      const text = extractText(message);
+      if (!text) return;
+      const executable = locateApp(options.agentsDir);
+      if (!executable) return;
+      const request = generation;
+      pending = runStopHook(executable, {
+        hook_event_name: "Stop",
+        session_id: sessionId,
+        cwd: ctx.cwd,
+        last_assistant_message: text,
+        stop_hook_active: false,
+      });
+      // Safety net in case the hook outlives the app's own wait (30–590 s).
+      const hardKill = setTimeout(() => {
+        if (request === generation) cancelPending();
+      }, options.hardKillMs);
+      hardKill.unref();
+      void pending.stdout.then((stdout) => {
+        clearTimeout(hardKill);
+        if (request !== generation) return;
+        pending = undefined;
+        const reply = stdout && parseReply(stdout);
+        if (!reply) return;
+        try {
+          pi.sendUserMessage(reply);
+        } catch {
+          // Fail open: the session went away mid-wait. An unhandled rejection would crash a Node host.
+        }
+      });
+    }
+
+    // Anything that starts or replaces a run makes the panel's question outdated. Our own
+    // injected reply arrives as "extension" input and must not cancel anything.
+    pi.on("input", (event) => {
+      if (event.source !== "extension") cancelPending();
+    });
+    pi.on("agent_start", cancelPending);
+    pi.on("session_shutdown", cancelPending);
+    pi.on("session_before_switch", cancelPending);
+
+    // pi: fires once the run is fully settled (no retry, compaction or queued continuation left).
+    pi.on("agent_settled", (event, ctx) => {
+      if (isOmp(ctx) || event.aborted) return;
+      const messages = ctx.sessionManager.getBranch().flatMap((entry) => (entry.type === "message" ? [entry.message] : []));
+      requestReply(ctx, lastAssistant(messages), ctx.sessionManager.getHeader()?.id ?? "");
+    });
+
+    // omp: has no settled event for extensions, so treat a terminal agent_end as settled once
+    // omp has finished handling it and nothing is queued. Subagent sessions never ask the user.
+    pi.on("agent_end", async (event, ctx) => {
+      if (!isOmp(ctx) || ctx.agent.kind !== "main") return;
+      const { messages, willContinue } = event as OmpAgentEndEvent;
+      if (willContinue) return;
+      const { promise, resolve } = Promise.withResolvers<void>();
+      setTimeout(resolve, 0);
+      await promise;
+      if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
+      requestReply(ctx, lastAssistant(messages), ctx.sessionManager.getSessionId());
+    });
+  };
+}
+
+/** omp-only members of the extension API (checked against oh-my-pi 18.12.6). pi has none of them. */
+interface OmpContext extends ExtensionContext {
+  getAsyncJobSnapshot(): unknown;
+  agent: { kind: "main" | "sub" };
+}
+
+interface OmpAgentEndEvent extends AgentEndEvent {
+  /** True when omp will continue on its own (retry, compaction recovery, reminders, async wakes). */
+  willContinue?: boolean;
+}
+
+/** Detects the host from its API, not the JS runtime: pi can run under Bun too. */
+function isOmp(ctx: ExtensionContext): ctx is OmpContext {
+  return typeof (ctx as Partial<OmpContext>).getAsyncJobSnapshot === "function";
+}
+
+function lastAssistant(messages: readonly { role: string }[]): AssistantMessageLike | undefined {
+  return messages.findLast((message): message is AssistantMessageLike => message.role === "assistant");
+}
+
+export default createExtension();

package/src/message.ts

@@ -0,0 +1,40 @@
+/** The parts of a pi/omp assistant message this extension reads. */
+export interface AssistantMessageLike {
+  role: string;
+  content?: unknown;
+  stopReason?: string;
+}
+
+/**
+ * Returns the visible text of an assistant message: its text blocks joined by a blank line,
+ * trimmed. Thinking, tool-call and image blocks are left out. Returns nothing when no text is left.
+ */
+export function extractText(message: AssistantMessageLike): string | undefined {
+  if (!Array.isArray(message.content)) return undefined;
+  const text = message.content
+    .filter((block): block is { type: "text"; text: string } => block?.type === "text" && typeof block.text === "string")
+    .map((block) => block.text.trim())
+    .filter((text) => text !== "")
+    .join("\n\n");
+  return text === "" ? undefined : text;
+}
+
+const REPLY_PREFIX = "The user answered by voice, through OpenSuperWhisper:\n\n";
+
+/**
+ * Parses the stdout of `agent-hook stop`. Returns the user's reply, or nothing when the
+ * panel was dismissed, timed out, or printed anything other than a block decision.
+ */
+export function parseReply(stdout: string): string | undefined {
+  let output: unknown;
+  try {
+    output = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (typeof output !== "object" || output === null) return undefined;
+  const { decision, reason } = output as { decision?: unknown; reason?: unknown };
+  if (decision !== "block" || typeof reason !== "string") return undefined;
+  const text = reason.startsWith(REPLY_PREFIX) ? reason.slice(REPLY_PREFIX.length) : reason;
+  return text.trim() === "" ? undefined : text;
+}