zoe-agent 0.3.1

package/dist/skills/loader.js

@@ -0,0 +1,59 @@
+import { readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { parseFrontmatter } from './parser.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export function getSkillPaths(cwd) {
+    const paths = [];
+    // 1. Environment variable (highest priority, colon-separated)
+    const envPath = process.env.ZOE_SKILLS_PATH;
+    if (envPath) {
+        paths.push(...envPath.split(':').filter(p => p));
+    }
+    // 2. Project skills
+    paths.push(join(cwd, '.zoe', 'skills'));
+    // 3. Volume-mounted skills (Docker)
+    paths.push('/mnt/skills');
+    // 4. Bundled skills (shipped with zoe)
+    if (!process.env.ZOE_NO_BUNDLED_SKILLS) {
+        paths.push(join(__dirname, '..', '..', 'skills'));
+    }
+    return paths;
+}
+export async function discoverSkills(cwd) {
+    const paths = getSkillPaths(cwd);
+    const skills = new Map();
+    // Load in reverse priority order so higher priority overwrites
+    for (const searchPath of [...paths].reverse()) {
+        if (!existsSync(searchPath))
+            continue;
+        try {
+            const entries = await readdir(searchPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillFile = join(searchPath, entry.name, 'SKILL.md');
+                if (!existsSync(skillFile))
+                    continue;
+                try {
+                    const skill = await parseFrontmatter(skillFile);
+                    skill.basePath = join(searchPath, entry.name);
+                    skill.source = searchPath;
+                    const existing = skills.get(skill.name);
+                    if (!existing || skill.priority >= existing.priority) {
+                        skills.set(skill.name, skill);
+                    }
+                }
+                catch (error) {
+                    console.warn(`Warning: Failed to load skill from ${skillFile}: ${error.message}`);
+                }
+            }
+        }
+        catch {
+            // Directory not readable, skip silently
+        }
+    }
+    return Array.from(skills.values());
+}

package/dist/skills/parser.d.ts

@@ -0,0 +1,7 @@
+import { Skill } from './types.js';
+export declare function parseSkillFile(filePath: string): Promise<Skill>;
+/**
+ * Parse only the YAML frontmatter from a skill file.
+ * Discards the body text immediately — body is loaded lazily via getBody().
+ */
+export declare function parseFrontmatter(filePath: string): Promise<Skill>;

package/dist/skills/parser.js

