gitclaw 0.3.1 → 0.4.0

package/dist/tools/shared.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { StringEnum } from "@mariozechner/pi-ai";
+import { homedir } from "os";
 // ── Constants ───────────────────────────────────────────────────────────
 export const MAX_OUTPUT = 100_000; // ~100KB max output to send to LLM
 export const MAX_LINES = 2000;
@@ -26,6 +27,26 @@ export const memorySchema = Type.Object({
     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)" })),
 });
+export const taskTrackerSchema = Type.Object({
+    action: StringEnum(["begin", "update", "end", "list"], { description: "Action to perform" }),
+    objective: Type.Optional(Type.String({ description: "Task objective (required for begin)" })),
+    task_id: Type.Optional(Type.String({ description: "Task ID (required for update/end)" })),
+    step: Type.Optional(Type.String({ description: "Step description (for update)" })),
+    outcome: Type.Optional(StringEnum(["success", "failure", "partial"], { description: "Task outcome (for end)" })),
+    failure_reason: Type.Optional(Type.String({ description: "Why the task failed (for end+failure)" })),
+    skill_used: Type.Optional(Type.String({ description: "Name of skill used, if any (for end)" })),
+});
+export const capturePhotoSchema = Type.Object({
+    reason: Type.String({ description: "Why this moment is being captured (e.g. 'user celebrating project launch')" }),
+});
+export const skillLearnerSchema = Type.Object({
+    action: StringEnum(["evaluate", "crystallize", "status", "review", "update", "delete"], { description: "Action to perform" }),
+    task_id: Type.Optional(Type.String({ description: "Task ID (for evaluate/crystallize)" })),
+    skill_name: Type.Optional(Type.String({ description: "Skill name (for crystallize/update/delete)" })),
+    skill_description: Type.Optional(Type.String({ description: "Skill description (for crystallize)" })),
+    instructions: Type.Optional(Type.String({ description: "New instructions content (for update)" })),
+    override_heuristic: Type.Optional(Type.Boolean({ description: "Override skill-worthiness heuristic (for evaluate)" })),
+});
 // ── Shared helpers ──────────────────────────────────────────────────────
 /** Truncate output to MAX_OUTPUT, keeping the tail. */
 export function truncateOutput(text) {
@@ -63,6 +84,9 @@ export function paginateLines(text, offset, limit) {
 }
 /** Resolve a path relative to a sandbox repo root. */
 export function resolveSandboxPath(path, repoRoot) {
+    if (path.startsWith("~/") || path === "~") {
+        path = homedir() + path.slice(1);
+    }
     if (path.startsWith("/"))
         return path;
     return repoRoot.endsWith("/") ? repoRoot + path : repoRoot + "/" + path;

package/dist/tools/skill-learner.d.ts

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

package/dist/tools/skill-learner.js

@@ -0,0 +1,358 @@
+import { readFile, writeFile, mkdir, readdir, rm } from "fs/promises";
+import { join } from "path";
+import { execSync } from "child_process";
+import { skillLearnerSchema } from "./shared.js";
+import { loadSkillStats, isSkillFlagged } from "../learning/reinforcement.js";
+import yaml from "js-yaml";
+async function loadTasks(gitagentDir) {
+    const tasksFile = join(gitagentDir, "learning", "tasks.json");
+    try {
+        const raw = await readFile(tasksFile, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { tasks: [] };
+    }
+}
+function extractKeywords(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+}
+function jaccardSimilarity(a, b) {
+    const setA = new Set(a);
+    const setB = new Set(b);
+    const intersection = [...setA].filter((x) => setB.has(x)).length;
+    const union = new Set([...setA, ...setB]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+// Checks if a step looks project-specific (absolute paths, UUIDs, etc.)
+function isProjectSpecific(step) {
+    const patterns = [
+        /\/[a-zA-Z][\w/.-]{5,}/, // absolute-ish paths
+        /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i, // UUID
+        /[A-Z][a-z]+(?:[A-Z][a-z]+){2,}/, // PascalCase with 3+ parts (likely project-specific class)
+    ];
+    return patterns.some((p) => p.test(step));
+}
+async function getExistingSkillDescriptions(agentDir) {
+    const skillsDir = join(agentDir, "skills");
+    const result = [];
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillFile = join(skillsDir, entry.name, "SKILL.md");
+        try {
+            const content = await readFile(skillFile, "utf-8");
+            const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+            if (!fmMatch)
+                continue;
+            const fm = yaml.load(fmMatch[1]);
+            if (fm.description) {
+                result.push({
+                    name: fm.name,
+                    keywords: extractKeywords(fm.description),
+                });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return result;
+}
+function gitCommit(agentDir, files, message) {
+    try {
+        for (const f of files) {
+            execSync(`git add "${f}"`, { cwd: agentDir, stdio: "pipe" });
+        }
+        execSync(`git commit -m "${message.replace(/"/g, '\\"')}"`, {
+            cwd: agentDir,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Not fatal — file was still written
+    }
+}
+// ── Tool factory ────────────────────────────────────────────────────────
+export function createSkillLearnerTool(agentDir, gitagentDir) {
+    return {
+        name: "skill_learner",
+        label: "skill_learner",
+        description: "Learn from successful tasks. Use 'evaluate' to check if a completed task is worth saving as a skill, 'crystallize' to save it, 'status' to list all skills with confidence scores, 'review' to see flagged low-confidence skills, 'update' to modify a skill, 'delete' to remove one.",
+        parameters: skillLearnerSchema,
+        execute: async (_toolCallId, params, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            switch (params.action) {
+                case "evaluate": {
+                    if (!params.task_id)
+                        throw new Error("task_id is required for evaluate action");
+                    const store = await loadTasks(gitagentDir);
+                    const task = store.tasks.find((t) => t.id === params.task_id);
+                    if (!task)
+                        throw new Error(`Task not found: ${params.task_id}`);
+                    if (task.status !== "succeeded") {
+                        return {
+                            content: [{ type: "text", text: `Task ${params.task_id} did not succeed (status: ${task.status}). Only successful tasks can become skills.` }],
+                            details: undefined,
+                        };
+                    }
+                    // Skill-worthiness heuristic
+                    const checks = {
+                        multi_step: task.steps.length >= 3,
+                        non_trivial: task.steps.length >= 2,
+                        novel: true,
+                        generalizable: true,
+                    };
+                    // Check novelty: no existing skill with >0.5 Jaccard similarity
+                    const taskKeywords = extractKeywords(task.objective);
+                    const existingSkills = await getExistingSkillDescriptions(agentDir);
+                    for (const skill of existingSkills) {
+                        if (jaccardSimilarity(taskKeywords, skill.keywords) > 0.5) {
+                            checks.novel = false;
+                            break;
+                        }
+                    }
+                    // Check generalizability: <30% of steps are project-specific
+                    const specificSteps = task.steps.filter((s) => isProjectSpecific(s.description)).length;
+                    checks.generalizable = specificSteps / Math.max(task.steps.length, 1) < 0.3;
+                    const passCount = Object.values(checks).filter(Boolean).length;
+                    const worthy = params.override_heuristic || passCount >= 3 || (checks.multi_step && checks.novel);
+                    const reasons = [
+                        `Multi-step (${task.steps.length} steps): ${checks.multi_step ? "PASS" : "FAIL"}`,
+                        `Non-trivial: ${checks.non_trivial ? "PASS" : "FAIL"}`,
+                        `Novel: ${checks.novel ? "PASS" : "FAIL"}`,
+                        `Generalizable: ${checks.generalizable ? "PASS" : "FAIL"}`,
+                    ];
+                    if (worthy) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Task IS worthy of becoming a skill.\n\nChecks:\n${reasons.join("\n")}\n\nCall skill_learner action "crystallize" with this task_id, a skill_name (kebab-case), and a skill_description.`,
+                                }],
+                            details: { worthy: true, checks },
+                        };
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Task is NOT worthy of becoming a skill (${passCount}/4 checks passed).\n\nChecks:\n${reasons.join("\n")}`,
+                            }],
+                        details: { worthy: false, checks },
+                    };
+                }
+                case "crystallize": {
+                    if (!params.task_id)
+                        throw new Error("task_id is required for crystallize action");
+                    if (!params.skill_name)
+                        throw new Error("skill_name is required for crystallize action");
+                    if (!params.skill_description)
+                        throw new Error("skill_description is required for crystallize action");
+                    // Validate kebab-case
+                    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(params.skill_name)) {
+                        throw new Error("skill_name must be kebab-case (e.g., deploy-staging)");
+                    }
+                    const store = await loadTasks(gitagentDir);
+                    const task = store.tasks.find((t) => t.id === params.task_id);
+                    if (!task)
+                        throw new Error(`Task not found: ${params.task_id}`);
+                    // SUCCESS GATE
+                    if (task.outcome !== "success") {
+                        throw new Error(`Cannot crystallize failed task. Only successful tasks can become skills.`);
+                    }
+                    // Build SKILL.md
+                    const frontmatter = {
+                        name: params.skill_name,
+                        description: params.skill_description,
+                        learned_from: `task:${task.id}`,
+                        learned_at: new Date().toISOString(),
+                        confidence: 1.0,
+                        usage_count: 0,
+                        success_count: 0,
+                        failure_count: 0,
+                        negative_examples: [],
+                    };
+                    const stepsSection = task.steps
+                        .map((s, i) => `${i + 1}. ${s.description}`)
+                        .join("\n");
+                    // Collect negative examples from prior failed attempts with same objective
+                    const priorFailed = store.tasks.filter((t) => t.status === "failed" && t.objective === task.objective);
+                    let whatDidNotWork = "";
+                    if (priorFailed.length > 0) {
+                        const failureReasons = priorFailed
+                            .filter((t) => t.failure_reason)
+                            .map((t) => `- ${t.failure_reason}`)
+                            .join("\n");
+                        if (failureReasons) {
+                            whatDidNotWork = failureReasons;
+                        }
+                    }
+                    let body = `\n## Steps\n${stepsSection}\n\n## What Worked\nThis approach succeeded on attempt #${task.attempts}.\n`;
+                    if (whatDidNotWork) {
+                        body += `\n## What Did NOT Work\n${whatDidNotWork}\n`;
+                    }
+                    const content = `---\n${yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trimEnd()}\n---\n${body}`;
+                    // Write skill
+                    const skillDir = join(agentDir, "skills", params.skill_name);
+                    await mkdir(skillDir, { recursive: true });
+                    const skillFile = join(skillDir, "SKILL.md");
+                    await writeFile(skillFile, content, "utf-8");
+                    // Git commit
+                    gitCommit(agentDir, [`skills/${params.skill_name}/SKILL.md`], `Learn skill: ${params.skill_name}`);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Skill "${params.skill_name}" crystallized and committed.\nPath: skills/${params.skill_name}/SKILL.md\nConfidence: 1.0\n\nThe skill is now available via /skill:${params.skill_name}`,
+                            }],
+                        details: { skill_name: params.skill_name, path: skillFile },
+                    };
+                }
+                case "status": {
+                    const skillsDir = join(agentDir, "skills");
+                    let entries;
+                    try {
+                        entries = await readdir(skillsDir, { withFileTypes: true });
+                    }
+                    catch {
+                        return {
+                            content: [{ type: "text", text: "No skills directory found." }],
+                            details: undefined,
+                        };
+                    }
+                    const skills = [];
+                    for (const entry of entries) {
+                        if (!entry.isDirectory())
+                            continue;
+                        const dir = join(skillsDir, entry.name);
+                        const stats = await loadSkillStats(dir);
+                        // Only include learned skills (those with stats fields)
+                        skills.push({
+                            name: entry.name,
+                            confidence: stats.confidence,
+                            usage: stats.usage_count,
+                            ratio: `${stats.success_count}/${stats.success_count + stats.failure_count}`,
+                        });
+                    }
+                    if (skills.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No skills found." }],
+                            details: undefined,
+                        };
+                    }
+                    const lines = skills.map((s) => `  ${s.name}: confidence=${s.confidence}, usage=${s.usage}, success_ratio=${s.ratio}`);
+                    return {
+                        content: [{ type: "text", text: `Skills:\n${lines.join("\n")}` }],
+                        details: { skills },
+                    };
+                }
+                case "review": {
+                    const skillsDir = join(agentDir, "skills");
+                    let entries;
+                    try {
+                        entries = await readdir(skillsDir, { withFileTypes: true });
+                    }
+                    catch {
+                        return {
+                            content: [{ type: "text", text: "No skills directory found." }],
+                            details: undefined,
+                        };
+                    }
+                    const flagged = [];
+                    for (const entry of entries) {
+                        if (!entry.isDirectory())
+                            continue;
+                        const dir = join(skillsDir, entry.name);
+                        const stats = await loadSkillStats(dir);
+                        if (isSkillFlagged(stats)) {
+                            flagged.push({
+                                name: entry.name,
+                                confidence: stats.confidence,
+                                negatives: stats.negative_examples,
+                            });
+                        }
+                    }
+                    if (flagged.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No flagged skills (all confidence >= 0.4)." }],
+                            details: undefined,
+                        };
+                    }
+                    const lines = flagged.map((s) => {
+                        let line = `  ${s.name}: confidence=${s.confidence}`;
+                        if (s.negatives.length > 0) {
+                            line += `\n    Failures: ${s.negatives.join("; ")}`;
+                        }
+                        return line;
+                    });
+                    return {
+                        content: [{ type: "text", text: `Flagged skills (confidence < 0.4):\n${lines.join("\n")}\n\nConsider updating or deleting these skills.` }],
+                        details: { flagged },
+                    };
+                }
+                case "update": {
+                    if (!params.skill_name)
+                        throw new Error("skill_name is required for update action");
+                    if (!params.instructions)
+                        throw new Error("instructions is required for update action");
+                    const skillFile = join(agentDir, "skills", params.skill_name, "SKILL.md");
+                    let content;
+                    try {
+                        content = await readFile(skillFile, "utf-8");
+                    }
+                    catch {
+                        throw new Error(`Skill not found: ${params.skill_name}`);
+                    }
+                    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+                    if (!fmMatch)
+                        throw new Error("Invalid SKILL.md format");
+                    const frontmatter = yaml.load(fmMatch[1]);
+                    const yamlStr = yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trimEnd();
+                    const updated = `---\n${yamlStr}\n---\n${params.instructions}\n`;
+                    await writeFile(skillFile, updated, "utf-8");
+                    gitCommit(agentDir, [`skills/${params.skill_name}/SKILL.md`], `Update skill: ${params.skill_name}`);
+                    return {
+                        content: [{ type: "text", text: `Skill "${params.skill_name}" updated and committed.` }],
+                        details: undefined,
+                    };
+                }
+                case "delete": {
+                    if (!params.skill_name)
+                        throw new Error("skill_name is required for delete action");
+                    const skillDir = join(agentDir, "skills", params.skill_name);
+                    try {
+                        await rm(skillDir, { recursive: true });
+                    }
+                    catch {
+                        throw new Error(`Skill not found: ${params.skill_name}`);
+                    }
+                    try {
+                        execSync(`git add -A && git commit -m "Delete skill: ${params.skill_name.replace(/"/g, '\\"')}"`, {
+                            cwd: agentDir,
+                            stdio: "pipe",
+                        });
+                    }
+                    catch {
+                        // Not fatal
+                    }
+                    return {
+                        content: [{ type: "text", text: `Skill "${params.skill_name}" deleted.` }],
+                        details: undefined,
+                    };
+                }
+                default:
+                    throw new Error(`Unknown action: ${params.action}`);
+            }
+        },
+    };
+}

package/dist/tools/task-tracker.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { taskTrackerSchema } from "./shared.js";
+interface TaskStep {
+    description: string;
+    timestamp: string;
+}
+export interface TaskRecord {
+    id: string;
+    objective: string;
+    steps: TaskStep[];
+    attempts: number;
+    status: "active" | "succeeded" | "failed";
+    outcome?: "success" | "failure" | "partial";
+    failure_reason?: string;
+    skill_used?: string;
+    started_at: string;
+    ended_at?: string;
+}
+export declare function createTaskTrackerTool(agentDir: string, gitagentDir: string): AgentTool<typeof taskTrackerSchema>;
+export {};