gitclaw 0.3.0

package/dist/skills.js

@@ -0,0 +1,104 @@
+import { readFile, readdir, stat } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontmatter = yaml.load(match[1]);
+    return { frontmatter, body: match[2] };
+}
+async function dirExists(path) {
+    try {
+        const s = await stat(path);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function discoverSkills(agentDir) {
+    const skillsDir = join(agentDir, "skills");
+    if (!(await dirExists(skillsDir))) {
+        return [];
+    }
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillDir = join(skillsDir, entry.name);
+        const skillFile = join(skillDir, "SKILL.md");
+        let content;
+        try {
+            content = await readFile(skillFile, "utf-8");
+        }
+        catch {
+            continue; // no SKILL.md, skip
+        }
+        const { frontmatter } = parseFrontmatter(content);
+        const name = frontmatter.name;
+        const description = frontmatter.description;
+        if (!name || !description) {
+            console.warn(`Skipping skill "${entry.name}": missing name or description in frontmatter`);
+            continue;
+        }
+        if (name !== entry.name) {
+            console.warn(`Skipping skill "${entry.name}": name "${name}" does not match directory`);
+            continue;
+        }
+        if (!KEBAB_RE.test(name)) {
+            console.warn(`Skipping skill "${entry.name}": name must be kebab-case`);
+            continue;
+        }
+        skills.push({
+            name,
+            description,
+            directory: skillDir,
+            filePath: skillFile,
+        });
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function loadSkill(meta) {
+    const content = await readFile(meta.filePath, "utf-8");
+    const { body } = parseFrontmatter(content);
+    return {
+        ...meta,
+        instructions: body.trim(),
+        hasScripts: await dirExists(join(meta.directory, "scripts")),
+        hasReferences: await dirExists(join(meta.directory, "references")),
+    };
+}
+export function formatSkillsForPrompt(skills) {
+    if (skills.length === 0)
+        return "";
+    const skillEntries = skills
+        .map((s) => `<skill>\n<name>${s.name}</name>\n<description>${s.description}</description>\n</skill>`)
+        .join("\n");
+    return `# Skills
+
+<available_skills>
+${skillEntries}
+</available_skills>
+
+When a task matches a skill, use the \`read\` tool to load \`skills/<name>/SKILL.md\` for full instructions. Scripts within a skill are relative to the skill's directory (e.g., \`skills/<name>/scripts/\`). Use the \`cli\` tool to execute them.`;
+}
+export async function expandSkillCommand(input, skills) {
+    const match = input.match(/^\/skill:([a-z0-9-]+)\s*([\s\S]*)$/);
+    if (!match)
+        return null;
+    const skillName = match[1];
+    const args = match[2].trim();
+    const skill = skills.find((s) => s.name === skillName);
+    if (!skill)
+        return null;
+    const parsed = await loadSkill(skill);
+    let expanded = `<skill name="${skillName}" baseDir="${skill.directory}">\n${parsed.instructions}\n</skill>`;
+    if (args) {
+        expanded += `\n\n${args}`;
+    }
+    return { expanded, skillName };
+}

package/dist/tool-loader.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+export declare function buildTypeboxSchema(schema: Record<string, any>): any;
+export declare function loadDeclarativeTools(agentDir: string): Promise<AgentTool<any>[]>;

package/dist/tool-loader.js

@@ -0,0 +1,138 @@
+import { readFile, readdir, stat } from "fs/promises";
+import { join } from "path";
+import { spawn } from "child_process";
+import yaml from "js-yaml";
+import { Type } from "@sinclair/typebox";
+export function buildTypeboxSchema(schema) {
+    // Convert a simplified JSON-schema-like object to Typebox properties
+    const properties = {};
+    if (schema.properties) {
+        for (const [key, def] of Object.entries(schema.properties)) {
+            const desc = def.description || "";
+            const required = schema.required?.includes(key) ?? false;
+            let prop;
+            switch (def.type) {
+                case "number":
+                    prop = Type.Number({ description: desc });
+                    break;
+                case "boolean":
+                    prop = Type.Boolean({ description: desc });
+                    break;
+                case "array":
+                    prop = Type.Array(Type.Any(), { description: desc });
+                    break;
+                case "object":
+                    prop = Type.Any({ description: desc });
+                    break;
+                default:
+                    prop = Type.String({ description: desc });
+                    break;
+            }
+            properties[key] = required ? prop : Type.Optional(prop);
+        }
+    }
+    return Type.Object(properties);
+}
+function createDeclarativeTool(def, agentDir) {
+    const schema = buildTypeboxSchema(def.input_schema);
+    const scriptPath = join(agentDir, "tools", def.implementation.script);
+    const runtime = def.implementation.runtime || "sh";
+    return {
+        name: def.name,
+        label: def.name,
+        description: def.description,
+        parameters: schema,
+        execute: async (_toolCallId, args, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            return new Promise((resolve, reject) => {
+                const child = spawn(runtime, [scriptPath], {
+                    cwd: agentDir,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    env: { ...process.env },
+                });
+                let stdout = "";
+                let stderr = "";
+                child.stdout.on("data", (data) => {
+                    stdout += data.toString("utf-8");
+                });
+                child.stderr.on("data", (data) => {
+                    stderr += data.toString("utf-8");
+                });
+                // Send args as JSON on stdin
+                child.stdin.write(JSON.stringify(args));
+                child.stdin.end();
+                const timeout = setTimeout(() => {
+                    child.kill("SIGTERM");
+                    reject(new Error(`Tool "${def.name}" timed out after 120s`));
+                }, 120_000);
+                const onAbort = () => child.kill("SIGTERM");
+                if (signal)
+                    signal.addEventListener("abort", onAbort, { once: true });
+                child.on("error", (err) => {
+                    clearTimeout(timeout);
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    reject(new Error(`Tool "${def.name}" failed to start: ${err.message}`));
+                });
+                child.on("close", (code) => {
+                    clearTimeout(timeout);
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    if (signal?.aborted) {
+                        reject(new Error("Operation aborted"));
+                        return;
+                    }
+                    if (code !== 0 && code !== null) {
+                        reject(new Error(`Tool "${def.name}" exited with code ${code}: ${stderr.trim()}`));
+                        return;
+                    }
+                    // Try parsing JSON output
+                    let text = stdout.trim();
+                    try {
+                        const parsed = JSON.parse(text);
+                        if (parsed.text)
+                            text = parsed.text;
+                        else if (parsed.result)
+                            text = typeof parsed.result === "string" ? parsed.result : JSON.stringify(parsed.result);
+                    }
+                    catch {
+                        // Raw text output is fine
+                    }
+                    resolve({
+                        content: [{ type: "text", text: text || "(no output)" }],
+                        details: undefined,
+                    });
+                });
+            });
+        },
+    };
+}
+export async function loadDeclarativeTools(agentDir) {
+    const toolsDir = join(agentDir, "tools");
+    try {
+        const s = await stat(toolsDir);
+        if (!s.isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(toolsDir);
+    const tools = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".yaml") && !entry.endsWith(".yml"))
+            continue;
+        try {
+            const raw = await readFile(join(toolsDir, entry), "utf-8");
+            const def = yaml.load(raw);
+            if (def?.name && def?.description && def?.input_schema && def?.implementation?.script) {
+                tools.push(createDeclarativeTool(def, agentDir));
+            }
+        }
+        catch {
+            // Skip invalid tool definitions
+        }
+    }
+    return tools;
+}

package/dist/tools/cli.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { cliSchema } from "./shared.js";
+export declare function createCliTool(cwd: string, defaultTimeout?: number): AgentTool<typeof cliSchema>;

package/dist/tools/cli.js

@@ -0,0 +1,86 @@
+import { spawn } from "child_process";
+import { cliSchema, MAX_OUTPUT, DEFAULT_TIMEOUT } from "./shared.js";
+export function createCliTool(cwd, defaultTimeout) {
+    const baseTimeout = defaultTimeout ?? DEFAULT_TIMEOUT;
+    return {
+        name: "cli",
+        label: "cli",
+        description: "Execute a shell command. Returns stdout and stderr combined. Output is truncated if it exceeds ~100KB. Default timeout is 120 seconds.",
+        parameters: cliSchema,
+        execute: async (_toolCallId, { command, timeout }, signal, onUpdate) => {
+            const timeoutSecs = timeout ?? baseTimeout;
+            return new Promise((resolve, reject) => {
+                if (signal?.aborted) {
+                    reject(new Error("Operation aborted"));
+                    return;
+                }
+                const child = spawn("sh", ["-c", command], {
+                    cwd,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    env: { ...process.env },
+                });
+                let output = "";
+                let timedOut = false;
+                const timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                }, timeoutSecs * 1000);
+                const onData = (data) => {
+                    output += data.toString("utf-8");
+                    if (onUpdate && output.length <= MAX_OUTPUT) {
+                        onUpdate({
+                            content: [{ type: "text", text: output }],
+                            details: undefined,
+                        });
+                    }
+                };
+                child.stdout?.on("data", onData);
+                child.stderr?.on("data", onData);
+                const onAbort = () => {
+                    child.kill("SIGTERM");
+                };
+                if (signal) {
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }
+                child.on("error", (err) => {
+                    clearTimeout(timeoutHandle);
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    reject(err);
+                });
+                child.on("close", (code) => {
+                    clearTimeout(timeoutHandle);
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    if (signal?.aborted) {
+                        reject(new Error("Operation aborted"));
+                        return;
+                    }
+                    if (timedOut) {
+                        reject(new Error(`Command timed out after ${timeoutSecs} seconds\n${output}`));
+                        return;
+                    }
+                    // Truncate if needed
+                    let text = output;
+                    if (text.length > MAX_OUTPUT) {
+                        text = text.slice(-MAX_OUTPUT);
+                        text = `[output truncated, showing last ~100KB]\n${text}`;
+                    }
+                    if (!text) {
+                        text = "(no output)";
+                    }
+                    if (code !== 0 && code !== null) {
+                        text += `\n\nExit code: ${code}`;
+                        reject(new Error(text));
+                    }
+                    else {
+                        resolve({
+                            content: [{ type: "text", text }],
+                            details: { exitCode: code },
+                        });
+                    }
+                });
+            });
+        },
+    };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { SandboxContext } from "../sandbox.js";
+export interface BuiltinToolsConfig {
+    dir: string;
+    timeout?: number;
+    sandbox?: SandboxContext;
+}
+/**
+ * Create the four built-in tools (cli, read, write, memory).
+ * If a SandboxContext is provided, returns sandbox-backed tools;
+ * otherwise returns the standard local tools.
+ */
+export declare function createBuiltinTools(config: BuiltinToolsConfig): AgentTool<any>[];

package/dist/tools/index.js

@@ -0,0 +1,29 @@
+import { createCliTool } from "./cli.js";
+import { createReadTool } from "./read.js";
+import { createWriteTool } from "./write.js";
+import { createMemoryTool } from "./memory.js";
+import { createSandboxCliTool } from "./sandbox-cli.js";
+import { createSandboxReadTool } from "./sandbox-read.js";
+import { createSandboxWriteTool } from "./sandbox-write.js";
+import { createSandboxMemoryTool } from "./sandbox-memory.js";
+/**
+ * Create the four built-in tools (cli, read, write, memory).
+ * If a SandboxContext is provided, returns sandbox-backed tools;
+ * otherwise returns the standard local tools.
+ */
+export function createBuiltinTools(config) {
+    if (config.sandbox) {
+        return [
+            createSandboxCliTool(config.sandbox, config.timeout),
+            createSandboxReadTool(config.sandbox),
+            createSandboxWriteTool(config.sandbox),
+            createSandboxMemoryTool(config.sandbox),
+        ];
+    }
+    return [
+        createCliTool(config.dir, config.timeout),
+        createReadTool(config.dir),
+        createWriteTool(config.dir),
+        createMemoryTool(config.dir),
+    ];
+}

package/dist/tools/memory.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { memorySchema } from "./shared.js";
+export declare function createMemoryTool(cwd: string): AgentTool<typeof memorySchema>;

package/dist/tools/memory.js

@@ -0,0 +1,128 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+import { execSync } from "child_process";
+import { memorySchema, DEFAULT_MEMORY_PATH } from "./shared.js";
+import yaml from "js-yaml";
+async function loadMemoryConfig(cwd) {
+    try {
+        const raw = await readFile(join(cwd, "memory", "memory.yaml"), "utf-8");
+        const config = yaml.load(raw);
+        if (!config?.layers || !Array.isArray(config.layers))
+            return null;
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+function getWorkingLayer(config) {
+    if (!config) {
+        return { path: DEFAULT_MEMORY_PATH };
+    }
+    const working = config.layers.find((l) => l.name === "working") || config.layers[0];
+    if (!working) {
+        return { path: DEFAULT_MEMORY_PATH };
+    }
+    return { path: working.path, maxLines: working.max_lines };
+}
+async function archiveOverflow(cwd, content, maxLines) {
+    const lines = content.split("\n");
+    if (lines.length <= maxLines)
+        return content;
+    // Keep the last maxLines, archive the rest
+    const overflow = lines.slice(0, lines.length - maxLines).join("\n");
+    const kept = lines.slice(lines.length - maxLines).join("\n");
+    const now = new Date();
+    const archiveFile = `memory/archive/${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}.md`;
+    const archivePath = join(cwd, archiveFile);
+    await mkdir(dirname(archivePath), { recursive: true });
+    // Append to archive
+    let existing = "";
+    try {
+        existing = await readFile(archivePath, "utf-8");
+    }
+    catch {
+        // New archive file
+    }
+    const archiveEntry = `\n---\n_Archived: ${now.toISOString()}_\n\n${overflow}\n`;
+    await writeFile(archivePath, existing + archiveEntry, "utf-8");
+    // Try to git add the archive
+    try {
+        execSync(`git add "${archiveFile}"`, { cwd, stdio: "pipe" });
+    }
+    catch {
+        // Not in git, that's fine
+    }
+    return kept;
+}
+export function createMemoryTool(cwd) {
+    return {
+        name: "memory",
+        label: "memory",
+        description: "Git-backed memory. Use 'load' to read current memory, 'save' to update memory and commit to git. Each save creates a git commit, giving you full history of what you've remembered.",
+        parameters: memorySchema,
+        execute: async (_toolCallId, { action, content, message }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const config = await loadMemoryConfig(cwd);
+            const { path: memoryPath, maxLines } = getWorkingLayer(config);
+            const memoryFile = join(cwd, memoryPath);
+            if (action === "load") {
+                try {
+                    const text = await readFile(memoryFile, "utf-8");
+                    const trimmed = text.trim();
+                    if (!trimmed || trimmed === "# Memory") {
+                        return {
+                            content: [{ type: "text", text: "No memories yet." }],
+                            details: undefined,
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: trimmed }],
+                        details: undefined,
+                    };
+                }
+                catch {
+                    return {
+                        content: [{ type: "text", text: "No memories yet." }],
+                        details: undefined,
+                    };
+                }
+            }
+            // action === "save"
+            if (!content) {
+                throw new Error("content is required for save action");
+            }
+            const commitMsg = message || "Update memory";
+            // Apply max_lines archiving if configured
+            let finalContent = content;
+            if (maxLines) {
+                finalContent = await archiveOverflow(cwd, content, maxLines);
+            }
+            await mkdir(dirname(memoryFile), { recursive: true });
+            await writeFile(memoryFile, finalContent, "utf-8");
+            try {
+                execSync(`git add "${memoryPath}" && git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, {
+                    cwd,
+                    stdio: "pipe",
+                });
+            }
+            catch (err) {
+                const stderr = err.stderr?.toString() || "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Memory saved to ${memoryPath} but git commit failed: ${stderr.trim() || "unknown error"}. The file was still written.`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Memory saved and committed: "${commitMsg}"` }],
+                details: undefined,
+            };
+        },
+    };
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { readSchema } from "./shared.js";
+export declare function createReadTool(cwd: string): AgentTool<typeof readSchema>;

package/dist/tools/read.js

@@ -0,0 +1,46 @@
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { readSchema, MAX_LINES, paginateLines } from "./shared.js";
+function resolvePath(path, cwd) {
+    return path.startsWith("/") ? path : resolve(cwd, path);
+}
+function isBinary(buffer) {
+    // Check first 8KB for null bytes
+    const check = buffer.subarray(0, 8192);
+    for (let i = 0; i < check.length; i++) {
+        if (check[i] === 0)
+            return true;
+    }
+    return false;
+}
+export function createReadTool(cwd) {
+    return {
+        name: "read",
+        label: "read",
+        description: `Read the contents of a file. Output is limited to ${MAX_LINES} lines or ~100KB. Use offset/limit for large files.`,
+        parameters: readSchema,
+        execute: async (_toolCallId, { path, offset, limit }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const absolutePath = resolvePath(path, cwd);
+            const buffer = await readFile(absolutePath);
+            if (isBinary(buffer)) {
+                return {
+                    content: [{ type: "text", text: `[Binary file: ${path} (${buffer.length} bytes)]` }],
+                    details: undefined,
+                };
+            }
+            const text = buffer.toString("utf-8");
+            const page = paginateLines(text, offset, limit);
+            let result = page.text;
+            if (page.hasMore) {
+                const nextOffset = page.shownRange[1] + 1;
+                result += `\n\n[Showing lines ${page.shownRange[0]}-${page.shownRange[1]} of ${page.totalLines}. Use offset=${nextOffset} to continue.]`;
+            }
+            return {
+                content: [{ type: "text", text: result }],
+                details: undefined,
+            };
+        },
+    };
+}

package/dist/tools/sandbox-cli.d.ts

@@ -0,0 +1,4 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { SandboxContext } from "../sandbox.js";
+import { cliSchema } from "./shared.js";
+export declare function createSandboxCliTool(ctx: SandboxContext, defaultTimeout?: number): AgentTool<typeof cliSchema>;

package/dist/tools/sandbox-cli.js

@@ -0,0 +1,48 @@
+import { cliSchema, MAX_OUTPUT, DEFAULT_TIMEOUT, truncateOutput } from "./shared.js";
+export function createSandboxCliTool(ctx, defaultTimeout) {
+    const baseTimeout = defaultTimeout ?? DEFAULT_TIMEOUT;
+    return {
+        name: "cli",
+        label: "cli",
+        description: "Execute a shell command in the sandbox VM. Returns stdout and stderr combined. Output is truncated if it exceeds ~100KB. Default timeout is 120 seconds.",
+        parameters: cliSchema,
+        execute: async (_toolCallId, { command, timeout }, signal, onUpdate) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const timeoutSecs = timeout ?? baseTimeout;
+            let output = "";
+            const result = await ctx.gitMachine.run(command, {
+                cwd: ctx.repoPath,
+                timeout: timeoutSecs,
+                onStdout: (data) => {
+                    output += data;
+                    if (onUpdate && output.length <= MAX_OUTPUT) {
+                        onUpdate({
+                            content: [{ type: "text", text: output }],
+                            details: undefined,
+                        });
+                    }
+                },
+                onStderr: (data) => {
+                    output += data;
+                    if (onUpdate && output.length <= MAX_OUTPUT) {
+                        onUpdate({
+                            content: [{ type: "text", text: output }],
+                            details: undefined,
+                        });
+                    }
+                },
+            });
+            const exitCode = result?.exitCode ?? 0;
+            let text = truncateOutput(output) || "(no output)";
+            if (exitCode !== 0) {
+                text += `\n\nExit code: ${exitCode}`;
+                throw new Error(text);
+            }
+            return {
+                content: [{ type: "text", text }],
+                details: { exitCode },
+            };
+        },
+    };
+}

package/dist/tools/sandbox-memory.d.ts

@@ -0,0 +1,4 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { SandboxContext } from "../sandbox.js";
+import { memorySchema } from "./shared.js";
+export declare function createSandboxMemoryTool(ctx: SandboxContext): AgentTool<typeof memorySchema>;