pi-cancel-current-shell 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# pi-cancel-current-shell
 
-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.
+A Pi extension that adds `/cancel-current-shell`.
+
+It requests cancellation of the most recently started active built-in `bash` or
+`powershell` tool execution while allowing Pi's agent turn to continue. The
+cancelled shell should return a normal tool result describing the cancellation,
+so the model can inspect prior output and decide what to do next.
+
+## Requirements
+
+- Pi with extension support.
+- A Pi version that exports `createBashTool` and `createPowerShellTool` from
+  `@earendil-works/pi-coding-agent`.
+- Node.js runtime supported by your Pi installation.
+
+## Install from a local folder
+
+From the parent directory containing this package folder:
+
+```sh
+pi install ./pi-cancel-current-shell
+```
+
+For npm publication, remove no files: the included `package.json` already
+contains the Pi `pi.extensions` manifest. After publishing, install it with:
+
+```sh
+pi install npm:pi-cancel-current-shell
+```
+
+Alternatively, copy the whole `pi-cancel-current-shell` folder into
+`~/.pi/agent/extensions/`. Pi discovers packages with a `package.json` containing
+a `pi.extensions` entry.
+
+The extension imports the shell-tool factories from Pi's extension API
+package. Pi documents this package as an available extension import. If your
+Pi distribution uses a different package name/version, adjust the import to
+match that distribution before installing.
+
+Restart Pi or run `/reload`.
+
+## Usage
+
+While Pi is executing a shell tool, enter:
+
+```text
+/cancel-current-shell
+```
+
+The extension selects the most recently started active `bash` or `powershell`
+execution and aborts its tool-level signal. It does **not** call `ctx.abort()`.
+
+Expected flow:
+
+1. Pi starts a shell tool call.
+2. You invoke `/cancel-current-shell`.
+3. The extension aborts that shell tool's signal.
+4. Pi's shell implementation performs its platform-specific process cleanup.
+5. The tool returns cancellation information to the model.
+6. The agent continues its existing turn.
+
+## Shell and platform behavior
+
+The extension delegates actual shell execution and process cleanup to Pi's
+`createBashTool()` and `createPowerShellTool()` implementations. This is
+intentional: it avoids hardcoding `bash`, `pwsh`, `taskkill`, Unix signals, or
+custom process-tree logic.
+
+- `bash` uses Pi's configured `shellPath` and normal shell resolution.
+- `powershell` uses Pi's PowerShell tool and its configured platform behavior.
+- A custom executable selected through `shellPath` is supported insofar as Pi's
+  Bash tool supports it.
+- Windows, macOS, and Linux behavior depends on the process-management
+  implementation in the installed Pi version.
+
+This does not guarantee termination of detached processes, remote jobs,
+daemonized children, or work already delegated to another service.
+
+## Scope and limitations
+
+- The command cancels the most recently started active shell tool call. If
+  multiple shell calls are running concurrently, it targets only the newest.
+- It wraps the built-in `bash` and `powershell` tools. Third-party extensions
+  that replace those tools later may supersede this wrapper.
+- It cannot interrupt arbitrary custom tools or shell commands started outside
+  these Pi tools.
+- If Pi itself aborts the whole turn (for example, via Escape), that separate
+  cancellation still takes precedence.
+- The wrapper passes Pi's original abort signal through to the underlying tool.
+  If the agent turn is independently aborted, the original cancellation
+  behavior is preserved.
+
+## Development
+
+The extension is TypeScript and is loaded by Pi. No build step is required.
+
+```sh
+npm install
+```
+
+## Compatibility note
+
+Pi's extension and shell-tool APIs evolve. This package relies on the exported
+`createBashTool()` and `createPowerShellTool()` factories and their `execute()`
+contract. Verify those exports against the version of Pi you run before
+publishing this package to npm. The package is intentionally conservative about
+process management: it delegates that work to Pi rather than attempting
+cross-platform signal emulation itself.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "pi-cancel-current-shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cancel the active Pi bash or PowerShell tool execution without aborting the agent turn.",
+  "license": "MIT",
+  "author": "DrkWzrd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DrkWzrd/pi-cancel-current-shell.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "shell",
+    "cancellation"
+  ],
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.ts

