@germanescobar/anita 0.3.0

package/dist/skills/skills.d.ts

@@ -0,0 +1,62 @@
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    "allowed-tools"?: string;
+    "disable-model-invocation"?: boolean;
+    [key: string]: unknown;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    disableModelInvocation: boolean;
+}
+export interface SkillDiagnostic {
+    type: "warning" | "error" | "collision";
+    message: string;
+    path: string;
+    collision?: {
+        name: string;
+        winnerPath: string;
+        loserPath: string;
+    };
+}
+export interface LoadSkillsResult {
+    skills: Skill[];
+    diagnostics: SkillDiagnostic[];
+}
+export interface LoadSkillsOptions {
+    /** Working directory for project-local skills. Default: process.cwd() */
+    cwd?: string;
+    /** Explicit skill paths (files or directories). Additive even with noSkills. */
+    skillPaths?: string[];
+    /** Include default discovery directories. Default: true */
+    includeDefaults?: boolean;
+}
+/**
+ * Load skills from a directory.
+ *
+ * Discovery rules (following the Agent Skills spec):
+ * - If a directory contains SKILL.md, treat it as a skill root (no further recursion)
+ * - Otherwise, recurse into subdirectories to find SKILL.md files
+ * - In agent-specific directories (~/.anita/skills/, .anita/skills/), root .md files
+ *   are also discovered as individual skills
+ * - Skip dot-dirs, node_modules
+ */
+export declare function loadSkillsFromDir(dir: string, options?: {
+    includeRootFiles?: boolean;
+}): LoadSkillsResult;
+export declare function loadSkills(options?: LoadSkillsOptions): LoadSkillsResult;
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per the Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via --skill or future command support).
+ */
+export declare function formatSkillsForPrompt(skills: Skill[]): string;

package/dist/skills/skills.js

