@vimsucks/pi-goon 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tom X Nguyen
+Copyright (c) 2026 vimsucks
+
+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,73 @@
-# Temporary Holding Version
+# @vimsucks/pi-goon
 
-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.
+通过 `/goon` 继续当前 Pi 会话，不向模型发送新的继续提示词。
+
+## 安装
+
+要求 Pi 1.0.0 或更新版本。
+
+当前可以从 GitHub 安装：
+
+```sh
+pi install git:github.com/vimsucks/pi-goon
+```
+
+npm 包名为 `@vimsucks/pi-goon`。发布到 npm 后，可以使用以下命令安装：
+
+```sh
+pi install npm:@vimsucks/pi-goon
+```
+
+安装后，在当前会话执行 `/reload`，或重新启动 Pi。
+
+## 使用
+
+- `/goon`：启动隐形继续。若当前正在生成，Pi 将继续请求加入原生 follow-up 队列。
+- `/goon status`：显示会话是否空闲，以及最后一条 assistant 消息的文本。
+- `/goon help`：显示命令帮助。
+
+网络请求失败或取消生成后，只要会话仍然存在，就可以执行 `/goon`。如果 Pi 已经退出，先恢复原会话，再执行 `/goon`。
+
+## 快捷键配置
+
+默认快捷键为 `Alt+G`，行为与 `/goon` 相同。快捷键不会提交或清空输入框中的文字。运行 `/hotkeys` 可以检查 Pi 当前启用的快捷键。
+
+要修改快捷键，在 `~/.pi/agent/settings.json` 中添加 `goon` 配置，保留已有的其他字段：
+
+```json
+{
+  "goon": {
+    "shortcut": "ctrl+alt+g"
+  }
+}
+```
+
+`goon.shortcut` 使用 Pi 按键标识符，例如 `alt+g`、`ctrl+alt+g` 或 `f6`。设为 `null` 可以禁用快捷键，`/goon` 命令仍然可用。缺少配置文件或 `goon.shortcut` 字段时，扩展使用 `alt+g`。
+
+扩展不再读取旧的 `goon.json`。如果已有该文件，将其中的 `shortcut` 值迁入 `settings.json` 的 `goon.shortcut` 字段。
+
+如果设置了 `PI_CODING_AGENT_DIR`，配置文件位于该目录下的 `settings.json`。配置仅作用于当前用户，不读取项目配置。修改配置后，执行 `/reload`。如果配置无效，Pi 会报告加载错误；修正配置后再次执行 `/reload`。
+
+快捷键由 Pi 原生机制处理。与其他快捷键冲突时，按 Pi 的冲突规则处理。macOS 终端需要将 Option 配置为 Alt/Meta，才能发送 `Alt+G`。
+
+## 工作方式与限制
+
+扩展通过 `pi.sendMessage()` 添加一条隐藏标记，并启动原生会话轮次。`context` 事件处理器在模型请求发出前移除该标记。模型不会收到新的 `go on` 提示词，界面也不会显示该标记，但会话文件仍保留隐藏记录。
+
+存在标记时，处理器还会移除末尾失败或取消的 assistant 消息。它保留带工具调用的消息，防止破坏工具调用与结果的配对。处理器不改写会话历史。
+
+扩展不会自动恢复，也不保证从中断的某个字精确接续。它保留 Pi 原生队列、重试和压缩行为。
+
+## 验证
+
+使用 Node.js 24 或更新版本运行无网络检查：
+
+```sh
+npm test
+```
+
+## 来源与许可
+
+本项目基于 [monotykamary/pi-invisible-continue](https://github.com/monotykamary/pi-invisible-continue) 的 npm 版本 `0.3.16`。原作者为 Tom X Nguyen，原包声明 MIT 许可。本项目保留其隐形继续与消息过滤逻辑，将命令改为 `/goon`，并使用独立的 `pi-goon:resume` 标记。
+
+许可见 [LICENSE](LICENSE)。

package/goon.ts

@@ -0,0 +1,83 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  CONTINUE_COMMAND_DESCRIPTION,
+  INVISIBLE_CONTINUE_CUSTOM_TYPE,
+  getLastAssistantMessageText,
+  isInvisibleContinueMarker,
+  readShortcut,
+  stripTrailingIncompleteAssistants,
+} from "./src/index.ts";
+
+/**
+ * Resume through AgentSession instead of calling Agent.prompt([]) directly.
+ * The hidden custom message starts or queues a canonical session turn, while
+ * the context hook removes it before provider serialization.
+ */
+export default function invisibleContinueExtension(pi: ExtensionAPI) {
+  const shortcut = readShortcut();
+  if (shortcut !== null) {
+    pi.registerShortcut(shortcut, {
+      description: CONTINUE_COMMAND_DESCRIPTION,
+      handler: (ctx) => runContinueCommand(pi, ctx, ""),
+    });
+  }
+  pi.on("context", (event) => {
+    const hasMarker = event.messages.some((message) => isInvisibleContinueMarker(message));
+    const messages = event.messages.filter((message) => !isInvisibleContinueMarker(message));
+    const next = hasMarker ? stripTrailingIncompleteAssistants(messages) : messages;
+    if (next.length !== event.messages.length) return { messages: next };
+  });
+
+  pi.registerCommand("goon", {
+    description: CONTINUE_COMMAND_DESCRIPTION,
+    handler: async (args, ctx) => {
+      runContinueCommand(pi, ctx, args);
+    },
+  });
+}
+
+function runContinueCommand(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  args: string,
+): void {
+  const subcommand = args.trim().toLowerCase();
+
+  if (subcommand === "status") {
+    const last = getLastAssistantMessageText(ctx.sessionManager.getEntries());
+    ctx.ui.notify(
+      [
+        "pi-goon status:",
+        `  Agent idle: ${ctx.isIdle() ? "yes" : "no"}`,
+        `  Last assistant: ${last ?? "(none)"}`.slice(0, 120),
+      ].join("\n"),
+      "info",
+    );
+    return;
+  }
+
+  if (subcommand === "help") {
+    ctx.ui.notify(
+      [
+        "pi-goon  /goon     Resume loop invisibly",
+        "                        /goon status  Show diagnostics",
+        "                        /goon help    This message",
+      ].join("\n"),
+      "info",
+    );
+    return;
+  }
+
+  pi.sendMessage(
+    {
+      customType: INVISIBLE_CONTINUE_CUSTOM_TYPE,
+      content: [],
+      display: false,
+      details: undefined,
+    },
+    {
+      triggerTurn: true,
+      deliverAs: "followUp",
+    },
+  );
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@vimsucks/pi-goon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Resume a Pi session invisibly with /goon, without a new prompt for the model",
+  "type": "module",
+  "author": "vimsucks",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vimsucks/pi-goon.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "continue",
+    "resume"
+  ],
+  "files": [
+    "goon.ts",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./goon.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test.mjs"
+  }
 }

