agent-sh 0.1.0

package/dist/context-manager.js

@@ -0,0 +1,405 @@
+const DEFAULT_WINDOW_SIZE = 20;
+const DEFAULT_BUDGET = 16384; // ~4K tokens at ~4 chars/token
+// Truncation thresholds (in lines)
+const SHELL_TRUNCATE_THRESHOLD = 30;
+const SHELL_HEAD_LINES = 10;
+const SHELL_TAIL_LINES = 10;
+const AGENT_RESPONSE_TRUNCATE_THRESHOLD = 20;
+const AGENT_RESPONSE_HEAD_LINES = 15;
+const TOOL_TRUNCATE_THRESHOLD = 20;
+const TOOL_HEAD_LINES = 5;
+const TOOL_TAIL_LINES = 5;
+const RECALL_EXPAND_MAX_LINES = 500;
+export class ContextManager {
+    exchanges = [];
+    nextId = 1;
+    currentCwd;
+    sessionStart;
+    pendingToolCalls = [];
+    constructor(bus) {
+        this.currentCwd = process.cwd();
+        this.sessionStart = Date.now();
+        // ── Subscribe to shell events ──
+        bus.on("shell:command-done", (e) => {
+            const lines = e.output.split("\n");
+            this.addExchange({
+                type: "shell_command",
+                command: e.command,
+                output: e.output,
+                cwd: e.cwd,
+                exitCode: e.exitCode,
+                outputLines: lines.length,
+                outputBytes: e.output.length,
+            });
+        });
+        bus.on("shell:cwd-change", (e) => {
+            this.currentCwd = e.cwd;
+        });
+        // ── Subscribe to agent events ──
+        bus.on("agent:query", (e) => {
+            this.pendingToolCalls = [];
+            this.addExchange({ type: "agent_query", query: e.query });
+        });
+        bus.on("agent:response-done", (e) => {
+            this.addExchange({
+                type: "agent_response",
+                response: e.response,
+                toolCalls: this.pendingToolCalls,
+            });
+            this.pendingToolCalls = [];
+        });
+        bus.on("agent:tool-call", (e) => {
+            // Accumulate tool calls for the agent_response summary
+            this.pendingToolCalls.push({
+                tool: e.tool,
+                args: e.args,
+                output: "",
+                exitCode: null,
+            });
+        });
+        bus.on("agent:tool-output", (e) => {
+            // Update the last pending tool call with output
+            const last = this.pendingToolCalls[this.pendingToolCalls.length - 1];
+            if (last) {
+                last.output = e.output;
+                last.exitCode = e.exitCode;
+            }
+            // Also store as a separate exchange for chronological log
+            const lines = e.output.split("\n");
+            this.addExchange({
+                type: "tool_execution",
+                tool: e.tool,
+                args: {},
+                output: e.output,
+                exitCode: e.exitCode,
+                outputLines: lines.length,
+                outputBytes: e.output.length,
+            });
+        });
+    }
+    // ── Public query API ──────────────────────────────────────────
+    getCwd() {
+        return this.currentCwd;
+    }
+    /**
+     * Build the <shell_context> block for the agent prompt.
+     * Pipeline: window → truncate → format
+     */
+    getContext(budget = DEFAULT_BUDGET) {
+        let exchanges = this.applyWindow(this.exchanges);
+        exchanges = this.applyTruncation(exchanges, budget);
+        return this.formatContext(exchanges);
+    }
+    /**
+     * Regex/keyword search across all exchanges. Returns formatted results.
+     */
+    search(query) {
+        if (!query.trim())
+            return "No query provided.";
+        let regex;
+        try {
+            regex = new RegExp(query, "i");
+        }
+        catch {
+            // Fallback: treat as literal keywords with OR logic
+            const words = query.split(/\s+/).filter((w) => w.length > 0);
+            const pattern = words.map((w) => escapeRegex(w)).join("|");
+            regex = new RegExp(pattern, "i");
+        }
+        const matches = [];
+        for (const ex of this.exchanges) {
+            const text = this.exchangeSearchText(ex);
+            const lines = text.split("\n");
+            const matchingLineIndices = [];
+            for (let i = 0; i < lines.length; i++) {
+                if (regex.test(lines[i])) {
+                    matchingLineIndices.push(i);
+                }
+            }
+            if (matchingLineIndices.length > 0) {
+                // Extract excerpts with 2 lines of context around each match
+                const excerpts = [];
+                for (const idx of matchingLineIndices.slice(0, 5)) {
+                    const start = Math.max(0, idx - 2);
+                    const end = Math.min(lines.length, idx + 3);
+                    excerpts.push(lines.slice(start, end).join("\n"));
+                }
+                matches.push({ exchange: ex, excerpts });
+            }
+        }
+        if (matches.length === 0) {
+            return `No results found for "${query}".`;
+        }
+        const parts = [`Search results for "${query}" (${matches.length} exchanges):\n`];
+        for (const m of matches.slice(0, 20)) {
+            parts.push(`#${m.exchange.id} [${m.exchange.type}]`);
+            for (const excerpt of m.excerpts) {
+                parts.push(indent(excerpt, "  "));
+            }
+            parts.push("");
+        }
+        return parts.join("\n");
+    }
+    /**
+     * Return full untruncated content for specific exchange IDs.
+     */
+    expand(ids) {
+        const results = [];
+        for (const id of ids) {
+            const ex = this.exchanges.find((e) => e.id === id);
+            if (!ex) {
+                results.push(`#${id}: not found`);
+                continue;
+            }
+            results.push(this.formatExchangeFull(ex));
+        }
+        return results.join("\n\n");
+    }
+    /**
+     * One-line summaries of last N exchanges.
+     */
+    getRecentSummary(n = 25) {
+        const recent = this.exchanges.slice(-n);
+        if (recent.length === 0)
+            return "No exchanges yet.";
+        return recent.map((ex) => this.exchangeOneLiner(ex)).join("\n");
+    }
+    /**
+     * Parse and handle __shell_recall commands.
+     */
+    handleRecallCommand(command) {
+        const args = command.replace(/^__shell_recall\s*/, "").trim();
+        if (!args || args === "--help") {
+            return [
+                "Usage:",
+                "  __shell_recall                    Browse recent exchanges",
+                "  __shell_recall --search <query>   Search all exchanges",
+                "  __shell_recall --expand <id,...>   Show full content of exchanges",
+                "",
+                "Examples:",
+                '  __shell_recall --search "test fail"',
+                "  __shell_recall --expand 41",
+                "  __shell_recall --expand 41,42,43",
+            ].join("\n");
+        }
+        const searchMatch = args.match(/^--search\s+(?:"([^"]+)"|(\S+))/);
+        if (searchMatch) {
+            return this.search(searchMatch[1] ?? searchMatch[2] ?? "");
+        }
+        const expandMatch = args.match(/^--expand\s+([\d,\s]+)/);
+        if (expandMatch) {
+            const ids = expandMatch[1]
+                .split(/[,\s]+/)
+                .map(Number)
+                .filter((n) => !isNaN(n));
+            if (ids.length === 0)
+                return "No valid IDs provided.";
+            return this.expand(ids);
+        }
+        // Default: browse
+        return this.getRecentSummary();
+    }
+    /**
+     * Clear exchange history (used by /clear command).
+     */
+    clear() {
+        this.exchanges = [];
+        this.pendingToolCalls = [];
+        // Don't reset nextId — IDs should be globally unique within a session
+    }
+    // ── Pipeline stages ───────────────────────────────────────────
+    applyWindow(exchanges, windowSize = DEFAULT_WINDOW_SIZE) {
+        return exchanges.slice(-windowSize);
+    }
+    applyTruncation(exchanges, budget) {
+        // Deep clone so we don't mutate the source
+        const result = exchanges.map((e) => ({ ...e }));
+        // Pass 1: per-type truncation
+        for (const ex of result) {
+            if (ex.type === "shell_command") {
+                ex.output = truncateOutput(ex.output, SHELL_TRUNCATE_THRESHOLD, SHELL_HEAD_LINES, SHELL_TAIL_LINES, ex.id);
+            }
+            else if (ex.type === "agent_response") {
+                ex.response = truncateHead(ex.response, AGENT_RESPONSE_TRUNCATE_THRESHOLD, AGENT_RESPONSE_HEAD_LINES, ex.id);
+            }
+            else if (ex.type === "tool_execution") {
+                ex.output = truncateOutput(ex.output, TOOL_TRUNCATE_THRESHOLD, TOOL_HEAD_LINES, TOOL_TAIL_LINES, ex.id);
+            }
+        }
+        // Pass 2: budget enforcement — strip output from oldest if over budget
+        let totalSize = result.reduce((sum, ex) => sum + this.exchangeSize(ex), 0);
+        for (let i = 0; i < result.length - 1 && totalSize > budget; i++) {
+            const ex = result[i];
+            const before = this.exchangeSize(ex);
+            if (ex.type === "shell_command") {
+                ex.output = `[output omitted, use __shell_recall --expand ${ex.id}]`;
+            }
+            else if (ex.type === "tool_execution") {
+                ex.output = `[output omitted, use __shell_recall --expand ${ex.id}]`;
+            }
+            else if (ex.type === "agent_response") {
+                ex.response = `[response omitted, use __shell_recall --expand ${ex.id}]`;
+            }
+            totalSize -= before - this.exchangeSize(ex);
+        }
+        return result;
+    }
+    formatContext(exchanges) {
+        const elapsed = Math.round((Date.now() - this.sessionStart) / 60000);
+        const totalCount = this.exchanges.length;
+        let out = "<shell_context>\n";
+        out += `cwd: ${this.currentCwd}\n`;
+        out += `session: ${totalCount} exchanges, ${elapsed}m elapsed\n`;
+        out += `[hint: run \`__shell_recall --search "query"\` or \`__shell_recall --expand ID\` to retrieve truncated content]\n`;
+        for (const ex of exchanges) {
+            out += "\n" + this.formatExchangeTruncated(ex);
+        }
+        out += "\n</shell_context>\n";
+        return out;
+    }
+    // ── Internal helpers ──────────────────────────────────────────
+    addExchange(partial) {
+        const exchange = {
+            ...partial,
+            id: this.nextId++,
+            timestamp: Date.now(),
+        };
+        this.exchanges.push(exchange);
+    }
+    formatExchangeTruncated(ex) {
+        switch (ex.type) {
+            case "shell_command": {
+                let s = `#${ex.id} [shell] $ ${ex.command}\n`;
+                if (ex.output)
+                    s += indent(ex.output, "  ") + "\n";
+                if (ex.exitCode !== null)
+                    s += `  exit ${ex.exitCode}\n`;
+                return s;
+            }
+            case "agent_query":
+                return `#${ex.id} [you] > ${ex.query}\n`;
+            case "agent_response": {
+                let s = `#${ex.id} [agent] `;
+                if (ex.response)
+                    s += ex.response.split("\n")[0] + "\n";
+                if (ex.response.includes("\n")) {
+                    const rest = ex.response.slice(ex.response.indexOf("\n") + 1);
+                    if (rest.trim())
+                        s += indent(rest, "  ") + "\n";
+                }
+                return s;
+            }
+            case "tool_execution": {
+                let s = `#${ex.id} [tool] ${ex.tool}\n`;
+                if (ex.output)
+                    s += indent(ex.output, "  ") + "\n";
+                if (ex.exitCode !== null)
+                    s += `  exit ${ex.exitCode}\n`;
+                return s;
+            }
+        }
+    }
+    truncateForRecall(text) {
+        const lines = text.split("\n");
+        if (lines.length <= RECALL_EXPAND_MAX_LINES)
+            return text;
+        const half = RECALL_EXPAND_MAX_LINES / 2;
+        return (lines.slice(0, half).join("\n") +
+            `\n[... ${lines.length - RECALL_EXPAND_MAX_LINES} more lines ...]\n` +
+            lines.slice(-half).join("\n"));
+    }
+    formatExchangeFull(ex) {
+        switch (ex.type) {
+            case "shell_command": {
+                const output = this.truncateForRecall(ex.output);
+                let s = `#${ex.id} [shell] $ ${ex.command} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
+                if (output)
+                    s += output + "\n";
+                if (ex.exitCode !== null)
+                    s += `exit ${ex.exitCode}\n`;
+                return s;
+            }
+            case "agent_query":
+                return `#${ex.id} [you] > ${ex.query}`;
+            case "agent_response":
+                return `#${ex.id} [agent]\n${ex.response}`;
+            case "tool_execution": {
+                const output = this.truncateForRecall(ex.output);
+                let s = `#${ex.id} [tool] ${ex.tool} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
+                if (output)
+                    s += output + "\n";
+                if (ex.exitCode !== null)
+                    s += `exit ${ex.exitCode}\n`;
+                return s;
+            }
+        }
+    }
+    exchangeOneLiner(ex) {
+        switch (ex.type) {
+            case "shell_command":
+                return `#${ex.id} shell: ${ex.command} (${ex.outputLines} lines, exit ${ex.exitCode ?? "?"})`;
+            case "agent_query":
+                return `#${ex.id} query: ${ex.query}`;
+            case "agent_response": {
+                const preview = ex.response.split("\n")[0]?.slice(0, 80) ?? "";
+                return `#${ex.id} agent: ${preview}${ex.response.length > 80 ? "..." : ""}`;
+            }
+            case "tool_execution":
+                return `#${ex.id} tool: ${ex.tool} (${ex.outputLines} lines, exit ${ex.exitCode ?? "?"})`;
+        }
+    }
+    exchangeSearchText(ex) {
+        switch (ex.type) {
+            case "shell_command":
+                return `${ex.command}\n${ex.output}`;
+            case "agent_query":
+                return ex.query;
+            case "agent_response":
+                return ex.response;
+            case "tool_execution":
+                return `${ex.tool}\n${ex.output}`;
+        }
+    }
+    exchangeSize(ex) {
+        switch (ex.type) {
+            case "shell_command":
+                return ex.command.length + ex.output.length;
+            case "agent_query":
+                return ex.query.length;
+            case "agent_response":
+                return ex.response.length;
+            case "tool_execution":
+                return ex.tool.length + ex.output.length;
+        }
+    }
+}
+// ── Utility functions ─────────────────────────────────────────
+function truncateOutput(text, threshold, headLines, tailLines, id) {
+    const lines = text.split("\n");
+    if (lines.length <= threshold)
+        return text;
+    const omitted = lines.length - headLines - tailLines;
+    return [
+        ...lines.slice(0, headLines),
+        `[... ${omitted} lines truncated, use __shell_recall --expand ${id} to see full output ...]`,
+        ...lines.slice(-tailLines),
+    ].join("\n");
+}
+function truncateHead(text, threshold, headLines, id) {
+    const lines = text.split("\n");
+    if (lines.length <= threshold)
+        return text;
+    return [
+        ...lines.slice(0, headLines),
+        `[... truncated, use __shell_recall --expand ${id} for full response ...]`,
+    ].join("\n");
+}
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((line) => prefix + line)
+        .join("\n");
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/core.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Core kernel — the minimum viable agent-sh.
+ *
+ * Wires up EventBus + ContextManager + AcpClient without any frontend.
+ * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
+ * subscribing to bus events and calling client methods.
+ *
+ * The core listens for `agent:submit` and `agent:cancel-request` events
+ * from any frontend, routing them to the AcpClient. This means frontends
+ * never need a direct reference to AcpClient — they just emit events.
+ *
+ * Usage:
+ *   import { createCore } from "agent-sh";
+ *   const core = createCore({ agentCommand: "pi-acp" });
+ *   core.bus.on("agent:response-chunk", ({ text }) => ws.send(text));
+ *   await core.start();
+ *   core.bus.emit("agent:submit", { query: "hello" });
+ */
+import { EventBus } from "./event-bus.js";
+import { ContextManager } from "./context-manager.js";
+import { AcpClient } from "./acp-client.js";
+import type { AgentShellConfig, ExtensionContext } from "./types.js";
+export { EventBus } from "./event-bus.js";
+export type { ShellEvents } from "./event-bus.js";
+export type { AgentShellConfig, ExtensionContext } from "./types.js";
+export { palette, setPalette, resetPalette } from "./utils/palette.js";
+export type { ColorPalette } from "./utils/palette.js";
+export interface AgentShellCore {
+    bus: EventBus;
+    contextManager: ContextManager;
+    client: AcpClient;
+    /** Connect to the agent subprocess. Call after wiring up bus listeners. */
+    start(): Promise<void>;
+    /** Build an ExtensionContext for loading extensions against this core. */
+    extensionContext(opts: {
+        quit: () => void;
+    }): ExtensionContext;
+    /** Tear down the agent process and clean up. */
+    kill(): void;
+}
+export declare function createCore(config: AgentShellConfig): AgentShellCore;

package/dist/core.js

@@ -0,0 +1,76 @@
+/**
+ * Core kernel — the minimum viable agent-sh.
+ *
+ * Wires up EventBus + ContextManager + AcpClient without any frontend.
+ * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
+ * subscribing to bus events and calling client methods.
+ *
+ * The core listens for `agent:submit` and `agent:cancel-request` events
+ * from any frontend, routing them to the AcpClient. This means frontends
+ * never need a direct reference to AcpClient — they just emit events.
+ *
+ * Usage:
+ *   import { createCore } from "agent-sh";
+ *   const core = createCore({ agentCommand: "pi-acp" });
+ *   core.bus.on("agent:response-chunk", ({ text }) => ws.send(text));
+ *   await core.start();
+ *   core.bus.emit("agent:submit", { query: "hello" });
+ */
+import { EventBus } from "./event-bus.js";
+import { ContextManager } from "./context-manager.js";
+import { AcpClient } from "./acp-client.js";
+import { setPalette } from "./utils/palette.js";
+// Re-export types that library consumers need
+export { EventBus } from "./event-bus.js";
+export { palette, setPalette, resetPalette } from "./utils/palette.js";
+export function createCore(config) {
+    const bus = new EventBus();
+    const contextManager = new ContextManager(bus);
+    const client = new AcpClient({ bus, contextManager, config });
+    let connected = false;
+    // Route frontend events to the agent — any frontend (Shell, WebSocket,
+    // REST handler, test harness) can emit these without knowing about AcpClient.
+    bus.on("agent:submit", ({ query }) => {
+        (async () => {
+            // Wait briefly for agent connection if start() is still in progress
+            if (!connected) {
+                for (let i = 0; i < 30 && !connected; i++) {
+                    await new Promise((r) => setTimeout(r, 100));
+                }
+            }
+            if (!connected) {
+                bus.emit("ui:error", { message: "Agent not connected. Please wait a moment and try again." });
+                return;
+            }
+            await client.sendPrompt(query);
+        })().catch((err) => {
+            bus.emit("agent:error", {
+                message: err instanceof Error ? err.message : String(err),
+            });
+        });
+    });
+    bus.on("agent:cancel-request", () => {
+        client.cancel().catch(() => { });
+    });
+    return {
+        bus,
+        contextManager,
+        client,
+        async start() {
+            await client.start();
+            connected = true;
+        },
+        extensionContext(opts) {
+            return {
+                bus,
+                contextManager,
+                getAcpClient: () => client,
+                quit: opts.quit,
+                setPalette,
+            };
+        },
+        kill() {
+            client.kill();
+        },
+    };
+}

package/dist/event-bus.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Typed event map — every event has a known payload shape.
+ */
+export interface ShellEvents {
+    "shell:command-start": {
+        command: string;
+        cwd: string;
+    };
+    "shell:command-done": {
+        command: string;
+        output: string;
+        cwd: string;
+        exitCode: number | null;
+    };
+    "shell:cwd-change": {
+        cwd: string;
+    };
+    "shell:foreground-busy": {
+        busy: boolean;
+    };
+    "agent:submit": {
+        query: string;
+    };
+    "agent:cancel-request": Record<string, never>;
+    "agent:query": {
+        query: string;
+    };
+    "agent:thinking-chunk": {
+        text: string;
+    };
+    "agent:response-chunk": {
+        text: string;
+    };
+    "agent:response-done": {
+        response: string;
+    };
+    "agent:processing-start": Record<string, never>;
+    "agent:processing-done": Record<string, never>;
+    "agent:cancelled": Record<string, never>;
+    "agent:error": {
+        message: string;
+    };
+    "agent:tool-call": {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+    "agent:tool-output": {
+        tool: string;
+        output: string;
+        exitCode: number | null;
+    };
+    "agent:tool-started": {
+        title: string;
+        toolCallId?: string;
+    };
+    "agent:tool-completed": {
+        toolCallId?: string;
+        exitCode: number | null;
+    };
+    "agent:tool-output-chunk": {
+        chunk: string;
+    };
+    "permission:request": {
+        kind: string;
+        title: string;
+        metadata: Record<string, unknown>;
+        decision: Record<string, unknown>;
+    };
+    "command:execute": {
+        name: string;
+        args: string;
+    };
+    "ui:info": {
+        message: string;
+    };
+    "ui:error": {
+        message: string;
+    };
+    "input:keypress": {
+        key: string;
+    };
+    "agent:terminal-intercept": {
+        command: string;
+        cwd: string;
+        intercepted: boolean;
+        output: string;
+    };
+    "shell:redraw-prompt": {
+        cwd: string;
+        handled: boolean;
+    };
+    "autocomplete:request": {
+        buffer: string;
+        items: {
+            name: string;
+            description: string;
+        }[];
+    };
+}
+type Listener<T> = (payload: T) => void;
+type PipeListener<T> = (payload: T) => T;
+type AsyncPipeListener<T> = (payload: T) => T | Promise<T>;
+/**
+ * Typed event bus with two modes:
+ * - emit/on/off: fire-and-forget notifications
+ * - emitPipe/onPipe: synchronous transform chain where each listener
+ *   can modify the payload before passing to the next
+ */
+export declare class EventBus {
+    private emitter;
+    private pipeListeners;
+    private asyncPipeListeners;
+    /** Subscribe to a fire-and-forget event. */
+    on<K extends keyof ShellEvents>(event: K, fn: Listener<ShellEvents[K]>): void;
+    /** Unsubscribe from a fire-and-forget event. */
+    off<K extends keyof ShellEvents>(event: K, fn: Listener<ShellEvents[K]>): void;
+    /** Emit a fire-and-forget event. */
+    emit<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): void;
+    /** Register a transform listener for a pipeline event. */
+    onPipe<K extends keyof ShellEvents>(event: K, fn: PipeListener<ShellEvents[K]>): void;
+    /**
+     * Emit a pipeline event — each registered pipe listener receives the
+     * output of the previous one. Returns the final transformed payload.
+     * If no listeners are registered, returns the original payload unchanged.
+     */
+    emitPipe<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): ShellEvents[K];
+    /** Register an async transform listener for a pipeline event. */
+    onPipeAsync<K extends keyof ShellEvents>(event: K, fn: AsyncPipeListener<ShellEvents[K]>): void;
+    /**
+     * Emit an async pipeline event. Two phases:
+     * 1. Notify — fire regular `on` listeners synchronously (e.g., TUI flushes state)
+     * 2. Transform — run async pipe listeners in series, each receiving the
+     *    output of the previous (e.g., extension provides a permission decision)
+     *
+     * Returns the final transformed payload. If no pipe listeners are registered,
+     * returns the original payload unchanged (with safe defaults).
+     */
+    emitPipeAsync<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): Promise<ShellEvents[K]>;
+}
+export {};