@@ -0,0 +1,371 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+// ── Constants ──────────────────────────────────────────────────────────────
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+// ── Frontmatter parsing ────────────────────────────────────────────────────
+/**
+ * Extract YAML frontmatter from a markdown file.
+ * Returns `{ frontmatter, body }` where frontmatter is parsed key-value pairs
+ * and body is the markdown content after the closing `---`.
+ */
+function parseFrontmatter(content) {
+    const trimmed = content.replace(/^\uFEFF/, ""); // strip BOM
+    if (!trimmed.startsWith("---")) {
+        return { frontmatter: {}, body: content };
+    }
+    const closingIndex = trimmed.indexOf("---", 3);
+    if (closingIndex === -1) {
+        return { frontmatter: {}, body: content };
+    }
+    const yamlBlock = trimmed.slice(3, closingIndex).trim();
+    const body = trimmed.slice(closingIndex + 3).trim();
+    const frontmatter = {};
+    for (const line of yamlBlock.split("\n")) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim();
+        let value = line.slice(colonIndex + 1).trim();
+        // Handle quoted strings
+        if ((typeof value === "string" && value.startsWith('"') && value.endsWith('"')) ||
+            (typeof value === "string" && value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Handle boolean
+        if (value === "true")
+            value = true;
+        if (value === "false")
+            value = false;
+        if (key === "metadata") {
+            // Skip nested metadata parsing for now; store as empty
+            continue;
+        }
+        frontmatter[key] = value;
+    }
+    return { frontmatter, body };
+}
+// ── Validation ─────────────────────────────────────────────────────────────
+function validateName(name, parentDirName) {
+    const errors = [];
+    if (name !== parentDirName) {
+        errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        errors.push("name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)");
+    }
+    if (name.startsWith("-") || name.endsWith("-")) {
+        errors.push("name must not start or end with a hyphen");
+    }
+    if (name.includes("--")) {
+        errors.push("name must not contain consecutive hyphens");
+    }
+    return errors;
+}
+function validateDescription(description) {
+    const errors = [];
+    if (!description || description.trim() === "") {
+        errors.push("description is required");
+    }
+    else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+// ── XML escaping ───────────────────────────────────────────────────────────
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+// ── Single file loading ────────────────────────────────────────────────────
+function loadSkillFromFile(filePath) {
+    const diagnostics = [];
+    try {
+        const rawContent = fs.readFileSync(filePath, "utf-8");
+        const { frontmatter } = parseFrontmatter(rawContent);
+        const skillDir = path.dirname(filePath);
+        const parentDirName = path.basename(skillDir);
+        // Validate description
+        const descErrors = validateDescription(frontmatter.description);
+        for (const error of descErrors) {
+            diagnostics.push({ type: "error", message: error, path: filePath });
+        }
+        // Use name from frontmatter, or fall back to parent directory name
+        const name = frontmatter.name || parentDirName;
+        // Validate name
+        const nameErrors = validateName(name, parentDirName);
+        for (const error of nameErrors) {
+            diagnostics.push({ type: "warning", message: error, path: filePath });
+        }
+        // Missing description → skip skill entirely
+        if (!frontmatter.description || frontmatter.description.trim() === "") {
+            return { skill: null, diagnostics };
+        }
+        return {
+            skill: {
+                name,
+                description: frontmatter.description,
+                filePath,
+                baseDir: skillDir,
+                disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+            },
+            diagnostics,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "failed to parse skill file";
+        diagnostics.push({ type: "error", message, path: filePath });
+        return { skill: null, diagnostics };
+    }
+}
+// ── Directory scanning ────────────────────────────────────────────────────
+/**
+ * Load skills from a directory.
+ *
+ * Discovery rules (following the Agent Skills spec):
+ * - If a directory contains SKILL.md, treat it as a skill root (no further recursion)
+ * - Otherwise, recurse into subdirectories to find SKILL.md files
+ * - In agent-specific directories (~/.anita/skills/, .anita/skills/), root .md files
+ *   are also discovered as individual skills
+ * - Skip dot-dirs, node_modules
+ */
+export function loadSkillsFromDir(dir, options = {}) {
+    return loadSkillsFromDirInternal(dir, options.includeRootFiles ?? false);
+}
+function loadSkillsFromDirInternal(dir, includeRootFiles) {
+    const skills = [];
+    const diagnostics = [];
+    if (!fs.existsSync(dir)) {
+        return { skills, diagnostics };
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return { skills, diagnostics };
+    }
+    // Check for SKILL.md at root → this directory IS a skill
+    for (const entry of entries) {
+        if (entry.name !== "SKILL.md")
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                isFile = fs.statSync(fullPath).isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!isFile)
+            continue;
+        const result = loadSkillFromFile(fullPath);
+        if (result.skill)
+            skills.push(result.skill);
+        diagnostics.push(...result.diagnostics);
+        // This directory is a skill root; do not recurse further
+        return { skills, diagnostics };
+    }
+    // No SKILL.md at root → scan subdirectories and optionally root .md files
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (entry.name === "node_modules")
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        let isDirectory = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const stat = fs.statSync(fullPath);
+                isDirectory = stat.isDirectory();
+                isFile = stat.isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDirectory) {
+            const subResult = loadSkillsFromDirInternal(fullPath, false);
+            skills.push(...subResult.skills);
+            diagnostics.push(...subResult.diagnostics);
+            continue;
+        }
+        if (isFile && includeRootFiles && entry.name.endsWith(".md")) {
+            const result = loadSkillFromFile(fullPath);
+            if (result.skill)
+                skills.push(result.skill);
+            diagnostics.push(...result.diagnostics);
+        }
+    }
+    return { skills, diagnostics };
+}
+// ── Full skills loading ────────────────────────────────────────────────────
+/**
+ * Load skills from all configured locations.
+ *
+ * Discovery order (later entries override earlier on name collision):
+ * 1. User-level: ~/.anita/skills/ and ~/.agents/skills/
+ * 2. Project-level: .anita/skills/ and .agents/skills/ (in cwd)
+ * 3. Explicit --skill paths (additive even with --no-skills)
+ *
+ * The agent-specific directory falls back to the legacy `.ada` location when
+ * `.anita` does not exist, so existing skill setups keep working.
+ */
+/*
+ * Resolve the agent-specific skills directory under `base`, preferring the
+ * canonical `.anita/skills` and falling back to the legacy `.ada/skills` when
+ * the canonical directory does not exist.
+ */
+function resolveAgentSkillsDir(base) {
+    const primary = path.join(base, ".anita", "skills");
+    if (fs.existsSync(primary))
+        return primary;
+    const legacy = path.join(base, ".ada", "skills");
+    if (fs.existsSync(legacy))
+        return legacy;
+    return primary;
+}
+export function loadSkills(options = {}) {
+    const { cwd = process.cwd(), skillPaths = [], includeDefaults = true } = options;
+    const skillMap = new Map();
+    const realPathSet = new Set();
+    const allDiagnostics = [];
+    function addSkills(result) {
+        allDiagnostics.push(...result.diagnostics);
+        for (const skill of result.skills) {
+            // Resolve symlinks to detect duplicate files
+            let realPath;
+            try {
+                realPath = fs.realpathSync(skill.filePath);
+            }
+            catch {
+                realPath = skill.filePath;
+            }
+            // Skip if already loaded via symlink
+            if (realPathSet.has(realPath))
+                continue;
+            const existing = skillMap.get(skill.name);
+            if (existing) {
+                allDiagnostics.push({
+                    type: "collision",
+                    message: `name "${skill.name}" collision`,
+                    path: skill.filePath,
+                    collision: {
+                        name: skill.name,
+                        winnerPath: existing.filePath,
+                        loserPath: skill.filePath,
+                    },
+                });
+            }
+            else {
+                skillMap.set(skill.name, skill);
+                realPathSet.add(realPath);
+            }
+        }
+    }
+    if (includeDefaults) {
+        const homeDir = os.homedir();
+        // User-level (agent-specific directory: includeRootFiles for standalone .md skills)
+        addSkills(loadSkillsFromDirInternal(resolveAgentSkillsDir(homeDir), true));
+        // User-level (cross-client .agents directory: no root .md files)
+        addSkills(loadSkillsFromDirInternal(path.join(homeDir, ".agents", "skills"), false));
+        // Project-level
+        addSkills(loadSkillsFromDirInternal(resolveAgentSkillsDir(cwd), true));
+        addSkills(loadSkillsFromDirInternal(path.join(cwd, ".agents", "skills"), false));
+    }
+    // Explicit skill paths (always additive)
+    for (const rawPath of skillPaths) {
+        const resolvedPath = resolveSkillPath(rawPath, cwd);
+        if (!fs.existsSync(resolvedPath)) {
+            allDiagnostics.push({
+                type: "warning",
+                message: "skill path does not exist",
+                path: resolvedPath,
+            });
+            continue;
+        }
+        try {
+            const stat = fs.statSync(resolvedPath);
+            if (stat.isDirectory()) {
+                addSkills(loadSkillsFromDirInternal(resolvedPath, true));
+            }
+            else if (stat.isFile() && resolvedPath.endsWith(".md")) {
+                const result = loadSkillFromFile(resolvedPath);
+                if (result.skill) {
+                    addSkills({ skills: [result.skill], diagnostics: result.diagnostics });
+                }
+                else {
+                    allDiagnostics.push(...result.diagnostics);
+                }
+            }
+            else {
+                allDiagnostics.push({
+                    type: "warning",
+                    message: "skill path is not a markdown file or directory",
+                    path: resolvedPath,
+                });
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "failed to read skill path";
+            allDiagnostics.push({ type: "warning", message, path: resolvedPath });
+        }
+    }
+    return {
+        skills: Array.from(skillMap.values()),
+        diagnostics: allDiagnostics,
+    };
+}
+// ── Path resolution ────────────────────────────────────────────────────────
+function resolveSkillPath(rawPath, cwd) {
+    const trimmed = rawPath.trim();
+    if (trimmed === "~")
+        return os.homedir();
+    if (trimmed.startsWith("~/"))
+        return path.join(os.homedir(), trimmed.slice(2));
+    if (trimmed.startsWith("~"))
+        return path.join(os.homedir(), trimmed.slice(1));
+    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+}
+// ── Prompt formatting ─────────────────────────────────────────────────────
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per the Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via --skill or future command support).
+ */
+export function formatSkillsForPrompt(skills) {
+    const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
+    if (visibleSkills.length === 0)
+        return "";
+    const lines = [
+        "",
+        "The following skills provide specialized instructions for specific tasks.",
+        "Use the read_file tool to load a skill's file when the task matches its description.",
+        "When a skill file references a relative path, resolve it against the skill directory (parent directory of SKILL.md) and use that absolute path in tool commands.",
+        "",
+        "<available_skills>",
+    ];
+    for (const skill of visibleSkills) {
+        lines.push("  <skill>");
+        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+        lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+        lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+        lines.push("  </skill>");
+    }
+    lines.push("</available_skills>");
+    return lines.join("\n");
+}

