pi-interrupt-steer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+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

@@ -0,0 +1,72 @@
+# pi-interrupt-steer
+
+Interrupt a running Pi turn and send the editor text as one new user message.
+
+## Install
+
+```sh
+pi install npm:pi-interrupt-steer
+```
+
+## External contract
+
+The default shortcut is `ctrl+alt+enter`. While Pi is streaming, it aborts the
+current operation and waits up to five seconds for Pi to become idle before
+sending the editor text. Pi first restores queued steering messages, then
+queued follow-up messages, and appends the text already in the editor. Each part
+is separated by a blank line. Pi stores steering and follow-up messages in
+separate queues, so their original cross-type typing order is not preserved. The
+extension sends that combined text once, then treats a user `message_start` as
+acceptance only when the message text exactly matches what it sent. For string
+content it compares the string; for content parts it compares their text joined
+together. Other user messages are ignored while it waits up to 60 seconds. It
+clears the editor only if it still contains the submitted text. A prompt rewritten
+by another extension can still be sent, but the original editor text stays and
+the timeout warning appears. While waiting for Pi to become idle or start a
+matching message, repeated shortcut presses show an info notice and do not abort
+or send again. If Pi does not start a matching message within 60 seconds, the text
+stays in the editor and the warning says to check the transcript before sending
+it again; an input handler may have handled the prompt without starting a message.
+
+When Pi is idle, the shortcut sends the editor text without aborting. With an
+empty editor and no queued session messages, it leaves the run alone and shows a
+notification. During compaction, the shortcut cannot see Pi's separate
+compaction queue, so an empty-editor press with no session messages visible to
+the shortcut does not interrupt Pi; Pi delivers its compaction queue after
+compaction. For idle sends as well, the extension clears the editor only after a
+matching user `message_start` and only if the editor still contains the submitted
+text.
+
+The terminal must send `ctrl+alt+enter` distinctly for this shortcut to fire.
+A terminal without the kitty keyboard protocol may send the legacy `ESC CR`
+sequence instead. Pi interprets that as `alt+enter`: the editor text is queued as
+a follow-up, the current response finishes first, and the run is not interrupted.
+
+## Settings
+
+Set `key` in `pi-interrupt-steer.json` in the Pi agent settings directory, or use
+`PI_INTERRUPT_STEER_KEY`:
+
+| setting | default | environment variable | purpose |
+|---|---|---|---|
+| `key` | `ctrl+alt+enter` | `PI_INTERRUPT_STEER_KEY` | Shortcut with one or more modifiers and a letter, digit, or named key. |
+
+For example:
+
+```json
+{
+  "key": "ctrl+shift+x"
+}
+```
+
+Valid modifiers are `ctrl`, `alt`, `shift`, and `super`. Valid named keys are
+`enter`, `escape`, `tab`, `space`, `backspace`, `delete`, `up`, `down`, `left`,
+`right`, `home`, and `end`.
+
+## If the contract is unmet
+
+An invalid key uses `ctrl+alt+enter` and shows one warning. If Pi does not emit
+a matching user `message_start` within 60 seconds after the send, the text remains
+in the editor and the extension warns you to check the transcript before sending
+it again. If the editor changes while Pi is processing the message, the extension
+leaves the current text there when it differs from the submitted text.

package/interrupt-steer.js

