gitclaw 0.3.0 → 0.4.0

package/dist/skills.js

@@ -27,9 +27,13 @@ export async function discoverSkills(agentDir) {
     const entries = await readdir(skillsDir, { withFileTypes: true });
     const skills = [];
     for (const entry of entries) {
-        if (!entry.isDirectory())
+        // Accept both real directories and symlinks pointing to directories
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
             continue;
         const skillDir = join(skillsDir, entry.name);
+        // For symlinks, verify the target is actually a directory
+        if (entry.isSymbolicLink() && !(await dirExists(skillDir)))
+            continue;
         const skillFile = join(skillDir, "SKILL.md");
         let content;
         try {
@@ -53,12 +57,22 @@ export async function discoverSkills(agentDir) {
             console.warn(`Skipping skill "${entry.name}": name must be kebab-case`);
             continue;
         }
-        skills.push({
+        const meta = {
             name,
             description,
             directory: skillDir,
             filePath: skillFile,
-        });
+        };
+        // Parse optional learning fields
+        if (typeof frontmatter.confidence === "number")
+            meta.confidence = frontmatter.confidence;
+        if (typeof frontmatter.usage_count === "number")
+            meta.usage_count = frontmatter.usage_count;
+        if (typeof frontmatter.success_count === "number")
+            meta.success_count = frontmatter.success_count;
+        if (typeof frontmatter.failure_count === "number")
+            meta.failure_count = frontmatter.failure_count;
+        skills.push(meta);
     }
     return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -76,15 +90,47 @@ 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>`)
+        .map((s) => {
+        let entry = `<skill>\n<name>${s.name}</name>\n<description>${s.description}</description>`;
+        entry += `\n<location>skills/${s.name}/SKILL.md</location>`;
+        if (s.confidence !== undefined) {
+            entry += `\n<confidence>${s.confidence}</confidence>`;
+        }
+        entry += "\n</skill>";
+        return entry;
+    })
         .join("\n");
-    return `# Skills
+    return `# Skills — FIRST PRIORITY (MANDATORY)
+
+CRITICAL: You have installed skills that provide specialized capabilities.
+Before attempting ANY task — simple or complex — you MUST check if an installed skill handles it.
+
+## Rules (MUST follow in order)
+1. ALWAYS scan the skill list below BEFORE taking ANY action on a user request
+2. If a skill's description matches or partially matches the task, you MUST load its full
+   instructions using the \`read\` tool: \`skills/<name>/SKILL.md\` — do this BEFORE anything else
+3. Follow the loaded skill instructions EXACTLY — do NOT improvise or use alternative approaches
+4. NEVER use general-purpose workarounds when a skill provides the right tool
+   (e.g., use \`agent-browser open <url>\` NOT \`open -a Safari\`)
+5. If multiple skills could apply, load the most specific one first
+6. Even for seemingly simple tasks, CHECK SKILLS FIRST — skills often handle edge cases
+   and produce higher quality results than ad-hoc approaches
+
+## Enforcement
+- If you skip checking skills and use a raw approach for a task that a skill handles,
+  this is considered a FAILURE. Always check skills first.
+- When calling \`task_tracker\` "begin", if it returns matching skills, you MUST load
+  the top match immediately before proceeding.
 
 <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.`;
+To load a skill's full instructions: read \`skills/<name>/SKILL.md\`
+Scripts within a skill are relative to the skill's directory: \`skills/<name>/scripts/\``;
+}
+export async function refreshSkills(agentDir) {
+    return discoverSkills(agentDir);
 }
 export async function expandSkillCommand(input, skills) {
     const match = input.match(/^\/skill:([a-z0-9-]+)\s*([\s\S]*)$/);
@@ -96,7 +142,12 @@ export async function expandSkillCommand(input, skills) {
     if (!skill)
         return null;
     const parsed = await loadSkill(skill);
-    let expanded = `<skill name="${skillName}" baseDir="${skill.directory}">\n${parsed.instructions}\n</skill>`;
+    let expanded = `<skill name="${skillName}" baseDir="${skill.directory}">
+References are relative to ${skill.directory}.
+
+${parsed.instructions}
+</skill>
+You MUST follow the skill instructions above. Do NOT use general alternatives.`;
     if (args) {
         expanded += `\n\n${args}`;
     }

package/dist/tools/capture-photo.d.ts

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

package/dist/tools/capture-photo.js

@@ -0,0 +1,91 @@
+import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import { join } from "path";
+import { execSync } from "child_process";
+import { capturePhotoSchema } from "./shared.js";
+const PHOTOS_DIR = "memory/photos";
+const INDEX_FILE = "memory/photos/INDEX.md";
+const LATEST_FRAME_FILE = "memory/.latest-frame.jpg";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+}
+export function createCapturePhotoTool(cwd) {
+    return {
+        name: "capture_photo",
+        label: "capture_photo",
+        description: "Capture a photo from the webcam during a memorable moment. Reads the latest camera frame, saves it as a named photo in memory/photos/, updates the index, and commits to git.",
+        parameters: capturePhotoSchema,
+        execute: async (_toolCallId, { reason }, signal) => {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            const framePath = join(cwd, LATEST_FRAME_FILE);
+            // Check if frame file exists and isn't stale
+            let frameStat;
+            try {
+                frameStat = await stat(framePath);
+            }
+            catch {
+                return {
+                    content: [{ type: "text", text: "No camera frame available. The webcam may not be active." }],
+                    details: undefined,
+                };
+            }
+            const ageMs = Date.now() - frameStat.mtimeMs;
+            if (ageMs > 5000) {
+                return {
+                    content: [{ type: "text", text: "No recent camera frame (camera may be off). Last frame is too stale to capture." }],
+                    details: undefined,
+                };
+            }
+            // Read the frame
+            const frameData = await readFile(framePath);
+            // Build filename
+            const now = new Date();
+            const pad = (n) => String(n).padStart(2, "0");
+            const datePart = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+            const timePart = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+            const slug = slugify(reason);
+            const filename = `${datePart}_${timePart}_${slug}.jpg`;
+            const photoRelPath = `${PHOTOS_DIR}/${filename}`;
+            const photoAbsPath = join(cwd, photoRelPath);
+            // Ensure photos directory exists
+            await mkdir(join(cwd, PHOTOS_DIR), { recursive: true });
+            // Write photo
+            await writeFile(photoAbsPath, frameData);
+            // Update INDEX.md
+            const indexPath = join(cwd, INDEX_FILE);
+            let indexContent = "";
+            try {
+                indexContent = await readFile(indexPath, "utf-8");
+            }
+            catch {
+                indexContent = "# Memorable Moments\n\nPhotos captured during happy and memorable moments.\n\n";
+            }
+            const entry = `- **${datePart} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}** — ${reason} → [\`${filename}\`](${filename})\n`;
+            indexContent += entry;
+            await writeFile(indexPath, indexContent, "utf-8");
+            // Git add + commit
+            const commitMsg = `Capture moment: ${reason}`;
+            try {
+                execSync(`git add "${photoRelPath}" "${INDEX_FILE}" && git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, {
+                    cwd,
+                    stdio: "pipe",
+                });
+            }
+            catch (err) {
+                const stderr = err.stderr?.toString() || "";
+                return {
+                    content: [{ type: "text", text: `Photo saved to ${photoRelPath} but git commit failed: ${stderr.trim() || "unknown error"}` }],
+                    details: undefined,
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Memorable moment captured! Photo saved to ${photoRelPath} and committed: "${commitMsg}"` }],
+                details: undefined,
+            };
+        },
+    };
+}

package/dist/tools/index.d.ts

@@ -4,9 +4,10 @@ export interface BuiltinToolsConfig {
     dir: string;
     timeout?: number;
     sandbox?: SandboxContext;
+    gitagentDir?: string;
 }
 /**
- * Create the four built-in tools (cli, read, write, memory).
+ * Create the built-in tools (cli, read, write, memory, task_tracker, skill_learner).
  * If a SandboxContext is provided, returns sandbox-backed tools;
  * otherwise returns the standard local tools.
  */

package/dist/tools/index.js

@@ -2,12 +2,15 @@ import { createCliTool } from "./cli.js";
 import { createReadTool } from "./read.js";
 import { createWriteTool } from "./write.js";
 import { createMemoryTool } from "./memory.js";
+import { createTaskTrackerTool } from "./task-tracker.js";
+import { createSkillLearnerTool } from "./skill-learner.js";
+import { createCapturePhotoTool } from "./capture-photo.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).
+ * Create the built-in tools (cli, read, write, memory, task_tracker, skill_learner).
  * If a SandboxContext is provided, returns sandbox-backed tools;
  * otherwise returns the standard local tools.
  */
@@ -20,10 +23,17 @@ export function createBuiltinTools(config) {
             createSandboxMemoryTool(config.sandbox),
         ];
     }