@@ -0,0 +1,152 @@
+import { readFile } from 'fs/promises';
+import { getSkillBodyLimits } from './types.js';
+export async function parseSkillFile(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    const { frontmatter, body } = extractFrontmatter(content);
+    if (!frontmatter.name)
+        throw new Error(`Skill missing 'name' field: ${filePath}`);
+    if (!frontmatter.description)
+        throw new Error(`Skill missing 'description' field: ${filePath}`);
+    // Warn at load time if body exceeds the soft warning threshold
+    const { warnChars } = getSkillBodyLimits();
+    if (body.length > warnChars) {
+        console.warn(`[SKILLS] Warning: Skill "${frontmatter.name}" body is ${body.length} chars ` +
+            `(~${Math.ceil(body.length / 4)} tokens). Consider trimming below ${warnChars} chars ` +
+            `for optimal context usage.`);
+    }
+    return {
+        name: frontmatter.name,
+        description: frontmatter.description,
+        version: frontmatter.version || '1.0.0',
+        author: frontmatter.author,
+        tags: frontmatter.tags || [],
+        allowedTools: frontmatter.allowedTools,
+        priority: frontmatter.priority || 0,
+        basePath: '',
+        source: '',
+        frontmatter,
+        filePath,
+    };
+}
+/**
+ * Parse only the YAML frontmatter from a skill file.
+ * Discards the body text immediately — body is loaded lazily via getBody().
+ */
+export async function parseFrontmatter(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    const frontmatter = extractFrontmatterOnly(content);
+    if (!frontmatter.name)
+        throw new Error(`Skill missing 'name' field: ${filePath}`);
+    if (!frontmatter.description)
+        throw new Error(`Skill missing 'description' field: ${filePath}`);
+    return {
+        name: frontmatter.name,
+        description: frontmatter.description,
+        version: frontmatter.version || '1.0.0',
+        author: frontmatter.author,
+        tags: frontmatter.tags || [],
+        allowedTools: frontmatter.allowedTools,
+        priority: frontmatter.priority || 0,
+        basePath: '',
+        source: '',
+        frontmatter,
+        filePath,
+    };
+}
+function extractFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('---')) {
+        return { frontmatter: {}, body: content };
+    }
+    const endIdx = trimmed.indexOf('---', 3);
+    if (endIdx === -1) {
+        return { frontmatter: {}, body: content };
+    }
+    const yaml = trimmed.slice(3, endIdx);
+    const body = trimmed.slice(endIdx + 3).trimStart();
+    return { frontmatter: parseYaml(yaml), body };
+}
+/**
+ * Extract only the frontmatter from a skill file.
+ * The body text is not returned — used during discovery to avoid holding bodies in memory.
+ */
+function extractFrontmatterOnly(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('---')) {
+        return {};
+    }
+    const endIdx = trimmed.indexOf('---', 3);
+    if (endIdx === -1) {
+        return {};
+    }
+    const yaml = trimmed.slice(3, endIdx);
+    return parseYaml(yaml);
+}
+function parseYaml(yaml) {
+    const result = {};
+    const lines = yaml.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Dash-based array item (skip — consumed by parent key)
+        if (/^\s+-\s/.test(line)) {
+            i++;
+            continue;
+        }
+        const match = line.match(/^(\w+):\s*(.*)/);
+        if (!match) {
+            i++;
+            continue;
+        }
+        const [, key, rawValue] = match;
+        const val = rawValue.trim();
+        // Multiline literal (|) or folded (>)
+        if (val === '|' || val === '>') {
+            const multiline = [];
+            i++;
+            while (i < lines.length && (lines[i].startsWith('  ') || lines[i] === '')) {
+                multiline.push(lines[i].replace(/^  /, ''));
+                i++;
+            }
+            result[key] = multiline.join('\n').trim();
+            continue;
+        }
+        // Empty value — check if next lines are dash-based array items
+        if (val === '') {
+            const arr = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const arrMatch = lines[j].match(/^\s+-\s+(.*)/);
+                if (!arrMatch)
+                    break;
+                arr.push(arrMatch[1].trim().replace(/^['"]|['"]$/g, ''));
+                j++;
+            }
+            if (arr.length > 0) {
+                result[key] = arr;
+                i = j;
+                continue;
+            }
+        }
+        // Inline array [a, b, c]
+        if (val.startsWith('[') && val.endsWith(']')) {
+            result[key] = val
+                .slice(1, -1)
+                .split(',')
+                .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
+                .filter(Boolean);
+            i++;
+            continue;
+        }
+        // Number
+        if (/^\d+(\.\d+)?$/.test(val)) {
+            result[key] = Number(val);
+            i++;
+            continue;
+        }
+        // String (strip surrounding quotes)
+        result[key] = val.replace(/^['"]|['"]$/g, '');
+        i++;
+    }
+    return result;
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,13 @@
+import { Skill, SkillMetadata, SkillRegistry } from './types.js';
+export declare class DefaultSkillRegistry implements SkillRegistry {
+    private skills;
+    private bodyCache;
+    private readonly maxCacheSize;
+    constructor(skills: Skill[]);
+    get(name: string): Skill | undefined;
+    getAll(): Skill[];
+    getMetadata(): SkillMetadata[];
+    getBody(name: string): Promise<string | undefined>;
+    private setCache;
+    getNames(): string[];
+}

package/dist/skills/registry.js

@@ -0,0 +1,74 @@
+import { readFile } from 'fs/promises';
+export class DefaultSkillRegistry {
+    skills;
+    bodyCache;
+    maxCacheSize = 5;
+    constructor(skills) {
+        this.skills = new Map(skills.map(s => [s.name, s]));
+        this.bodyCache = new Map();
+    }
+    get(name) {
+        return this.skills.get(name);
+    }
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    getMetadata() {
+        return this.getAll().map(s => ({
+            name: s.name,
+            description: s.description,
+            version: s.version,
+            tags: s.tags,
+            allowedTools: s.allowedTools,
+        }));
+    }
+    async getBody(name) {
+        const skill = this.get(name);
+        if (!skill)
+            return undefined;
+        // Check cache first
+        const cached = this.bodyCache.get(name);
+        if (cached !== undefined)
+            return cached;
+        // Load body lazily from disk
+        try {
+            const content = await readFile(skill.filePath, 'utf-8');
+            const body = extractBody(content);
+            if (body === undefined)
+                return undefined;
+            this.setCache(name, body);
+            return body;
+        }
+        catch {
+            // File deleted, moved, or unreadable
+            return undefined;
+        }
+    }
+    setCache(name, body) {
+        this.bodyCache.delete(name); // Remove if exists (moves to end)
+        this.bodyCache.set(name, body);
+        // Evict oldest
+        if (this.bodyCache.size > this.maxCacheSize) {
+            const firstKey = this.bodyCache.keys().next().value;
+            if (firstKey)
+                this.bodyCache.delete(firstKey);
+        }
+    }
+    getNames() {
+        return Array.from(this.skills.keys());
+    }
+}
+/**
+ * Extract the body text after the closing --- delimiter of YAML frontmatter.
+ */
+function extractBody(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('---')) {
+        return content;
+    }
+    const endIdx = trimmed.indexOf('---', 3);
+    if (endIdx === -1) {
+        return undefined;
+    }
+    return trimmed.slice(endIdx + 3).trimStart() || undefined;
+}

package/dist/skills/resolver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @path file reference resolver for skills and chat.
+ *
+ * Supported patterns:
+ * - @path/to/file         — relative to project root (process.cwd())
+ * - @zoe_documents/file — resolves to ~/zoe_documents/file
+ * - @~/path/to/file       — explicit home directory path
+ *
+ * Resolution flow:
+ * 1. Scan text for @reference patterns
+ * 2. Resolve each path
+ * 3. Read file content
+ * 4. Replace @reference with inlined content
+ */
+/**
+ * Resolve all @path references in a text string, inlining file contents.
+ * Returns the text with references replaced by file contents.
+ */
+export declare function resolveReferences(text: string, projectRoot?: string): Promise<string>;

package/dist/skills/resolver.js

@@ -0,0 +1,116 @@
+/**
+ * @path file reference resolver for skills and chat.
+ *
+ * Supported patterns:
+ * - @path/to/file         — relative to project root (process.cwd())
+ * - @zoe_documents/file — resolves to ~/zoe_documents/file
+ * - @~/path/to/file       — explicit home directory path
+ *
+ * Resolution flow:
+ * 1. Scan text for @reference patterns
+ * 2. Resolve each path
+ * 3. Read file content
+ * 4. Replace @reference with inlined content
+ */
+import { readFile } from 'fs/promises';
+import { resolve, join } from 'path';
+import { existsSync, statSync } from 'fs';
+import { homedir } from 'os';
+const MAX_FILE_SIZE = 1024 * 1024; // 1MB per file
+const MAX_REFERENCES = 10; // Max @references per input
+const MAX_TOTAL_RESOLVED_SIZE = 2 * 1024 * 1024; // 2MB total across all inlined files
+/**
+ * Extract all @reference patterns from text.
+ * Matches @path/to/file, @zoe_documents/foo, @~/foo/bar
+ * Does NOT match email addresses (requires word boundary before @)
+ */
+function extractReferences(text) {
+    // Match @path patterns but exclude email addresses
+    // Pattern: @ followed by a path-like string (no spaces, starts with alphanumeric or ~ or zoe_documents)
+    const pattern = /(?:^|[^a-zA-Z0-9])@(~?\/?[a-zA-Z0-9_][a-zA-Z0-9_./-]*)/g;
+    const matches = [];
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+        matches.push(match[1]); // The path part without @
+    }
+    return matches.slice(0, MAX_REFERENCES);
+}
+/**
+ * Resolve a reference path to an absolute file path.
+ */
+function resolveReference(refPath, projectRoot) {
+    // @~/... → explicit home directory
+    if (refPath.startsWith('~/')) {
+        return resolve(join(homedir(), refPath.slice(2)));
+    }
+    // @zoe_documents/... → ~/zoe_documents/...
+    if (refPath.startsWith('zoe_documents/') || refPath === 'zoe_documents') {
+        return resolve(join(homedir(), refPath));
+    }
+    // @path/to/file → relative to project root
+    return resolve(join(projectRoot, refPath));
+}
+/**
+ * Validate a resolved path is within allowed boundaries.
+ * Prevents path traversal attacks.
+ */
+function isPathAllowed(resolvedPath, projectRoot) {
+    const home = homedir();
+    const allowedPrefixes = [
+        projectRoot, // Project files (read-only via @)
+        join(home, 'zoe_documents'), // Agent workspace
+        join(home, '.zoe'), // Config/skills
+    ];
+    return allowedPrefixes.some(prefix => resolvedPath.startsWith(prefix));
+}
+/**
+ * Resolve all @path references in a text string, inlining file contents.
+ * Returns the text with references replaced by file contents.
+ */
+export async function resolveReferences(text, projectRoot) {
+    const root = projectRoot || process.cwd();
+    const refs = extractReferences(text);
+    if (refs.length === 0)
+        return text;
+    let result = text;
+    let cumulativeSize = 0;
+    for (const ref of refs) {
+        const resolvedPath = resolveReference(ref, root);
+        // Security check
+        if (!isPathAllowed(resolvedPath, root)) {
+            result = result.replace(`@${ref}`, `[Error: Access denied — path outside allowed boundaries: @${ref}]`);
+            continue;
+        }
+        // Existence check
+        if (!existsSync(resolvedPath)) {
+            result = result.replace(`@${ref}`, `[Error: File not found: @${ref}]`);
+            continue;
+        }
+        try {
+            const stat = statSync(resolvedPath);
+            if (stat.size > MAX_FILE_SIZE) {
+                result = result.replace(`@${ref}`, `[Error: File too large (${Math.round(stat.size / 1024)}KB exceeds 1MB limit): @${ref}]`);
+                continue;
+            }
+            const content = await readFile(resolvedPath, 'utf-8');
+            // Cumulative size cap — stop inlining if total exceeds budget
+            if (cumulativeSize + content.length > MAX_TOTAL_RESOLVED_SIZE) {
+                result = result.replace(`@${ref}`, `[Skipped: cumulative resolved size would exceed ${Math.round(MAX_TOTAL_RESOLVED_SIZE / 1024)}KB limit]: @${ref}]`);
+                continue;
+            }
+            cumulativeSize += content.length;
+            const ext = resolvedPath.split('.').pop() || '';
+            const langMap = {
+                ts: 'typescript', tsx: 'typescript', js: 'javascript', jsx: 'javascript',
+                py: 'python', rs: 'rust', go: 'go', json: 'json', yaml: 'yaml', yml: 'yaml',
+                md: 'markdown', html: 'html', css: 'css', sh: 'bash', sql: 'sql',
+            };
+            const lang = langMap[ext] || ext;
+            result = result.replace(`@${ref}`, `\n---\n**File: ${ref}**\n\`\`\`${lang}\n${content}\n\`\`\`\n---\n`);
+        }
+        catch (error) {
+            result = result.replace(`@${ref}`, `[Error: Failed to read @${ref}: ${error.message}]`);
+        }
+    }
+    return result;
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,74 @@
+export interface SkillModelConfig {
+    provider?: string;
+    model: string;
+}
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    version?: string;
+    author?: string;
+    tags?: string[];
+    allowedTools?: string[];
+    priority?: number;
+    args?: string[];
+    model?: SkillModelConfig;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    version: string;
+    author?: string;
+    tags: string[];
+    allowedTools?: string[];
+    priority: number;
+    basePath: string;
+    source: string;
+    frontmatter: SkillFrontmatter;
+    filePath: string;
+}
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    version: string;
+    tags: string[];
+    allowedTools?: string[];
+}
+export interface SkillRegistry {
+    get(name: string): Skill | undefined;
+    getAll(): Skill[];
+    getMetadata(): SkillMetadata[];
+    getBody(name: string): Promise<string | undefined>;
+}
+/** Default maximum skill body size in characters (~8k tokens at 4 chars/token). */
+export declare const DEFAULT_SKILL_BODY_MAX_CHARS = 32000;
+/** Default warning threshold in characters (~2k tokens at 4 chars/token). */
+export declare const DEFAULT_SKILL_BODY_WARN_CHARS = 8000;
+/**
+ * Resolved skill body limits from environment variables.
+ * Falls back to defaults if not set or unparsable.
+ */
+export declare function getSkillBodyLimits(): {
+    maxChars: number;
+    warnChars: number;
+};
+/** Result of applying skill body size limits. */
+export interface TruncationResult {
+    /** The (possibly truncated) body */
+    body: string;
+    /** Whether truncation was applied */
+    truncated: boolean;
+    /** Original body size in characters */
+    originalChars: number;
+    /** Estimated original token count (chars / 4) */
+    originalTokenEstimate: number;
+    /** Final body size in characters */
+    finalChars: number;
+    /** Estimated final token count (chars / 4) */
+    finalTokenEstimate: number;
+}
+/**
+ * Enforce size limits on a skill body.
+ * Truncates with a clear marker if the body exceeds maxChars.
+ * Fail-soft: never throws, always returns a usable body.
+ */
+export declare function limitSkillBody(body: string, maxChars?: number, warnChars?: number): TruncationResult;

package/dist/skills/types.js

@@ -0,0 +1,50 @@
+/** Default maximum skill body size in characters (~8k tokens at 4 chars/token). */
+export const DEFAULT_SKILL_BODY_MAX_CHARS = 32_000;
+/** Default warning threshold in characters (~2k tokens at 4 chars/token). */
+export const DEFAULT_SKILL_BODY_WARN_CHARS = 8_000;
+/**
+ * Resolved skill body limits from environment variables.
+ * Falls back to defaults if not set or unparsable.
+ */
+export function getSkillBodyLimits() {
+    const maxChars = parseInt(process.env.ZOE_SKILL_BODY_MAX_CHARS || '', 10);
+    const warnChars = parseInt(process.env.ZOE_SKILL_BODY_WARN_CHARS || '', 10);
+    return {
+        maxChars: Number.isFinite(maxChars) && maxChars > 0 ? maxChars : DEFAULT_SKILL_BODY_MAX_CHARS,
+        warnChars: Number.isFinite(warnChars) && warnChars > 0 ? warnChars : DEFAULT_SKILL_BODY_WARN_CHARS,
+    };
+}
+/**
+ * Enforce size limits on a skill body.
+ * Truncates with a clear marker if the body exceeds maxChars.
+ * Fail-soft: never throws, always returns a usable body.
+ */
+export function limitSkillBody(body, maxChars, warnChars) {
+    const limits = getSkillBodyLimits();
+    const max = maxChars ?? limits.maxChars;
+    const originalChars = body.length;
+    const originalTokenEstimate = Math.ceil(originalChars / 4);
+    if (originalChars <= max) {
+        return {
+            body,
+            truncated: false,
+            originalChars,
+            originalTokenEstimate,
+            finalChars: originalChars,
+            finalTokenEstimate: originalTokenEstimate,
+        };
+    }
+    const marker = `\n\n[... Skill body truncated: ${originalChars} chars total, ${max} shown. ` +
+        `Reduce skill body size or set ZOE_SKILL_BODY_MAX_CHARS to increase the limit. ...]`;
+    const truncatedBody = body.slice(0, max - marker.length) + marker;
+    const finalChars = truncatedBody.length;
+    const finalTokenEstimate = Math.ceil(finalChars / 4);
+    return {
+        body: truncatedBody,
+        truncated: true,
+        originalChars,
+        originalTokenEstimate,
+        finalChars,
+        finalTokenEstimate,
+    };
+}

package/dist/tools/browser.d.ts

@@ -0,0 +1,2 @@
+import { ToolModule } from './interface.js';
+export declare const BrowserTool: ToolModule;

package/dist/tools/browser.js

@@ -0,0 +1,68 @@
+import { chromium } from 'playwright';
+import { Readability } from '@mozilla/readability';
+import { JSDOM } from 'jsdom';
+export const BrowserTool = {
+    name: "Web Browser",
+    risk: "safe",
+    configKeys: [],
+    definition: {
+        type: "function",
+        function: {
+            name: "read_website",
+            description: "Reads and extracts the main content from a website URL. Use this to summarize articles or get information from specific pages.",
+            parameters: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "The full URL of the website to read (e.g., https://example.com/article)."
+                    }
+                },
+                required: ["url"]
+            }
+        }
+    },
+    handler: async (args, config) => {
+        let browser;
+        try {
+            browser = await chromium.launch({ headless: true });
+        }
+        catch (error) {
+            if (error.message.includes("Executable doesn't exist")) {
+                return "Error: Playwright browsers are not installed. Please run `npx playwright install chromium` to enable this feature.";
+            }
+            return `Error launching browser: ${error.message}`;
+        }
+        const context = await browser.newContext({
+            userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
+        });
+        const page = await context.newPage();
+        try {
+            console.log(`Navigating to ${args.url}...`);
+            await page.goto(args.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+            // Get the full HTML content
+            const html = await page.content();
+            // Use JSDOM to create a virtual DOM for Readability
+            const dom = new JSDOM(html, { url: args.url });
+            const reader = new Readability(dom.window.document);
+            const article = reader.parse();
+            if (!article) {
+                // Fallback: just return body text if Readability fails
+                const bodyText = await page.innerText('body');
+                return `Could not parse article content with Readability. Raw text content:
+
+${bodyText.slice(0, 5000)}... (truncated)`;
+            }
+            return `Title: ${article.title}
+
+Content:
+${(article.textContent || "").trim()}`;
+        }
+        catch (error) {
+            return `Error reading website: ${error.message}`;
+        }
+        finally {
+            await browser.close();
+        }
+    }
+};

package/dist/tools/core.d.ts

@@ -0,0 +1,20 @@
+import { ToolModule } from './interface.js';
+export declare const ShellTool: ToolModule;
+export declare const ReadFileTool: ToolModule;
+/** Diff-viewer payload for `write_file`. Owned by the producer (this module);
+ *  the TUI parses it via `isFileWriteMetadata`. `oldContent`/`newContent` are
+ *  omitted when `diffSkipped` (oversized) so we don't hold large strings. */
+export interface FileWriteMetadata {
+    path: string;
+    isNewFile: boolean;
+    byteDelta: number;
+    oldContent?: string | null;
+    newContent?: string;
+    diffSkipped?: boolean;
+    skipReason?: string;
+    /** Index signature so this typed payload satisfies ToolResult.metadata's
+     *  Record<string, unknown> without a cast at the producer site. */
+    [key: string]: unknown;
+}
+export declare const WriteFileTool: ToolModule;
+export declare const DateTimeTool: ToolModule;