shariq-pi-extensions 0.2.6 → 0.2.8

package/README.md

@@ -31,6 +31,7 @@ The package contains:
 - Firecrawl search and scraping
 - Git status UI
 - persistent task goals
+- configurable steer, interrupt, or follow-up input behavior
 - dedicated multi-agent orchestration
 - Pi Memory
 - per-response TPS, TTFT, elapsed-time, and output status

package/docs/EXTENSIONS.md

@@ -38,7 +38,7 @@ The goal extension adds persistent, branch-safe objectives, progress evidence, b
 
 The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
 
-The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as a turn-triggering follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle; status tools are for explicit inspection, not waiting.
+The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as an extension-originated user follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context; status tools are for explicit inspection, not waiting.
 
 ### [Orchestration](../extensions/orchestration/README.md)
 
@@ -50,7 +50,7 @@ The model-facing `create_orchestration` tool starts planning only after an expli
 
 Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
 
-Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as a turn-triggering follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as an extension-originated user follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle with the bounded output guaranteed in model context. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
 
 ## Web access
 
@@ -80,6 +80,10 @@ Adds repository state to Pi's interface. `/lg` opens the local Git view and `/pr
 
 `/copy-all` copies the current conversation in a readable form while omitting tool protocol noise that does not belong in the transcript.
 
+### [Input mode](../extensions/input-mode/README.md)
+
+`/input-mode` chooses what ordinary Enter does while Pi is running: steer before the next model step, interrupt the active run, or wait as a follow-up. The global selection lives in `<agent-dir>/input-mode.json`; explicit Alt+Enter follow-ups and non-interactive inputs retain native behavior. Pi does not expose extension rows in core `/settings`, so this is a dedicated extension settings picker rather than a private TUI patch.
+
 ### [Shell shortcuts](../extensions/shell-shortcuts/README.md)
 
 Adds `/exit` as an alias for Pi's normal quit command. Keep this extension limited to small, low-risk conveniences.

package/extensions/background-terminals/README.md

@@ -10,7 +10,7 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the parent can continue other work or end its turn rather than poll.
+Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with bounded output guaranteed in model context, so the parent can continue other work or end its turn rather than poll.
 
 ## User interface
 
@@ -34,7 +34,7 @@ Each output response carries a byte cursor. Pass it to the next read/write opera
 - Output is sanitized before TUI or model rendering.
 - Processes run in their own PTY process group and are stopped on session shutdown, replacement, or reload.
 - Shutdown and stop operations are bounded and escalate from SIGTERM to SIGKILL.
-- Model-started terminals immediately hand one completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
+- Model-started terminals immediately hand one model-visible completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
 - Reading settled output does not consume or suppress the automatic completion delivery.
 - Completion delivery is keyed by terminal id to prevent duplicate follow-ups.
 

package/extensions/input-mode/README.md

@@ -0,0 +1,13 @@
+# Input mode
+
+Controls what ordinary **Enter** does when the interactive Pi agent is already running:
+
+- `steer` (default) queues the message before the agent's next model step.
+- `interrupt` signals Pi's active abort controller immediately, then preserves the submitted text, images, prompt-template expansion, and normal delivery as the next input.
+- `follow-up` queues the message until the active run finishes.
+
+Use `/input-mode` for the picker or `/input-mode steer|interrupt|follow-up` for direct selection. The global choice is stored with restrictive permissions in `<agent-dir>/input-mode.json`; non-default modes appear in Pi's status area.
+
+Pi does not expose an extension API for adding rows to its built-in `/settings` selector, so this extension owns a dedicated settings command rather than patching private TUI internals. The existing core **Steering mode** and **Follow-up mode** settings remain batching controls (`all` versus `one-at-a-time`).
+
+Explicit Alt+Enter follow-ups, extension-originated messages, commands, idle input, compaction input, and RPC input retain Pi's native behavior. Interrupt cancellation is cooperative: Pi stops model streaming and abort-aware tools, but it cannot undo an external side effect that already completed or force a third-party operation that ignores its abort signal to stop.

package/extensions/input-mode/config.ts

