@archon-claw/cli 0.0.2

package/dist/agent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig, SSEEvent, Session } from "./types.js";
+export declare function runAgentLoop(config: AgentConfig, session: Session, userMessage: string, emit: (event: SSEEvent) => void, hostContext?: Record<string, unknown> | null): Promise<void>;

package/dist/agent.js

@@ -0,0 +1,152 @@
+import { createClient, toOpenAITools, streamChat } from "./llm.js";
+import { waitForToolResult } from "./pending-tool-results.js";
+const MAX_ITERATIONS = 20;
+function buildToolTargets(tools) {
+    const map = new Map();
+    for (const t of tools) {
+        map.set(t.name, {
+            target: (t.execution_target ?? "server"),
+            handler: t.handler,
+        });
+    }
+    return map;
+}
+export async function runAgentLoop(config, session, userMessage, emit, hostContext) {
+    const client = createClient(config.model);
+    const openAITools = toOpenAITools(config.tools);
+    const toolTargets = buildToolTargets(config.tools);
+    // Add system prompt on first message
+    if (session.messages.length === 0) {
+        let systemPrompt = config.systemPrompt;
+        if (hostContext && Object.keys(hostContext).length > 0) {
+            systemPrompt += `\n\n<host-context>\n${JSON.stringify(hostContext, null, 2)}\n</host-context>`;
+        }
+        session.messages.push({ role: "system", content: systemPrompt });
+    }
+    // Add user message
+    session.messages.push({ role: "user", content: userMessage });
+    // Emit tools_config for client/host tools and tools with custom UIs
+    const configuredTools = config.tools
+        .filter((t) => t.execution_target === "client" || t.execution_target === "host" || config.toolUIs.has(t.name))
+        .map((t) => ({
+        name: t.name,
+        handler: t.handler,
+        executionTarget: t.execution_target ?? "server",
+        component: config.toolUIs.has(t.name) ? t.name : undefined,
+    }));
+    if (configuredTools.length > 0) {
+        emit({ type: "tools_config", tools: configuredTools });
+    }
+    let completed = false;
+    for (let i = 0; i < MAX_ITERATIONS; i++) {
+        const stream = streamChat(client, config.model, session.messages, openAITools);
+        let textContent = "";
+        const toolCalls = new Map();
+        for await (const chunk of stream) {
+            const delta = chunk.choices[0]?.delta;
+            if (!delta)
+                continue;
+            // Accumulate text
+            if (delta.content) {
+                textContent += delta.content;
+                emit({ type: "text", content: delta.content });
+            }
+            // Accumulate tool calls (streamed in fragments by index)
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    const existing = toolCalls.get(tc.index);
+                    if (existing) {
+                        if (tc.function?.arguments) {
+                            existing.args += tc.function.arguments;
+                        }
+                    }
+                    else {
+                        toolCalls.set(tc.index, {
+                            id: tc.id ?? "",
+                            name: tc.function?.name ?? "",
+                            args: tc.function?.arguments ?? "",
+                        });
+                    }
+                }
+            }
+        }
+        // Build assistant message
+        const assistantToolCalls = [...toolCalls.values()].map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: { name: tc.name, arguments: tc.args },
+        }));
+        const assistantMessage = assistantToolCalls.length > 0
+            ? { role: "assistant", content: textContent || null, tool_calls: assistantToolCalls }
+            : { role: "assistant", content: textContent };
+        session.messages.push(assistantMessage);
+        // No tool calls — done
+        if (assistantToolCalls.length === 0) {
+            completed = true;
+            break;
+        }
+        // Execute each tool call
+        for (const tc of assistantToolCalls) {
+            let args;
+            try {
+                args = JSON.parse(tc.function.arguments);
+            }
+            catch {
+                const result = { error: `Invalid JSON in tool arguments: ${tc.function.arguments}` };
+                emit({ type: "tool_result", name: tc.function.name, result, toolCallId: tc.id });
+                session.messages.push({
+                    role: "tool",
+                    tool_call_id: tc.id,
+                    content: JSON.stringify(result),
+                });
+                continue;
+            }
+            const targetInfo = toolTargets.get(tc.function.name);
+            const target = targetInfo?.target ?? "server";
+            let result;
+            if (target === "server") {
+                // Server execution: use local impl
+                emit({ type: "tool_call", name: tc.function.name, args, toolCallId: tc.id });
+                const impl = config.toolImpls.get(tc.function.name);
+                if (impl) {
+                    try {
+                        result = await impl(args);
+                    }
+                    catch (err) {
+                        result = { error: err instanceof Error ? err.message : String(err) };
+                    }
+                }
+                else {
+                    result = { error: `Unknown tool: ${tc.function.name}` };
+                }
+            }
+            else {
+                // Client or Host execution: emit tool_call with target and wait for result
+                emit({
+                    type: "tool_call",
+                    name: tc.function.name,
+                    args,
+                    toolCallId: tc.id,
+                    executionTarget: target,
+                });
+                try {
+                    result = await waitForToolResult(tc.id);
+                }
+                catch (err) {
+                    result = { error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+            emit({ type: "tool_result", name: tc.function.name, result, toolCallId: tc.id });
+            session.messages.push({
+                role: "tool",
+                tool_call_id: tc.id,
+                content: JSON.stringify(result),
+            });
+        }
+        // Continue loop — LLM will see tool results and generate next response
+    }
+    if (!completed) {
+        emit({ type: "error", message: `Agent stopped: reached maximum iterations (${MAX_ITERATIONS})` });
+    }
+    emit({ type: "done", sessionId: session.id });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "url";
+import path from "path";
+import { readFileSync } from "fs";
+import dotenv from "dotenv";
+import { Command } from "commander";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { loadAgentConfig } from "./config.js";
+import { createServer } from "./server.js";
+import { initSessionStore } from "./session.js";
+import { runToolTests, formatResults } from "./test-runner.js";
+import { runEvals } from "./eval/runner.js";
+import { scaffoldAgent, scaffoldWorkspace } from "./scaffold.js";
+const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "../package.json"), "utf-8"));
+const program = new Command();
+program
+    .name("archon-claw")
+    .description("AI Agent CLI")
+    .version(pkg.version)
+    .option("-e, --env-file <path>", "Path to .env file (default: .env in cwd)")
+    .hook("preAction", () => {
+    const envPath = program.opts().envFile
+        ? path.resolve(program.opts().envFile)
+        : path.resolve(process.cwd(), ".env");
+    dotenv.config({ path: envPath });
+});
+program
+    .command("chat")
+    .description("Start an agent chat session")
+    .action(() => {
+    console.log("Starting agent...");
+});
+program
+    .command("start")
+    .description("Start an agent HTTP server")
+    .argument("<agent-dir>", "Path to agent directory")
+    .option("-p, --port <port>", "Server port", "4000")
+    .action(async (agentDir, opts) => {
+    try {
+        const config = await loadAgentConfig(agentDir);
+        await initSessionStore(agentDir);
+        const port = parseInt(opts.port, 10);
+        console.log(`Agent loaded:`);
+        console.log(`  Model: ${config.model.provider}/${config.model.model}`);
+        console.log(`  Tools: ${config.tools.map((t) => t.name).join(", ")}`);
+        if (config.mcpManager) {
+            const servers = config.mcpManager.getServerNames();
+            console.log(`  MCP servers: ${servers.join(", ")}`);
+        }
+        console.log(`  Skills: ${Object.keys(config.skills).join(", ") || "(none)"}`);
+        console.log(`  System prompt: ${config.systemPrompt.length} chars`);
+        const server = createServer(config, port);
+        const shutdown = async () => {
+            console.log("\nShutting down...");
+            await config.mcpManager?.shutdown();
+            server.close(() => process.exit(0));
+            // Force exit if server hasn't closed within 3s
+            setTimeout(() => process.exit(1), 3000).unref();
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command("test")
+    .description("Run tool implementation tests")
+    .argument("<agent-dir>", "Path to agent directory")
+    .action(async (agentDir) => {
+    try {
+        const results = await runToolTests(agentDir);
+        if (results.length === 0) {
+            console.log("No test files found (*.test.js in tool-impls/)");
+            return;
+        }
+        console.log(formatResults(results));
+        const failed = results.some((t) => t.results.some((r) => !r.passed));
+        if (failed)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command("eval")
+    .description("Run agent evaluation cases")
+    .argument("<agent-dir>", "Path to agent directory")
+    .option("-f, --file <file>", "Only run a specific .eval.json file")
+    .option("-t, --tag <tag>", "Only run cases with this tag")
+    .option("-s, --save", "Save results to eval-results/")
+    .option("--no-judge", "Skip judge evaluation")
+    .action(async (agentDir, opts) => {
+    try {
+        const { summary, formatted } = await runEvals(agentDir, {
+            file: opts.file,
+            tag: opts.tag,
+            save: opts.save,
+            noJudge: opts.judge === false,
+        });
+        console.log(formatted);
+        if (summary.failed > 0)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command("init")
+    .description("Initialise an agent workspace with shared .claude/ skills")
+    .argument("[dir]", "Directory to initialise", "./agents")
+    .action(async (dir) => {
+    try {
+        await scaffoldWorkspace(dir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command("create")
+    .description("Create a new agent project")
+    .argument("<agent-name>", "Name of the agent (used as directory name)")
+    .option("-d, --dir <path>", "Parent directory for the agent", "./agents")
+    .action(async (agentName, opts) => {
+    try {
+        await scaffoldAgent(agentName, opts.dir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "./types.js";
+export declare function loadAgentConfig(agentDir: string): Promise<AgentConfig>;

package/dist/config.js

@@ -0,0 +1,161 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Liquid } from "liquidjs";
+import matter from "gray-matter";
+import { validateDir } from "./validator/index.js";
+import { mcpConfigSchema } from "./schemas.js";
+import { McpManager } from "./mcp-manager.js";
+export async function loadAgentConfig(agentDir) {
+    const absDir = path.resolve(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")}`);
+    }
+    // Load model.json
+    const modelRaw = await fs.readFile(path.join(absDir, "model.json"), "utf-8");
+    const model = JSON.parse(modelRaw);
+    // Load datasets
+    const datasets = {};
+    const datasetsDir = path.join(absDir, "datasets");
+    try {
+        const files = await fs.readdir(datasetsDir);
+        const jsonFiles = files.filter((f) => f.endsWith(".json"));
+        const loaded = await Promise.all(jsonFiles.map(async (file) => ({
+            name: file.replace(/\.json$/, ""),
+            content: await fs.readFile(path.join(datasetsDir, file), "utf-8"),
+        })));
+        for (const { name, content } of loaded) {
+            datasets[name] = JSON.parse(content);
+        }
+    }
+    catch {
+        // datasets/ is optional
+    }
+    // Load skills (optional)
+    const skills = {};
+    const skillsMeta = [];
+    const skillsDir = path.join(absDir, "skills");
+    try {
+        const files = await fs.readdir(skillsDir);
+        const mdFiles = files.filter((f) => f.endsWith(".md"));
+        const loaded = await Promise.all(mdFiles.map(async (file) => ({
+            key: file.replace(/\.md$/, ""),
+            content: await fs.readFile(path.join(skillsDir, file), "utf-8"),
+        })));
+        for (const { key, content } of loaded) {
+            const { data, content: body } = matter(content);
+            skills[key] = body.trim();
+            if (data.name && data.description) {
+                skillsMeta.push({ name: data.name, description: data.description });
+            }
+        }
+    }
+    catch {
+        // skills/ is optional
+    }
+    // Load tool schemas
+    const toolsDir = path.join(absDir, "tools");
+    const toolFiles = (await fs.readdir(toolsDir)).filter((f) => f.endsWith(".json"));
+    const tools = await Promise.all(toolFiles.map(async (file) => {
+        const content = await fs.readFile(path.join(toolsDir, file), "utf-8");
+        return JSON.parse(content);
+    }));
+    // Build set of tools that don't need server-side implementations
+    const nonServerToolNames = new Set(tools
+        .filter((t) => t.execution_target === "client" || t.execution_target === "host")
+        .map((t) => t.name));
+    // Load tool implementations (only for server tools)
+    const toolImpls = new Map();
+    const implsDir = path.join(absDir, "tool-impls");
+    try {
+        const implFiles = (await fs.readdir(implsDir)).filter((f) => f.endsWith(".impl.js"));
+        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);
+            return [name, mod.default];
+        }));
+        for (const [name, impl] of implEntries) {
+            toolImpls.set(name, impl);
+        }
+    }
+    catch {
+        // tool-impls/ may not exist if all tools are client/host
+        if (tools.length > nonServerToolNames.size) {
+            throw new Error("Missing required directory: tool-impls/");
+        }
+    }
+    // Load MCP servers (optional)
+    let mcpManager;
+    try {
+        const mcpRaw = await fs.readFile(path.join(absDir, "mcp.json"), "utf-8");
+        const mcpData = JSON.parse(mcpRaw);
+        const mcpConfig = mcpConfigSchema.parse(mcpData);
+        mcpManager = new McpManager(mcpConfig);
+        await mcpManager.initialize();
+        // Merge MCP tools into tools + toolImpls
+        const localToolNames = new Set(tools.map((t) => t.name));
+        for (const mcpTool of mcpManager.getTools()) {
+            if (localToolNames.has(mcpTool.name)) {
+                console.warn(`[mcp] Skipping tool "${mcpTool.name}" — conflicts with local tool`);
+                continue;
+            }
+            tools.push(mcpTool);
+            const toolName = mcpTool.name;
+            toolImpls.set(toolName, async (args) => mcpManager.callTool(toolName, args));
+        }
+    }
+    catch (err) {
+        const isNotFound = err instanceof Error && "code" in err && err.code === "ENOENT";
+        if (!isNotFound)
+            throw err;
+        // mcp.json not found — that's fine
+    }
+    // Scan tool-uis/ for custom UI components
+    const toolUIs = new Set();
+    const toolUIsDir = path.join(absDir, "tool-uis");
+    try {
+        const uiFiles = (await fs.readdir(toolUIsDir)).filter((f) => f.endsWith(".ui.js"));
+        const toolNames = new Set(tools.map((t) => t.name));
+        for (const file of uiFiles) {
+            const name = file.replace(/\.ui\.js$/, "");
+            if (toolNames.has(name)) {
+                toolUIs.add(name);
+            }
+        }
+    }
+    catch {
+        // tool-uis/ is optional
+    }
+    // Build tool template variables: tools (array) + tool (map by name)
+    const toolsMeta = tools.map((t) => ({ name: t.name, description: t.description }));
+    const toolMap = {};
+    for (const t of toolsMeta) {
+        toolMap[t.name] = t;
+    }
+    // Build mcp template variable: mcp.{serverName}.tools/tool + mcp.servers
+    const mcpVar = { servers: [] };
+    if (mcpManager) {
+        const byServer = mcpManager.getToolsByServer();
+        const servers = [];
+        for (const serverName of mcpManager.getServerNames()) {
+            const serverTools = byServer[serverName] ?? [];
+            const serverToolMap = {};
+            for (const t of serverTools) {
+                serverToolMap[t.name] = t;
+            }
+            const serverObj = { name: serverName, tools: serverTools, tool: serverToolMap };
+            mcpVar[serverName] = serverObj;
+            servers.push(serverObj);
+        }
+        mcpVar.servers = servers;
+    }
+    // Load and render system prompt (after tools/MCP so they're available in template)
+    const promptRaw = await fs.readFile(path.join(absDir, "system-prompt.md"), "utf-8");
+    const engine = new Liquid();
+    const templateVars = { ...datasets, skills: skillsMeta, tools: toolsMeta, tool: toolMap, mcp: mcpVar };
+    const systemPrompt = (await engine.parseAndRender(promptRaw, templateVars)).trim();
+    return { systemPrompt, model: model, tools, toolImpls, skills, mcpManager, agentDir: absDir, toolUIs };
+}

package/dist/eval/assertions.d.ts

@@ -0,0 +1,9 @@
+import type { Assertion, AssertionResult, ToolCallRecord } from "./types.js";
+/**
+ * Run a single assertion against a response text and tool calls.
+ */
+export declare function runAssertion(assertion: Assertion, responseText: string, toolCalls: ToolCallRecord[]): AssertionResult;
+/**
+ * Run multiple assertions and return all results.
+ */
+export declare function runAssertions(assertions: Assertion[], responseText: string, toolCalls: ToolCallRecord[]): AssertionResult[];

package/dist/eval/assertions.js

@@ -0,0 +1,137 @@
+/**
+ * Run a single assertion against a response text and tool calls.
+ */
+export function runAssertion(assertion, responseText, toolCalls) {
+    const { type, value } = assertion;
+    switch (type) {
+        case "contains":
+            return {
+                type,
+                value,
+                passed: responseText.toLowerCase().includes(value.toLowerCase()),
+                message: responseText.toLowerCase().includes(value.toLowerCase())
+                    ? undefined
+                    : `"${value}" not found in response`,
+            };
+        case "not-contains":
+            return {
+                type,
+                value,
+                passed: !responseText.toLowerCase().includes(value.toLowerCase()),
+                message: !responseText.toLowerCase().includes(value.toLowerCase())
+                    ? undefined
+                    : `"${value}" found in response`,
+            };
+        case "regex": {
+            const re = new RegExp(value);
+            const matched = re.test(responseText);
+            return {
+                type,
+                value,
+                passed: matched,
+                message: matched ? undefined : `regex /${value}/ did not match`,
+            };
+        }
+        case "length-min": {
+            const min = parseInt(value, 10);
+            const passed = responseText.length >= min;
+            return {
+                type,
+                value,
+                passed,
+                message: passed ? undefined : `response length ${responseText.length} < ${min}`,
+            };
+        }
+        case "length-max": {
+            const max = parseInt(value, 10);
+            const passed = responseText.length <= max;
+            return {
+                type,
+                value,
+                passed,
+                message: passed ? undefined : `response length ${responseText.length} > ${max}`,
+            };
+        }
+        case "json-valid": {
+            let passed = false;
+            try {
+                JSON.parse(responseText);
+                passed = true;
+            }
+            catch {
+                // not valid JSON
+            }
+            return {
+                type,
+                value,
+                passed,
+                message: passed ? undefined : "response is not valid JSON",
+            };
+        }
+        case "tool-called": {
+            const called = toolCalls.some((tc) => tc.name === value);
+            return {
+                type,
+                value,
+                passed: called,
+                message: called ? undefined : `tool "${value}" was not called`,
+            };
+        }
+        case "tool-not-called": {
+            const called = toolCalls.some((tc) => tc.name === value);
+            return {
+                type,
+                value,
+                passed: !called,
+                message: !called ? undefined : `tool "${value}" was called`,
+            };
+        }
+        case "tool-called-with": {
+            const spec = JSON.parse(value);
+            const match = toolCalls.find((tc) => {
+                if (tc.name !== spec.tool)
+                    return false;
+                return objectContains(tc.args, spec.args);
+            });
+            return {
+                type,
+                value,
+                passed: !!match,
+                message: match
+                    ? undefined
+                    : `tool "${spec.tool}" was not called with matching args`,
+            };
+        }
+        default:
+            return {
+                type,
+                value,
+                passed: false,
+                message: `unknown assertion type: ${type}`,
+            };
+    }
+}
+/**
+ * Run multiple assertions and return all results.
+ */
+export function runAssertions(assertions, responseText, toolCalls) {
+    return assertions.map((a) => runAssertion(a, responseText, toolCalls));
+}
+/**
+ * Check if `obj` contains all key-value pairs from `subset` (shallow).
+ */
+function objectContains(obj, subset) {
+    for (const [key, val] of Object.entries(subset)) {
+        if (typeof val === "object" && val !== null) {
+            if (typeof obj[key] !== "object" || obj[key] === null)
+                return false;
+            if (!objectContains(obj[key], val)) {
+                return false;
+            }
+        }
+        else if (obj[key] !== val) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/eval/execute.d.ts

@@ -0,0 +1,13 @@
+import type { AgentConfig, ChatMessage } from "../types.js";
+import type { EvalCase, CaseResult, JudgeResult } from "./types.js";
+interface ExecuteOptions {
+    config: AgentConfig;
+    evalCase: EvalCase;
+    fileName: string;
+    judgeRunner?: (userInput: string, expectedOutput: string | undefined, actualResponse: string, conversation: ChatMessage[]) => Promise<JudgeResult>;
+}
+/**
+ * Execute a single eval case, dispatching to the appropriate mode.
+ */
+export declare function executeCase(opts: ExecuteOptions): Promise<CaseResult>;
+export {};