agent-sh 0.3.1 → 0.5.0

package/dist/agent/conversation-state.js

@@ -0,0 +1,59 @@
+/**
+ * Manages the OpenAI chat messages array for the agent loop.
+ * Separate from ContextManager — this is the LLM conversation,
+ * not the shell history.
+ */
+export class ConversationState {
+    messages = [];
+    addUserMessage(text) {
+        this.messages.push({ role: "user", content: text });
+    }
+    addAssistantMessage(content, toolCalls) {
+        if (toolCalls?.length) {
+            this.messages.push({
+                role: "assistant",
+                content: content ?? null,
+                tool_calls: toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: "function",
+                    function: tc.function,
+                })),
+            });
+        }
+        else {
+            this.messages.push({ role: "assistant", content: content ?? "" });
+        }
+    }
+    addToolResult(toolCallId, content) {
+        this.messages.push({
+            role: "tool",
+            tool_call_id: toolCallId,
+            content,
+        });
+    }
+    /** Inject a system-level note into the conversation (e.g. context change). */
+    addSystemNote(text) {
+        this.messages.push({ role: "user", content: text });
+    }
+    getMessages() {
+        return this.messages;
+    }
+    /**
+     * Simple compaction — drop oldest turns, keeping the first user message
+     * (original task context) and the most recent turns.
+     */
+    compact(maxTurns) {
+        if (this.messages.length <= maxTurns * 2)
+            return;
+        const first = this.messages[0];
+        const recent = this.messages.slice(-(maxTurns * 2));
+        this.messages = [
+            first,
+            { role: "user", content: "[Earlier conversation turns omitted for context space]" },
+            ...recent,
+        ];
+    }
+    clear() {
+        this.messages = [];
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Agent backend exports.
+ *
+ * The default backend is AgentLoop (in-process, OpenAI-compatible API).
+ * Extensions can register alternative backends via agent:register-backend.
+ */
+export type { AgentBackend } from "./types.js";
+export type { ToolDefinition, ToolResult, ToolDisplayInfo } from "./types.js";
+export { AgentLoop } from "./agent-loop.js";
+export { ToolRegistry } from "./tool-registry.js";
+export { runSubagent, type SubagentOptions } from "./subagent.js";

package/dist/agent/index.js

@@ -0,0 +1,9 @@
+/**
+ * Agent backend exports.
+ *
+ * The default backend is AgentLoop (in-process, OpenAI-compatible API).
+ * Extensions can register alternative backends via agent:register-backend.
+ */
+export { AgentLoop } from "./agent-loop.js";
+export { ToolRegistry } from "./tool-registry.js";
+export { runSubagent } from "./subagent.js";

package/dist/agent/skills.d.ts

@@ -0,0 +1,25 @@
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+}
+/**
+ * Discover global skills (stable across cwd changes).
+ * Default: ~/.agents/skills/, plus any skillPaths from settings.
+ */
+export declare function discoverGlobalSkills(): Skill[];
+/**
+ * Discover project-level skills from .agents/skills/ in cwd hierarchy.
+ * Scans from cwd up to git root.
+ */
+export declare function discoverProjectSkills(cwd: string): Skill[];
+/**
+ * Discover all skills (global + project).
+ */
+export declare function discoverSkills(cwd: string): Skill[];
+/**
+ * Load the full content of a skill (frontmatter stripped).
+ * Returns XML-wrapped content suitable for injection into conversation.
+ */
+export declare function loadSkillContent(skill: Skill): string | null;

package/dist/agent/skills.js