package/dist/storage/event-store.d.ts

@@ -0,0 +1,7 @@
+import type { AgentEvent, EventType } from "../types/events.js";
+export declare class EventStore {
+    private baseDir;
+    constructor(baseDir: string);
+    append(sessionId: string, type: EventType, data: Record<string, unknown>): Promise<AgentEvent>;
+    getEvents(sessionId: string): Promise<AgentEvent[]>;
+}

package/dist/storage/event-store.js

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { v4 as uuidv4 } from "uuid";
+export class EventStore {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async append(sessionId, type, data) {
+        const event = {
+            id: uuidv4(),
+            sessionId,
+            timestamp: new Date().toISOString(),
+            type,
+            data,
+        };
+        await fs.mkdir(this.baseDir, { recursive: true });
+        const filePath = path.join(this.baseDir, `${sessionId}.jsonl`);
+        await fs.appendFile(filePath, JSON.stringify(event) + "\n");
+        return event;
+    }
+    async getEvents(sessionId) {
+        const filePath = path.join(this.baseDir, `${sessionId}.jsonl`);
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            return content
+                .trim()
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => JSON.parse(line));
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/storage/session-store.d.ts

@@ -0,0 +1,11 @@
+import type { SessionState } from "../types/agent.js";
+export declare class SessionStore {
+    private baseDir;
+    constructor(baseDir: string);
+    save(session: SessionState): Promise<void>;
+    load(sessionId: string): Promise<SessionState | null>;
+    list(includeArchived?: boolean): Promise<SessionState[]>;
+    archive(sessionId: string): Promise<void>;
+    getLatest(): Promise<SessionState | null>;
+    private normalize;
+}

package/dist/storage/session-store.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { conversationItemsToMessages, messagesToConversationItems, } from "../types/conversation.js";
+export class SessionStore {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async save(session) {
+        await fs.mkdir(this.baseDir, { recursive: true });
+        const filePath = path.join(this.baseDir, `${session.id}.json`);
+        await fs.writeFile(filePath, JSON.stringify(this.normalize(session), null, 2));
+    }
+    async load(sessionId) {
+        const filePath = path.join(this.baseDir, `${sessionId}.json`);
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            return this.normalize(JSON.parse(content));
+        }
+        catch {
+            return null;
+        }
+    }
+    async list(includeArchived = false) {
+        try {
+            const files = await fs.readdir(this.baseDir);
+            const sessions = [];
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const content = await fs.readFile(path.join(this.baseDir, file), "utf-8");
+                const session = this.normalize(JSON.parse(content));
+                if (!includeArchived && session.status === "archived")
+                    continue;
+                sessions.push(session);
+            }
+            sessions.sort((a, b) => new Date(b.lastActiveAt).getTime() -
+                new Date(a.lastActiveAt).getTime());
+            return sessions;
+        }
+        catch {
+            return [];
+        }
+    }
+    async archive(sessionId) {
+        const session = await this.load(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        session.status = "archived";
+        await this.save(session);
+    }
+    async getLatest() {
+        const sessions = await this.list();
+        return sessions[0] ?? null;
+    }
+    normalize(session) {
+        if (!Array.isArray(session.conversationItems)) {
+            session.conversationItems = messagesToConversationItems(session.messages ?? []);
+        }
+        session.messages = conversationItemsToMessages(session.conversationItems);
+        return session;
+    }
+}