@@ -0,0 +1,213 @@
+import {
+  createBashTool,
+  createPowerShellTool,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+
+type ToolLike = {
+  execute: (...args: any[]) => Promise<any>;
+  [key: string]: any;
+};
+
+type ActiveExecution = {
+  toolName: "bash" | "powershell";
+  controller: AbortController;
+  startedAt: number;
+};
+
+/**
+ * Combines several abort signals into one, with a dispose() that removes any
+ * listeners the fallback implementation attached.
+ */
+function combineSignals(signals: AbortSignal[]): {
+  signal: AbortSignal;
+  dispose: () => void;
+} {
+  if (typeof AbortSignal.any === "function") {
+    return { signal: AbortSignal.any(signals), dispose: () => {} };
+  }
+
+  const controller = new AbortController();
+  const listeners: Array<[AbortSignal, () => void]> = [];
+
+  const abort = () => {
+    if (!controller.signal.aborted) controller.abort();
+  };
+
+  for (const signal of signals) {
+    if (signal.aborted) {
+      abort();
+      break;
+    }
+    signal.addEventListener("abort", abort, { once: true });
+    listeners.push([signal, abort]);
+  }
+
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      for (const [signal, listener] of listeners) {
+        signal.removeEventListener("abort", listener);
+      }
+    },
+  };
+}
+
+/** Pulls the concatenated text content out of a tool result / partial update. */
+function extractText(result: any): string {
+  if (!result?.content || !Array.isArray(result.content)) return "";
+  return result.content
+    .filter((c: any) => c?.type === "text" && typeof c.text === "string")
+    .map((c: any) => c.text)
+    .join("");
+}
+
+/** Builds the message the model sees when the user cancels a shell command. */
+function cancellationMessage(toolName: string, partialOutput: string): string {
+  const header = `The user cancelled the ${toolName} script execution.`;
+  const output = partialOutput.trim();
+
+  return output
+    ? `${header} Output produced before cancellation:\n\n${partialOutput}\n\nInspect the output above and continue.`
+    : `${header} No output was produced before cancellation. Continue.`;
+}
+
+function cancellationResult(toolName: string, partialOutput: string) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: cancellationMessage(toolName, partialOutput),
+      },
+    ],
+    details: {},
+  };
+}
+
+/** Errors the base tool may throw on abort that carry no useful output. */
+function isGenericAbortMessage(message: string): boolean {
+  return /^(aborted|command aborted|the operation was aborted\.?)$/i.test(
+    message.trim(),
+  );
+}
+
+export default function (pi: ExtensionAPI) {
+  const active = new Map<string, ActiveExecution>();
+
+  // Keep Pi responsible for shell resolution, streaming, truncation, and
+  // platform-specific process-tree termination.
+  const bash = createBashTool(pi.cwd);
+  const powershell = createPowerShellTool(pi.cwd);
+
+  function wrapTool<T extends ToolLike>(
+    toolName: "bash" | "powershell",
+    baseTool: T,
+  ): T {
+    const wrapped = {
+      ...baseTool,
+      async execute(...args: any[]) {
+        const [toolCallId, _params, piSignal, onUpdate] = args as [
+          string,
+          unknown,
+          AbortSignal,
+          ((partial: any) => void) | undefined,
+          unknown,
+        ];
+
+        const controller = new AbortController();
+        const { signal, dispose } = combineSignals([
+          piSignal,
+          controller.signal,
+        ]);
+
+        active.set(toolCallId, {
+          toolName,
+          controller,
+          startedAt: Date.now(),
+        });
+
+        // Remember the latest streamed output while still forwarding every
+        // update to Pi so the UI keeps streaming normally.
+        // Assumes each update holds the current (possibly tail-truncated)
+        // output. If you only ever see the last chunk, switch to `+=`.
+        let lastPartial = "";
+
+        // Preserve every argument; replace only the signal and onUpdate.
+        const forwarded = [...args];
+        forwarded[2] = signal;
+        forwarded[3] = (partial: any) => {
+          const text = extractText(partial);
+          if (text) lastPartial = text;
+          if (typeof onUpdate === "function") onUpdate(partial);
+        };
+
+        const cancelledByUs = () =>
+          controller.signal.aborted && !piSignal.aborted;
+
+        try {
+          const result = await baseTool.execute(...forwarded);
+
+          // If the base tool resolves (rather than rejects) on abort, still
+          // surface the cancellation message along with whatever it returned.
+          if (cancelledByUs()) {
+            return cancellationResult(
+              toolName,
+              extractText(result) || lastPartial,
+            );
+          }
+
+          return result;
+        } catch (error: any) {
+          // Never propagate our own AbortError to Pi's agent loop.
+          if (cancelledByUs()) {
+            // Prefer streamed output. Some versions of Pi's shell tools embed
+            // the captured output in the abort error, so fall back to that
+            // unless it's just a generic "aborted" message.
+            const fallback =
+              error instanceof Error && !isGenericAbortMessage(error.message)
+                ? error.message
+                : "";
+            return cancellationResult(toolName, lastPartial || fallback);
+          }
+          throw error;
+        } finally {
+          dispose();
+          active.delete(toolCallId);
+        }
+      },
+    };
+
+    return wrapped as T;
+  }
+
+  // defaultActive: false so these re-registered wrappers do not force-activate
+  // on registration, keeping `-bash`/`-powershell` in defaultTools effective.
+  pi.registerTool({ ...wrapTool("bash", bash), defaultActive: false });
+  pi.registerTool({
+    ...wrapTool("powershell", powershell),
+    defaultActive: false,
+  });
+
+  pi.registerCommand("cancel-current-shell", {
+    description:
+      "Interrupt the most recently started bash or PowerShell command without cancelling the agent turn",
+    handler: async (_args, ctx) => {
+      const current = [...active.entries()].sort(
+        (a, b) => b[1].startedAt - a[1].startedAt,
+      )[0];
+
+      if (!current) {
+        ctx.ui.notify("No active shell execution to cancel.", "info");
+        return;
+      }
+
+      const [toolCallId, execution] = current;
+      execution.controller.abort();
+
+      ctx.ui.notify(
+        `Cancellation requested for ${execution.toolName} execution (${toolCallId}).`,
+        "warning",
+      );
+    },
+  });
+}