@archon-claw/cli 0.0.4 → 0.1.0

package/dist/cli.js

@@ -8,6 +8,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { loadAgentConfig } from "./config.js";
 import { createServer } from "./server.js";
 import { initSessionStore } from "./session.js";
+import { startDev } from "./dev.js";
 import { runToolTests, formatResults } from "./test-runner.js";
 import { runEvals } from "./eval/runner.js";
 import { scaffoldAgent, scaffoldWorkspace } from "./scaffold.js";
@@ -30,6 +31,24 @@ program
     .action(() => {
     console.log("Starting agent...");
 });
+program
+    .command("dev")
+    .description("Start dev server with hot-reload for agent development")
+    .argument("<agent-dir>", "Path to agent directory")
+    .option("-p, --port <port>", "Server port", "5100")
+    .option("--no-open", "Don't auto-open browser")
+    .action(async (agentDir, opts) => {
+    try {
+        await startDev(agentDir, {
+            port: parseInt(opts.port, 10),
+            open: opts.open,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 program
     .command("start")
     .description("Start an agent HTTP server")

package/dist/config.js

@@ -11,7 +11,7 @@ export async function loadAgentConfig(agentDir) {
     // Validate directory structure
     const validation = await validateDir("agent-dir", absDir);
     if (!validation.valid) {
-        throw new Error(`Invalid agent directory:\n${validation.errors.map((e) => `  - ${e}`).join("\n")}`);
+        throw new Error(`Invalid agent directory:\n${validation.errors.map((e) => `  - ${e.file ? `[${e.file}] ` : ""}${e.message}`).join("\n")}`);
     }
     // Load model.json
     const modelRaw = await fs.readFile(path.join(absDir, "model.json"), "utf-8");
@@ -74,7 +74,8 @@ export async function loadAgentConfig(agentDir) {
         const implEntries = await Promise.all(implFiles.map(async (file) => {
             const name = file.replace(/\.impl\.js$/, "");
             const implPath = pathToFileURL(path.join(implsDir, file)).href;
-            const mod = await import(implPath);
+            // Cache-bust ESM module cache so dev reload picks up changes
+            const mod = await import(`${implPath}?t=${Date.now()}`);
             return [name, mod.default];
         }));
         for (const [name, impl] of implEntries) {

package/dist/dev.d.ts

@@ -0,0 +1,20 @@
+import http from "node:http";
+import { type FSWatcher } from "chokidar";
+import type { AgentConfig } from "./types.js";
+export interface DevOptions {
+    port: number;
+    open: boolean;
+}
+/** Returned by startDev for cleanup and testing */
+export interface DevHandle {
+    server: http.Server;
+    watcher: FSWatcher;
+    /** Current config reference (mutable via reload) */
+    getConfig(): AgentConfig;
+    /** Manually trigger config reload */
+    reload(changedFiles?: string[]): Promise<void>;
+    /** Graceful shutdown */
+    close(): Promise<void>;
+}
+export declare function startDev(agentDir: string, opts: DevOptions): Promise<DevHandle>;
+export declare function printBanner(config: AgentConfig, port: number, absDir: string): void;

package/dist/dev.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { watch } from "chokidar";
+import open from "open";
+import { loadAgentConfig } from "./config.js";
+import { createServer } from "./server.js";
+import { initSessionStore } from "./session.js";
+export async function startDev(agentDir, opts) {
+    const absDir = path.resolve(agentDir);
+    // Initial load
+    let currentConfig = await loadAgentConfig(absDir);
+    await initSessionStore(absDir);
+    // Start server with getter — every request reads latest config
+    const server = createServer(() => currentConfig, opts.port);
+    printBanner(currentConfig, opts.port, absDir);
+    // Open browser (skip in SSH)
+    if (opts.open && !process.env.SSH_CLIENT && !process.env.SSH_TTY) {
+        open(`http://localhost:${opts.port}`).catch(() => { });
+    }
+    // Reload logic
+    let reloadInFlight = false;
+    async function reload(changedFiles) {
+        if (reloadInFlight)
+            return;
+        reloadInFlight = true;
+        const ts = new Date().toLocaleTimeString();
+        if (changedFiles?.length) {
+            const relFiles = changedFiles.map((f) => path.relative(absDir, f));
+            console.log(`\n[dev] ${ts} Changed: ${relFiles.join(", ")}`);
+        }
+        try {
+            // Shutdown old MCP connections before reloading
+            await currentConfig.mcpManager?.shutdown();
+            const newConfig = await loadAgentConfig(absDir);
+            currentConfig = newConfig;
+            console.log(`[dev] ${ts} Reloaded \u2713` +
+                ` (tools: ${newConfig.tools.length}, skills: ${Object.keys(newConfig.skills).length})`);
+        }
+        catch (err) {
+            console.error(`[dev] ${ts} Reload failed: ${err instanceof Error ? err.message : err}`);
+            console.error(`[dev] Continuing with previous valid configuration`);
+        }
+        finally {
+            reloadInFlight = false;
+        }
+    }
+    // Watch agent directory
+    const watcher = watch(absDir, {
+        ignored: [
+            "**/sessions/**",
+            "**/node_modules/**",
+            "**/eval-results/**",
+            "**/.DS_Store",
+        ],
+        ignoreInitial: true,
+    });
+    let debounceTimer = null;
+    let pendingFiles = [];
+    watcher.on("all", (_event, filePath) => {
+        pendingFiles.push(filePath);
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            const files = [...pendingFiles];
+            pendingFiles = [];
+            await reload(files);
+        }, 100);
+    });
+    // Graceful shutdown
+    const shutdown = async () => {
+        console.log("\nShutting down...");
+        await close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    async function close() {
+        process.removeListener("SIGINT", shutdown);
+        process.removeListener("SIGTERM", shutdown);
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        await watcher.close();
+        await currentConfig.mcpManager?.shutdown();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    return {
+        server,
+        watcher,
+        getConfig: () => currentConfig,
+        reload,
+        close,
+    };
+}
+export function printBanner(config, port, absDir) {
+    const mcpCount = config.mcpManager
+        ? config.tools.length -
+            config.tools.filter((t) => config.toolImpls.has(t.name) &&
+                !t.name.includes("__")).length
+        : 0;
+    const localCount = config.tools.length - mcpCount;
+    const lines = [
+        "",
+        "  archon-claw dev",
+        "",
+        `  Agent:   ${path.relative(process.cwd(), absDir)}`,
+        `  Model:   ${config.model.provider}/${config.model.model}`,
+        `  Tools:   ${localCount}${mcpCount > 0 ? ` (+ ${mcpCount} from MCP)` : ""}`,
+        `  Skills:  ${Object.keys(config.skills).length}`,
+        `  URL:     http://localhost:${port}`,
+        "",
+        "  Watching for changes...",
+        "",
+    ];
+    const maxLen = Math.max(...lines.map((l) => l.length));
+    const top = "\u250C" + "\u2500".repeat(maxLen + 1) + "\u2510";
+    const bot = "\u2514" + "\u2500".repeat(maxLen + 1) + "\u2518";
+    console.log(top);
+    for (const line of lines) {
+        console.log("\u2502" + line.padEnd(maxLen + 1) + "\u2502");
+    }
+    console.log(bot);
+}

package/dist/server.d.ts

@@ -1,3 +1,3 @@
 import http from "node:http";
 import type { AgentConfig } from "./types.js";
-export declare function createServer(config: AgentConfig, port: number): http.Server;
+export declare function createServer(getConfig: AgentConfig | (() => AgentConfig), port: number): http.Server;

package/dist/server.js

@@ -96,8 +96,10 @@ function readBody(req) {
         });
     });
 }
-export function createServer(config, port) {
+export function createServer(getConfig, port) {
+    const resolveConfig = typeof getConfig === "function" ? getConfig : () => getConfig;
     const server = http.createServer(async (req, res) => {
+        const config = resolveConfig();
         const url = new URL(req.url ?? "/", `http://localhost:${port}`);
         const method = req.method ?? "GET";
         // CORS preflight

package/dist/validator/index.d.ts

@@ -1,5 +1,5 @@
 import type { ValidatorPlugin, DirValidatorPlugin, ValidationResult } from "./plugin.js";
-export type { ValidatorPlugin, DirValidatorPlugin, ValidationResult } from "./plugin.js";
+export type { ValidatorPlugin, DirValidatorPlugin, ValidationResult, ValidationError } from "./plugin.js";
 /** Get a content validator plugin by name */
 export declare function getPlugin(name: string): ValidatorPlugin | undefined;
 /** Get all registered content plugins */
@@ -8,6 +8,8 @@ export declare function getPlugins(): ValidatorPlugin[];
 export declare function getDirPlugin(name: string): DirValidatorPlugin | undefined;
 /** Register a custom content plugin */
 export declare function registerPlugin(plugin: ValidatorPlugin): void;
+/** Unregister a content plugin by name */
+export declare function unregisterPlugin(name: string): boolean;
 /** Register a custom directory plugin */
 export declare function registerDirPlugin(plugin: DirValidatorPlugin): void;
 /** Validate content using a specific plugin by name */

package/dist/validator/index.js

@@ -32,6 +32,14 @@ export function getDirPlugin(name) {
 export function registerPlugin(plugin) {
     contentPlugins.push(plugin);
 }
+/** Unregister a content plugin by name */
+export function unregisterPlugin(name) {
+    const idx = contentPlugins.findIndex((p) => p.name === name);
+    if (idx === -1)
+        return false;
+    contentPlugins.splice(idx, 1);
+    return true;
+}
 /** Register a custom directory plugin */
 export function registerDirPlugin(plugin) {
     dirPlugins.push(plugin);
@@ -40,7 +48,7 @@ export function registerDirPlugin(plugin) {
 export function validate(pluginName, content, fileName) {
     const plugin = getPlugin(pluginName);
     if (!plugin) {
-        return { valid: false, errors: [`Unknown validator plugin: ${pluginName}`] };
+        return { valid: false, errors: [{ message: `Unknown validator plugin: ${pluginName}`, severity: "error" }] };
     }
     return plugin.validate(content, fileName);
 }
@@ -48,7 +56,7 @@ export function validate(pluginName, content, fileName) {
 export async function validateDir(pluginName, dirPath) {
     const plugin = getDirPlugin(pluginName);
     if (!plugin) {
-        return { valid: false, errors: [`Unknown dir validator plugin: ${pluginName}`] };
+        return { valid: false, errors: [{ message: `Unknown dir validator plugin: ${pluginName}`, severity: "error" }] };
     }
     return plugin.validate(dirPath);
 }

package/dist/validator/plugin.d.ts

@@ -1,7 +1,17 @@
+/** Structured validation error */
+export interface ValidationError {
+    message: string;
+    severity: "error" | "warning";
+    file?: string;
+    path?: string;
+    expected?: string;
+    received?: string;
+    line?: number;
+}
 /** Validation result */
 export interface ValidationResult {
     valid: boolean;
-    errors: string[];
+    errors: ValidationError[];
 }
 /** Content validator plugin - validates file content */
 export interface ValidatorPlugin {
@@ -9,6 +19,8 @@ export interface ValidatorPlugin {
     name: string;
     /** File pattern this plugin handles, e.g. "*.json", "*.md" */
     pattern: string;
+    /** Whether this plugin's file(s) are required in an agent directory */
+    required?: boolean;
     /** Validate raw content, return result */
     validate(content: string, fileName?: string): ValidationResult;
 }

package/dist/validator/plugins/agent-dir.js

@@ -1,170 +1,154 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { modelPlugin } from "./model.js";
-import { systemPromptPlugin } from "./system-prompt.js";
-import { toolPlugin } from "./tool.js";
-import { agentSkillPlugin } from "./agent-skill.js";
-import { datasetPlugin } from "./dataset.js";
-import { mcpPlugin } from "./mcp.js";
-export const agentDirPlugin = {
-    name: "agent-dir",
-    async validate(dirPath) {
-        const errors = [];
-        // Check directory exists
+import picomatch from "picomatch";
+import { getPlugins } from "../index.js";
+/**
+ * Given a pattern like "model.json" or "tools/*.json", find matching files
+ * in the agent directory. Returns relative paths (e.g. "tools/t.json").
+ */
+async function matchFiles(dirPath, pattern) {
+    const parts = pattern.split("/");
+    if (parts.length === 1) {
+        // Flat file pattern like "model.json" or "custom-config.json"
+        const matcher = picomatch(pattern);
         try {
-            const stat = await fs.stat(dirPath);
-            if (!stat.isDirectory()) {
-                return { valid: false, errors: [`${dirPath} is not a directory`] };
-            }
+            const entries = await fs.readdir(dirPath);
+            return entries.filter((f) => matcher(f));
         }
         catch {
-            return { valid: false, errors: [`${dirPath} does not exist`] };
+            return [];
         }
-        // Check system-prompt.md
-        const promptPath = path.join(dirPath, "system-prompt.md");
+    }
+    // Directory pattern like "tools/*.json" or "skills/*.md"
+    const subDir = parts.slice(0, -1).join("/");
+    const filePattern = parts[parts.length - 1];
+    const matcher = picomatch(filePattern);
+    const fullSubDir = path.join(dirPath, subDir);
+    try {
+        const stat = await fs.stat(fullSubDir);
+        if (!stat.isDirectory())
+            return [];
+        const entries = await fs.readdir(fullSubDir);
+        return entries.filter((f) => matcher(f)).map((f) => `${subDir}/${f}`);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Validate tools/ + tool-impls/ cross-matching.
+ * This is special logic that cannot be driven purely by pattern matching.
+ * Receives pre-read tool file contents to avoid reading/validating them again.
+ */
+async function validateToolImpls(dirPath, toolContents, errors) {
+    const toolNames = [];
+    const nonServerToolNames = new Set();
+    for (const [relPath, content] of toolContents) {
+        const name = path.basename(relPath, ".json");
+        toolNames.push(name);
         try {
-            const content = await fs.readFile(promptPath, "utf-8");
-            const result = systemPromptPlugin.validate(content, "system-prompt.md");
-            if (!result.valid) {
-                errors.push(...result.errors.map((e) => `[system-prompt.md] ${e}`));
+            const parsed = JSON.parse(content);
+            if (parsed.execution_target === "client" || parsed.execution_target === "host") {
+                nonServerToolNames.add(name);
             }
         }
-        catch {
-            errors.push("Missing required file: system-prompt.md");
-        }
-        // Check model.json
-        const modelPath = path.join(dirPath, "model.json");
-        try {
-            const content = await fs.readFile(modelPath, "utf-8");
-            const result = modelPlugin.validate(content, "model.json");
-            if (!result.valid) {
-                errors.push(...result.errors.map((e) => `[model.json] ${e}`));
+        catch { /* already validated in main loop */ }
+    }
+    const serverToolNames = toolNames.filter((n) => !nonServerToolNames.has(n));
+    // Check tool-impls/
+    const implsDir = path.join(dirPath, "tool-impls");
+    try {
+        const implStat = await fs.stat(implsDir);
+        if (implStat.isDirectory()) {
+            const implFiles = await fs.readdir(implsDir);
+            const implNames = implFiles
+                .filter((f) => f.endsWith(".impl.js"))
+                .map((f) => f.replace(/\.impl\.js$/, ""));
+            for (const name of serverToolNames) {
+                if (!implNames.includes(name)) {
+                    errors.push({ message: `Missing implementation for tool: ${name}`, severity: "error", file: "tool-impls/" });
+                }
+            }
+            for (const name of implNames) {
+                if (!toolNames.includes(name)) {
+                    errors.push({ message: `No matching tool schema in tools/ for ${name}.impl.js`, severity: "warning", file: `tool-impls/${name}.impl.js` });
+                }
             }
         }
-        catch {
-            errors.push("Missing required file: model.json");
+        else {
+            errors.push({ message: "tool-impls is not a directory", severity: "error", file: "tool-impls" });
         }
-        // Check tools/ directory
-        const toolsDir = path.join(dirPath, "tools");
+    }
+    catch {
+        if (serverToolNames.length > 0) {
+            errors.push({ message: "Missing required directory: tool-impls/", severity: "error", file: "tool-impls/" });
+        }
+    }
+}
+export const agentDirPlugin = {
+    name: "agent-dir",
+    async validate(dirPath) {
+        const errors = [];
+        // Check directory exists
         try {
-            const stat = await fs.stat(toolsDir);
+            const stat = await fs.stat(dirPath);
             if (!stat.isDirectory()) {
-                errors.push("tools is not a directory");
+                return { valid: false, errors: [{ message: `${dirPath} is not a directory`, severity: "error", file: dirPath }] };
             }
-            else {
-                const files = await fs.readdir(toolsDir);
-                const jsonFiles = files.filter((f) => f.endsWith(".json"));
-                if (jsonFiles.length === 0) {
-                    errors.push("[tools/] No tool definitions found");
-                }
-                const toolNames = [];
-                const nonServerToolNames = new Set();
-                for (const file of jsonFiles) {
-                    const content = await fs.readFile(path.join(toolsDir, file), "utf-8");
-                    const result = toolPlugin.validate(content, file);
-                    if (!result.valid) {
-                        errors.push(...result.errors.map((e) => `[tools/${file}] ${e}`));
-                    }
-                    else {
-                        const name = file.replace(/\.json$/, "");
-                        toolNames.push(name);
-                        // Check if tool has execution_target that doesn't need server impl
-                        try {
-                            const parsed = JSON.parse(content);
-                            if (parsed.execution_target === "client" || parsed.execution_target === "host") {
-                                nonServerToolNames.add(name);
-                            }
-                        }
-                        catch { /* already validated above */ }
-                    }
+        }
+        catch {
+            return { valid: false, errors: [{ message: `${dirPath} does not exist`, severity: "error", file: dirPath }] };
+        }
+        const plugins = getPlugins();
+        // Track valid tool file contents for cross-matching with tool-impls
+        const validToolContents = new Map();
+        for (const plugin of plugins) {
+            const files = await matchFiles(dirPath, plugin.pattern);
+            if (files.length === 0) {
+                if (plugin.required) {
+                    errors.push({
+                        message: `Missing required file: ${plugin.pattern}`,
+                        severity: "error",
+                        file: plugin.pattern,
+                    });
                 }
-                // Server tools that need impl files
-                const serverToolNames = toolNames.filter((n) => !nonServerToolNames.has(n));
-                // Check tool-impls/ matches server tools
-                const implsDir = path.join(dirPath, "tool-impls");
-                try {
-                    const implStat = await fs.stat(implsDir);
-                    if (implStat.isDirectory()) {
-                        const implFiles = await fs.readdir(implsDir);
-                        const implNames = implFiles
-                            .filter((f) => f.endsWith(".impl.js"))
-                            .map((f) => f.replace(/\.impl\.js$/, ""));
-                        // server tools without impl
-                        for (const name of serverToolNames) {
-                            if (!implNames.includes(name)) {
-                                errors.push(`[tool-impls/] Missing implementation for tool: ${name}`);
-                            }
+                // Special case: tool plugin needs at least 1 tool file
+                if (plugin.name === "tool") {
+                    // Check if the tools/ directory exists at all
+                    const toolsDir = path.join(dirPath, "tools");
+                    try {
+                        const stat = await fs.stat(toolsDir);
+                        if (!stat.isDirectory()) {
+                            errors.push({ message: "tools is not a directory", severity: "error", file: "tools" });
                         }
-                        // impls without tool
-                        for (const name of implNames) {
-                            if (!toolNames.includes(name)) {
-                                errors.push(`[tool-impls/${name}.impl.js] No matching tool schema in tools/`);
-                            }
+                        else {
+                            errors.push({ message: "No tool definitions found", severity: "error", file: "tools/" });
                         }
                     }
-                    else {
-                        errors.push("tool-impls is not a directory");
-                    }
-                }
-                catch {
-                    if (serverToolNames.length > 0) {
-                        errors.push("Missing required directory: tool-impls/");
+                    catch {
+                        errors.push({ message: "Missing required directory: tools/", severity: "error", file: "tools/" });
                     }
                 }
+                continue;
             }
-        }
-        catch {
-            errors.push("Missing required directory: tools/");
-        }
-        // Check datasets/ directory (optional)
-        const datasetsDir = path.join(dirPath, "datasets");
-        try {
-            const stat = await fs.stat(datasetsDir);
-            if (stat.isDirectory()) {
-                const files = await fs.readdir(datasetsDir);
-                const jsonFiles = files.filter((f) => f.endsWith(".json"));
-                for (const file of jsonFiles) {
-                    const content = await fs.readFile(path.join(datasetsDir, file), "utf-8");
-                    const result = datasetPlugin.validate(content, file);
-                    if (!result.valid) {
-                        errors.push(...result.errors.map((e) => `[datasets/${file}] ${e}`));
-                    }
+            // Validate each matched file
+            for (const relPath of files) {
+                const absPath = path.join(dirPath, relPath);
+                const content = await fs.readFile(absPath, "utf-8");
+                const fileName = path.basename(relPath);
+                const result = plugin.validate(content, fileName);
+                if (!result.valid) {
+                    errors.push(...result.errors.map((e) => ({ ...e, file: relPath })));
                 }
-            }
-        }
-        catch {
-            // datasets/ is optional, skip if not exists
-        }
-        // Check skills/ directory (optional)
-        const skillsDir = path.join(dirPath, "skills");
-        try {
-            const stat = await fs.stat(skillsDir);
-            if (stat.isDirectory()) {
-                const files = await fs.readdir(skillsDir);
-                const mdFiles = files.filter((f) => f.endsWith(".md"));
-                for (const file of mdFiles) {
-                    const content = await fs.readFile(path.join(skillsDir, file), "utf-8");
-                    const result = agentSkillPlugin.validate(content, file);
-                    if (!result.valid) {
-                        errors.push(...result.errors.map((e) => `[skills/${file}] ${e}`));
-                    }
+                else if (plugin.name === "tool") {
+                    // Track valid tool contents for impl cross-matching
+                    validToolContents.set(relPath, content);
                 }
             }
         }
-        catch {
-            // skills/ is optional, skip if not exists
-        }
-        // Check mcp.json (optional)
-        const mcpPath = path.join(dirPath, "mcp.json");
-        try {
-            const content = await fs.readFile(mcpPath, "utf-8");
-            const result = mcpPlugin.validate(content, "mcp.json");
-            if (!result.valid) {
-                errors.push(...result.errors.map((e) => `[mcp.json] ${e}`));
-            }
-        }
-        catch {
-            // mcp.json is optional, skip if not exists
+        // tools/ + tool-impls/ cross-matching (special logic)
+        if (validToolContents.size > 0) {
+            await validateToolImpls(dirPath, validToolContents, errors);
         }
         return { valid: errors.length === 0, errors };
     },

package/dist/validator/plugins/agent-skill.js

@@ -11,20 +11,24 @@ export const agentSkillPlugin = {
             parsed = matter(content);
         }
         catch {
-            return { valid: false, errors: ["Invalid frontmatter syntax"] };
+            return { valid: false, errors: [{ message: "Invalid frontmatter syntax", severity: "error" }] };
         }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            errors.push("Missing frontmatter (---) block");
+            errors.push({ message: "Missing frontmatter (---) block", severity: "error" });
         }
         else {
             const result = agentSkillFrontmatterSchema.safeParse(parsed.data);
             if (!result.success) {
-                const schemaErrors = formatZodErrors(result.error).map((e) => `frontmatter${e}`);
+                const schemaErrors = formatZodErrors(result.error, parsed.data).map((e) => ({
+                    ...e,
+                    message: `frontmatter${e.message}`,
+                    path: e.path ? `frontmatter${e.path}` : e.path,
+                }));
                 errors.push(...schemaErrors);
             }
         }
         if (!parsed.content.trim()) {
-            errors.push("Skill body content is empty");
+            errors.push({ message: "Skill body content is empty", severity: "error" });
         }
         return { valid: errors.length === 0, errors };
     },

package/dist/validator/plugins/dataset.js

@@ -9,11 +9,11 @@ export const datasetPlugin = {
             data = JSON.parse(content);
         }
         catch {
-            return { valid: false, errors: ["Invalid JSON"] };
+            return { valid: false, errors: [{ message: "Invalid JSON", severity: "error" }] };
         }
         const result = datasetSchema.safeParse(data);
         if (!result.success) {
-            return { valid: false, errors: formatZodErrors(result.error) };
+            return { valid: false, errors: formatZodErrors(result.error, data, content) };
         }
         return { valid: true, errors: [] };
     },

package/dist/validator/plugins/mcp.js

@@ -9,11 +9,11 @@ export const mcpPlugin = {
             data = JSON.parse(content);
         }
         catch {
-            return { valid: false, errors: ["Invalid JSON"] };
+            return { valid: false, errors: [{ message: "Invalid JSON", severity: "error" }] };
         }
         const result = mcpConfigSchema.safeParse(data);
         if (!result.success) {
-            return { valid: false, errors: formatZodErrors(result.error) };
+            return { valid: false, errors: formatZodErrors(result.error, data, content) };
         }
         return { valid: true, errors: [] };
     },

package/dist/validator/plugins/model.js

@@ -3,17 +3,18 @@ import { formatZodErrors } from "../zod-utils.js";
 export const modelPlugin = {
     name: "model",
     pattern: "model.json",
+    required: true,
     validate(content, _fileName) {
         let data;
         try {
             data = JSON.parse(content);
         }
         catch {
-            return { valid: false, errors: ["Invalid JSON"] };
+            return { valid: false, errors: [{ message: "Invalid JSON", severity: "error" }] };
         }
         const result = modelConfigSchema.safeParse(data);
         if (!result.success) {
-            return { valid: false, errors: formatZodErrors(result.error) };
+            return { valid: false, errors: formatZodErrors(result.error, data, content) };
         }
         return { valid: true, errors: [] };
     },

package/dist/validator/plugins/system-prompt.js

@@ -3,10 +3,11 @@ const liquid = new Liquid({ strictVariables: false, strictFilters: true });
 export const systemPromptPlugin = {
     name: "system-prompt",
     pattern: "system-prompt.md",
+    required: true,
     validate(content, _fileName) {
         const errors = [];
         if (!content.trim()) {
-            errors.push("System prompt content is empty");
+            errors.push({ message: "System prompt content is empty", severity: "error" });
             return { valid: false, errors };
         }
         // Validate Liquid template syntax if template tags are present
@@ -17,7 +18,7 @@ export const systemPromptPlugin = {
             }
             catch (e) {
                 const msg = e instanceof Error ? e.message : String(e);
-                errors.push(`Liquid template syntax error: ${msg}`);
+                errors.push({ message: `Liquid template syntax error: ${msg}`, severity: "error" });
             }
         }
         return { valid: errors.length === 0, errors };

package/dist/validator/plugins/tool.js

@@ -9,11 +9,11 @@ export const toolPlugin = {
             data = JSON.parse(content);
         }
         catch {
-            return { valid: false, errors: ["Invalid JSON"] };
+            return { valid: false, errors: [{ message: "Invalid JSON", severity: "error" }] };
         }
         const result = toolSchemaSchema.safeParse(data);
         if (!result.success) {
-            return { valid: false, errors: formatZodErrors(result.error) };
+            return { valid: false, errors: formatZodErrors(result.error, data, content) };
         }
         return { valid: true, errors: [] };
     },

package/dist/validator/zod-utils.d.ts

@@ -1,3 +1,10 @@
 import type { ZodError } from "zod";
-/** Format Zod errors to match the AJV-style output: `/{path} {message}` */
-export declare function formatZodErrors(error: ZodError): string[];
+import type { ValidationError } from "./plugin.js";
+/**
+ * Given a raw JSON string, find the 1-based line number where a key at
+ * the given path (e.g. ["provider"] or ["input_schema", "type"]) appears.
+ * Returns undefined if the key cannot be located.
+ */
+export declare function getLineForPath(jsonString: string, pathSegments: (string | number)[]): number | undefined;
+/** Format Zod errors into structured ValidationError objects */
+export declare function formatZodErrors(error: ZodError, data?: unknown, rawJson?: string): ValidationError[];

package/dist/validator/zod-utils.js

@@ -1,7 +1,96 @@
-/** Format Zod errors to match the AJV-style output: `/{path} {message}` */
-export function formatZodErrors(error) {
+/** Traverse an object using a path array to get the value at that path */
+function getValueAtPath(data, path) {
+    let current = data;
+    for (const key of path) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** Extract expected/received from a Zod issue based on its code */
+function extractDetails(issue, data) {
+    const result = {};
+    switch (issue.code) {
+        case "invalid_enum_value":
+            result.expected = issue.options?.join(" | ");
+            result.received = String(issue.received);
+            break;
+        case "too_big":
+            result.expected = `<= ${issue.maximum}`;
+            result.received = String(issue.value ?? "");
+            break;
+        case "too_small":
+            result.expected = `>= ${issue.minimum}`;
+            result.received = String(issue.value ?? "");
+            break;
+        case "invalid_string": {
+            const validation = issue.validation;
+            if (typeof validation === "object" && validation !== null && "regex" in validation) {
+                result.expected = `regex: ${validation.regex}`;
+            }
+            else {
+                result.expected = `${validation}`;
+            }
+            // Zod doesn't include received for invalid_string — look up from original data
+            const issueReceived = issue.received;
+            if (issueReceived !== undefined) {
+                result.received = String(issueReceived);
+            }
+            else if (data !== undefined) {
+                const val = getValueAtPath(data, issue.path);
+                if (val !== undefined) {
+                    result.received = String(val);
+                }
+            }
+            break;
+        }
+        case "invalid_type":
+            result.expected = String(issue.expected);
+            result.received = String(issue.received);
+            break;
+        case "unrecognized_keys":
+            result.received = issue.keys?.join(", ");
+            break;
+    }
+    return result;
+}
+/**
+ * Given a raw JSON string, find the 1-based line number where a key at
+ * the given path (e.g. ["provider"] or ["input_schema", "type"]) appears.
+ * Returns undefined if the key cannot be located.
+ */
+export function getLineForPath(jsonString, pathSegments) {
+    if (pathSegments.length === 0)
+        return undefined;
+    const lastKey = pathSegments[pathSegments.length - 1];
+    if (typeof lastKey === "number")
+        return undefined;
+    // Build a regex that matches `"key":` — we search for the last segment
+    const escaped = lastKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`"${escaped}"\\s*:`);
+    const lines = jsonString.split("\n");
+    // For simple (flat) paths, find the first occurrence
+    // For nested paths, we'd need smarter logic, but for typical JSON configs this works
+    for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i])) {
+            return i + 1; // 1-based
+        }
+    }
+    return undefined;
+}
+/** Format Zod errors into structured ValidationError objects */
+export function formatZodErrors(error, data, rawJson) {
     return error.issues.map((issue) => {
         const path = issue.path.length > 0 ? `/${issue.path.join("/")}` : "/";
-        return `${path} ${issue.message}`;
+        const details = extractDetails(issue, data);
+        const line = rawJson ? getLineForPath(rawJson, issue.path) : undefined;
+        return {
+            message: `${path} ${issue.message}`,
+            severity: "error",
+            path,
+            ...details,
+            ...(line !== undefined ? { line } : {}),
+        };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archon-claw/cli",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "AI Agent CLI",
   "type": "module",
   "bin": {
@@ -8,10 +8,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && cp -r templates dist/ && rm -rf dist/public && cp -r ../web/dist dist/public",
-    "dev": "tsx src/cli.ts start ../../agents/my-agent",
+    "dev": "tsx src/cli.ts start examples/my-agent",
     "start": "node dist/cli.js",
-    "test": "vitest run --exclude dist",
-    "test:watch": "vitest --exclude dist"
+    "test": "vitest run --exclude dist --exclude examples",
+    "test:watch": "vitest --exclude dist --exclude examples",
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui"
   },
   "files": [
     "dist"
@@ -21,6 +23,8 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@archon-claw/web": "workspace:*",
+    "@playwright/test": "^1.58.2",
     "@types/node": "^25.3.3",
     "@types/picomatch": "^4.0.2",
     "@vitest/coverage-v8": "^4.0.18",
@@ -29,12 +33,13 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@archon-claw/web": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "dotenv": "^17.3.1",
     "gray-matter": "^4.0.3",
     "liquidjs": "^10.24.0",
+    "open": "^10.2.0",
     "openai": "^6.25.0",
     "picomatch": "^4.0.3",
     "zod": "^3.24.0"