@stfade/pi-read-delegator 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# pi-read-delegator
+
+Pi extension that removes read tools (`read`, `grep`, `find`, `ls`) from the main model and delegates all read operations to a local **Reader** subagent.
+
+## How It Works
+
+```
+Main Model                    Reader Subagent
+┌──────────┐                  ┌──────────┐
+│ write    │                  │ read     │
+│ edit     │    ──task──>     │ grep     │
+│ bash     │    <──result──   │ find     │
+│ (write)  │                  │ ls       │
+└──────────┘                  └──────────┘
+```
+
+- **Write tools** (`write`, `edit`) remain with the main model.
+- **Read tools** (`read`, `grep`, `find`, `ls`) are blocked on the main model and routed to the Reader subagent.
+- **Bash commands** are filtered: read commands go to Reader, write commands execute directly, ambiguous commands prompt the user.
+
+## Requirements
+
+- [pi-subagents](https://github.com/earendil-works/pi-subagents) installed
+- A local LLM for the Reader subagent (default: `lmstudio/nemotron-mini`)
+
+## Installation
+
+```bash
+pi install pi-read-delegator
+```
+
+Or manually:
+
+```bash
+npm install -g pi-read-delegator
+```
+
+Then edit `~/.pi/agent/agents/reader.md` to set your preferred Reader model.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/read-delegator on` | Enable read delegation |
+| `/read-delegator off` | Disable read delegation |
+| `/read-delegator status` | Show current status |
+
+## Configuration
+
+Edit `~/.pi/agent/read-delegator.json`:
+
+```json
+{
+  "enabled": true,
+  "reader_subagent_name": "reader",
+  "blocked_tools": ["read", "grep", "find", "ls"],
+  "allowed_bash_write_commands": ["mkdir", "echo", "touch", "sed", "rm", "mv", "cp"],
+  "orchestrator_prompt": "You are an orchestrator. For any file reading... use the subagent tool...",
+  "language": "auto"
+}
+```
+
+| Field | Description |
+|---|---|
+| `enabled` | Enable/disable the extension |
+| `reader_subagent_name` | Name of the Reader subagent (must match `reader.md`) |
+| `blocked_tools` | Tools to block from the main model |
+| `language` | `"auto"`, `"tr"`, or `"en"` |
+
+## Reader Subagent
+
+The Reader template is created at `~/.pi/agent/agents/reader.md` on first run. Edit the `model:` line to use your preferred provider:
+
+```yaml
+model: lmstudio/nemotron-mini   # LM Studio
+# model: ollama/phi3             # Ollama
+# model: openai/gpt-4o-mini      # OpenAI
+# model: anthropic/claude-haiku   # Anthropic
+```
+
+## Error Handling
+
+When the Reader fails:
+
+- **[R]etry** — resend the same task to Reader
+- **[A]llow once** — temporarily unblock tools for one operation
+- **[C]ancel** — report the failure
+
+## Bash Filter
+
+| Read commands → Reader | Write commands → Direct |
+|---|---|
+| `cat`, `grep`, `find`, `ls` | `mkdir`, `touch`, `rm`, `mv` |
+| `head`, `tail`, `less`, `wc` | `cp`, `chmod`, `chown` |
+| `bat`, `rg`, `fd`, `awk` | `npm`, `git`, `docker` |
+| `sed` (without `-i`) | `sed -i` (in-place edit) |
+
+## Supported Languages
+
+- **English** (`en`)
+- **Turkish** (`tr`)
+
+Language is auto-detected from Pi's settings or the OS locale.
+
+## License
+
+MIT

package/bash-filter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * bash-filter.ts — Bash command classification and Reader forwarding
+ *
+ * Classifies shell commands as read-only (delegate to Reader subagent),
+ * write (execute directly), or ambiguous (prompt user).
+ */
+/**
+ * Determine if a bash command is read-only and should be forwarded to Reader.
+ *
+ * Rules:
+ * - If the first word is in READ_COMMANDS → true
+ * - sed without -i flag → true (read-only stream edit)
+ * - sed with -i → false (in-place edit = write)
+ */
+export declare function isReadCommand(command: string): boolean;
+/**
+ * Determine if a bash command modifies the filesystem and should run directly.
+ *
+ * Rules:
+ * - If the first word is in WRITE_COMMANDS → true
+ * - sed with -i flag → true (in-place edit)
+ * - Command contains > or >> redirect → true (writes to file)
+ * - Command contains tee without -a flag → true (writes to file)
+ */
+export declare function isWriteCommand(command: string): boolean;
+/**
+ * Wrap a shell command into a Reader subagent task.
+ *
+ * Returns a formatted string instructing the Reader to execute and report
+ * minimal results.
+ */
+export declare function wrapForReader(command: string): string;
+/**
+ * Wrap a generic task (non-bash) into a Reader subagent task.
+ */
+export declare function wrapTaskForReader(task: string): string;
+//# sourceMappingURL=bash-filter.d.ts.map

package/bash-filter.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * bash-filter.ts — Bash command classification and Reader forwarding
+ *
+ * Classifies shell commands as read-only (delegate to Reader subagent),
+ * write (execute directly), or ambiguous (prompt user).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReadCommand = isReadCommand;
+exports.isWriteCommand = isWriteCommand;
+exports.wrapForReader = wrapForReader;
+exports.wrapTaskForReader = wrapTaskForReader;
+// ---------------------------------------------------------------------------
+// Command lists
+// ---------------------------------------------------------------------------
+/**
+ * Commands that ONLY read and should be forwarded to the Reader subagent.
+ * - sed without -i is read-only (stream editor writing to stdout).
+ * - awk is read-only (pattern scanning and processing language).
+ */
+const READ_COMMANDS = new Set([
+    "cat",
+    "grep",
+    "find",
+    "ls",
+    "head",
+    "tail",
+    "less",
+    "wc",
+    "nl",
+    "more",
+    "bat",
+    "rg",
+    "fd",
+    "awk",
+    "du",
+    "df",
+    "stat",
+    "file",
+    "which",
+    "where",
+    "type",
+    "dir",
+]);
+/**
+ * Commands that write to the filesystem and should execute directly.
+ * sed and tee are context-dependent — handled specially in isWriteCommand.
+ */
+const WRITE_COMMANDS = new Set([
+    "mkdir",
+    "touch",
+    "echo",
+    "rm",
+    "mv",
+    "cp",
+    "chmod",
+    "chown",
+    "ln",
+    "rmdir",
+    "npm",
+    "pnpm",
+    "yarn",
+    "pip",
+    "cargo",
+    "go",
+    "npx",
+    "node",
+    "python",
+    "python3",
+    "git",
+    "docker",
+    "kubectl",
+    "tsc",
+    "make",
+    "cmake",
+    "dotnet",
+    "rustc",
+    "gcc",
+    "g++",
+]);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Determine if a bash command is read-only and should be forwarded to Reader.
+ *
+ * Rules:
+ * - If the first word is in READ_COMMANDS → true
+ * - sed without -i flag → true (read-only stream edit)
+ * - sed with -i → false (in-place edit = write)
+ */
+function isReadCommand(command) {
+    const argv = parseArgv(command);
+    if (argv.length === 0)
+        return false;
+    const cmd = argv[0].toLowerCase();
+    // sed is special: if -i is present, it's a write; otherwise read-only
+    if (cmd === "sed" || cmd === "sed.exe") {
+        return !hasInlineFlag(argv);
+    }
+    return READ_COMMANDS.has(cmd);
+}
+/**
+ * Determine if a bash command modifies the filesystem and should run directly.
+ *
+ * Rules:
+ * - If the first word is in WRITE_COMMANDS → true
+ * - sed with -i flag → true (in-place edit)
+ * - Command contains > or >> redirect → true (writes to file)
+ * - Command contains tee without -a flag → true (writes to file)
+ */
+function isWriteCommand(command) {
+    const argv = parseArgv(command);
+    if (argv.length === 0)
+        return false;
+    const cmd = argv[0].toLowerCase();
+    // sed with -i = write
+    if (cmd === "sed" || cmd === "sed.exe") {
+        return hasInlineFlag(argv);
+    }
+    if (WRITE_COMMANDS.has(cmd))
+        return true;
+    // Check for output redirection markers (> or >>)
+    // We do a simple string match outside the parsed argv because parseArgv
+    // might stop at the redirect operator.
+    if (/\b>>?\b/.test(command))
+        return true;
+    // tee is ambiguous: if -a (append) it's write, otherwise also write
+    if (cmd === "tee" || cmd === "tee.exe")
+        return true;
+    return false;
+}
+/**
+ * Wrap a shell command into a Reader subagent task.
+ *
+ * Returns a formatted string instructing the Reader to execute and report
+ * minimal results.
+ */
+function wrapForReader(command) {
+    return [
+        "Execute this shell command and return ONLY the essential result.",
+        "Max 5 lines or a single number. Never dump full file contents.",
+        `Command: ${command}`,
+    ].join("\n");
+}
+/**
+ * Wrap a generic task (non-bash) into a Reader subagent task.
+ */
+function wrapTaskForReader(task) {
+    return [
+        "Execute this task and return ONLY the essential result.",
+        "Max 5 lines or a single number. Never dump full file contents.",
+        `Task: ${task}`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+/**
+ * Parse a command string into argv tokens, respecting single/double quotes.
+ *
+ * This is a simplified parser — edge cases like escaped quotes inside
+ * opposite-quoted strings are handled on a best-effort basis.
+ */
+function parseArgv(command) {
+    const tokens = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (inSingle) {
+            if (ch === "'") {
+                inSingle = false;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (inDouble) {
+            if (ch === '"') {
+                inDouble = false;
+            }
+            else if (ch === "\\" && i + 1 < command.length) {
+                // Simple escape handling inside double quotes
+                const next = command[i + 1];
+                if (next === '"' || next === "\\" || next === "$" || next === "`") {
+                    current += next;
+                    i++;
+                }
+                else {
+                    current += ch;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === "'") {
+                inSingle = true;
+            }
+            else if (ch === '"') {
+                inDouble = true;
+            }
+            else if (ch === " " || ch === "\t") {
+                if (current.length > 0) {
+                    tokens.push(current);
+                    current = "";
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    // Flush remaining token
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+/**
+ * Check whether `sed` has the -i (in-place) flag.
+ */
+function hasInlineFlag(argv) {
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        // -i, -i.bak, --in-place, --in-place=.bak
+        if (arg === "-i" || arg.startsWith("-i.") || arg === "--in-place") {
+            return true;
+        }
+        if (arg.startsWith("--in-place=")) {
+            return true;
+        }
+        // Stop at the expression (s/.../.../ or -e '...') — flags after that
+        // might apply to the expression, not sed itself. In practice, -i always
+        // comes before the expression.
+    }
+    return false;
+}
+//# sourceMappingURL=bash-filter.js.map

package/config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * config.ts — Configuration loader for pi-read-delegator
+ *
+ * Reads/writes ~/.pi/agent/read-delegator.json with sensible defaults.
+ * If the config file doesn't exist, it creates one with defaults.
+ * If the config file is corrupted, it overwrites with defaults and logs a warning.
+ */
+export interface ReadDelegatorConfig {
+    enabled: boolean;
+    reader_subagent_name: string;
+    blocked_tools: string[];
+    allowed_bash_write_commands: string[];
+    orchestrator_prompt: string;
+    language: string;
+}
+/**
+ * Load configuration from disk.
+ * - If the file doesn't exist, create it with defaults and return them.
+ * - If the file is corrupted, overwrite with defaults, log a warning, return defaults.
+ * - Otherwise parse and return the typed config.
+ */
+export declare function loadConfig(): ReadDelegatorConfig;
+/**
+ * Save configuration to disk.
+ * @param config  The config object to persist
+ * @param options.silent  If true, suppress console output
+ */
+export declare function saveConfig(config: ReadDelegatorConfig, options?: {
+    silent?: boolean;
+}): void;
+//# sourceMappingURL=config.d.ts.map

package/config.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * config.ts — Configuration loader for pi-read-delegator
+ *
+ * Reads/writes ~/.pi/agent/read-delegator.json with sensible defaults.
+ * If the config file doesn't exist, it creates one with defaults.
+ * If the config file is corrupted, it overwrites with defaults and logs a warning.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    enabled: true,
+    reader_subagent_name: "reader",
+    blocked_tools: ["read", "grep", "find", "ls"],
+    allowed_bash_write_commands: [
+        "mkdir",
+        "echo",
+        "touch",
+        "sed",
+        "rm",
+        "mv",
+        "cp",
+    ],
+    orchestrator_prompt: "You are an orchestrator. For any file reading, searching, or listing operation, you MUST use the subagent tool with subagent='reader'. Do not use read/grep/find/ls yourself. If you need to run a shell command that only reads (like cat, grep, find, ls), also delegate it to the reader subagent.",
+    language: "auto",
+};
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Expand ~ to the user's home directory. */
+function expandTilde(filePath) {
+    if (filePath.startsWith("~")) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+/** Full path to the config file. */
+function configFilePath() {
+    return expandTilde("~/.pi/agent/read-delegator.json");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Load configuration from disk.
+ * - If the file doesn't exist, create it with defaults and return them.
+ * - If the file is corrupted, overwrite with defaults, log a warning, return defaults.
+ * - Otherwise parse and return the typed config.
+ */
+function loadConfig() {
+    const filePath = configFilePath();
+    try {
+        if (!fs.existsSync(filePath)) {
+            // First run: create the config directory and write defaults
+            ensureDir(path.dirname(filePath));
+            saveConfig(DEFAULT_CONFIG, { silent: true });
+            return { ...DEFAULT_CONFIG };
+        }
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        // Merge with defaults so missing keys get their default values
+        const config = mergeDefaults(parsed, DEFAULT_CONFIG);
+        return config;
+    }
+    catch (err) {
+        // File is missing, unreadable, or invalid JSON → overwrite with defaults
+        console.warn(`[pi-read-delegator] Corrupted config file at ${filePath}. Overwriting with defaults. Error: ${err}`);
+        try {
+            ensureDir(path.dirname(filePath));
+            fs.writeFileSync(filePath, JSON.stringify(DEFAULT_CONFIG, null, 2), "utf-8");
+        }
+        catch {
+            // Silently fail — we tried our best
+        }
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Save configuration to disk.
+ * @param config  The config object to persist
+ * @param options.silent  If true, suppress console output
+ */
+function saveConfig(config, options) {
+    const filePath = configFilePath();
+    ensureDir(path.dirname(filePath));
+    try {
+        fs.writeFileSync(filePath, JSON.stringify(config, null, 2), "utf-8");
+        if (!options?.silent) {
+            console.log(`[pi-read-delegator] Config saved to ${filePath}`);
+        }
+    }
+    catch (err) {
+        console.error(`[pi-read-delegator] Failed to save config: ${err}`);
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Recursively merge a partial user config on top of the defaults. */
+function mergeDefaults(partial, defaults) {
+    if (typeof partial !== "object" || partial === null) {
+        return { ...defaults };
+    }
+    const p = partial;
+    return {
+        enabled: typeof p.enabled === "boolean" ? p.enabled : defaults.enabled,
+        reader_subagent_name: typeof p.reader_subagent_name === "string"
+            ? p.reader_subagent_name
+            : defaults.reader_subagent_name,
+        blocked_tools: Array.isArray(p.blocked_tools)
+            ? p.blocked_tools
+            : defaults.blocked_tools,
+        allowed_bash_write_commands: Array.isArray(p.allowed_bash_write_commands)
+            ? p.allowed_bash_write_commands
+            : defaults.allowed_bash_write_commands,
+        orchestrator_prompt: typeof p.orchestrator_prompt === "string"
+            ? p.orchestrator_prompt
+            : defaults.orchestrator_prompt,
+        language: typeof p.language === "string" ? p.language : defaults.language,
+    };
+}
+/** Recursively ensure a directory exists. */
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=config.js.map

package/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * index.ts — pi-read-delegator extension entry point
+ *
+ * Lifecycle:
+ *   init(agent)  → load config, check deps, ensure template, enable/disable
+ *   enable(agent) → block tools, add system prompt, attach bash filter
+ *   disable(agent) → restore tools, remove prompt, detach bash filter
+ *
+ * Commands:
+ *   /read-delegator on     → enable the delegator
+ *   /read-delegator off    → disable the delegator
+ *   /read-delegator status  → show current status
+ */
+import { type AgentWithSubagent } from "./reader-manager";
+/**
+ * The Pi agent interface as consumed by pi-read-delegator.
+ * Extends the building-block types from sub-modules.
+ */
+export interface PiAgent extends AgentWithSubagent {
+    /** Return current tool definitions. */
+    getTools(): Array<{
+        name: string;
+    }>;
+    /** Remove a tool by name. */
+    removeTool(name: string): void;
+    /** Add/re-add a tool definition. */
+    addTool(definition: {
+        name: string;
+        [key: string]: unknown;
+    }): void;
+    /** Append a persistent system message to the conversation. */
+    addSystemMessage(text: string): void;
+    /** Remove a previously-added system message by its exact text. */
+    removeSystemMessage(text: string): void;
+    /** Register a hook that fires BEFORE a tool with the given name is called. */
+    onBeforeToolCall(toolName: string, callback: (params: unknown) => Promise<unknown> | unknown): void;
+    /** Register a Pi command (like /read-delegator on). */
+    registerCommand(name: string, handler: (args: string[]) => Promise<string> | string): void;
+    /** Execute a raw shell command directly on the system. */
+    executeShellCommand(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Prompt the user for input. */
+    promptUser(message: string): Promise<string>;
+    /** Display a message to the user. */
+    displayMessage(message: string): void;
+    /** Set status bar text. */
+    setStatusBarText(text: string): void;
+}
+/**
+ * Initialize the extension.
+ *
+ * This is the function Pi calls when loading the extension.
+ * It returns a lifecycle object with enable() and disable().
+ */
+export declare function init(agent: PiAgent): {
+    enable: () => void;
+    disable: () => void;
+};
+//# sourceMappingURL=index.d.ts.map