@andares/pi-toolkits 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andares Cui
+
+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,51 @@
+# @andares/pi-toolkits
+
+Integrated toolkit extension for [pi](https://github.com/earendil-works/pi-coding-agent) — a single npm package that grows new capabilities over time. Currently provides **ask mode**.
+
+## Features
+
+### ask — read-only Q&A mode
+
+Toggle with `/ask` (press again to exit). While active:
+
+- **`write`/`edit` hard-disabled** — removed from the active tool set; pi's runtime rejects calls to non-active tools, so file modification is genuinely impossible
+- **`bash` kept but sandboxed to read-only commands** — shell-quote tokenization with per-segment validation plus write-intent detection (`curl -o/-O`, `wget -O`, `dd of=`, `tee`, redirects); heuristic, not a security boundary
+- **System prompt banner** appended describing the current mode and its restrictions
+- **Gray `ask` footer status** while active
+
+Exiting restores the exact tool set from before ask mode was entered.
+
+## Install
+
+```bash
+# local development
+pi install .
+# or one-off session
+pi -e ./src/index.ts
+```
+
+## Development
+
+```bash
+pnpm install      # install deps (pnpm is the only supported toolchain)
+pnpm typecheck    # tsc --noEmit
+pnpm test         # vitest (bash sandbox boundary cases)
+```
+
+## Project structure
+
+```text
+src/
+├── index.ts              # entry point: aggregates feature modules
+├── lib/                  # shared infrastructure (tool-set snapshot/restore)
+└── features/             # feature modules — one directory per feature
+    └── ask/              # ask mode: command + state machine, bash sandbox,
+                          #           system prompt banner, tests
+```
+
+Adding a new feature = create `src/features/<name>/` exporting `registerXxx(pi)`
+and call it from `src/index.ts`. Existing modules stay untouched.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@andares/pi-toolkits",
+  "version": "0.1.0",
+  "description": "Integrated toolkit extension for pi — currently provides ask mode (read-only Q&A); more features to come",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andares/pi-toolkits.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "ask-mode",
+    "readonly",
+    "toolkit"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@dreki-gg/pi-command-sandbox": "^0.4.3"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/features/ask/bash-sandbox.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Boundary tests for the ask-mode read-only bash sandbox.
+ */
+import { describe, expect, it } from "vitest";
+import { isReadOnlyCommand } from "./bash-sandbox.js";
+
+describe("isReadOnlyCommand — allowed (read-only)", () => {
+	const allowed = [
+		"echo hi",
+		"echo a && echo b",
+		"ls -la",
+		"cat package.json",
+		"head -20 README.md",
+		"git status",
+		"git log --oneline -5",
+		"git diff --stat",
+		"grep -r foo src",
+		"find . -name '*.ts'",
+		"cd src && ls",
+		"node --version",
+		"npm list --depth=0",
+		"curl -s https://example.com",
+		"curl -o - https://example.com", // stdout, allowed
+		"wget -O - https://example.com", // stdout, allowed
+		"echo 'hello && world'", // quoted operator is data, not control
+	];
+
+	it.each(allowed)("allows: %s", (command) => {
+		expect(isReadOnlyCommand(command)).toBe(true);
+	});
+});
+
+describe("isReadOnlyCommand — blocked (mutating/destructive)", () => {
+	const blocked = [
+		"rm -rf /",
+		"echo a && rm -rf /",
+		"mv a b",
+		"cp a b",
+		"mkdir -p foo",
+		"touch foo",
+		"npm install",
+		"npm run build",
+		"git commit -m x",
+		"git push",
+		"git checkout main",
+		"cat x > out.txt",
+		"echo hi >> log",
+		"echo $(rm -rf /)", // command substitution
+		"ls | rm -rf /", // pipeline with destructive command
+		"curl -o file https://example.com",
+		"curl -O https://example.com/x",
+		"curl --output file https://example.com",
+		"wget -O file https://example.com",
+		"wget --output-document file https://example.com",
+		"wget -qO- https://example.com", // sandbox rejects (only wget -O - is safe); fine, be strict
+		"dd if=/dev/zero of=/tmp/x bs=1 count=1",
+		"echo x | tee file",
+		"vim README.md",
+		"sudo ls",
+		"kill -9 1",
+	];
+
+	it.each(blocked)("blocks: %s", (command) => {
+		expect(isReadOnlyCommand(command)).toBe(false);
+	});
+});

package/src/features/ask/bash-sandbox.ts

@@ -0,0 +1,39 @@
+/**
+ * ask feature — read-only bash sandbox.
+ *
+ * Delegates to @dreki-gg/pi-command-sandbox: proper shell-quote tokenization,
+ * per-segment validation (&& | ; etc.), command-substitution rejection and
+ * deny-by-default for unmodeled operators.
+ *
+ * On top of that, this wrapper adds write-intent detection for known blind
+ * spots: allowlisted commands whose arguments can write files (curl -o/-O,
+ * wget -O, dd of=, tee). Heuristic only — not a security boundary.
+ */
+import { isSafeCommand } from "@dreki-gg/pi-command-sandbox";
+
+const WRITE_INTENT_PATTERNS: RegExp[] = [
+	// curl --output FILE
+	/\bcurl\b[^|;&]*\s--output\b/i,
+	// curl -o FILE (curl -o - / -o- = stdout, allowed)
+	/\bcurl\b[^|;&]*\s-o\s+(?!-)\S+/,
+	// curl -O (uppercase: save to disk under remote name)
+	/\bcurl\b[^|;&]*\s-O\b/,
+	// wget --output-document FILE
+	/\bwget\b[^|;&]*\s--output-document\b/i,
+	// wget -O FILE (wget -O - / -qO- = stdout, allowed)
+	/\bwget\b[^|;&]*\s-O\s+(?!-)\S+/,
+	// dd of=FILE
+	/\bdd\b[^|;&]*\sof=/i,
+	// tee FILE (writes to stdout AND file)
+	/\btee\b/i,
+];
+
+function hasWriteIntent(command: string): boolean {
+	return WRITE_INTENT_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+/** True when `command` is considered read-only by the sandbox. */
+export function isReadOnlyCommand(command: string): boolean {
+	if (hasWriteIntent(command)) return false;
+	return isSafeCommand(command);
+}

package/src/features/ask/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * ask feature — constants (tool names, UI keys, labels).
+ */
+
+/** Tools hard-removed from the active set while ask mode is on. */
+export const ASK_BLOCKED_TOOLS: ReadonlySet<string> = new Set([
+	"write",
+	"edit",
+]);
+
+/** Footer status key (extension-scoped) and label. */
+export const ASK_STATUS_KEY = "ask-mode";
+export const ASK_STATUS_LABEL = "ask";

package/src/features/ask/index.ts

@@ -0,0 +1,112 @@
+/**
+ * ask feature — read-only Q&A mode.
+ *
+ * Design notes (see PLAN.md):
+ *  - Hard guarantee: write/edit are removed from the active tool set via
+ *    pi.setActiveTools(); pi's runtime rejects calls to non-active tools
+ *    ("Tool not found") so nothing executes.
+ *  - bash stays available but is gated by a read-only sandbox
+ *    (see bash-sandbox.ts) via the tool_call hook.
+ *  - Mode banner appended to the system prompt via before_agent_start
+ *    chained systemPrompt (see prompt.ts).
+ */
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	restoreActiveTools,
+	snapshotActiveTools,
+	withoutTools,
+} from "../../lib/tools.js";
+import {
+	ASK_BLOCKED_TOOLS,
+	ASK_STATUS_KEY,
+	ASK_STATUS_LABEL,
+} from "./constants.js";
+import { isReadOnlyCommand } from "./bash-sandbox.js";
+import { appendAskBanner } from "./prompt.js";
+
+export function registerAsk(pi: ExtensionAPI): void {
+	let enabled = false;
+	/** Active tools before ask mode was entered (for exact restore on exit). */
+	let snapshot: string[] = [];
+
+	/** Gray footer status while ask mode is active; cleared on exit. */
+	function updateStatus(ctx: ExtensionContext): void {
+		ctx.ui.setStatus(
+			ASK_STATUS_KEY,
+			enabled ? ctx.ui.theme.fg("muted", ASK_STATUS_LABEL) : undefined,
+		);
+	}
+
+	function enter(ctx: ExtensionContext): void {
+		if (enabled) return;
+		enabled = true;
+		snapshot = snapshotActiveTools(pi);
+		pi.setActiveTools(withoutTools(snapshot, ASK_BLOCKED_TOOLS));
+		updateStatus(ctx);
+		ctx.ui.notify(
+			"Ask mode ON — read-only (write/edit disabled). /ask to exit.",
+			"info",
+		);
+	}
+
+	function exit(ctx: ExtensionContext): void {
+		if (!enabled) return;
+		enabled = false;
+		restoreActiveTools(pi, snapshot);
+		snapshot = [];
+		updateStatus(ctx);
+		ctx.ui.notify("Ask mode OFF — full tool access restored.", "info");
+	}
+
+	function toggle(ctx: ExtensionContext): void {
+		if (enabled) {
+			exit(ctx);
+		} else {
+			enter(ctx);
+		}
+	}
+
+	pi.registerCommand("ask", {
+		description: "Toggle ask mode (read-only Q&A)",
+		handler: async (_args, ctx) => {
+			toggle(ctx);
+		},
+	});
+
+	// Defense-in-depth gate while ask mode is active:
+	//  - write/edit are already removed from the active set (runtime rejects
+	//    them), this blocks them again in case anything re-enables them.
+	//  - bash is kept available but only read-only commands pass the sandbox.
+	pi.on("tool_call", (event) => {
+		if (!enabled) return;
+
+		if (event.toolName === "write" || event.toolName === "edit") {
+			return {
+				block: true,
+				reason:
+					"Ask mode: write/edit are disabled. Use /ask to exit ask mode first.",
+			};
+		}
+
+		if (event.toolName === "bash") {
+			const command = event.input.command as string;
+			if (!isReadOnlyCommand(command)) {
+				return {
+					block: true,
+					reason: `Ask mode: only read-only bash commands are allowed.\nCommand: ${command}\nUse /ask to exit ask mode first.`,
+				};
+			}
+		}
+	});
+
+	// Mode banner: chained append to the current system prompt while enabled.
+	pi.on("before_agent_start", (event) => {
+		if (!enabled) return;
+		// event.systemPrompt is the current (possibly already modified by other
+		// extensions) system prompt — append, don't replace.
+		return { systemPrompt: appendAskBanner(event.systemPrompt) };
+	});
+}

package/src/features/ask/prompt.ts

@@ -0,0 +1,22 @@
+/**
+ * ask feature — system prompt banner.
+ *
+ * Appended to the system prompt (chained append, not replacement) while
+ * ask mode is active so the model knows the current mode and its
+ * restrictions. Do NOT use the removed `systemPromptAppend` field or
+ * wholesale systemPrompt replacement (see PLAN.md).
+ */
+
+export const ASK_BANNER = `[ASK MODE]
+You are in ask mode — a read-only Q&A mode. You may read, search, and analyze the codebase, but you MUST NOT modify anything.
+
+Restrictions:
+- write and edit are disabled (hard-blocked; calls will fail)
+- bash is restricted to read-only commands (ls, cat, grep, git status/log/diff, etc.)
+
+Answer the user's question directly. If a question requires changing files, say so and suggest exiting ask mode with /ask.`;
+
+/** Append the ask-mode banner to an existing system prompt. */
+export function appendAskBanner(systemPrompt: string): string {
+	return `${systemPrompt}\n\n${ASK_BANNER}`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @andares/pi-toolkits — integrated pi extension entry point.
+ *
+ * Registers every feature module. Add new features by creating
+ * src/features/<name>/ with a registerXxx(pi) export and calling it here.
+ *
+ * Current features:
+ *  - ask — read-only Q&A mode (/ask)
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAsk } from "./features/ask/index.js";
+
+export default function piToolkits(pi: ExtensionAPI): void {
+	registerAsk(pi);
+	// registerXxx(pi); // future features
+}

package/src/lib/tools.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared tool-set management helpers (feature-agnostic).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Snapshot the currently active tool names (for later restore). */
+export function snapshotActiveTools(pi: ExtensionAPI): string[] {
+	return [...pi.getActiveTools()];
+}
+
+/** Restore a previously snapshotted tool set. No-op when the snapshot is empty. */
+export function restoreActiveTools(pi: ExtensionAPI, snapshot: string[]): void {
+	if (snapshot.length === 0) return;
+	pi.setActiveTools([...snapshot]);
+}
+
+/** Return `active` minus the tools in `removed` (order preserved). */
+export function withoutTools(
+	active: readonly string[],
+	removed: ReadonlySet<string>,
+): string[] {
+	return active.filter((name) => !removed.has(name));
+}