agent-sh 0.4.0 → 0.6.0

package/dist/agent/conversation-state.d.ts

@@ -0,0 +1,27 @@
+import type { ChatCompletionMessageParam } from "../utils/llm-client.js";
+/**
+ * Manages the OpenAI chat messages array for the agent loop.
+ * Separate from ContextManager — this is the LLM conversation,
+ * not the shell history.
+ */
+export declare class ConversationState {
+    private messages;
+    addUserMessage(text: string): void;
+    addAssistantMessage(content: string | null, toolCalls?: {
+        id: string;
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[]): void;
+    addToolResult(toolCallId: string, content: string): void;
+    /** Inject a system-level note into the conversation (e.g. context change). */
+    addSystemNote(text: string): void;
+    getMessages(): ChatCompletionMessageParam[];
+    /**
+     * Simple compaction — drop oldest turns, keeping the first user message
+     * (original task context) and the most recent turns.
+     */
+    compact(maxTurns: number): void;
+    clear(): void;
+}

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,119 @@
+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" };
+                const resultDisplay = tool.formatResult?.(args, result);
+                bus.emitTransform("agent:tool-completed", {
+                    toolCallId: tc.id,
+                    exitCode: result.exitCode,
+                    rawOutput: result.content,
+                    kind: display.kind,
+                    resultDisplay,
+                });
+            }
+            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# Tool Decision Guide\n\nYou have three categories of tools \u2014 choose based on who needs the output and\nwhether the command has lasting effects:\n\n**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):\nUse these to investigate, search, read, and modify files. Output is returned\nto you for reasoning \u2014 the user doesn't see it directly.\n\n**Display** (display):\nUse this to show output to the user in their terminal. The user sees the\noutput directly, but it is NOT returned to you. Use when:\n- The user asks to see something (cat a file, git log, git diff, man page)\n- The output is for the user to read, not for you to process\n\n**Live shell** (user_shell):\nUse this to run commands with lasting effects in the user's real shell. Use for:\n- Commands that affect shell state (cd, export, source)\n- Installing packages, starting servers, running builds\n- Any command where the user wants real side effects\n- Set return_output=true only if you need to inspect the result\n\nDefault to scratchpad tools for your own investigation. Use display when the\nuser is the intended audience. Use user_shell when the command has real effects.\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";
+/**
+ * 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,103 @@
+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.
+
+# Tool Decision Guide
+
+You have three categories of tools — choose based on who needs the output and
+whether the command has lasting effects:
+
+**Scratchpad tools** (bash, read_file, grep, glob, ls, edit_file, write_file):
+Use these to investigate, search, read, and modify files. Output is returned
+to you for reasoning — the user doesn't see it directly.
+
+**Display** (display):
+Use this to show output to the user in their terminal. The user sees the
+output directly, but it is NOT returned to you. Use when:
+- The user asks to see something (cat a file, git log, git diff, man page)
+- The output is for the user to read, not for you to process
+
+**Live shell** (user_shell):
+Use this to run commands with lasting effects in the user's real shell. Use for:
+- Commands that affect shell state (cd, export, source)
+- Installing packages, starting servers, running builds
+- Any command where the user wants real side effects
+- Set return_output=true only if you need to inspect the result
+
+Default to scratchpad tools for your own investigation. Use display when the
+user is the intended audience. Use user_shell when the command has real effects.
+
+# 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`;
+/**
+ * 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;