gitclaw 0.3.0

package/dist/compliance.js

@@ -0,0 +1,108 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+/**
+ * Validate compliance section of agent manifest against spec rules.
+ */
+export function validateCompliance(manifest) {
+    const warnings = [];
+    const compliance = manifest.compliance;
+    if (!compliance)
+        return warnings;
+    // Rule: High/critical risk agents should have human_in_the_loop
+    if ((compliance.risk_level === "high" || compliance.risk_level === "critical") &&
+        !compliance.human_in_the_loop) {
+        warnings.push({
+            rule: "high_risk_hitl",
+            message: `Agent with risk_level "${compliance.risk_level}" should have human_in_the_loop enabled`,
+            severity: "warning",
+        });
+    }
+    // Rule: Critical risk agents must have audit logging
+    if (compliance.risk_level === "critical" && !compliance.recordkeeping?.audit_logging) {
+        warnings.push({
+            rule: "critical_audit",
+            message: "Critical risk agents must have recordkeeping.audit_logging enabled",
+            severity: "error",
+        });
+    }
+    // Rule: If regulatory frameworks specified, recordkeeping should exist
+    if (compliance.regulatory_frameworks &&
+        compliance.regulatory_frameworks.length > 0 &&
+        !compliance.recordkeeping) {
+        warnings.push({
+            rule: "regulatory_recordkeeping",
+            message: "Agents with regulatory frameworks should have recordkeeping configured",
+            severity: "warning",
+        });
+    }
+    // Rule: Review required for high/critical risk
+    if ((compliance.risk_level === "high" || compliance.risk_level === "critical") &&
+        !compliance.review) {
+        warnings.push({
+            rule: "high_risk_review",
+            message: `Agent with risk_level "${compliance.risk_level}" should have review configuration`,
+            severity: "warning",
+        });
+    }
+    // Rule: Audit logging requires retention policy
+    if (compliance.recordkeeping?.audit_logging && !compliance.recordkeeping?.retention_days) {
+        warnings.push({
+            rule: "audit_retention",
+            message: "Audit logging enabled but no retention_days specified",
+            severity: "warning",
+        });
+    }
+    // Rule: Data classification should be specified for regulated agents
+    if (compliance.regulatory_frameworks && !compliance.data_classification) {
+        warnings.push({
+            rule: "data_classification",
+            message: "Regulated agents should specify data_classification",
+            severity: "warning",
+        });
+    }
+    return warnings;
+}
+/**
+ * Load compliance directory files and format summary for system prompt.
+ */
+export async function loadComplianceContext(agentDir) {
+    const complianceDir = join(agentDir, "compliance");
+    const parts = [];
+    // Load regulatory map
+    try {
+        const raw = await readFile(join(complianceDir, "regulatory-map.yaml"), "utf-8");
+        const map = yaml.load(raw);
+        if (map?.frameworks) {
+            const frameworks = Object.keys(map.frameworks).join(", ");
+            parts.push(`Regulatory frameworks: ${frameworks}`);
+        }
+    }
+    catch {
+        // No regulatory map
+    }
+    // Load validation schedule
+    try {
+        const raw = await readFile(join(complianceDir, "validation-schedule.yaml"), "utf-8");
+        const schedule = yaml.load(raw);
+        if (schedule?.checks && schedule.checks.length > 0) {
+            const checkList = schedule.checks
+                .map((c) => `- ${c.name} (${c.frequency})${c.description ? `: ${c.description}` : ""}`)
+                .join("\n");
+            parts.push(`Validation schedule:\n${checkList}`);
+        }
+    }
+    catch {
+        // No validation schedule
+    }
+    if (parts.length === 0)
+        return "";
+    return `# Compliance\n\n${parts.join("\n\n")}`;
+}
+export function formatComplianceWarnings(warnings) {
+    if (warnings.length === 0)
+        return "";
+    return warnings
+        .map((w) => `  ${w.severity === "error" ? "✗" : "⚠"} [${w.rule}] ${w.message}`)
+        .join("\n");
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface EnvConfig {
+    log_level?: string;
+    model_override?: string;
+    [key: string]: any;
+}
+/**
+ * Load environment configuration.
+ * Loads config/default.yaml, then merges config/<env>.yaml on top.
+ * Env is determined by --env flag or GITCLAW_ENV environment variable.
+ */
+export declare function loadEnvConfig(agentDir: string, env?: string): Promise<EnvConfig>;

package/dist/config.js

@@ -0,0 +1,43 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+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 loadYamlFile(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        return yaml.load(raw) || {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Load environment configuration.
+ * Loads config/default.yaml, then merges config/<env>.yaml on top.
+ * Env is determined by --env flag or GITCLAW_ENV environment variable.
+ */
+export async function loadEnvConfig(agentDir, env) {
+    const configDir = join(agentDir, "config");
+    const envName = env || process.env.GITCLAW_ENV;
+    const base = await loadYamlFile(join(configDir, "default.yaml"));
+    if (envName) {
+        const envOverride = await loadYamlFile(join(configDir, `${envName}.yaml`));
+        return deepMerge(base, envOverride);
+    }
+    return base;
+}

package/dist/examples.d.ts

@@ -0,0 +1,6 @@
+export interface ExampleEntry {
+    name: string;
+    content: string;
+}
+export declare function loadExamples(agentDir: string): Promise<ExampleEntry[]>;
+export declare function formatExamplesForPrompt(examples: ExampleEntry[]): string;

package/dist/examples.js

@@ -0,0 +1,40 @@
+import { readFile, readdir, stat } from "fs/promises";
+import { join } from "path";
+export async function loadExamples(agentDir) {
+    const examplesDir = join(agentDir, "examples");
+    try {
+        const s = await stat(examplesDir);
+        if (!s.isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(examplesDir);
+    const examples = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        try {
+            const content = await readFile(join(examplesDir, entry), "utf-8");
+            const name = entry.replace(/\.md$/, "");
+            examples.push({ name, content: content.trim() });
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return examples.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function formatExamplesForPrompt(examples) {
+    if (examples.length === 0)
+        return "";
+    const blocks = examples
+        .map((e) => `<example name="${e.name}">\n${e.content}\n</example>`)
+        .join("\n\n");
+    return `# Examples
+
+<examples>
+${blocks}
+</examples>`;
+}

package/dist/exports.d.ts

@@ -0,0 +1,13 @@
+export { query, tool } from "./sdk.js";
+export type { Query, QueryOptions, LocalRepoOptions, SandboxOptions, GCMessage, GCAssistantMessage, GCUserMessage, GCToolUseMessage, GCToolResultMessage, GCSystemMessage, GCStreamDelta, GCToolDefinition, GCHooks, GCHookResult, GCPreToolUseContext, GCHookContext, } from "./sdk-types.js";
+export type { AgentManifest, LoadedAgent } from "./loader.js";
+export type { SkillMetadata } from "./skills.js";
+export type { WorkflowMetadata } from "./workflows.js";
+export type { SubAgentMetadata } from "./agents.js";
+export type { ComplianceWarning } from "./compliance.js";
+export type { EnvConfig } from "./config.js";
+export type { SandboxConfig, SandboxContext } from "./sandbox.js";
+export { createSandboxContext } from "./sandbox.js";
+export type { LocalSession } from "./session.js";
+export { initLocalSession } from "./session.js";
+export { loadAgent } from "./loader.js";

package/dist/exports.js

@@ -0,0 +1,6 @@
+// SDK core
+export { query, tool } from "./sdk.js";
+export { createSandboxContext } from "./sandbox.js";
+export { initLocalSession } from "./session.js";
+// Loader (escape hatch)
+export { loadAgent } from "./loader.js";

package/dist/hooks.d.ts

@@ -0,0 +1,24 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+export interface HookDefinition {
+    script: string;
+    description?: string;
+}
+export interface HooksConfig {
+    hooks: {
+        on_session_start?: HookDefinition[];
+        pre_tool_use?: HookDefinition[];
+        post_response?: HookDefinition[];
+        on_error?: HookDefinition[];
+    };
+}
+export interface HookResult {
+    action: "allow" | "block" | "modify";
+    reason?: string;
+    args?: Record<string, any>;
+}
+export declare function loadHooksConfig(agentDir: string): Promise<HooksConfig | null>;
+export declare function runHooks(hooks: HookDefinition[] | undefined, agentDir: string, input: Record<string, any>): Promise<HookResult>;
+/**
+ * Wraps a tool's execute function with pre_tool_use hook support.
+ */
+export declare function wrapToolWithHooks<T extends AgentTool<any>>(tool: T, hooksConfig: HooksConfig, agentDir: string, sessionId: string): T;

package/dist/hooks.js

@@ -0,0 +1,108 @@
+import { spawn } from "child_process";
+import { readFile } from "fs/promises";
+import { join } from "path";
+import yaml from "js-yaml";
+export async function loadHooksConfig(agentDir) {
+    const hooksPath = join(agentDir, "hooks", "hooks.yaml");
+    try {
+        const raw = await readFile(hooksPath, "utf-8");
+        const config = yaml.load(raw);
+        if (!config?.hooks)
+            return null;
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+async function executeHook(hook, agentDir, input) {
+    return new Promise((resolve, reject) => {
+        const scriptPath = join(agentDir, "hooks", hook.script);
+        const child = spawn("sh", [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");
+        });
+        child.stdin.write(JSON.stringify(input));
+        child.stdin.end();
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error(`Hook "${hook.script}" timed out after 10s`));
+        }, 10_000);
+        child.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`Hook "${hook.script}" failed to start: ${err.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                reject(new Error(`Hook "${hook.script}" exited with code ${code}: ${stderr.trim()}`));
+                return;
+            }
+            try {
+                const result = JSON.parse(stdout.trim());
+                resolve(result);
+            }
+            catch {
+                // If hook doesn't return JSON, treat as allow
+                resolve({ action: "allow" });
+            }
+        });
+    });
+}
+export async function runHooks(hooks, agentDir, input) {
+    if (!hooks || hooks.length === 0) {
+        return { action: "allow" };
+    }
+    for (const hook of hooks) {
+        try {
+            const result = await executeHook(hook, agentDir, input);
+            if (result.action === "block") {
+                return result;
+            }
+            if (result.action === "modify") {
+                return result;
+            }
+        }
+        catch (err) {
+            console.error(`Hook error: ${err.message}`);
+            // Hook errors don't block execution by default
+        }
+    }
+    return { action: "allow" };
+}
+/**
+ * Wraps a tool's execute function with pre_tool_use hook support.
+ */
+export function wrapToolWithHooks(tool, hooksConfig, agentDir, sessionId) {
+    const preToolHooks = hooksConfig.hooks.pre_tool_use;
+    if (!preToolHooks || preToolHooks.length === 0)
+        return tool;
+    const originalExecute = tool.execute;
+    const wrappedTool = {
+        ...tool,
+        execute: async (toolCallId, args, signal, onUpdate) => {
+            const hookInput = {
+                event: "pre_tool_use",
+                session_id: sessionId,
+                tool: tool.name,
+                args,
+            };
+            const result = await runHooks(preToolHooks, agentDir, hookInput);
+            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);
+        },
+    };
+    return wrappedTool;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};