gitclaw 0.3.0

package/dist/loader.js

@@ -0,0 +1,222 @@
+import { readFile, mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { execSync } from "child_process";
+import { getModel } from "@mariozechner/pi-ai";
+import yaml from "js-yaml";
+import { discoverSkills, formatSkillsForPrompt } from "./skills.js";
+import { loadKnowledge, formatKnowledgeForPrompt } from "./knowledge.js";
+import { discoverWorkflows, formatWorkflowsForPrompt } from "./workflows.js";
+import { loadEnvConfig } from "./config.js";
+import { discoverSubAgents, formatSubAgentsForPrompt } from "./agents.js";
+import { loadExamples, formatExamplesForPrompt } from "./examples.js";
+import { validateCompliance, loadComplianceContext } from "./compliance.js";
+async function readFileOr(path, fallback) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return fallback;
+    }
+}
+function parseModelString(modelStr) {
+    const colonIndex = modelStr.indexOf(":");
+    if (colonIndex === -1) {
+        throw new Error(`Invalid model format: "${modelStr}". Expected "provider:model" (e.g., "anthropic:claude-sonnet-4-5-20250929")`);
+    }
+    return {
+        provider: modelStr.slice(0, colonIndex),
+        modelId: modelStr.slice(colonIndex + 1),
+    };
+}
+async function ensureGitagentDir(agentDir) {
+    const gitagentDir = join(agentDir, ".gitagent");
+    await mkdir(gitagentDir, { recursive: true });
+    // Ensure .gitagent is in .gitignore
+    const gitignorePath = join(agentDir, ".gitignore");
+    try {
+        const gitignore = await readFile(gitignorePath, "utf-8");
+        if (!gitignore.includes(".gitagent")) {
+            await writeFile(gitignorePath, gitignore.trimEnd() + "\n.gitagent/\n", "utf-8");
+        }
+    }
+    catch {
+        // No .gitignore or can't read — that's fine
+    }
+    return gitagentDir;
+}
+async function writeSessionState(gitagentDir) {
+    const sessionId = randomUUID();
+    const state = {
+        session_id: sessionId,
+        started_at: new Date().toISOString(),
+    };
+    await writeFile(join(gitagentDir, "state.json"), JSON.stringify(state, null, 2), "utf-8");
+    return sessionId;
+}
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        if (result[key] &&
+            typeof result[key] === "object" &&
+            !Array.isArray(result[key]) &&
+            typeof override[key] === "object" &&
+            !Array.isArray(override[key])) {
+            result[key] = deepMerge(result[key], override[key]);
+        }
+        else {
+            result[key] = override[key];
+        }
+    }
+    return result;
+}
+async function resolveInheritance(manifest, agentDir, gitagentDir) {
+    if (!manifest.extends) {
+        return { manifest, parentRules: "" };
+    }
+    const depsDir = join(gitagentDir, "deps");
+    await mkdir(depsDir, { recursive: true });
+    // Clone parent into .gitagent/deps/
+    const parentName = manifest.extends.split("/").pop()?.replace(/\.git$/, "") || "parent";
+    const parentDir = join(depsDir, parentName);
+    try {
+        execSync(`git clone --depth 1 "${manifest.extends}" "${parentDir}" 2>/dev/null || true`, {
+            cwd: agentDir,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Clone failed, continue without parent
+        return { manifest, parentRules: "" };
+    }
+    // Load parent manifest
+    let parentManifest;
+    try {
+        const parentRaw = await readFile(join(parentDir, "agent.yaml"), "utf-8");
+        parentManifest = yaml.load(parentRaw);
+    }
+    catch {
+        return { manifest, parentRules: "" };
+    }
+    // Deep merge: child wins
+    const merged = deepMerge(parentManifest, manifest);
+    // Tools and skills: union, child shadows
+    if (parentManifest.tools && manifest.tools) {
+        const toolSet = new Set([...parentManifest.tools, ...manifest.tools]);
+        merged.tools = [...toolSet];
+    }
+    // Load parent RULES.md for appending (union)
+    const parentRules = await readFileOr(join(parentDir, "RULES.md"), "");
+    return { manifest: merged, parentRules };
+}
+async function resolveDependencies(manifest, agentDir, gitagentDir) {
+    if (!manifest.dependencies || manifest.dependencies.length === 0)
+        return;
+    const depsDir = join(gitagentDir, "deps");
+    await mkdir(depsDir, { recursive: true });
+    for (const dep of manifest.dependencies) {
+        const depDir = join(depsDir, dep.name);
+        try {
+            execSync(`git clone --depth 1 --branch "${dep.version}" "${dep.source}" "${depDir}" 2>/dev/null || true`, { cwd: agentDir, stdio: "pipe" });
+        }
+        catch {
+            // Clone failed, skip this dependency
+        }
+    }
+}
+export async function loadAgent(agentDir, modelFlag, envFlag) {
+    // Parse agent.yaml
+    const manifestRaw = await readFile(join(agentDir, "agent.yaml"), "utf-8");
+    let manifest = yaml.load(manifestRaw);
+    // Load environment config
+    const envConfig = await loadEnvConfig(agentDir, envFlag);
+    // Ensure .gitagent/ directory and write session state
+    const gitagentDir = await ensureGitagentDir(agentDir);
+    const sessionId = await writeSessionState(gitagentDir);
+    // Resolve inheritance (Phase 2.4)
+    let parentRules = "";
+    if (manifest.extends) {
+        const resolved = await resolveInheritance(manifest, agentDir, gitagentDir);
+        manifest = resolved.manifest;
+        parentRules = resolved.parentRules;
+    }
+    // Resolve dependencies (Phase 2.5)
+    await resolveDependencies(manifest, agentDir, gitagentDir);
+    // Validate compliance (Phase 3)
+    const complianceWarnings = validateCompliance(manifest);
+    // Read identity files
+    const soul = await readFileOr(join(agentDir, "SOUL.md"), "");
+    const rules = await readFileOr(join(agentDir, "RULES.md"), "");
+    const duties = await readFileOr(join(agentDir, "DUTIES.md"), "");
+    const agentsMd = await readFileOr(join(agentDir, "AGENTS.md"), "");
+    // Build system prompt
+    const parts = [];
+    parts.push(`# ${manifest.name} v${manifest.version}\n${manifest.description}`);
+    if (soul)
+        parts.push(soul);
+    if (rules)
+        parts.push(rules);
+    if (parentRules)
+        parts.push(parentRules); // Append parent rules (union)
+    if (duties)
+        parts.push(duties);
+    if (agentsMd)
+        parts.push(agentsMd);
+    parts.push(`# Memory\n\nYou have a memory file at memory/MEMORY.md. Use the \`memory\` tool to load and save memories. Each save creates a git commit, so your memory has full history. You can also use the \`cli\` tool to run git commands for deeper memory inspection (git log, git diff, git show).`);
+    // Discover and load knowledge
+    const knowledge = await loadKnowledge(agentDir);
+    const knowledgeBlock = formatKnowledgeForPrompt(knowledge);
+    if (knowledgeBlock)
+        parts.push(knowledgeBlock);
+    // Discover skills (filtered by manifest.skills if set)
+    let skills = await discoverSkills(agentDir);
+    if (manifest.skills && manifest.skills.length > 0) {
+        const allowed = new Set(manifest.skills);
+        skills = skills.filter((s) => allowed.has(s.name));
+    }
+    const skillsBlock = formatSkillsForPrompt(skills);
+    if (skillsBlock)
+        parts.push(skillsBlock);
+    // Discover workflows
+    const workflows = await discoverWorkflows(agentDir);
+    const workflowsBlock = formatWorkflowsForPrompt(workflows);
+    if (workflowsBlock)
+        parts.push(workflowsBlock);
+    // Discover sub-agents (Phase 2.1)
+    const subAgents = await discoverSubAgents(agentDir);
+    const subAgentsBlock = formatSubAgentsForPrompt(subAgents);
+    if (subAgentsBlock)
+        parts.push(subAgentsBlock);
+    // Load examples (Phase 2.3)
+    const examples = await loadExamples(agentDir);
+    const examplesBlock = formatExamplesForPrompt(examples);
+    if (examplesBlock)
+        parts.push(examplesBlock);
+    // Load compliance context (Phase 3)
+    const complianceBlock = await loadComplianceContext(agentDir);
+    if (complianceBlock)
+        parts.push(complianceBlock);
+    const systemPrompt = parts.join("\n\n");
+    // Resolve model — env config model_override > CLI flag > manifest preferred
+    const modelStr = envConfig.model_override || modelFlag || manifest.model.preferred;
+    if (!modelStr) {
+        throw new Error('No model configured. Either:\n  - Set model.preferred in agent.yaml (e.g., "anthropic:claude-sonnet-4-5-20250929")\n  - Pass --model provider:model on the command line');
+    }
+    const { provider, modelId } = parseModelString(modelStr);
+    const model = getModel(provider, modelId);
+    return {
+        systemPrompt,
+        manifest,
+        model,
+        skills,
+        knowledge,
+        workflows,
+        subAgents,
+        examples,
+        envConfig,
+        sessionId,
+        agentDir,
+        gitagentDir,
+        complianceWarnings,
+    };
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,28 @@
+export interface SandboxConfig {
+    provider: "e2b";
+    template?: string;
+    timeout?: number;
+    repository?: string;
+    token?: string;
+    session?: string;
+    autoCommit?: boolean;
+    envs?: Record<string, string>;
+}
+/**
+ * Wraps the gitmachine GitMachine + Machine instances.
+ * Types are `any` because gitmachine is an optional peer dependency
+ * loaded via dynamic import — we don't have compile-time types.
+ */
+export interface SandboxContext {
+    /** GitMachine instance (gitmachine) — provides run(), commit(), start(), stop() */
+    gitMachine: any;
+    /** Underlying Machine instance — provides readFile(), writeFile() */
+    machine: any;
+    /** Absolute path to the repo root inside the sandbox (e.g. /home/user/repo) */
+    repoPath: string;
+}
+/**
+ * Create a SandboxContext by dynamically importing gitmachine.
+ * Throws a clear error if gitmachine is not installed.
+ */
+export declare function createSandboxContext(config: SandboxConfig, dir: string): Promise<SandboxContext>;

package/dist/sandbox.js

@@ -0,0 +1,54 @@
+import { execSync } from "child_process";
+// ── Factory ─────────────────────────────────────────────────────────────
+function detectRepoUrl(dir) {
+    try {
+        return execSync("git remote get-url origin", { cwd: dir, stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create a SandboxContext by dynamically importing gitmachine.
+ * Throws a clear error if gitmachine is not installed.
+ */
+export async function createSandboxContext(config, dir) {
+    let gitmachine;
+    try {
+        // @ts-ignore — gitmachine is an optional peer dependency
+        gitmachine = await import("gitmachine");
+    }
+    catch {
+        throw new Error("Sandbox mode requires the 'gitmachine' package.\n" +
+            "Install it with: npm install gitmachine");
+    }
+    const token = config.token
+        || process.env.GITHUB_TOKEN
+        || process.env.GIT_TOKEN;
+    const repository = config.repository || detectRepoUrl(dir);
+    if (!repository) {
+        throw new Error("Sandbox mode requires a repository URL. Provide it via --sandbox config, " +
+            "or ensure the working directory has a git remote named 'origin'.");
+    }
+    const gitMachine = new gitmachine.GitMachine({
+        provider: config.provider,
+        template: config.template,
+        timeout: config.timeout,
+        repository,
+        token,
+        session: config.session,
+        autoCommit: config.autoCommit ?? true,
+        envs: config.envs,
+    });
+    // The repo path inside the sandbox is determined by gitmachine after start().
+    // Convention: /home/user/<repo-name>
+    const repoName = repository.split("/").pop()?.replace(/\.git$/, "") || "repo";
+    const repoPath = `/home/user/${repoName}`;
+    return {
+        gitMachine,
+        machine: gitMachine.machine,
+        repoPath,
+    };
+}

package/dist/sdk-hooks.d.ts

@@ -0,0 +1,8 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { GCHooks } from "./sdk-types.js";
+/**
+ * Wraps a tool's execute function with programmatic SDK hook callbacks.
+ * Mirrors the pattern in hooks.ts:wrapToolWithHooks() but uses in-process
+ * callbacks instead of spawning shell scripts.
+ */
+export declare function wrapToolWithProgrammaticHooks(tool: AgentTool<any>, hooks: GCHooks, sessionId: string, agentName: string): AgentTool<any>;

package/dist/sdk-hooks.js

@@ -0,0 +1,31 @@
+/**
+ * Wraps a tool's execute function with programmatic SDK hook callbacks.
+ * Mirrors the pattern in hooks.ts:wrapToolWithHooks() but uses in-process
+ * callbacks instead of spawning shell scripts.
+ */
+export function wrapToolWithProgrammaticHooks(tool, hooks, sessionId, agentName) {
+    if (!hooks.preToolUse)
+        return tool;
+    const originalExecute = tool.execute;
+    const preToolUse = hooks.preToolUse;
+    return {
+        ...tool,
+        execute: async (toolCallId, args, signal, onUpdate) => {
+            const ctx = {
+                sessionId,
+                agentName,
+                event: "PreToolUse",
+                toolName: tool.name,
+                args,
+            };
+            const result = await preToolUse(ctx);
+            if (result.action === "block") {
+                throw new Error(`Tool "${tool.name}" blocked by hook: ${result.reason || "no reason given"}`);
+            }
+            const finalArgs = result.action === "modify" && result.args
+                ? result.args
+                : args;
+            return originalExecute.call(tool, toolCallId, finalArgs, signal, onUpdate);
+        },
+    };
+}

package/dist/sdk-types.d.ts

@@ -0,0 +1,127 @@
+import type { AgentManifest } from "./loader.js";
+export type GCMessage = GCAssistantMessage | GCUserMessage | GCToolUseMessage | GCToolResultMessage | GCSystemMessage | GCStreamDelta;
+export interface GCAssistantMessage {
+    type: "assistant";
+    content: string;
+    thinking?: string;
+    model: string;
+    provider: string;
+    stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+    errorMessage?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        totalTokens: number;
+        costUsd: number;
+    };
+}
+export interface GCUserMessage {
+    type: "user";
+    content: string;
+}
+export interface GCToolUseMessage {
+    type: "tool_use";
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, any>;
+}
+export interface GCToolResultMessage {
+    type: "tool_result";
+    toolCallId: string;
+    toolName: string;
+    content: string;
+    isError: boolean;
+}
+export interface GCSystemMessage {
+    type: "system";
+    subtype: "session_start" | "session_end" | "hook_blocked" | "compliance_warning" | "error";
+    content: string;
+    metadata?: Record<string, any>;
+}
+export interface GCStreamDelta {
+    type: "delta";
+    deltaType: "text" | "thinking";
+    content: string;
+}
+export type GCHookEvent = "SessionStart" | "PreToolUse" | "PostResponse" | "OnError";
+export interface GCHookContext {
+    sessionId: string;
+    agentName: string;
+    event: GCHookEvent;
+}
+export interface GCPreToolUseContext extends GCHookContext {
+    event: "PreToolUse";
+    toolName: string;
+    args: Record<string, any>;
+}
+export interface GCHookResult {
+    action: "allow" | "block" | "modify";
+    reason?: string;
+    args?: Record<string, any>;
+}
+export interface GCHooks {
+    onSessionStart?: (ctx: GCHookContext) => Promise<GCHookResult> | GCHookResult;
+    preToolUse?: (ctx: GCPreToolUseContext) => Promise<GCHookResult> | GCHookResult;
+    postResponse?: (ctx: GCHookContext) => Promise<void> | void;
+    onError?: (ctx: GCHookContext & {
+        error: string;
+    }) => Promise<void> | void;
+}
+export interface GCToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, any>;
+    handler: (args: any, signal?: AbortSignal) => Promise<string | {
+        text: string;
+        details?: any;
+    }>;
+}
+export interface LocalRepoOptions {
+    url: string;
+    token: string;
+    dir?: string;
+    session?: string;
+}
+export interface SandboxOptions {
+    provider: "e2b";
+    template?: string;
+    timeout?: number;
+    repository?: string;
+    token?: string;
+    session?: string;
+    autoCommit?: boolean;
+    envs?: Record<string, string>;
+}
+export interface QueryOptions {
+    prompt: string | AsyncIterable<GCUserMessage>;
+    dir?: string;
+    model?: string;
+    env?: string;
+    systemPrompt?: string;
+    systemPromptSuffix?: string;
+    tools?: GCToolDefinition[];
+    replaceBuiltinTools?: boolean;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    repo?: LocalRepoOptions;
+    sandbox?: SandboxOptions | boolean;
+    hooks?: GCHooks;
+    maxTurns?: number;
+    abortController?: AbortController;
+    sessionId?: string;
+    constraints?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        topK?: number;
+    };
+}
+export interface Query extends AsyncGenerator<GCMessage, void, undefined> {
+    abort(): void;
+    steer(message: string): void;
+    sessionId(): string;
+    manifest(): AgentManifest;
+    messages(): GCMessage[];
+}

package/dist/sdk-types.js

@@ -0,0 +1 @@
+export {};

package/dist/sdk.d.ts

@@ -0,0 +1,6 @@
+import type { GCToolDefinition, Query, QueryOptions } from "./sdk-types.js";
+export declare function query(options: QueryOptions): Query;
+export declare function tool(name: string, description: string, inputSchema: Record<string, any>, handler: (args: any, signal?: AbortSignal) => Promise<string | {
+    text: string;
+    details?: any;
+}>): GCToolDefinition;