@@ -0,0 +1,46 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const INPUT_MODES = ["steer", "interrupt", "follow-up"] as const;
+export type InputMode = (typeof INPUT_MODES)[number];
+
+interface InputModeDocument {
+  version: 1;
+  mode: InputMode;
+}
+
+export function inputModePath(): string {
+  return path.join(getAgentDir(), "input-mode.json");
+}
+
+export function isInputMode(value: unknown): value is InputMode {
+  return typeof value === "string" && INPUT_MODES.includes(value as InputMode);
+}
+
+export function loadInputMode(file = inputModePath()): InputMode {
+  try {
+    const document = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<InputModeDocument>;
+    return document.version === 1 && isInputMode(document.mode) ? document.mode : "steer";
+  } catch {
+    return "steer";
+  }
+}
+
+export function saveInputMode(mode: InputMode, file = inputModePath()): void {
+  const directory = path.dirname(file);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const document: InputModeDocument = { version: 1, mode };
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    fs.chmodSync(file, 0o600);
+  } finally {
+    try {
+      fs.rmSync(temporary, { force: true });
+    } catch {
+      // Best-effort cleanup after a failed atomic replacement.
+    }
+  }
+}

package/extensions/input-mode/index.ts

@@ -0,0 +1,104 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionUIContext,
+  InputEvent,
+  InputEventResult,
+} from "@earendil-works/pi-coding-agent";
+import {
+  INPUT_MODES,
+  isInputMode,
+  loadInputMode,
+  saveInputMode,
+  type InputMode,
+} from "./config.ts";
+
+const STATUS_KEY = "input-mode";
+
+interface InputModeExtensionOptions {
+  configFile?: string;
+}
+
+function modelInput(event: InputEvent) {
+  if (!event.images?.length) return event.text;
+  return [{ type: "text" as const, text: event.text }, ...event.images];
+}
+
+export function createInputModeExtension(options: InputModeExtensionOptions = {}) {
+  return (pi: ExtensionAPI) => {
+    let mode = loadInputMode(options.configFile);
+    let ui: ExtensionUIContext | undefined;
+
+    const updateStatus = () => {
+      if (!ui) return;
+      ui.setStatus(STATUS_KEY, mode === "steer" ? undefined : `input: ${mode}`);
+    };
+
+    const selectMode = async (args: string, ctx: ExtensionCommandContext) => {
+      const requested = args.trim().toLowerCase();
+      let selected: InputMode | undefined;
+      if (requested) {
+        if (!isInputMode(requested)) {
+          ctx.ui.notify(`Usage: /input-mode [${INPUT_MODES.join("|")}]`, "warning");
+          return;
+        }
+        selected = requested;
+      } else if (ctx.hasUI) {
+        selected = await ctx.ui.select(
+          `Input behavior while agent is running (current: ${mode})`,
+          [...INPUT_MODES],
+        ) as InputMode | undefined;
+      } else {
+        ctx.ui.notify(`Input mode: ${mode}. Usage: /input-mode [${INPUT_MODES.join("|")}]`, "info");
+        return;
+      }
+      if (!selected) return;
+      mode = selected;
+      saveInputMode(mode, options.configFile);
+      updateStatus();
+      const explanation = mode === "interrupt"
+        ? "new Enter input aborts the active run before it is delivered"
+        : mode === "follow-up"
+          ? "new Enter input waits until the active run finishes"
+          : "new Enter input is injected before the agent's next step";
+      ctx.ui.notify(`Input mode: ${mode} — ${explanation}.`, "info");
+    };
+
+    pi.registerCommand("input-mode", {
+      description: "Choose Enter behavior while the agent runs: steer, interrupt, or follow-up",
+      handler: selectMode,
+    });
+
+    pi.on("session_start", (_event, ctx) => {
+      if (ctx.hasUI) ui = ctx.ui;
+      updateStatus();
+    });
+
+    pi.on("session_shutdown", () => {
+      ui?.setStatus(STATUS_KEY, undefined);
+      ui = undefined;
+    });
+
+    pi.on("input", (event, ctx): InputEventResult => {
+      // Extension-originated results and explicit Alt+Enter follow-ups retain
+      // their requested delivery. Idle input and commands use Pi unchanged.
+      if (event.source !== "interactive" || event.streamingBehavior !== "steer") {
+        return { action: "continue" };
+      }
+      if (mode === "steer") return { action: "continue" };
+      if (mode === "follow-up") {
+        pi.sendUserMessage(modelInput(event), { deliverAs: "followUp" });
+        return { action: "handled" };
+      }
+
+      // Abort is signalled synchronously. Returning continue preserves Pi's
+      // normal template expansion, image handling, history, and queue logic;
+      // the prompt becomes a fresh turn if abort settlement wins the race, or
+      // a steering message consumed immediately after the aborted run.
+      ctx.abort();
+      return { action: "continue" };
+    });
+  };
+}
+
+export default createInputModeExtension();

