@alejandroroman/agent-kit 0.1.0

package/dist/llm/openai.js

@@ -0,0 +1,85 @@
+import OpenAI from "openai";
+import { defaultStream } from "./provider.js";
+export class OpenAIProvider {
+    name = "openai";
+    client;
+    constructor(apiKey) {
+        this.client = new OpenAI({ apiKey: apiKey ?? process.env.OPENAI_API_KEY });
+    }
+    async complete(model, messages, options) {
+        const params = {
+            model,
+            max_completion_tokens: options?.maxTokens ?? 4096,
+            messages: this.toOpenAIMessages(messages, options?.systemPrompt),
+        };
+        if (options?.tools?.length) {
+            params.tools = options.tools.map((t) => ({
+                type: "function",
+                function: { name: t.name, description: t.description, parameters: t.parameters },
+            }));
+        }
+        const response = await this.client.chat.completions.create(params);
+        return this.fromOpenAIResponse(response);
+    }
+    async *stream(model, messages, options) {
+        yield* defaultStream(this, model, messages, options);
+    }
+    toOpenAIMessages(messages, systemPrompt) {
+        const result = [];
+        if (systemPrompt)
+            result.push({ role: "system", content: systemPrompt });
+        for (const msg of messages) {
+            if (msg.role === "user") {
+                result.push({ role: "user", content: msg.content });
+            }
+            else if (msg.role === "assistant") {
+                const textParts = msg.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+                const toolCalls = msg.content.filter((b) => b.type === "tool_call").map((b) => ({
+                    id: b.id, type: "function", function: { name: b.name, arguments: JSON.stringify(b.arguments) },
+                }));
+                const openaiMsg = { role: "assistant" };
+                if (textParts)
+                    openaiMsg.content = textParts;
+                if (toolCalls.length)
+                    openaiMsg.tool_calls = toolCalls;
+                result.push(openaiMsg);
+            }
+            else if (msg.role === "tool_result") {
+                result.push({ role: "tool", tool_call_id: msg.tool_call_id, content: msg.content });
+            }
+        }
+        return result;
+    }
+    fromOpenAIResponse(response) {
+        const choice = response.choices[0];
+        const content = [];
+        if (choice.message.content)
+            content.push({ type: "text", text: choice.message.content });
+        if (choice.message.tool_calls) {
+            for (const tc of choice.message.tool_calls) {
+                content.push({ type: "tool_call", id: tc.id, name: tc.function.name, arguments: JSON.parse(tc.function.arguments) });
+            }
+        }
+        return {
+            content,
+            stopReason: this.mapStopReason(choice.finish_reason),
+            usage: {
+                inputTokens: response.usage?.prompt_tokens ?? 0,
+                outputTokens: response.usage?.completion_tokens ?? 0,
+                cacheCreationTokens: 0,
+                cacheReadTokens: response.usage?.prompt_tokens_details?.cached_tokens ?? 0,
+                reasoningTokens: response.usage?.completion_tokens_details?.reasoning_tokens ?? 0,
+            },
+            model: "",
+            latencyMs: 0,
+        };
+    }
+    mapStopReason(reason) {
+        switch (reason) {
+            case "stop": return "end_turn";
+            case "tool_calls": return "tool_use";
+            case "length": return "max_tokens";
+            default: return "end_turn";
+        }
+    }
+}

package/dist/llm/provider.d.ts

@@ -0,0 +1,12 @@
+import type { Message, ToolDefinition, LLMResponse, StreamEvent } from "./types.js";
+export interface CompleteOptions {
+    systemPrompt?: string;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+}
+export interface LLMProvider {
+    name: string;
+    complete(model: string, messages: Message[], options?: CompleteOptions): Promise<LLMResponse>;
+    stream(model: string, messages: Message[], options?: CompleteOptions): AsyncIterable<StreamEvent>;
+}
+export declare function defaultStream(provider: LLMProvider, model: string, messages: Message[], options?: CompleteOptions): AsyncIterable<StreamEvent>;

package/dist/llm/provider.js