@@ -0,0 +1,186 @@
+/**
+ * Skill discovery and loading.
+ *
+ * Follows the Agent Skills standard (agentskills.io):
+ *   - Skills are directories containing a SKILL.md with YAML frontmatter
+ *   - Frontmatter must include `name` and `description`
+ *   - Full content is loaded on-demand (only names/descriptions in system prompt)
+ *
+ * Discovery locations:
+ *   Global:  ~/.agent-sh/skills/ (default), plus skillPaths from settings
+ *   Project: .agents/skills/ in cwd and ancestor dirs (up to git root)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { getSettings } from "../settings.js";
+/** Parse YAML frontmatter from a SKILL.md file. */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+    if (!match)
+        return null;
+    const meta = {};
+    for (const line of match[1].split("\n")) {
+        const colon = line.indexOf(":");
+        if (colon > 0) {
+            const key = line.slice(0, colon).trim();
+            const value = line.slice(colon + 1).trim();
+            meta[key] = value;
+        }
+    }
+    return { meta, body: match[2] };
+}
+/** Load a single skill from a SKILL.md file. */
+function loadSkillFromFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        if (!parsed)
+            return null;
+        const name = parsed.meta.name;
+        const description = parsed.meta.description;
+        if (!name || !description)
+            return null;
+        if (parsed.meta["disable-model-invocation"] === "true")
+            return null;
+        return {
+            name,
+            description,
+            filePath,
+            baseDir: path.dirname(filePath),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Recursively scan a directory for SKILL.md files. */
+function scanDir(dir) {
+    const skills = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return skills;
+    }
+    // If this directory has a SKILL.md, it's a skill root — don't recurse further
+    const skillMd = path.join(dir, "SKILL.md");
+    try {
+        fs.accessSync(skillMd);
+        const skill = loadSkillFromFile(skillMd);
+        if (skill)
+            skills.push(skill);
+        return skills;
+    }
+    catch {
+        // No SKILL.md here — check subdirectories
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        const isDir = entry.isDirectory() ||
+            (entry.isSymbolicLink() && (() => { try {
+                return fs.statSync(fullPath).isDirectory();
+            }
+            catch {
+                return false;
+            } })());
+        if (isDir) {
+            skills.push(...scanDir(fullPath));
+        }
+    }
+    return skills;
+}
+/** Find the git root from a directory. */
+function findGitRoot(dir) {
+    let current = path.resolve(dir);
+    while (true) {
+        try {
+            fs.accessSync(path.join(current, ".git"));
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return null;
+            current = parent;
+        }
+    }
+}
+/** Expand ~ to home directory. */
+function expandHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+function addUnique(target, source, seen) {
+    for (const skill of source) {
+        if (!seen.has(skill.name)) {
+            seen.add(skill.name);
+            target.push(skill);
+        }
+    }
+}
+/**
+ * Discover global skills (stable across cwd changes).
+ * Default: ~/.agents/skills/, plus any skillPaths from settings.
+ */
+export function discoverGlobalSkills() {
+    const seen = new Set();
+    const skills = [];
+    addUnique(skills, scanDir(path.join(os.homedir(), ".agent-sh", "skills")), seen);
+    const settings = getSettings();
+    for (const p of settings.skillPaths ?? []) {
+        addUnique(skills, scanDir(path.resolve(expandHome(p))), seen);
+    }
+    return skills;
+}
+/**
+ * Discover project-level skills from .agents/skills/ in cwd hierarchy.
+ * Scans from cwd up to git root.
+ */
+export function discoverProjectSkills(cwd) {
+    const seen = new Set();
+    const skills = [];
+    const gitRoot = findGitRoot(cwd);
+    let current = path.resolve(cwd);
+    while (true) {
+        addUnique(skills, scanDir(path.join(current, ".agents", "skills")), seen);
+        if (gitRoot && current === gitRoot)
+            break;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return skills;
+}
+/**
+ * Discover all skills (global + project).
+ */
+export function discoverSkills(cwd) {
+    const seen = new Set();
+    const skills = [];
+    addUnique(skills, discoverGlobalSkills(), seen);
+    addUnique(skills, discoverProjectSkills(cwd), seen);
+    return skills;
+}
+/**
+ * Load the full content of a skill (frontmatter stripped).
+ * Returns XML-wrapped content suitable for injection into conversation.
+ */
+export function loadSkillContent(skill) {
+    try {
+        const content = fs.readFileSync(skill.filePath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        if (!parsed)
+            return content;
+        return `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${parsed.body.trim()}\n</skill>`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/subagent.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subagent runner — executes a focused agent loop with its own context.
+ *
+ * Unlike the main AgentLoop, a subagent:
+ *   - Has its own conversation (starts fresh, stays focused)
+ *   - Has its own system prompt (specialized for the task)
+ *   - Runs to completion and returns the final text
+ *   - Optionally emits tool events to the bus for TUI rendering
+ *
+ * Used by the subagent extension to delegate tasks from the main agent.
+ */
+import type { EventBus } from "../event-bus.js";
+import type { LlmClient } from "../utils/llm-client.js";
+import type { ToolDefinition } from "./types.js";
+export interface SubagentOptions {
+    /** LLM client to use. */
+    llmClient: LlmClient;
+    /** Tools available to the subagent. */
+    tools: ToolDefinition[];
+    /** System prompt for this subagent. */
+    systemPrompt: string;
+    /** The task to perform. */
+    task: string;
+    /** Model override (optional, defaults to llmClient's model). */
+    model?: string;
+    /** Event bus for TUI events (optional — silent if omitted). */
+    bus?: EventBus;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Max tool loop iterations (default 20). */
+    maxIterations?: number;
+}
+/**
+ * Run a subagent to completion.
+ * Returns the final response text.
+ */
+export declare function runSubagent(opts: SubagentOptions): Promise<string>;

package/dist/agent/subagent.js

@@ -0,0 +1,117 @@
+import { ConversationState } from "./conversation-state.js";
+/**
+ * Run a subagent to completion.
+ * Returns the final response text.
+ */
+export async function runSubagent(opts) {
+    const { llmClient, tools, systemPrompt, task, model, bus, signal, maxIterations = 20, } = opts;
+    const toolMap = new Map(tools.map(t => [t.name, t]));
+    const apiTools = tools.map(t => ({
+        type: "function",
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.input_schema,
+        },
+    }));
+    const conversation = new ConversationState();
+    conversation.addUserMessage(task);
+    let fullResponseText = "";
+    let iterations = 0;
+    while (iterations++ < maxIterations) {
+        if (signal?.aborted)
+            break;
+        // Stream LLM response
+        const { text, toolCalls, assistantContent, assistantToolCalls } = await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal);
+        fullResponseText += text;
+        conversation.addAssistantMessage(assistantContent, assistantToolCalls);
+        // No tool calls → done
+        if (toolCalls.length === 0)
+            break;
+        // Execute tools
+        for (const tc of toolCalls) {
+            if (signal?.aborted)
+                break;
+            const tool = toolMap.get(tc.name);
+            if (!tool) {
+                conversation.addToolResult(tc.id, `Error: Unknown tool "${tc.name}"`);
+                continue;
+            }
+            let args;
+            try {
+                args = JSON.parse(tc.argumentsJson);
+            }
+            catch {
+                conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`);
+                continue;
+            }
+            // Emit tool events for TUI (if bus provided)
+            if (bus) {
+                const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
+                bus.emit("agent:tool-started", {
+                    title: tc.name,
+                    toolCallId: tc.id,
+                    kind: display.kind,
+                    locations: display.locations,
+                    rawInput: args,
+                });
+            }
+            const onChunk = bus && tool.showOutput !== false
+                ? (chunk) => { bus.emit("agent:tool-output-chunk", { chunk }); }
+                : undefined;
+            const result = await tool.execute(args, onChunk);
+            if (bus) {
+                const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
+                bus.emit("agent:tool-completed", {
+                    toolCallId: tc.id,
+                    exitCode: result.exitCode,
+                    rawOutput: result.content,
+                    kind: display.kind,
+                });
+            }
+            const content = result.isError ? `Error: ${result.content}` : result.content;
+            conversation.addToolResult(tc.id, content);
+        }
+    }
+    return fullResponseText;
+}
+/** Stream a single LLM response. */
+async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal) {
+    let text = "";
+    const pendingToolCalls = [];
+    const stream = await llmClient.stream({
+        messages: [
+            { role: "system", content: systemPrompt },
+            ...conversation.getMessages(),
+        ],
+        tools: apiTools.length > 0 ? apiTools : undefined,
+        model,
+        signal,
+    });
+    for await (const chunk of stream) {
+        if (signal?.aborted)
+            break;
+        const choice = chunk.choices[0];
+        if (!choice)
+            continue;
+        const delta = choice.delta;
+        if (delta?.content) {
+            text += delta.content;
+        }
+        if (delta?.tool_calls) {
+            for (const tc of delta.tool_calls) {
+                const idx = tc.index;
+                if (!pendingToolCalls[idx]) {
+                    pendingToolCalls[idx] = { id: tc.id, name: tc.function.name, argumentsJson: "" };
+                }
+                if (tc.function?.arguments) {
+                    pendingToolCalls[idx].argumentsJson += tc.function.arguments;
+                }
+            }
+        }
+    }
+    const assistantToolCalls = pendingToolCalls.length
+        ? pendingToolCalls.map(tc => ({ id: tc.id, function: { name: tc.name, arguments: tc.argumentsJson } }))
+        : undefined;
+    return { text, toolCalls: pendingToolCalls, assistantContent: text || null, assistantToolCalls };
+}

package/dist/agent/system-prompt.d.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition } from "./types.js";
+import type { ContextManager } from "../context-manager.js";
+/**
+ * Static system prompt — identical across all queries, cacheable.
+ * Contains only identity and behavioral instructions.
+ */
+export declare const STATIC_SYSTEM_PROMPT = "You are an AI coding assistant embedded in agent-sh, a terminal shell.\nYou have access to the user's shell environment and can read, write, and execute code.\nYou share the user's working directory, environment variables, and shell history.\n\n# Input Modes\n\nThe user interacts with you through two modes:\n\nEXECUTE mode (triggered by '>'): The user is asking questions or requesting tasks.\nUse your internal tools (bash, file operations, etc.) to accomplish tasks.\nDo NOT use user_shell in this mode unless the user explicitly asks to run\nsomething in their live shell.\n\nHELP mode (triggered by '?'): The user wants a command run in their live shell.\nYou may use your tools to investigate first (read files, grep, etc.), but the\nfinal action must be running the command via user_shell with return_output=false.\nThe user sees the output directly \u2014 you don't need to see or summarize it.\nDo not explain, confirm, or comment on the result \u2014 just run it and stop.\n\nEach prompt includes a per-query mode instruction \u2014 follow it.\n\n# Tool Usage Guidelines\n- Use read_file before editing a file you haven't seen\n- Prefer edit_file over write_file for modifying existing files\n- Use grep/glob to find files before reading them\n- Keep bash commands focused; avoid long-running blocking commands\n- Always check command exit codes for errors\n- user_shell runs commands in the user's live terminal \u2014 use for cd, export, source, etc.\n- user_shell output is shown directly to the user but NOT returned to you by default.\n  Set return_output=true if you need to inspect the result to answer a question.";
+/**
+ * Build the dynamic context — injected as a user message before each query.
+ * Contains everything that changes: tools, shell context, conventions, cwd.
+ *
+ * Runs through the "agent:dynamic-context" pipe so extensions can append.
+ */
+export declare function buildDynamicContext(tools: ToolDefinition[], contextManager: ContextManager): string;

package/dist/agent/system-prompt.js

@@ -0,0 +1,98 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverSkills } from "./skills.js";
+/** File names to scan for project conventions (checked in order). */
+const CONVENTION_FILES = ["CLAUDE.md", "AGENT.md"];
+/**
+ * Scan from `dir` upward for project convention files.
+ * Returns contents ordered root-first (general → specific).
+ */
+function loadConventionFiles(dir) {
+    const files = [];
+    let current = path.resolve(dir);
+    while (true) {
+        for (const name of CONVENTION_FILES) {
+            const candidate = path.join(current, name);
+            try {
+                const content = fs.readFileSync(candidate, "utf-8").trim();
+                if (content) {
+                    files.push({ path: candidate, content });
+                    break;
+                }
+            }
+            catch {
+                // File doesn't exist
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    files.reverse();
+    return files.map(f => `<!-- ${f.path} -->\n${f.content}`);
+}
+/**
+ * Static system prompt — identical across all queries, cacheable.
+ * Contains only identity and behavioral instructions.
+ */
+export const STATIC_SYSTEM_PROMPT = `You are an AI coding assistant embedded in agent-sh, a terminal shell.
+You have access to the user's shell environment and can read, write, and execute code.
+You share the user's working directory, environment variables, and shell history.
+
+# Input Modes
+
+The user interacts with you through two modes:
+
+EXECUTE mode (triggered by '>'): The user is asking questions or requesting tasks.
+Use your internal tools (bash, file operations, etc.) to accomplish tasks.
+Do NOT use user_shell in this mode unless the user explicitly asks to run
+something in their live shell.
+
+HELP mode (triggered by '?'): The user wants a command run in their live shell.
+You may use your tools to investigate first (read files, grep, etc.), but the
+final action must be running the command via user_shell with return_output=false.
+The user sees the output directly — you don't need to see or summarize it.
+Do not explain, confirm, or comment on the result — just run it and stop.
+
+Each prompt includes a per-query mode instruction — follow it.
+
+# Tool Usage Guidelines
+- Use read_file before editing a file you haven't seen
+- Prefer edit_file over write_file for modifying existing files
+- Use grep/glob to find files before reading them
+- Keep bash commands focused; avoid long-running blocking commands
+- Always check command exit codes for errors
+- user_shell runs commands in the user's live terminal — use for cd, export, source, etc.
+- user_shell output is shown directly to the user but NOT returned to you by default.
+  Set return_output=true if you need to inspect the result to answer a question.`;
+/**
+ * Build the dynamic context — injected as a user message before each query.
+ * Contains everything that changes: tools, shell context, conventions, cwd.
+ *
+ * Runs through the "agent:dynamic-context" pipe so extensions can append.
+ */
+export function buildDynamicContext(tools, contextManager) {
+    const sections = [];
+    // Tools
+    sections.push("# Available Tools\n" +
+        tools.map((t) => `- ${t.name}: ${t.description}`).join("\n"));
+    // Project conventions (CLAUDE.md / AGENT.md)
+    const conventions = loadConventionFiles(contextManager.getCwd());
+    if (conventions.length > 0) {
+        sections.push("# Project Conventions\n\n" + conventions.join("\n\n"));
+    }
+    // Skills hint
+    const skills = discoverSkills(contextManager.getCwd());
+    if (skills.length > 0) {
+        sections.push(`You have access to ${skills.length} skill(s). Use the list_skills tool to see them, then read_file to load one.`);
+    }
+    // Shell context
+    const shellContext = contextManager.getContext();
+    if (shellContext) {
+        sections.push(shellContext);
+    }
+    // Metadata
+    sections.push(`Current date: ${new Date().toISOString().split("T")[0]}\nWorking directory: ${contextManager.getCwd()}`);
+    return sections.join("\n\n");
+}

package/dist/agent/tool-registry.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDefinition } from "./types.js";
+import type { ChatCompletionTool } from "../utils/llm-client.js";
+/**
+ * Registry for agent tools. Holds tool definitions and converts them
+ * to OpenAI-compatible function schemas for API calls.
+ */
+export declare class ToolRegistry {
+    private tools;
+    register(tool: ToolDefinition): void;
+    unregister(name: string): void;
+    get(name: string): ToolDefinition | undefined;
+    all(): ToolDefinition[];
+    /** Convert to OpenAI-compatible tool schemas for API calls. */
+    toAPITools(): ChatCompletionTool[];
+}

package/dist/agent/tool-registry.js

@@ -0,0 +1,30 @@
+/**
+ * Registry for agent tools. Holds tool definitions and converts them
+ * to OpenAI-compatible function schemas for API calls.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    unregister(name) {
+        this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    all() {
+        return Array.from(this.tools.values());
+    }
+    /** Convert to OpenAI-compatible tool schemas for API calls. */
+    toAPITools() {
+        return this.all().map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.input_schema,
+            },
+        }));
+    }
+}

package/dist/agent/tools/bash.d.ts

@@ -0,0 +1,7 @@
+import type { EventBus } from "../../event-bus.js";
+import type { ToolDefinition } from "../types.js";
+export declare function createBashTool(opts: {
+    getCwd: () => string;
+    getEnv: () => Record<string, string>;
+    bus: EventBus;
+}): ToolDefinition;

package/dist/agent/tools/bash.js

@@ -0,0 +1,62 @@
+import { executeCommand } from "../../executor.js";
+export function createBashTool(opts) {
+    return {
+        name: "bash",
+        description: "Execute a bash command in an isolated subprocess. Output is captured and returned to you. Does not affect the user's shell state.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "The bash command to execute",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in seconds (default: 60)",
+                },
+            },
+            required: ["command"],
+        },
+        showOutput: true,
+        modifiesFiles: true,
+        requiresPermission: true,
+        getDisplayInfo: (args) => ({
+            kind: "execute",
+            locations: [],
+        }),
+        async execute(args, onChunk) {
+            const command = args.command;
+            const timeout = (args.timeout ?? 60) * 1000;
+            // Let extensions intercept before execution
+            const intercepted = opts.bus.emitPipe("agent:terminal-intercept", {
+                command,
+                cwd: opts.getCwd(),
+                intercepted: false,
+                output: "",
+            });
+            if (intercepted.intercepted) {
+                return {
+                    content: intercepted.output,
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const { session, done } = executeCommand({
+                command,
+                cwd: opts.getCwd(),
+                env: opts.getEnv(),
+                timeout,
+                onOutput: onChunk,
+            });
+            await done;
+            const content = session.truncated
+                ? `[output truncated, showing last portion]\n${session.output}`
+                : session.output;
+            return {
+                content: content || "(no output)",
+                exitCode: session.exitCode,
+                isError: session.exitCode !== 0,
+            };
+        },
+    };
+}