@stibbons/pi-opensuperwhisper 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+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. On oh-my-pi, questions the agent asks with its `ask` tool open in the panel too.
 
 ## Install
 
@@ -32,6 +32,8 @@ There's nothing to configure. Turn the panel on or off in OpenSuperWhisper's own
 - **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.
+- **oh-my-pi `ask` questions** open in the panel and in the terminal dialog at the same time. Whichever you answer first wins: a panel answer closes the terminal dialog and reaches the agent exactly as if you had picked it there (single choice, multi-select or free text); answering in the terminal closes the panel. Dismissing the panel, or letting it time out, leaves the terminal dialog open. Questions from subagents, and calls with two identical question texts, stay terminal-only.
+- **pi has no `ask` tool.** For structured questions on pi, install a question plugin such as [`@mazli/pi-ask-user-question`](https://www.npmjs.com/package/@mazli/pi-ask-user-question) (`pi install npm:@mazli/pi-ask-user-question`). Its questions are answered in the terminal and don't open in the panel: pi gives extensions no `ctx.invokeTool`, so this extension can't run another extension's question tool and the panel side by side.
 - **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.
 
@@ -39,6 +41,10 @@ There's nothing to configure. Turn the panel on or off in OpenSuperWhisper's own
 
 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.
 
+For oh-my-pi's `ask` tool, the extension registers its own `ask` (same description and parameters) when a session starts. Each call runs the native `ask` through `ctx.invokeTool` and, at the same time, `<app> agent-hook question` with the questions as a Claude Code `AskUserQuestion` request. The first answer wins and the other side is cancelled.
+
+**Known cost:** because the extension replaces the built-in `ask`, oh-my-pi shows `ask` calls in the transcript like any other extension tool instead of with its built-in renderer. The interactive question dialog is unchanged.
+
 ## Development
 
 The package ships TypeScript source; there's no build step. pi loads it through jiti, oh-my-pi through Bun.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@stibbons/pi-opensuperwhisper",
-  "version": "0.1.0",
+  "version": "0.2.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"
+    "url": "git+https://github.com/stibbons-ai/pi-opensuperwhisper.git"
   },
   "publishConfig": {
     "access": "public"

package/src/hook.ts

@@ -1,4 +1,11 @@
 import { spawn } from "node:child_process";
+import type { QuestionRequest } from "./question.ts";
+
+/** The `agent-hook` subcommands this extension runs, each with the request it reads on stdin. */
+interface HookRequests {
+  stop: StopRequest;
+  question: QuestionRequest;
+}
 
 /** The Claude Code–style Stop payload `agent-hook stop` reads from stdin. */
 export interface StopRequest {
@@ -9,7 +16,7 @@ export interface StopRequest {
   stop_hook_active: false;
 }
 
-export interface StopHook {
+export interface HookProcess {
   /** 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. */
@@ -17,12 +24,12 @@ export interface StopHook {
 }
 
 /**
- * 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.
+ * Spawns `<executable> agent-hook <event>` without blocking, writes the request as JSON 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 {
+export function runHook<E extends keyof HookRequests>(executable: string, event: E, request: HookRequests[E]): HookProcess {
   const { promise, resolve } = Promise.withResolvers<string | undefined>();
-  const child = spawn(executable, ["agent-hook", "stop"], {
+  const child = spawn(executable, ["agent-hook", event], {
     env: { ...process.env, CLAUDE_PROJECT_DIR: request.cwd },
     stdio: ["pipe", "pipe", "ignore"],
   });

package/src/index.ts

@@ -1,15 +1,23 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import type { AgentEndEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  AgentEndEvent,
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+  ToolInfo,
+} from "@earendil-works/pi-coding-agent";
 import { locateApp } from "./app.ts";
-import { runStopHook, type StopHook } from "./hook.ts";
+import { type HookProcess, runHook, type StopRequest } from "./hook.ts";
 import { type AssistantMessageLike, extractText, parseReply } from "./message.ts";
+import { type AskInput, parseQuestionAnswers, sanitizeAskInput, toQuestionRequest } from "./question.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). */
+  /** Safety net: kill a hook that outlives the app's own wait (30–590 s). */
   hardKillMs: number;
 }
 
@@ -21,11 +29,26 @@ const DEFAULT_OPTIONS: ExtensionOptions = {
 
 export function createExtension(overrides: Partial<ExtensionOptions> = {}): (pi: ExtensionAPI) => void {
   const options = { ...DEFAULT_OPTIONS, ...overrides };
+
+  /** The panel is a macOS app, and only an interactive terminal session has a user to ask. */
+  function canShowPanel(ctx: ExtensionContext): boolean {
+    return options.platform === "darwin" && ctx.mode === "tui";
+  }
+
+  /** Calls `kill` once the hook has outlived `hardKillMs`. Returns the function that disarms it. */
+  function armHardKill(kill: () => void): () => void {
+    const timer = setTimeout(kill, options.hardKillMs);
+    timer.unref();
+    return () => clearTimeout(timer);
+  }
+
   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 pending: HookProcess | undefined;
     let generation = 0;
+    /** Panel requests of `ask` calls still in flight. */
+    const askHooks = new Set<HookProcess>();
 
     function cancelPending(): void {
       generation++;
@@ -36,27 +59,26 @@ export function createExtension(overrides: Partial<ExtensionOptions> = {}): (pi:
     /** 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 (!canShowPanel(ctx)) 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, {
+      const stopRequest: StopRequest = {
         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(() => {
+      };
+      pending = runHook(executable, "stop", stopRequest);
+      const disarmHardKill = armHardKill(() => {
         if (request === generation) cancelPending();
-      }, options.hardKillMs);
-      hardKill.unref();
+      });
       void pending.stdout.then((stdout) => {
-        clearTimeout(hardKill);
+        disarmHardKill();
         if (request !== generation) return;
         pending = undefined;
         const reply = stdout && parseReply(stdout);
@@ -75,7 +97,10 @@ export function createExtension(overrides: Partial<ExtensionOptions> = {}): (pi:
       if (event.source !== "extension") cancelPending();
     });
     pi.on("agent_start", cancelPending);
-    pi.on("session_shutdown", cancelPending);
+    pi.on("session_shutdown", () => {
+      cancelPending();
+      for (const hook of askHooks) hook.kill();
+    });
     pi.on("session_before_switch", cancelPending);
 
     // pi: fires once the run is fully settled (no retry, compaction or queued continuation left).
@@ -97,6 +122,73 @@ export function createExtension(overrides: Partial<ExtensionOptions> = {}): (pi:
       if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
       requestReply(ctx, lastAssistant(messages), ctx.sessionManager.getSessionId());
     });
+
+    // omp: shadow the built-in `ask` and race its native dialog against the panel; the first
+    // answer wins. pi has no built-in `ask`.
+    let askRegistered = false;
+
+    pi.on("session_start", (_event, ctx) => {
+      if (askRegistered || !isOmp(ctx)) return;
+      const builtin = pi.getAllTools().find((tool) => tool.name === "ask" && tool.sourceInfo.source === "builtin");
+      if (!builtin) return;
+      askRegistered = true;
+      const ask: OmpToolDefinition = {
+        name: "ask",
+        description: builtin.description,
+        parameters: builtin.parameters,
+        // The native tool's traits (`tools/ask.ts`). Exclusive: the dialog is one shared UI
+        // surface, so two concurrent asks would clobber each other.
+        label: "Ask",
+        approval: "read",
+        strict: true,
+        loadMode: "discoverable",
+        concurrency: "exclusive",
+        execute: (_toolCallId, params, signal, _onUpdate, toolCtx) =>
+          answerAsk(params as Record<string, unknown>, signal, toolCtx as unknown as OmpToolContext),
+      };
+      pi.registerTool(ask);
+    });
+
+    /** Runs the native `ask`, plus the panel when a guard doesn't rule it out. */
+    async function answerAsk(params: Record<string, unknown>, signal: AbortSignal | undefined, ctx: OmpToolContext) {
+      if (!ctx.invokeTool) throw new Error("omp offers no native `ask` to delegate to");
+      // The panel must show and answer the text native shows; native gets the call unchanged.
+      const input = sanitizeAskInput(params as unknown as AskInput);
+      const request =
+        canShowPanel(ctx) && ctx.agent.kind === "main" && !signal?.aborted
+          ? toQuestionRequest(input, ctx.sessionManager.getSessionId(), ctx.cwd)
+          : undefined;
+      const executable = request && locateApp(options.agentsDir);
+      if (!request || !executable) return ctx.invokeTool(params);
+
+      const abortNativeDialog = new AbortController();
+      const native = ctx.invokeTool(params, {
+        signal: signal ? AbortSignal.any([signal, abortNativeDialog.signal]) : abortNativeDialog.signal,
+      });
+      const hook = runHook(executable, "question", request);
+      askHooks.add(hook);
+      const kill = () => hook.kill();
+      signal?.addEventListener("abort", kill, { once: true });
+      const disarmHardKill = armHardKill(kill);
+      try {
+        // Resolves with the panel's answer, or nothing once native settled or the panel closed
+        // without one. Handling native's rejection here also swallows the one the panel's win causes.
+        const answer = await Promise.race([
+          native.then(() => undefined, () => undefined),
+          hook.stdout.then((stdout) => (stdout === undefined ? undefined : parseQuestionAnswers(stdout, input))),
+        ]);
+        if (answer) {
+          abortNativeDialog.abort();
+          return answer;
+        }
+        return await native;
+      } finally {
+        disarmHardKill();
+        signal?.removeEventListener("abort", kill);
+        askHooks.delete(hook);
+        hook.kill();
+      }
+    }
   };
 }
 
@@ -106,6 +198,19 @@ interface OmpContext extends ExtensionContext {
   agent: { kind: "main" | "sub" };
 }
 
+/** The `ctx` omp passes to a tool that re-registers a built-in: `invokeTool` runs the native one. */
+interface OmpToolContext extends OmpContext {
+  invokeTool?(params: Record<string, unknown>, options?: { signal?: AbortSignal }): Promise<AgentToolResult<unknown>>;
+}
+
+/** omp-only tool traits (`extensibility/extensions/types.ts`, proxied by `RegisteredToolAdapter`). */
+interface OmpToolDefinition extends ToolDefinition {
+  approval: "read";
+  strict: boolean;
+  loadMode: "discoverable";
+  concurrency: "exclusive";
+}
+
 interface OmpAgentEndEvent extends AgentEndEvent {
   /** True when omp will continue on its own (retry, compaction recovery, reminders, async wakes). */
   willContinue?: boolean;

package/src/question.ts

@@ -0,0 +1,194 @@
+/** The parts of an omp `ask` call this extension reads (`tools/ask.ts` input schema). */
+export interface AskInput {
+  questions: AskQuestion[];
+}
+
+export interface AskQuestion {
+  id: string;
+  question: string;
+  header?: string;
+  options: { label: string; description?: string; preview?: string }[];
+  multi?: boolean;
+  recommended?: number;
+}
+
+/** What `agent-hook question` reads on stdin: a Claude Code `AskUserQuestion` PreToolUse call. */
+export interface QuestionRequest {
+  hook_event_name: "PreToolUse";
+  tool_name: "AskUserQuestion";
+  tool_input: { questions: PanelQuestion[] };
+  session_id: string;
+  cwd: string;
+}
+
+interface PanelQuestion {
+  question: string;
+  header?: string;
+  options: { label: string; description?: string }[];
+  multiSelect: boolean;
+}
+
+/**
+ * Strips the `\r` runs models sometimes inject, as native `ask` does before it shows or answers a
+ * call (`sanitizeAskParams` in `tools/ask.ts` at v18.12.6), so the panel shows and answers the
+ * same text native would.
+ */
+export function sanitizeAskInput(input: AskInput): AskInput {
+  return {
+    ...input,
+    questions: input.questions.map((q) => ({
+      ...q,
+      id: sanitizeCarriageReturns(q.id),
+      question: sanitizeCarriageReturns(q.question),
+      ...(q.header === undefined ? {} : { header: sanitizeCarriageReturns(q.header) }),
+      options: q.options.map((o) => ({
+        ...o,
+        label: sanitizeCarriageReturns(o.label),
+        ...(o.description === undefined ? {} : { description: sanitizeCarriageReturns(o.description) }),
+        ...(o.preview === undefined ? {} : { preview: sanitizeCarriageReturns(o.preview) }),
+      })),
+    })),
+  };
+}
+
+/** omp's `sanitizeCarriageReturns` (`pi-tui/render/render-utils.ts` at v18.12.6). */
+function sanitizeCarriageReturns(text: string): string {
+  if (!text.includes("\r")) return text;
+  return text.replaceAll("\r\n", "\n").replace(/\r+/g, " ");
+}
+
+/**
+ * Maps an `ask` call to the stdin of `agent-hook question`. Returns nothing when the panel
+ * can't represent the call: it keys answers by question text, so two questions with the same
+ * text can't be told apart.
+ */
+export function toQuestionRequest(input: AskInput, sessionId: string, cwd: string): QuestionRequest | undefined {
+  const texts = new Set(input.questions.map((q) => q.question));
+  if (texts.size !== input.questions.length) return undefined;
+  return {
+    hook_event_name: "PreToolUse",
+    tool_name: "AskUserQuestion",
+    tool_input: {
+      questions: input.questions.map((q) => ({
+        question: q.question,
+        ...(q.header === undefined ? {} : { header: q.header }),
+        options: q.options.map((o) => ({
+          label: o.label,
+          ...(o.description === undefined ? {} : { description: o.description }),
+        })),
+        multiSelect: q.multi ?? false,
+      })),
+    },
+    session_id: sessionId,
+    cwd,
+  };
+}
+
+/** One answered question, as native `ask` reports it in `details.results` (`AskToolDetails`). */
+export interface QuestionResult {
+  id: string;
+  question: string;
+  options: string[];
+  multi: boolean;
+  selectedOptions: string[];
+  customInput?: string;
+}
+
+/** The `ask` tool result: one question puts its answer in `details`, several in `details.results`. */
+export interface AskResult {
+  content: [{ type: "text"; text: string }];
+  details: Partial<Omit<QuestionResult, "id">> & { results?: QuestionResult[] };
+}
+
+/**
+ * Maps the stdout of `agent-hook question` to the result omp's native `ask` returns for the same
+ * selections (`tools/ask.ts` at v18.12.6). Returns nothing unless the panel allowed the call with
+ * an answer for every question: dismissed, timed out, empty or malformed output.
+ */
+export function parseQuestionAnswers(stdout: string, input: AskInput): AskResult | undefined {
+  const answers = readAnswers(stdout);
+  if (answers === undefined) return undefined;
+  const results: QuestionResult[] = [];
+  for (const q of input.questions) {
+    const answer = answers[q.question];
+    if (typeof answer !== "string" || answer === "") return undefined;
+    results.push(toResult(q, answer));
+  }
+  const [only] = results;
+  if (only !== undefined && results.length === 1) {
+    const { id: _, ...details } = only;
+    return { content: [{ type: "text", text: formatSingleQuestionResponse(only) }], details };
+  }
+  return {
+    content: [{ type: "text", text: `User answers:\n${results.map(formatQuestionResult).join("\n")}` }],
+    details: { results },
+  };
+}
+
+/** The parts of `agent-hook question` stdout this extension reads; any of them may be missing or wrong. */
+interface HookOutput {
+  hookSpecificOutput?: { permissionDecision?: unknown; updatedInput?: { answers?: unknown } };
+}
+
+/** The `updatedInput.answers` of an allowed `agent-hook question` call, keyed by question text. */
+function readAnswers(stdout: string): Record<string, unknown> | undefined {
+  let json: HookOutput | null;
+  try {
+    json = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  const output = json?.hookSpecificOutput;
+  if (output?.permissionDecision !== "allow") return undefined;
+  const answers = output.updatedInput?.answers;
+  return typeof answers === "object" && answers !== null ? (answers as Record<string, unknown>) : undefined;
+}
+
+/**
+ * The panel answers with one label, the picked labels joined with ", " in option order
+ * (multi-select), or free text. Anything that isn't a label (or labels) is custom input.
+ */
+function toResult(q: AskQuestion, answer: string): QuestionResult {
+  const labels = q.options.map((o) => o.label);
+  const multi = q.multi ?? false;
+  const selected = labels.includes(answer) ? [answer] : multi ? splitLabels(answer, labels, 0) : undefined;
+  const base = { id: q.id, question: q.question, options: labels, multi };
+  return selected === undefined
+    ? { ...base, selectedOptions: [], customInput: answer }
+    : { ...base, selectedOptions: selected };
+}
+
+/** Labels from `labels[from..]`, in order, whose ", "-join is `value`; labels may contain ", " themselves. */
+function splitLabels(value: string, labels: string[], from: number): string[] | undefined {
+  for (let i = from; i < labels.length; i++) {
+    const label = labels[i] as string;
+    if (value === label) return [label];
+    if (!value.startsWith(`${label}, `)) continue;
+    const rest = splitLabels(value.slice(label.length + 2), labels, i + 1);
+    if (rest !== undefined) return [label, ...rest];
+  }
+  return undefined;
+}
+
+// The two formatters mirror omp's `tools/ask.ts` (v18.12.6) for the answers the panel can give:
+// picked labels or custom input, never both, and no note or timeout.
+
+function formatQuestionResult(result: QuestionResult): string {
+  if (result.customInput !== undefined) return `${result.id}: "${result.customInput}"`;
+  const picked = result.multi ? `[${result.selectedOptions.join(", ")}]` : result.selectedOptions[0];
+  return `${result.id}: ${picked}`;
+}
+
+function formatSingleQuestionResponse(result: QuestionResult): string {
+  if (result.customInput === undefined) {
+    return result.multi
+      ? `User selected: ${result.selectedOptions.join(", ")}`
+      : `User selected: ${result.selectedOptions[0]}`;
+  }
+  return result.customInput.includes("\n")
+    ? `User provided custom input:\n${result.customInput
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n")}`
+    : `User provided custom input: ${result.customInput}`;
+}