@@ -0,0 +1,9 @@
+export async function* defaultStream(provider, model, messages, options) {
+    const response = await provider.complete(model, messages, options);
+    for (const block of response.content) {
+        if (block.type === "text") {
+            yield { type: "text_delta", delta: block.text };
+        }
+    }
+    yield { type: "done", response };
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,73 @@
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+export interface ToolCallBlock {
+    type: "tool_call";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export type ContentBlock = TextBlock | ToolCallBlock;
+export interface UserMessage {
+    role: "user";
+    content: string;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: ContentBlock[];
+}
+export interface ToolResultMessage {
+    role: "tool_result";
+    tool_call_id: string;
+    content: string;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export type StopReason = "end_turn" | "tool_use" | "max_tokens" | "error";
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    reasoningTokens: number;
+}
+export interface LLMResponse {
+    content: ContentBlock[];
+    stopReason: StopReason;
+    usage: TokenUsage;
+    model: string;
+    latencyMs: number;
+}
+export interface TextDeltaEvent {
+    type: "text_delta";
+    delta: string;
+}
+export interface ToolCallStartEvent {
+    type: "tool_call_start";
+    id: string;
+    name: string;
+}
+export interface ToolCallDeltaEvent {
+    type: "tool_call_delta";
+    id: string;
+    delta: string;
+}
+export interface DoneEvent {
+    type: "done";
+    response: LLMResponse;
+}
+export interface ErrorEvent {
+    type: "error";
+    error: string;
+}
+export type StreamEvent = TextDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | DoneEvent | ErrorEvent;
+export declare function extractText(content: ContentBlock[]): string;

package/dist/llm/types.js

@@ -0,0 +1,6 @@
+export function extractText(content) {
+    return content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+import pino from "pino";
+export declare function createLogger(name: string): pino.Logger<never, boolean>;

package/dist/logger.js

@@ -0,0 +1,15 @@
+import pino from "pino";
+const root = pino({
+    level: process.env.LOG_LEVEL ?? "info",
+    transport: {
+        target: "pino-pretty",
+        options: {
+            ignore: "pid,hostname",
+            translateTime: "HH:MM:ss",
+            colorize: true,
+        },
+    },
+});
+export function createLogger(name) {
+    return root.child({ component: name });
+}

package/dist/multi/registry.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from "../config/schema.js";
+export interface AgentEntry {
+    name: string;
+    model: string;
+    tools: string[];
+    soul?: string;
+    spawn_only: boolean;
+}
+export declare class AgentRegistry {
+    private agents;
+    constructor(config: Config, dataDir: string);
+    getAgent(name: string): AgentEntry | undefined;
+    listAgents(): string[];
+    listAll(): string[];
+}

package/dist/multi/registry.js

@@ -0,0 +1,28 @@
+import { loadSoul } from "../agent/soul.js";
+import * as path from "path";
+export class AgentRegistry {
+    agents = new Map();
+    constructor(config, dataDir) {
+        for (const [name, agentDef] of Object.entries(config.agents)) {
+            const agentDir = path.join(dataDir, "agents", name);
+            this.agents.set(name, {
+                name,
+                model: agentDef.model ?? config.defaults.model,
+                tools: agentDef.tools,
+                soul: loadSoul(agentDir),
+                spawn_only: agentDef.spawn_only,
+            });
+        }
+    }
+    getAgent(name) {
+        return this.agents.get(name);
+    }
+    listAgents() {
+        return [...this.agents.entries()]
+            .filter(([, entry]) => !entry.spawn_only)
+            .map(([name]) => name);
+    }
+    listAll() {
+        return [...this.agents.keys()];
+    }
+}

package/dist/multi/spawn.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from "../tools/types.js";
+import type { AgentResult } from "../agent/types.js";
+import type { UsageStore } from "../usage/store.js";
+export interface SpawnOptions {
+    model: string;
+    fallbacks?: string[];
+    systemPrompt?: string;
+    task: string;
+    tools?: Tool[];
+    maxIterations?: number;
+    label?: string;
+    usageStore?: UsageStore;
+}
+export declare function spawnAgent(options: SpawnOptions): Promise<AgentResult>;

package/dist/multi/spawn.js

@@ -0,0 +1,14 @@
+import { runAgentLoop } from "../agent/loop.js";
+export async function spawnAgent(options) {
+    return runAgentLoop([{ role: "user", content: options.task }], {
+        model: options.model,
+        fallbacks: options.fallbacks,
+        systemPrompt: options.systemPrompt,
+        tools: options.tools,
+        maxIterations: options.maxIterations ?? 10,
+        label: options.label,
+        agentName: options.label,
+        usageStore: options.usageStore,
+        source: "spawn",
+    });
+}

package/dist/scripts/validate-agent-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/validate-agent-cli.js

@@ -0,0 +1,47 @@
+import * as path from "path";
+import { loadConfig } from "../config/loader.js";
+import { validateAgent } from "./validate-agent.js";
+const PASS = "\u2713";
+const FAIL = "\u2717";
+const agentName = process.argv[2];
+if (!agentName) {
+    console.error(`Usage: agent:validate <agent-name>`);
+    process.exit(1);
+}
+// Load config
+let config;
+try {
+    config = loadConfig(path.resolve("agent-kit.json"));
+    console.log(`${PASS} Config loaded`);
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`${FAIL} Config failed to load: ${message}`);
+    process.exit(1);
+}
+// Validate agent
+let result;
+try {
+    result = validateAgent(agentName, config, {
+        skillsDir: path.resolve("skills"),
+        dataDir: path.resolve("data"),
+    });
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`${FAIL} Validator crashed unexpectedly: ${message}`);
+    process.exit(2);
+}
+for (const check of result.checks) {
+    const icon = check.passed ? PASS : FAIL;
+    console.log(`${icon} [${check.name}] ${check.message}`);
+}
+if (result.success) {
+    console.log("\nAll checks passed.");
+    process.exit(0);
+}
+else {
+    const errorCount = result.checks.filter((c) => !c.passed).length;
+    console.log(`\n${errorCount} error(s) found.`);
+    process.exit(1);
+}

package/dist/scripts/validate-agent.d.ts

@@ -0,0 +1,17 @@
+import type { Config } from "../config/schema.js";
+export declare const BUILTIN_TOOLS: readonly ["read_file", "write_file", "run_command", "web_search", "store_memory", "search_memory", "get_memory", "update_memory", "forget_memory", "list_memories"];
+export interface Check {
+    name: string;
+    passed: boolean;
+    message: string;
+}
+export interface ValidationResult {
+    agentName: string;
+    success: boolean;
+    checks: Check[];
+}
+export interface ValidateOptions {
+    skillsDir: string;
+    dataDir: string;
+}
+export declare function validateAgent(agentName: string, config: Config, options: ValidateOptions): ValidationResult;

package/dist/scripts/validate-agent.js

@@ -0,0 +1,242 @@
+import * as fs from "fs";
+import * as path from "path";
+import { loadSkillManifest } from "../skills/loader.js";
+// NOTE: This list must be kept in sync with src/tools/builtin/index.ts.
+// We hardcode it here to avoid importing the registry (which requires config to instantiate).
+export const BUILTIN_TOOLS = [
+    "read_file",
+    "write_file",
+    "run_command",
+    "web_search",
+    "store_memory",
+    "search_memory",
+    "get_memory",
+    "update_memory",
+    "forget_memory",
+    "list_memories",
+];
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+function findClosestTool(name) {
+    let best;
+    let bestDist = Infinity;
+    for (const tool of BUILTIN_TOOLS) {
+        const dist = levenshtein(name, tool);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = tool;
+        }
+    }
+    return bestDist <= 3 ? best : undefined;
+}
+export function validateAgent(agentName, config, options) {
+    const checks = [];
+    // agent-exists
+    const agentDef = config.agents[agentName];
+    if (!agentDef) {
+        checks.push({
+            name: "agent-exists",
+            passed: false,
+            message: `Agent "${agentName}" not found in config`,
+        });
+        return { agentName, success: false, checks };
+    }
+    checks.push({
+        name: "agent-exists",
+        passed: true,
+        message: `Agent "${agentName}" found in config`,
+    });
+    // model-resolves
+    const model = agentDef.model ?? config.defaults.model;
+    if (config.models) {
+        const aliases = new Set(config.models.map((m) => m.alias));
+        const resolves = aliases.has(model);
+        checks.push({
+            name: "model-resolves",
+            passed: resolves,
+            message: resolves
+                ? `Model "${model}" resolves`
+                : `Model "${model}" not found in models allowlist`,
+        });
+    }
+    else {
+        checks.push({
+            name: "model-resolves",
+            passed: true,
+            message: `Model "${model}" (no allowlist, assumed valid)`,
+        });
+    }
+    // tools-resolve
+    const unknownTools = [];
+    const suggestions = [];
+    const builtinSet = new Set(BUILTIN_TOOLS);
+    for (const tool of agentDef.tools) {
+        if (!builtinSet.has(tool)) {
+            unknownTools.push(tool);
+            const suggestion = findClosestTool(tool);
+            if (suggestion) {
+                suggestions.push(`"${tool}" -> did you mean "${suggestion}"?`);
+            }
+        }
+    }
+    if (unknownTools.length === 0) {
+        checks.push({
+            name: "tools-resolve",
+            passed: true,
+            message: agentDef.tools.length > 0
+                ? `All ${agentDef.tools.length} tool(s) resolve`
+                : "No tools configured",
+        });
+    }
+    else {
+        const detail = suggestions.length > 0
+            ? ` (${suggestions.join(", ")})`
+            : "";
+        checks.push({
+            name: "tools-resolve",
+            passed: false,
+            message: `Unknown tools: ${unknownTools.join(", ")}${detail}`,
+        });
+    }
+    // skills-resolve
+    const skillErrors = [];
+    for (const skillName of agentDef.skills) {
+        const skillDir = path.join(options.skillsDir, skillName);
+        try {
+            const manifest = loadSkillManifest(skillDir);
+            // Verify tool files listed in manifest exist on disk
+            if (manifest.tools) {
+                for (const toolFile of manifest.tools) {
+                    const toolPath = path.join(skillDir, "tools", `${toolFile}.ts`);
+                    if (!fs.existsSync(toolPath)) {
+                        skillErrors.push(`${skillName}: tool file missing: tools/${toolFile}.ts`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            skillErrors.push(`${skillName}: ${err.message}`);
+        }
+    }
+    if (skillErrors.length === 0) {
+        checks.push({
+            name: "skills-resolve",
+            passed: true,
+            message: agentDef.skills.length > 0
+                ? `All ${agentDef.skills.length} skill(s) resolve`
+                : "No skills configured",
+        });
+    }
+    else {
+        checks.push({
+            name: "skills-resolve",
+            passed: false,
+            message: `Skill errors: ${skillErrors.join("; ")}`,
+        });
+    }
+    // soul-exists
+    const soulPath = path.join(options.dataDir, "agents", agentName, "SOUL.md");
+    let soulContent = null;
+    try {
+        soulContent = fs.readFileSync(soulPath, "utf-8");
+    }
+    catch {
+        // File doesn't exist or isn't readable
+    }
+    const soulNonEmpty = soulContent !== null && soulContent.trim().length > 0;
+    checks.push({
+        name: "soul-exists",
+        passed: soulNonEmpty,
+        message: soulNonEmpty
+            ? `SOUL.md found at ${soulPath}`
+            : soulContent !== null
+                ? `SOUL.md at ${soulPath} is empty`
+                : `SOUL.md not found at ${soulPath}`,
+    });
+    // sandbox-declared
+    const agentSandbox = agentDef.sandbox;
+    const defaultsSandbox = config.defaults.sandbox;
+    if (agentSandbox) {
+        checks.push({
+            name: "sandbox-declared",
+            passed: true,
+            message: "Sandbox declared on agent",
+        });
+    }
+    else if (defaultsSandbox) {
+        checks.push({
+            name: "sandbox-declared",
+            passed: true,
+            message: "Sandbox inherited from defaults",
+        });
+    }
+    else {
+        checks.push({
+            name: "sandbox-declared",
+            passed: false,
+            message: "No sandbox declared on agent or defaults",
+        });
+    }
+    // spawn-targets
+    const spawnErrors = [];
+    for (const target of agentDef.can_spawn) {
+        const targetAgent = config.agents[target.agent];
+        if (!targetAgent) {
+            spawnErrors.push(`Target "${target.agent}" not found in config`);
+        }
+        else if (!targetAgent.spawn_only) {
+            spawnErrors.push(`Target "${target.agent}" is missing spawn_only: true`);
+        }
+    }
+    if (spawnErrors.length === 0) {
+        checks.push({
+            name: "spawn-targets",
+            passed: true,
+            message: agentDef.can_spawn.length > 0
+                ? `All ${agentDef.can_spawn.length} spawn target(s) valid`
+                : "No spawn targets configured",
+        });
+    }
+    else {
+        checks.push({
+            name: "spawn-targets",
+            passed: false,
+            message: `Spawn target errors: ${spawnErrors.join("; ")}`,
+        });
+    }
+    // cron-refs
+    const cronJobs = config.cron.filter((job) => job.agent === agentName);
+    if (cronJobs.length > 0) {
+        const jobList = cronJobs
+            .map((j) => `${j.id} (${j.schedule}, ${j.enabled ? "enabled" : "disabled"})`)
+            .join(", ");
+        checks.push({
+            name: "cron-refs",
+            passed: true,
+            message: `Cron jobs: ${jobList}`,
+        });
+    }
+    else {
+        checks.push({
+            name: "cron-refs",
+            passed: true,
+            message: "No cron jobs reference this agent",
+        });
+    }
+    const success = checks.every((c) => c.passed);
+    return { agentName, success, checks };
+}

package/dist/session/compaction.d.ts

@@ -0,0 +1,4 @@
+import type { Message } from "../llm/types.js";
+export declare function estimateTokens(message: Message): number;
+export declare function estimateTotalTokens(messages: Message[]): number;
+export declare function compactMessages(messages: Message[], model: string, tokenThreshold?: number): Promise<Message[]>;

package/dist/session/compaction.js

@@ -0,0 +1,30 @@
+import { complete } from "../llm/index.js";
+import { extractText } from "../llm/types.js";
+export function estimateTokens(message) {
+    return Math.ceil(JSON.stringify(message).length / 4);
+}
+export function estimateTotalTokens(messages) {
+    return messages.reduce((sum, msg) => sum + estimateTokens(msg), 0);
+}
+export async function compactMessages(messages, model, tokenThreshold = 100_000) {
+    const totalTokens = estimateTotalTokens(messages);
+    if (totalTokens < tokenThreshold)
+        return messages;
+    const splitPoint = Math.floor(messages.length / 2);
+    const oldMessages = messages.slice(0, splitPoint);
+    const recentMessages = messages.slice(splitPoint);
+    const summaryResponse = await complete(model, [{
+            role: "user",
+            content: "Summarize this conversation concisely. Preserve:\n" +
+                "- Key facts about the user (name, preferences)\n" +
+                "- Important decisions made\n" +
+                "- Open tasks or TODOs\n" +
+                "- File paths and code changes discussed\n\n" +
+                JSON.stringify(oldMessages, null, 2),
+        }]);
+    const summaryText = extractText(summaryResponse.content);
+    return [
+        { role: "user", content: `[Previous conversation summary]\n${summaryText}` },
+        ...recentMessages,
+    ];
+}

package/dist/session/manager.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "../llm/types.js";
+export declare class SessionManager {
+    private filePath;
+    constructor(sessionDir: string, sessionId: string);
+    getMessages(): Message[];
+    append(message: Message): void;
+    replaceAll(messages: Message[]): void;
+    static list(sessionDir: string): string[];
+}