-    return [
+    const tools = [
         createCliTool(config.dir, config.timeout),
         createReadTool(config.dir),
         createWriteTool(config.dir),
         createMemoryTool(config.dir),
+        createCapturePhotoTool(config.dir),
     ];
+    // Add learning tools if gitagentDir is available
+    if (config.gitagentDir) {
+        tools.push(createTaskTrackerTool(config.dir, config.gitagentDir));
+        tools.push(createSkillLearnerTool(config.dir, config.gitagentDir));
+    }
+    return tools;
 }

package/dist/tools/read.js

@@ -1,7 +1,11 @@
 import { readFile } from "fs/promises";
 import { resolve } from "path";
+import { homedir } from "os";
 import { readSchema, MAX_LINES, paginateLines } from "./shared.js";
 function resolvePath(path, cwd) {
+    if (path.startsWith("~/") || path === "~") {
+        path = homedir() + path.slice(1);
+    }
     return path.startsWith("/") ? path : resolve(cwd, path);
 }
 function isBinary(buffer) {

package/dist/tools/shared.d.ts

@@ -22,6 +22,26 @@ export declare const memorySchema: import("@sinclair/typebox").TObject<{
     content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     message: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
+export declare const taskTrackerSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnsafe<string>;
+    objective: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    step: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    outcome: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<string>>;
+    failure_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    skill_used: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare const capturePhotoSchema: import("@sinclair/typebox").TObject<{
+    reason: import("@sinclair/typebox").TString;
+}>;
+export declare const skillLearnerSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnsafe<string>;
+    task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    skill_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    skill_description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    override_heuristic: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
 /** Truncate output to MAX_OUTPUT, keeping the tail. */
 export declare function truncateOutput(text: string): string;
 /**

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>;