package/dist/tools/delete-file.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types/tools.js";
+export declare const deleteFileTool: ToolDefinition;

package/dist/tools/delete-file.js

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+export const deleteFileTool = {
+    name: "delete_file",
+    description: "Delete a file at the given path. Fails if the file does not exist.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative file path" },
+        },
+        required: ["path"],
+    },
+    async execute(input) {
+        const filePath = input.path;
+        try {
+            await fs.unlink(filePath);
+            return { content: `File deleted: ${filePath}` };
+        }
+        catch (err) {
+            return {
+                content: `Error deleting file: ${err.message}`,
+                isError: true,
+            };
+        }
+    },
+};

package/dist/tools/edit-file.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types/tools.js";
+export declare const editFileTool: ToolDefinition;

package/dist/tools/edit-file.js

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+export const editFileTool = {
+    name: "edit_file",
+    description: "Edit a file by replacing an exact string match. The old_text must appear exactly once in the file. Use read_file first to see the current content.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Absolute or relative file path" },
+            old_text: {
+                type: "string",
+                description: "The exact text to find and replace",
+            },
+            new_text: {
+                type: "string",
+                description: "The text to replace it with",
+            },
+        },
+        required: ["path", "old_text", "new_text"],
+    },
+    async execute(input) {
+        const filePath = input.path;
+        const oldText = input.old_text;
+        const newText = input.new_text;
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            const occurrences = content.split(oldText).length - 1;
+            if (occurrences === 0) {
+                return {
+                    content: `Error: old_text not found in ${filePath}. Use read_file to check the current content.`,
+                    isError: true,
+                };
+            }
+            if (occurrences > 1) {
+                return {
+                    content: `Error: old_text found ${occurrences} times in ${filePath}. Provide a more specific string.`,
+                    isError: true,
+                };
+            }
+            const newContent = content.replace(oldText, newText);
+            await fs.writeFile(filePath, newContent);
+            return { content: `File edited: ${filePath}` };
+        }
+        catch (err) {
+            return {
+                content: `Error editing file: ${err.message}`,
+                isError: true,
+            };
+        }
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types/tools.js";
+export declare const readFileTool: ToolDefinition;