@@ -0,0 +1,184 @@
+// shared/announce.ts
+var stderrAnnounced = /* @__PURE__ */ new Set();
+function announce(ctx, message, level, reason = message) {
+  if (ctx?.hasUI === false) {
+    if (stderrAnnounced.has(reason)) return;
+    stderrAnnounced.add(reason);
+    try {
+      process.stderr.write(`${message}
+`);
+    } catch {
+    }
+    return;
+  }
+  try {
+    ctx?.ui?.notify?.(message, level);
+  } catch {
+  }
+}
+
+// shared/settings.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+var announcedConfigErrors = /* @__PURE__ */ new Set();
+function readConfig(path, ctx) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!announcedConfigErrors.has(path)) {
+      announcedConfigErrors.add(path);
+      const message = error instanceof Error ? error.message : String(error);
+      announce(ctx, `settings: could not parse ${path} (${message}); using defaults.`, "warning", `settings-parse:${path}`);
+    }
+    return {};
+  }
+}
+function resolveSettings(name, definitions, context, runtime = {}) {
+  const environment = runtime.environment ?? process.env;
+  const globalPath = join(runtime.agentDir ?? getAgentDir(), `${name}.json`);
+  const projectPath = join(context.cwd, CONFIG_DIR_NAME, `${name}.json`);
+  const globalConfig = readConfig(globalPath, context);
+  const projectConfig = context.isProjectTrusted() ? readConfig(projectPath, context) : {};
+  const resolved = {};
+  for (const key of Object.keys(definitions)) {
+    const definition = definitions[key];
+    let value = definition.default;
+    let provenance = { source: "default" };
+    if (definition.discover) {
+      try {
+        const discovered = definition.discover();
+        if (discovered !== void 0) {
+          value = discovered.value;
+          provenance = { source: "discovered", name: definition.discoverName ?? "discovery" };
+        }
+      } catch {
+      }
+    }
+    if (Object.hasOwn(globalConfig, key)) {
+      value = globalConfig[key];
+      provenance = { source: "global", path: globalPath };
+    }
+    if (Object.hasOwn(projectConfig, key)) {
+      value = projectConfig[key];
+      provenance = { source: "project", path: projectPath };
+    }
+    const environmentValue = environment[definition.env];
+    if (environmentValue !== void 0) {
+      value = definition.parseEnv ? definition.parseEnv(environmentValue) : environmentValue;
+      provenance = { source: "environment", name: definition.env };
+    }
+    resolved[key] = { value, provenance };
+  }
+  return resolved;
+}
+
+// extensions/interrupt-steer/interrupt-steer.ts
+var DEFAULT_KEY = "ctrl+alt+enter";
+var KEY_SETTING = { key: { default: DEFAULT_KEY, env: "PI_INTERRUPT_STEER_KEY" } };
+var IDLE_WAIT_TIMEOUT_MS = 5e3;
+var MESSAGE_ACCEPT_TIMEOUT_MS = 6e4;
+var IDLE_POLL_INTERVAL_MS = 25;
+async function waitUntilIdle(ctx) {
+  const deadline = Date.now() + IDLE_WAIT_TIMEOUT_MS;
+  while (!ctx.isIdle()) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(IDLE_POLL_INTERVAL_MS, remaining)));
+  }
+  return true;
+}
+function isShortcutKey(value) {
+  if (typeof value !== "string") return false;
+  const parts = value.split("+");
+  const base = parts.pop();
+  return parts.length > 0 && new Set(parts).size === parts.length && parts.every((part) => ["ctrl", "alt", "shift", "super"].includes(part)) && base !== void 0 && (/^[a-z0-9]$/.test(base) || ["enter", "escape", "tab", "space", "backspace", "delete", "up", "down", "left", "right", "home", "end"].includes(base));
+}
+function waitForAcceptedUserMessage(pi, text) {
+  return new Promise((resolve) => {
+    let timeout;
+    let unsubscribe;
+    let settled = false;
+    const finish = (accepted) => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== void 0) clearTimeout(timeout);
+      unsubscribe?.();
+      resolve(accepted);
+    };
+    unsubscribe = pi.on("message_start", (event) => {
+      const content = event.message.content;
+      const messageText = typeof content === "string" ? content : content.filter((part) => part.type === "text").map((part) => part.text).join("");
+      if (event.message.role === "user" && messageText === text) finish(true);
+    });
+    timeout = setTimeout(() => finish(false), MESSAGE_ACCEPT_TIMEOUT_MS);
+    try {
+      pi.sendUserMessage(text);
+    } catch {
+      finish(false);
+    }
+  });
+}
+async function sendEditorText(pi, ctx, text) {
+  if (!text) {
+    announce(ctx, "pi-interrupt-steer: nothing to send", "info");
+    return;
+  }
+  if (!await waitForAcceptedUserMessage(pi, text)) {
+    announce(ctx, "pi-interrupt-steer: Pi has not started the message yet; text was kept. Check the transcript before sending it again.", "warning");
+    return;
+  }
+  if (ctx.ui.getEditorText() === text) ctx.ui.setEditorText("");
+}
+function registerInterruptSteer(pi, settingsRuntime = {}) {
+  const resolved = resolveSettings("pi-interrupt-steer", KEY_SETTING, {
+    cwd: process.cwd(),
+    hasUI: true,
+    isProjectTrusted: () => false
+  }, settingsRuntime);
+  const configuredKey = resolved.key.value;
+  const validKey = isShortcutKey(configuredKey);
+  const key = validKey ? configuredKey : DEFAULT_KEY;
+  let warnedAboutKey = false;
+  let inFlight = false;
+  pi.on("session_start", (_event, ctx) => {
+    if (!validKey && !warnedAboutKey) {
+      announce(ctx, "pi-interrupt-steer: invalid key setting; using ctrl+alt+enter", "warning", "pi-interrupt-steer:invalid-key");
+      warnedAboutKey = true;
+    }
+  });
+  pi.registerShortcut(key, {
+    description: "Interrupt the current run and send the editor text",
+    handler: async (ctx) => {
+      if (inFlight) {
+        announce(ctx, "pi-interrupt-steer: already waiting for Pi; this press did not send again", "info");
+        return;
+      }
+      inFlight = true;
+      try {
+        const idle = ctx.isIdle();
+        const text = ctx.ui.getEditorText();
+        if (idle) {
+          await sendEditorText(pi, ctx, text);
+          return;
+        }
+        if (!text && !ctx.hasPendingMessages()) {
+          announce(ctx, "pi-interrupt-steer: nothing to send", "info");
+          return;
+        }
+        ctx.abort();
+        if (!await waitUntilIdle(ctx)) {
+          announce(ctx, "pi-interrupt-steer: agent did not become idle within 5 seconds; text left in the editor", "warning");
+          return;
+        }
+        await sendEditorText(pi, ctx, ctx.ui.getEditorText());
+      } finally {
+        inFlight = false;
+      }
+    }
+  });
+}
+export {
+  registerInterruptSteer as default
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-interrupt-steer",
+  "version": "0.1.0",
+  "description": "Interrupt a Pi run and send the editor text as the next prompt.",
+  "type": "module",
+  "main": "./interrupt-steer.js",
+  "exports": "./interrupt-steer.js",
+  "files": [
+    "interrupt-steer.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/interrupt-steer"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/interrupt-steer#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./interrupt-steer.js"
+    ]
+  }
+}