package/src/index.ts

@@ -0,0 +1,134 @@
+/** Shared constants and utilities for pi-goon. */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function readShortcut(): Parameters<ExtensionAPI["registerShortcut"]>[0] | null {
+  const agentDir = process.env.PI_CODING_AGENT_DIR?.replace(/^~(?=$|[\\/])/, homedir())
+    || join(homedir(), ".pi", "agent");
+  const path = join(agentDir, "settings.json");
+  let config: unknown;
+  try {
+    config = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "alt+g";
+    throw new Error(`Cannot read ${path}`, { cause: error });
+  }
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`${path} must contain a JSON object`);
+  }
+  const goon = (config as { goon?: unknown }).goon;
+  if (goon === undefined) return "alt+g";
+  if (!goon || typeof goon !== "object" || Array.isArray(goon)) {
+    throw new Error(`${path}: goon must be a JSON object`);
+  }
+  const shortcut = (goon as { shortcut?: unknown }).shortcut;
+  if (shortcut === undefined) return "alt+g";
+  if (shortcut === null) return null;
+  if (typeof shortcut === "string") {
+    const match = /^((?:(?:ctrl|shift|alt|super)\+)*)(.+)$/.exec(shortcut);
+    if (match) {
+      const modifiers = match[1].split("+").filter(Boolean);
+      const key = match[2];
+      const validKey = /^[a-z0-9]$/.test(key)
+        || (key.length === 1 && "`-=[]\\;',./!@#$%^&*()_+|~{}:<>?".includes(key))
+        || /^(escape|esc|enter|return|tab|space|backspace|delete|insert|clear|home|end|pageUp|pageDown|up|down|left|right|f[1-9]|f1[0-2])$/.test(key);
+      if (validKey && new Set(modifiers).size === modifiers.length) {
+        return shortcut as Parameters<ExtensionAPI["registerShortcut"]>[0];
+      }
+    }
+  }
+  throw new Error(`${path}: goon.shortcut must be a Pi key identifier (e.g. alt+g) or null`);
+}
+
+export const CONTINUE_COMMAND_DESCRIPTION =
+  "Resume the agentic loop without sending a prompt the LLM can read";
+
+export const INVISIBLE_CONTINUE_CUSTOM_TYPE = "pi-goon:resume";
+
+export function isInvisibleContinueMarker(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const candidate = message as { role?: unknown; customType?: unknown };
+  return (
+    candidate.role === "custom" &&
+    candidate.customType === INVISIBLE_CONTINUE_CUSTOM_TYPE
+  );
+}
+
+const INCOMPLETE_ASSISTANT_STOP_REASONS = new Set(["error", "aborted"]);
+
+export function isIncompleteAssistantMessage(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const candidate = message as { role?: unknown; stopReason?: unknown };
+  return (
+    candidate.role === "assistant" &&
+    typeof candidate.stopReason === "string" &&
+    INCOMPLETE_ASSISTANT_STOP_REASONS.has(candidate.stopReason)
+  );
+}
+
+export function hasToolCallBlocks(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const content = (message as { content?: unknown }).content;
+  return (
+    Array.isArray(content) &&
+    content.some(
+      (block) =>
+        !!block &&
+        typeof block === "object" &&
+        (block as { type?: unknown }).type === "toolCall",
+    )
+  );
+}
+
+/**
+ * Pop trailing incomplete assistant attempts (retry-exhausted errors, aborts)
+ * so a continuation does not re-serve the failed run to the LLM.
+ *
+ * Guards: stops at the first message that is not an incomplete assistant,
+ * never pops an assistant carrying toolCall blocks (their tool results must
+ * stay paired), and never empties the context entirely.
+ */
+export function stripTrailingIncompleteAssistants<T>(
+  messages: ReadonlyArray<T>,
+): T[] {
+  const stripped = [...messages];
+  while (
+    stripped.length > 1 &&
+    isIncompleteAssistantMessage(stripped[stripped.length - 1]) &&
+    !hasToolCallBlocks(stripped[stripped.length - 1])
+  ) {
+    stripped.pop();
+  }
+  return stripped;
+}
+
+export function getLastAssistantMessageText(
+  entries: ReadonlyArray<{ type: string; message?: { role?: string; content?: unknown } }>,
+): string | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (
+      entry.type === "message" &&
+      entry.message?.role === "assistant" &&
+      entry.message.content
+    ) {
+      const content = entry.message.content;
+      if (typeof content === "string") return content;
+      if (Array.isArray(content)) {
+        const textBlocks = content.filter(
+          (block: unknown): block is { type: "text"; text: string } => {
+            if (!block || typeof block !== "object") return false;
+            const candidate = block as { type?: unknown; text?: unknown };
+            return candidate.type === "text" && typeof candidate.text === "string";
+          },
+        );
+        if (textBlocks.length === 0) return undefined;
+        return textBlocks.map((block) => block.text).join("\n");
+      }
+    }
+  }
+  return undefined;
+}