gitclaw 0.3.0

package/dist/tools/sandbox-memory.js

@@ -0,0 +1,117 @@
+import { memorySchema, DEFAULT_MEMORY_PATH, resolveSandboxPath } from "./shared.js";
+import yaml from "js-yaml";
+async function loadMemoryConfig(ctx) {
+    try {
+        const raw = await ctx.machine.readFile(resolveSandboxPath("memory/memory.yaml", ctx.repoPath));
+        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(ctx, content, maxLines) {
+    const lines = content.split("\n");
+    if (lines.length <= maxLines)
+        return content;
+    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 = resolveSandboxPath(archiveFile, ctx.repoPath);
+    // Ensure archive directory exists
+    await ctx.gitMachine.run(`mkdir -p "${archivePath.substring(0, archivePath.lastIndexOf("/"))}"`, {
+        cwd: ctx.repoPath,
+    });
+    // Append to archive
+    let existing = "";
+    try {
+        existing = await ctx.machine.readFile(archivePath);
+    }
+    catch {
+        // New archive file
+    }
+    const archiveEntry = `\n---\n_Archived: ${now.toISOString()}_\n\n${overflow}\n`;
+    await ctx.machine.writeFile(archivePath, existing + archiveEntry);
+    return kept;
+}
+export function createSandboxMemoryTool(ctx) {
+    return {
+        name: "memory",
+        label: "memory",
+        description: "Git-backed memory in the sandbox VM. Use 'load' to read current memory, 'save' to update memory and commit to git. Each save creates a git commit, giving you full history.",
+        parameters: memorySchema,
+        execute: async (_toolCallId, { action, content, message }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const config = await loadMemoryConfig(ctx);
+            const { path: memoryPath, maxLines } = getWorkingLayer(config);
+            const memoryFile = resolveSandboxPath(memoryPath, ctx.repoPath);
+            if (action === "load") {
+                try {
+                    const text = await ctx.machine.readFile(memoryFile);
+                    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";
+            let finalContent = content;
+            if (maxLines) {
+                finalContent = await archiveOverflow(ctx, content, maxLines);
+            }
+            // Ensure parent directory exists
+            const dir = memoryFile.substring(0, memoryFile.lastIndexOf("/"));
+            if (dir) {
+                await ctx.gitMachine.run(`mkdir -p "${dir}"`, { cwd: ctx.repoPath });
+            }
+            await ctx.machine.writeFile(memoryFile, finalContent);
+            try {
+                await ctx.gitMachine.commit(commitMsg);
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Memory saved to ${memoryPath} but git commit failed: ${err.message || "unknown error"}. The file was still written.`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Memory saved and committed: "${commitMsg}"` }],
+                details: undefined,
+            };
+        },
+    };
+}

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

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

package/dist/tools/sandbox-read.js

@@ -0,0 +1,25 @@
+import { readSchema, paginateLines, resolveSandboxPath } from "./shared.js";
+export function createSandboxReadTool(ctx) {
+    return {
+        name: "read",
+        label: "read",
+        description: "Read the contents of a file in the sandbox VM. Output is limited to 2000 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 sandboxPath = resolveSandboxPath(path, ctx.repoPath);
+            const text = await ctx.machine.readFile(sandboxPath);
+            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-write.d.ts

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

package/dist/tools/sandbox-write.js

@@ -0,0 +1,26 @@
+import { writeSchema, resolveSandboxPath } from "./shared.js";
+export function createSandboxWriteTool(ctx) {
+    return {
+        name: "write",
+        label: "write",
+        description: "Write content to a file in the sandbox VM. Creates the file if it doesn't exist, overwrites if it does. Parent directories are created automatically.",
+        parameters: writeSchema,
+        execute: async (_toolCallId, { path, content, createDirs }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const sandboxPath = resolveSandboxPath(path, ctx.repoPath);
+            if (createDirs !== false) {
+                const dir = sandboxPath.substring(0, sandboxPath.lastIndexOf("/"));
+                if (dir) {
+                    await ctx.gitMachine.run(`mkdir -p "${dir}"`, { cwd: ctx.repoPath });
+                }
+            }
+            await ctx.machine.writeFile(sandboxPath, content);
+            const bytes = Buffer.byteLength(content, "utf-8");
+            return {
+                content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }],
+                details: undefined,
+            };
+        },
+    };
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,38 @@
+export declare const MAX_OUTPUT = 100000;
+export declare const MAX_LINES = 2000;
+export declare const MAX_BYTES = 100000;
+export declare const DEFAULT_TIMEOUT = 120;
+export declare const DEFAULT_MEMORY_PATH = "memory/MEMORY.md";
+export declare const cliSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare const readSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare const writeSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    content: import("@sinclair/typebox").TString;
+    createDirs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export declare const memorySchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnsafe<string>;
+    content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    message: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Truncate output to MAX_OUTPUT, keeping the tail. */
+export declare function truncateOutput(text: string): string;
+/**
+ * Paginate text by lines with offset (1-indexed) and limit.
+ * Returns { text, hasMore, shownRange, totalLines }.
+ */
+export declare function paginateLines(text: string, offset?: number, limit?: number): {
+    text: string;
+    hasMore: boolean;
+    shownRange: [number, number];
+    totalLines: number;
+};
+/** Resolve a path relative to a sandbox repo root. */
+export declare function resolveSandboxPath(path: string, repoRoot: string): string;

package/dist/tools/shared.js

@@ -0,0 +1,69 @@
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+// ── Constants ───────────────────────────────────────────────────────────
+export const MAX_OUTPUT = 100_000; // ~100KB max output to send to LLM
+export const MAX_LINES = 2000;
+export const MAX_BYTES = 100_000;
+export const DEFAULT_TIMEOUT = 120;
+export const DEFAULT_MEMORY_PATH = "memory/MEMORY.md";
+// ── Schemas ─────────────────────────────────────────────────────────────
+export const cliSchema = Type.Object({
+    command: Type.String({ description: "Shell command to execute" }),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 120)" })),
+});
+export const readSchema = Type.Object({
+    path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+    offset: Type.Optional(Type.Number({ description: "Line number to start from (1-indexed)" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+export const writeSchema = Type.Object({
+    path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+    content: Type.String({ description: "Content to write to the file" }),
+    createDirs: Type.Optional(Type.Boolean({ description: "Create parent directories if needed (default: true)" })),
+});
+export const memorySchema = Type.Object({
+    action: StringEnum(["load", "save"], { description: "Whether to load or save memory" }),
+    content: Type.Optional(Type.String({ description: "Memory content to save (required for save)" })),
+    message: Type.Optional(Type.String({ description: "Commit message describing why this memory changed (required for save)" })),
+});
+// ── Shared helpers ──────────────────────────────────────────────────────
+/** Truncate output to MAX_OUTPUT, keeping the tail. */
+export function truncateOutput(text) {
+    if (text.length > MAX_OUTPUT) {
+        return `[output truncated, showing last ~100KB]\n${text.slice(-MAX_OUTPUT)}`;
+    }
+    return text;
+}
+/**
+ * Paginate text by lines with offset (1-indexed) and limit.
+ * Returns { text, hasMore, shownRange, totalLines }.
+ */
+export function paginateLines(text, offset, limit) {
+    const allLines = text.split("\n");
+    const totalLines = allLines.length;
+    const startLine = offset ? Math.max(0, offset - 1) : 0;
+    if (startLine >= totalLines) {
+        throw new Error(`Offset ${offset} is beyond end of file (${totalLines} lines)`);
+    }
+    const maxLines = limit ?? MAX_LINES;
+    const endLine = Math.min(startLine + maxLines, totalLines);
+    let selected = allLines.slice(startLine, endLine).join("\n");
+    let truncatedByBytes = false;
+    if (Buffer.byteLength(selected, "utf-8") > MAX_BYTES) {
+        selected = selected.slice(0, MAX_BYTES);
+        truncatedByBytes = true;
+    }
+    const hasMore = endLine < totalLines || truncatedByBytes;
+    return {
+        text: selected,
+        hasMore,
+        shownRange: [startLine + 1, endLine],
+        totalLines,
+    };
+}
+/** Resolve a path relative to a sandbox repo root. */
+export function resolveSandboxPath(path, repoRoot) {
+    if (path.startsWith("/"))
+        return path;
+    return repoRoot.endsWith("/") ? repoRoot + path : repoRoot + "/" + path;
+}

package/dist/tools/write.d.ts

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

package/dist/tools/write.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { writeSchema } from "./shared.js";
+function resolvePath(path, cwd) {
+    return path.startsWith("/") ? path : resolve(cwd, path);
+}
+export function createWriteTool(cwd) {
+    return {
+        name: "write",
+        label: "write",
+        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Parent directories are created automatically.",
+        parameters: writeSchema,
+        execute: async (_toolCallId, { path, content, createDirs }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const absolutePath = resolvePath(path, cwd);
+            if (createDirs !== false) {
+                await mkdir(dirname(absolutePath), { recursive: true });
+            }
+            await writeFile(absolutePath, content, "utf-8");
+            const bytes = Buffer.byteLength(content, "utf-8");
+            return {
+                content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }],
+                details: undefined,
+            };
+        },
+    };
+}

package/dist/workflows.d.ts

@@ -0,0 +1,8 @@
+export interface WorkflowMetadata {
+    name: string;
+    description: string;
+    filePath: string;
+    format: "yaml" | "markdown";
+}
+export declare function discoverWorkflows(agentDir: string): Promise<WorkflowMetadata[]>;
+export declare function formatWorkflowsForPrompt(workflows: WorkflowMetadata[]): string;

package/dist/workflows.js

@@ -0,0 +1,81 @@
+import { readFile, readdir, stat } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+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] };
+}
+export async function discoverWorkflows(agentDir) {
+    const workflowsDir = join(agentDir, "workflows");
+    try {
+        const s = await stat(workflowsDir);
+        if (!s.isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(workflowsDir);
+    const workflows = [];
+    for (const entry of entries) {
+        const filePath = join(workflowsDir, entry);
+        const s = await stat(filePath);
+        if (!s.isFile())
+            continue;
+        if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+            try {
+                const raw = await readFile(filePath, "utf-8");
+                const data = yaml.load(raw);
+                if (data?.name && data?.description) {
+                    workflows.push({
+                        name: data.name,
+                        description: data.description,
+                        filePath: `workflows/${entry}`,
+                        format: "yaml",
+                    });
+                }
+            }
+            catch {
+                // Skip invalid YAML
+            }
+        }
+        else if (entry.endsWith(".md")) {
+            try {
+                const raw = await readFile(filePath, "utf-8");
+                const { frontmatter } = parseFrontmatter(raw);
+                const name = frontmatter.name || entry.replace(/\.md$/, "");
+                const description = frontmatter.description || "";
+                if (description) {
+                    workflows.push({
+                        name,
+                        description,
+                        filePath: `workflows/${entry}`,
+                        format: "markdown",
+                    });
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+    }
+    return workflows.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function formatWorkflowsForPrompt(workflows) {
+    if (workflows.length === 0)
+        return "";
+    const entries = workflows
+        .map((w) => `<workflow>\n<name>${w.name}</name>\n<description>${w.description}</description>\n<path>${w.filePath}</path>\n</workflow>`)
+        .join("\n");
+    return `# Workflows
+
+<available_workflows>
+${entries}
+</available_workflows>
+
+Use the \`read\` tool to load a workflow's full definition when you need to follow it.`;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "gitclaw",
+  "version": "0.3.0",
+  "description": "A universal git-native agent powered by pi-agent-core",
+  "author": "shreyaskapale",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-gitagent/gitclaw"
+  },
+  "homepage": "https://github.com/open-gitagent/gitclaw",
+  "keywords": ["ai", "agent", "git", "cli", "sdk", "llm"],
+  "type": "module",
+  "files": ["dist", "README.md"],
+  "main": "./dist/exports.js",
+  "types": "./dist/exports.d.ts",
+  "bin": {
+    "gitclaw": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/exports.js",
+      "types": "./dist/exports.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "node --test test/*.test.ts --experimental-strip-types"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "^0.55.4",
+    "@mariozechner/pi-agent-core": "^0.55.4",
+    "@sinclair/typebox": "^0.34.41",
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "gitmachine": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "gitmachine": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}