gitclaw 0.3.0

package/dist/index.js

@@ -0,0 +1,542 @@
+#!/usr/bin/env node
+import { createInterface } from "readline";
+import { Agent } from "@mariozechner/pi-agent-core";
+import { loadAgent } from "./loader.js";
+import { createBuiltinTools } from "./tools/index.js";
+import { createSandboxContext } from "./sandbox.js";
+import { expandSkillCommand } from "./skills.js";
+import { loadHooksConfig, runHooks, wrapToolWithHooks } from "./hooks.js";
+import { loadDeclarativeTools } from "./tool-loader.js";
+import { AuditLogger, isAuditEnabled } from "./audit.js";
+import { formatComplianceWarnings } from "./compliance.js";
+import { readFile, mkdir, writeFile, access } from "fs/promises";
+import { join, resolve } from "path";
+import { execSync } from "child_process";
+import { initLocalSession } from "./session.js";
+// ANSI helpers
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let model;
+    let dir = process.cwd();
+    let prompt;
+    let env;
+    let sandbox = false;
+    let sandboxRepo;
+    let sandboxToken;
+    let repo;
+    let pat;
+    let session;
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--model":
+            case "-m":
+                model = args[++i];
+                break;
+            case "--dir":
+            case "-d":
+                dir = args[++i];
+                break;
+            case "--prompt":
+            case "-p":
+                prompt = args[++i];
+                break;
+            case "--env":
+            case "-e":
+                env = args[++i];
+                break;
+            case "--sandbox":
+            case "-s":
+                sandbox = true;
+                break;
+            case "--sandbox-repo":
+                sandboxRepo = args[++i];
+                break;
+            case "--sandbox-token":
+                sandboxToken = args[++i];
+                break;
+            case "--repo":
+            case "-r":
+                repo = args[++i];
+                break;
+            case "--pat":
+                pat = args[++i];
+                break;
+            case "--session":
+                session = args[++i];
+                break;
+            default:
+                if (!args[i].startsWith("-")) {
+                    prompt = args[i];
+                }
+                break;
+        }
+    }
+    return { model, dir, prompt, env, sandbox, sandboxRepo, sandboxToken, repo, pat, session };
+}
+function handleEvent(event, hooksConfig, agentDir, sessionId, auditLogger) {
+    switch (event.type) {
+        case "message_update": {
+            const e = event.assistantMessageEvent;
+            if (e.type === "text_delta") {
+                process.stdout.write(e.delta);
+            }
+            break;
+        }
+        case "message_end": {
+            process.stdout.write("\n");
+            // Fire post_response hooks (non-blocking)
+            if (hooksConfig?.hooks.post_response) {
+                runHooks(hooksConfig.hooks.post_response, agentDir, {
+                    event: "post_response",
+                    session_id: sessionId,
+                }).catch(() => { });
+            }
+            auditLogger?.logResponse().catch(() => { });
+            break;
+        }
+        case "tool_execution_start":
+            process.stdout.write(dim(`\n▶ ${event.toolName}(${summarizeArgs(event.args)})\n`));
+            auditLogger?.logToolUse(event.toolName, event.args || {}).catch(() => { });
+            break;
+        case "tool_execution_end": {
+            if (event.isError) {
+                process.stdout.write(red(`✗ ${event.toolName} failed\n`));
+            }
+            else {
+                const result = event.result;
+                const text = result?.content?.[0]?.text || "";
+                const preview = text.length > 200 ? text.slice(0, 200) + "…" : text;
+                if (preview) {
+                    process.stdout.write(dim(preview) + "\n");
+                }
+            }
+            break;
+        }
+        case "agent_end":
+            break;
+    }
+}
+function summarizeArgs(args) {
+    if (!args)
+        return "";
+    const entries = Object.entries(args);
+    if (entries.length === 0)
+        return "";
+    return entries
+        .map(([k, v]) => {
+        const str = typeof v === "string" ? v : JSON.stringify(v);
+        const short = str.length > 60 ? str.slice(0, 60) + "…" : str;
+        return `${k}: ${short}`;
+    })
+        .join(", ");
+}
+function askQuestion(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            res(answer.trim());
+        });
+    });
+}
+function isGitRepo(dir) {
+    try {
+        execSync("git rev-parse --is-inside-work-tree", { cwd: dir, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureRepo(dir, model) {
+    const absDir = resolve(dir);
+    // Create directory if it doesn't exist
+    if (!(await fileExists(absDir))) {
+        console.log(dim(`Creating directory: ${absDir}`));
+        await mkdir(absDir, { recursive: true });
+    }
+    // Git init if not a repo
+    if (!isGitRepo(absDir)) {
+        console.log(dim("Initializing git repository..."));
+        execSync("git init", { cwd: absDir, stdio: "pipe" });
+        // Create .gitignore
+        const gitignorePath = join(absDir, ".gitignore");
+        if (!(await fileExists(gitignorePath))) {
+            await writeFile(gitignorePath, "node_modules/\ndist/\n.gitagent/\n", "utf-8");
+        }
+        // Initial commit so memory saves work
+        execSync("git add -A && git commit -m 'Initial commit' --allow-empty", {
+            cwd: absDir,
+            stdio: "pipe",
+        });
+    }
+    // Scaffold agent.yaml if missing
+    const agentYamlPath = join(absDir, "agent.yaml");
+    if (!(await fileExists(agentYamlPath))) {
+        const defaultModel = model || "openai:gpt-4o-mini";
+        const agentName = absDir.split("/").pop() || "my-agent";
+        const yaml = [
+            'spec_version: "0.1.0"',
+            `name: ${agentName}`,
+            "version: 0.1.0",
+            `description: Gitclaw agent for ${agentName}`,
+            "model:",
+            `  preferred: "${defaultModel}"`,
+            "  fallback: []",
+            "tools: [cli, read, write, memory]",
+            "runtime:",
+            "  max_turns: 50",
+            "",
+        ].join("\n");
+        await writeFile(agentYamlPath, yaml, "utf-8");
+        console.log(dim(`Created agent.yaml (model: ${defaultModel})`));
+    }
+    // Scaffold memory if missing
+    const memoryDir = join(absDir, "memory");
+    const memoryFile = join(memoryDir, "MEMORY.md");
+    if (!(await fileExists(memoryFile))) {
+        await mkdir(memoryDir, { recursive: true });
+        await writeFile(memoryFile, "# Memory\n", "utf-8");
+    }
+    // Scaffold SOUL.md if missing
+    const soulPath = join(absDir, "SOUL.md");
+    if (!(await fileExists(soulPath))) {
+        await writeFile(soulPath, [
+            "# Identity",
+            "",
+            "You are a helpful AI agent. You live inside a git repository.",
+            "You can run commands, read and write files, and remember things.",
+            "Be concise and action-oriented.",
+            "",
+        ].join("\n"), "utf-8");
+    }
+    // Stage new scaffolded files
+    try {
+        execSync("git add -A && git diff --cached --quiet || git commit -m 'Scaffold gitclaw agent'", {
+            cwd: absDir,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // ok if nothing to commit
+    }
+    return absDir;
+}
+async function main() {
+    const { model, dir: rawDir, prompt, env, sandbox: useSandbox, sandboxRepo, sandboxToken, repo, pat, session: sessionBranch } = parseArgs(process.argv);
+    // If --repo is given, derive a default dir from the repo URL (skip interactive prompt)
+    let dir = rawDir;
+    let localSession;
+    if (repo) {
+        // Validate mutually exclusive flags
+        if (useSandbox) {
+            console.error(red("Error: --repo and --sandbox are mutually exclusive"));
+            process.exit(1);
+        }
+        const token = pat || process.env.GITHUB_TOKEN || process.env.GIT_TOKEN;
+        if (!token) {
+            console.error(red("Error: --pat, GITHUB_TOKEN, or GIT_TOKEN is required with --repo"));
+            process.exit(1);
+        }
+        // Default dir: /tmp/gitclaw/<repo-name> if no --dir given
+        if (dir === process.cwd()) {
+            const repoName = repo.split("/").pop()?.replace(/\.git$/, "") || "repo";
+            dir = resolve(`/tmp/gitclaw/${repoName}`);
+        }
+        localSession = initLocalSession({
+            url: repo,
+            token,
+            dir,
+            session: sessionBranch,
+        });
+        dir = localSession.dir;
+        console.log(dim(`Local session: ${localSession.branch} (${localSession.dir})`));
+    }
+    else if (dir === process.cwd() && !prompt) {
+        // No --repo: interactive prompt for dir
+        const answer = await askQuestion(green("? ") + bold("Repository path") + dim(" (. for current dir)") + green(": "));
+        if (answer) {
+            dir = resolve(answer === "." ? process.cwd() : answer);
+        }
+    }
+    // Create sandbox context if --sandbox flag is set
+    let sandboxCtx;
+    if (useSandbox) {
+        const sandboxConfig = {
+            provider: "e2b",
+            repository: sandboxRepo,
+            token: sandboxToken,
+        };
+        sandboxCtx = await createSandboxContext(sandboxConfig, resolve(dir));
+        console.log(dim("Starting sandbox VM..."));
+        await sandboxCtx.gitMachine.start();
+        console.log(dim(`Sandbox ready (repo: ${sandboxCtx.repoPath})`));
+    }
+    // Ensure the target is a valid gitclaw repo (skip in sandbox/local-repo mode)
+    if (localSession) {
+        // Already cloned and scaffolded by initLocalSession
+    }
+    else if (!useSandbox) {
+        dir = await ensureRepo(dir, model);
+    }
+    else {
+        dir = resolve(dir);
+    }
+    let loaded;
+    try {
+        loaded = await loadAgent(dir, model, env);
+    }
+    catch (err) {
+        console.error(red(`Error: ${err.message}`));
+        process.exit(1);
+    }
+    const { systemPrompt, manifest, skills, sessionId, agentDir, gitagentDir, complianceWarnings } = loaded;
+    // Show compliance warnings
+    if (complianceWarnings.length > 0) {
+        const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+        console.log(yellow("Compliance warnings:"));
+        console.log(yellow(formatComplianceWarnings(complianceWarnings)));
+    }
+    // Initialize audit logger
+    const auditEnabled = isAuditEnabled(manifest.compliance);
+    const auditLogger = new AuditLogger(gitagentDir, sessionId, auditEnabled);
+    if (auditEnabled) {
+        await auditLogger.logSessionStart();
+    }
+    // Load hooks config
+    const hooksConfig = await loadHooksConfig(agentDir);
+    // Run on_session_start hooks
+    if (hooksConfig?.hooks.on_session_start) {
+        try {
+            const result = await runHooks(hooksConfig.hooks.on_session_start, agentDir, {
+                event: "on_session_start",
+                session_id: sessionId,
+                agent: manifest.name,
+            });
+            if (result.action === "block") {
+                console.error(red(`Session blocked by hook: ${result.reason || "no reason given"}`));
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            console.error(red(`Hook error: ${err.message}`));
+        }
+    }
+    // Map provider to expected env var
+    const apiKeyEnvVars = {
+        anthropic: "ANTHROPIC_API_KEY",
+        openai: "OPENAI_API_KEY",
+        google: "GOOGLE_API_KEY",
+        xai: "XAI_API_KEY",
+        groq: "GROQ_API_KEY",
+        mistral: "MISTRAL_API_KEY",
+    };
+    const provider = loaded.model.provider;
+    const envVar = apiKeyEnvVars[provider];
+    if (envVar && !process.env[envVar]) {
+        console.error(red(`Error: ${envVar} environment variable is not set.`));
+        console.error(dim(`Set it with: export ${envVar}=your-key-here`));
+        process.exit(1);
+    }
+    // Build tools — built-in + declarative
+    let tools = createBuiltinTools({
+        dir,
+        timeout: manifest.runtime.timeout,
+        sandbox: sandboxCtx,
+    });
+    // Load declarative tools from tools/*.yaml (Phase 2.2)
+    const declarativeTools = await loadDeclarativeTools(agentDir);
+    tools = [...tools, ...declarativeTools];
+    // Wrap with hooks if configured
+    if (hooksConfig) {
+        tools = tools.map((t) => wrapToolWithHooks(t, hooksConfig, agentDir, sessionId));
+    }
+    // Build model options from manifest constraints
+    const modelOptions = {};
+    if (manifest.model.constraints) {
+        const c = manifest.model.constraints;
+        if (c.temperature !== undefined)
+            modelOptions.temperature = c.temperature;
+        if (c.max_tokens !== undefined)
+            modelOptions.maxTokens = c.max_tokens;
+        if (c.top_p !== undefined)
+            modelOptions.topP = c.top_p;
+        if (c.top_k !== undefined)
+            modelOptions.topK = c.top_k;
+        if (c.stop_sequences !== undefined)
+            modelOptions.stopSequences = c.stop_sequences;
+    }
+    const agent = new Agent({
+        initialState: {
+            systemPrompt,
+            model: loaded.model,
+            tools,
+            ...modelOptions,
+        },
+    });
+    agent.subscribe((event) => handleEvent(event, hooksConfig, agentDir, sessionId, auditLogger));
+    console.log(bold(`${manifest.name} v${manifest.version}`));
+    console.log(dim(`Model: ${loaded.model.provider}:${loaded.model.id}`));
+    const allToolNames = tools.map((t) => t.name);
+    console.log(dim(`Tools: ${allToolNames.join(", ")}`));
+    if (skills.length > 0) {
+        console.log(dim(`Skills: ${skills.map((s) => s.name).join(", ")}`));
+    }
+    if (loaded.workflows.length > 0) {
+        console.log(dim(`Workflows: ${loaded.workflows.map((w) => w.name).join(", ")}`));
+    }
+    if (loaded.subAgents.length > 0) {
+        console.log(dim(`Agents: ${loaded.subAgents.map((a) => a.name).join(", ")}`));
+    }
+    console.log(dim('Type /skills to list skills, /memory to view memory, /quit to exit\n'));
+    // Single-shot mode
+    if (prompt) {
+        try {
+            await agent.prompt(prompt);
+        }
+        catch (err) {
+            auditLogger?.logError(err.message).catch(() => { });
+            // Fire on_error hooks
+            if (hooksConfig?.hooks.on_error) {
+                runHooks(hooksConfig.hooks.on_error, agentDir, {
+                    event: "on_error",
+                    session_id: sessionId,
+                    error: err.message,
+                }).catch(() => { });
+            }
+            throw err;
+        }
+        finally {
+            if (localSession) {
+                console.log(dim("Finalizing session..."));
+                localSession.finalize();
+            }
+            if (sandboxCtx) {
+                console.log(dim("Stopping sandbox..."));
+                await sandboxCtx.gitMachine.stop();
+            }
+        }
+        return;
+    }
+    // REPL mode
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = () => {
+        rl.question(green("→ "), async (input) => {
+            const trimmed = input.trim();
+            if (!trimmed) {
+                ask();
+                return;
+            }
+            if (trimmed === "/quit" || trimmed === "/exit") {
+                rl.close();
+                if (localSession) {
+                    console.log(dim("Finalizing session..."));
+                    localSession.finalize();
+                }
+                await stopSandbox();
+                process.exit(0);
+            }
+            if (trimmed === "/memory") {
+                try {
+                    const mem = await readFile(join(dir, "memory/MEMORY.md"), "utf-8");
+                    console.log(dim("--- memory ---"));
+                    console.log(mem.trim() || "(empty)");
+                    console.log(dim("--- end ---"));
+                }
+                catch {
+                    console.log(dim("(no memory file)"));
+                }
+                ask();
+                return;
+            }
+            if (trimmed === "/skills") {
+                if (skills.length === 0) {
+                    console.log(dim("No skills installed."));
+                }
+                else {
+                    for (const s of skills) {
+                        console.log(`  ${bold(s.name)} — ${dim(s.description)}`);
+                    }
+                }
+                ask();
+                return;
+            }
+            // Skill expansion: /skill:name [args]
+            let promptText = trimmed;
+            if (trimmed.startsWith("/skill:")) {
+                const result = await expandSkillCommand(trimmed, skills);
+                if (result) {
+                    console.log(dim(`▶ loading skill: ${result.skillName}`));
+                    promptText = result.expanded;
+                }
+                else {
+                    const requested = trimmed.match(/^\/skill:([a-z0-9-]*)/)?.[1] || "?";
+                    console.error(red(`Unknown skill: ${requested}`));
+                    ask();
+                    return;
+                }
+            }
+            try {
+                await agent.prompt(promptText);
+            }
+            catch (err) {
+                console.error(red(`Error: ${err.message}`));
+                auditLogger?.logError(err.message).catch(() => { });
+                // Fire on_error hooks
+                if (hooksConfig?.hooks.on_error) {
+                    runHooks(hooksConfig.hooks.on_error, agentDir, {
+                        event: "on_error",
+                        session_id: sessionId,
+                        error: err.message,
+                    }).catch(() => { });
+                }
+            }
+            ask();
+        });
+    };
+    // Sandbox cleanup helper
+    const stopSandbox = async () => {
+        if (sandboxCtx) {
+            console.log(dim("Stopping sandbox..."));
+            await sandboxCtx.gitMachine.stop();
+        }
+    };
+    // Handle Ctrl+C during streaming
+    rl.on("SIGINT", () => {
+        if (agent.state.isStreaming) {
+            agent.abort();
+        }
+        else {
+            console.log("\nBye!");
+            rl.close();
+            if (localSession) {
+                try {
+                    localSession.finalize();
+                }
+                catch { /* best-effort */ }
+            }
+            stopSandbox().finally(() => process.exit(0));
+        }
+    });
+    ask();
+}
+main().catch((err) => {
+    console.error(red(`Fatal: ${err.message}`));
+    process.exit(1);
+});

package/dist/knowledge.d.ts

@@ -0,0 +1,17 @@
+export interface KnowledgeEntry {
+    path: string;
+    tags: string[];
+    priority: "high" | "medium" | "low";
+    always_load?: boolean;
+}
+export interface LoadedKnowledge {
+    /** Content from always_load docs, ready to inject into system prompt */
+    preloaded: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Entries available on demand via read tool */
+    available: KnowledgeEntry[];
+}
+export declare function loadKnowledge(agentDir: string): Promise<LoadedKnowledge>;
+export declare function formatKnowledgeForPrompt(knowledge: LoadedKnowledge): string;

package/dist/knowledge.js

@@ -0,0 +1,55 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+export async function loadKnowledge(agentDir) {
+    const knowledgeDir = join(agentDir, "knowledge");
+    const indexPath = join(knowledgeDir, "index.yaml");
+    let raw;
+    try {
+        raw = await readFile(indexPath, "utf-8");
+    }
+    catch {
+        return { preloaded: [], available: [] };
+    }
+    const index = yaml.load(raw);
+    if (!index?.entries || !Array.isArray(index.entries)) {
+        return { preloaded: [], available: [] };
+    }
+    const preloaded = [];
+    const available = [];
+    for (const entry of index.entries) {
+        if (entry.always_load) {
+            try {
+                const content = await readFile(join(knowledgeDir, entry.path), "utf-8");
+                preloaded.push({ path: entry.path, content: content.trim() });
+            }
+            catch {
+                // Skip missing files
+            }
+        }
+        else {
+            available.push(entry);
+        }
+    }
+    return { preloaded, available };
+}
+export function formatKnowledgeForPrompt(knowledge) {
+    const parts = [];
+    // Inject always_load content directly
+    for (const doc of knowledge.preloaded) {
+        parts.push(`<knowledge path="${doc.path}">\n${doc.content}\n</knowledge>`);
+    }
+    // List available docs for on-demand access
+    if (knowledge.available.length > 0) {
+        const entries = knowledge.available
+            .map((e) => {
+            const tags = e.tags.length > 0 ? ` tags="${e.tags.join(",")}"` : "";
+            return `<doc path="knowledge/${e.path}" priority="${e.priority}"${tags} />`;
+        })
+            .join("\n");
+        parts.push(`<available_knowledge>\n${entries}\n</available_knowledge>\n\nUse the \`read\` tool to load any available knowledge document when needed.`);
+    }
+    if (parts.length === 0)
+        return "";
+    return `# Knowledge\n\n${parts.join("\n\n")}`;
+}

package/dist/loader.d.ts

@@ -0,0 +1,64 @@
+import type { Model } from "@mariozechner/pi-ai";
+import type { SkillMetadata } from "./skills.js";
+import type { LoadedKnowledge } from "./knowledge.js";
+import type { WorkflowMetadata } from "./workflows.js";
+import type { EnvConfig } from "./config.js";
+import type { SubAgentMetadata } from "./agents.js";
+import type { ExampleEntry } from "./examples.js";
+import type { ComplianceWarning } from "./compliance.js";
+export interface AgentManifest {
+    spec_version: string;
+    name: string;
+    version: string;
+    description: string;
+    author?: string;
+    license?: string;
+    tags?: string[];
+    metadata?: Record<string, string | number | boolean>;
+    model: {
+        preferred: string;
+        fallback: string[];
+        constraints?: {
+            temperature?: number;
+            max_tokens?: number;
+            top_p?: number;
+            top_k?: number;
+            stop_sequences?: string[];
+        };
+    };
+    tools: string[];
+    skills?: string[];
+    runtime: {
+        max_turns: number;
+        timeout?: number;
+    };
+    extends?: string;
+    dependencies?: Array<{
+        name: string;
+        source: string;
+        version: string;
+        mount: string;
+    }>;
+    agents?: Record<string, any>;
+    delegation?: {
+        mode: "auto" | "explicit" | "router";
+        router?: string;
+    };
+    compliance?: Record<string, any>;
+}
+export interface LoadedAgent {
+    systemPrompt: string;
+    manifest: AgentManifest;
+    model: Model<any>;
+    skills: SkillMetadata[];
+    knowledge: LoadedKnowledge;
+    workflows: WorkflowMetadata[];
+    subAgents: SubAgentMetadata[];
+    examples: ExampleEntry[];
+    envConfig: EnvConfig;
+    sessionId: string;
+    agentDir: string;
+    gitagentDir: string;
+    complianceWarnings: ComplianceWarning[];
+}
+export declare function loadAgent(agentDir: string, modelFlag?: string, envFlag?: string): Promise<LoadedAgent>;