package/extensions/shared/README.md

@@ -8,7 +8,7 @@ Internal runtime utilities used by more than one extension. This directory is no
 - `child-session.ts` owns trust-aware child resources and bounded session shutdown.
 - `context-utilization.ts` formats model-context usage and capacity.
 - `dashboard-state.ts` keeps list selection stable as live rows change.
-- `settlement-delivery.ts` immediately hands asynchronous results to Pi as turn-triggering follow-ups.
+- `settlement-delivery.ts` immediately hands asynchronous results to Pi as extension-originated user follow-ups, guaranteeing model-visible settlement context.
 - `tool-call-timeout.ts` applies cancellation-aware execution limits to registered tools.
 - `tui-dashboard.ts` provides bounded, sanitized terminal-dashboard rendering helpers.
 

package/extensions/shared/settlement-delivery.ts

@@ -3,9 +3,17 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 type SettlementMessage = Parameters<ExtensionAPI["sendMessage"]>[0];
 
 /**
- * Hand settlement to Pi immediately. Pi starts a turn when idle and queues the
- * same message as a follow-up when the parent is still running.
+ * Hand settlement to Pi as an extension-originated user follow-up. A custom
+ * message can wake the parent yet fail to appear in the invoked model turn;
+ * sendUserMessage guarantees that the bounded result is model-visible. Pi
+ * starts a turn when idle and queues the same input while the parent is active.
  */
 export function deliverSettlement(pi: ExtensionAPI, message: SettlementMessage): void {
-  pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+  const content = typeof message.content === "string"
+    ? message.content
+    : message.content
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n");
+  pi.sendUserMessage(content, { deliverAs: "followUp" });
 }

package/extensions/subagents/README.md

@@ -19,7 +19,7 @@ The system is deliberately flat. Only the main Pi thread can spawn subagents. Ch
 - `reply_question` — answer a child’s blocking `ask_parent` request
 - `task` — atomically reserve capacity for up to the configured limit (maximum 50), start the fan-out in the background, and return child ids immediately
 
-Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the main turn can continue independent work or end and remain available to the user.
+Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context, so the main turn can continue independent work or end and remain available to the user.
 
 ## Profiles and capabilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",
@@ -47,6 +47,7 @@
       "./extensions/firecrawl-web/index.ts",
       "./extensions/git-info/index.ts",
       "./extensions/goal/index.ts",
+      "./extensions/input-mode/index.ts",
       "./extensions/orchestration/index.ts",
       "./extensions/performance-status/index.ts",
       "./extensions/pi-memory/index.ts",

package/skills/background-terminals/SKILL.md

@@ -24,9 +24,9 @@ Provide:
 - the working directory when it differs from the current directory;
 - an initial wait only when startup output is needed for the next decision.
 
-After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
+After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output visible in model context. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
 
-When that completion follow-up invokes the next turn, treat its attached output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
+When that completion follow-up invokes the next turn, treat its model-visible output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
 
 ## Inspect and interact only when necessary
 

package/skills/subagents/SKILL.md

@@ -24,14 +24,14 @@ This skill governs temporary Pi child agents. The `codex-thread-orchestrator` sk
 
 ## Wait by notification; inspect progress only when justified
 
-A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next main-agent turn. The parent does not need to remain active or check once before ending its turn.
+A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next main-agent turn with the summary visible in model context. The parent does not need to remain active or check once before ending its turn.
 
 After dispatch:
 
 1. Continue only parent work that is independently useful to the requested result.
 2. If no such work remains, end the turn immediately. A short progress note is enough when the user needs one.
 3. Do not call `wait_agent`, `list_agents`, or `check_agent` in the same turn merely because the child was just launched. Ending the turn is the waiting mechanism.
-4. When a child completion notice invokes the main agent, treat the attached summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
+4. When a child completion notice invokes the main agent, treat its model-visible summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
 
 A progress check is reasonable when the user asks for status, a child has run materially longer than expected for its task and model, an interruption left its state unclear, or current status will change an immediate coordination decision. Prefer `check_agent` for one known child and `list_agents` for a batch overview. Use `wait_agent` to collect results already expected to be available, not as a running-status probe.