@alejandroroman/agent-kit 0.1.0

package/dist/session/manager.js

@@ -0,0 +1,41 @@
+import * as fs from "fs";
+import * as path from "path";
+export class SessionManager {
+    filePath;
+    constructor(sessionDir, sessionId) {
+        fs.mkdirSync(sessionDir, { recursive: true });
+        this.filePath = path.join(sessionDir, `${sessionId}.jsonl`);
+    }
+    getMessages() {
+        if (!fs.existsSync(this.filePath))
+            return [];
+        const lines = fs.readFileSync(this.filePath, "utf-8").split("\n");
+        const messages = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                messages.push(JSON.parse(line));
+            }
+            catch {
+                // Skip corrupt lines (crash recovery)
+            }
+        }
+        return messages;
+    }
+    append(message) {
+        fs.appendFileSync(this.filePath, JSON.stringify(message) + "\n");
+    }
+    replaceAll(messages) {
+        const content = messages.map((m) => JSON.stringify(m)).join("\n") + "\n";
+        fs.writeFileSync(this.filePath, content);
+    }
+    static list(sessionDir) {
+        if (!fs.existsSync(sessionDir))
+            return [];
+        return fs
+            .readdirSync(sessionDir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .map((f) => f.replace(".jsonl", ""));
+    }
+}

package/dist/skills/activate.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from "../tools/types.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { SkillManifest } from "./schema.js";
+export interface SkillActivationContext {
+    manifests: SkillManifest[];
+    skillsDir: string;
+    toolRegistry: ToolRegistry;
+    promptFragments: string[];
+    activatedSkills: Set<string>;
+}
+export declare function createActivateSkillTool(ctx: SkillActivationContext): Tool;

package/dist/skills/activate.js

@@ -0,0 +1,62 @@
+import * as fs from "fs";
+import * as path from "path";
+import { loadSkillManifest } from "./loader.js";
+export function createActivateSkillTool(ctx) {
+    return {
+        name: "activate_skill",
+        description: "Activate a skill to load its full instructions and tools. Call this when you need a skill's capabilities.",
+        parameters: {
+            type: "object",
+            properties: {
+                skill_name: {
+                    type: "string",
+                    description: "Name of the skill to activate",
+                },
+            },
+            required: ["skill_name"],
+        },
+        execute: async (args) => {
+            const skillName = args.skill_name;
+            if (ctx.activatedSkills.has(skillName)) {
+                return `Skill "${skillName}" is already activated.`;
+            }
+            const manifest = ctx.manifests.find((m) => m.name === skillName);
+            if (!manifest) {
+                return `Skill "${skillName}" is not available. Available skills: ${ctx.manifests.map((m) => m.name).join(", ")}`;
+            }
+            const skillDir = path.join(ctx.skillsDir, skillName);
+            const fullManifest = loadSkillManifest(skillDir);
+            const loadedTools = [];
+            // Load prompt fragment
+            if (fullManifest.prompt) {
+                const promptPath = path.join(skillDir, fullManifest.prompt);
+                if (fs.existsSync(promptPath)) {
+                    ctx.promptFragments.push(fs.readFileSync(promptPath, "utf-8"));
+                }
+            }
+            // Load tools via dynamic import
+            if (fullManifest.tools) {
+                for (const toolName of fullManifest.tools) {
+                    const toolPath = path.join(skillDir, "tools", `${toolName}.ts`);
+                    if (fs.existsSync(toolPath)) {
+                        try {
+                            const mod = await import(toolPath);
+                            const tool = mod.default;
+                            ctx.toolRegistry.register(tool);
+                            loadedTools.push(tool.name);
+                        }
+                        catch (err) {
+                            return `Error loading tool "${toolName}" from skill "${skillName}": ${err instanceof Error ? err.message : String(err)}`;
+                        }
+                    }
+                }
+            }
+            ctx.activatedSkills.add(skillName);
+            const parts = [`Skill "${skillName}" activated.`];
+            if (loadedTools.length > 0) {
+                parts.push(`Tools now available: ${loadedTools.join(", ")}`);
+            }
+            return parts.join(" ");
+        },
+    };
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,3 @@
+export { SkillManifestSchema, type SkillManifest } from "./schema.js";
+export { loadSkillManifest, loadAllSkillManifests } from "./loader.js";
+export { createActivateSkillTool, type SkillActivationContext } from "./activate.js";

package/dist/skills/index.js

@@ -0,0 +1,3 @@
+export { SkillManifestSchema } from "./schema.js";
+export { loadSkillManifest, loadAllSkillManifests } from "./loader.js";
+export { createActivateSkillTool } from "./activate.js";

package/dist/skills/loader.d.ts

@@ -0,0 +1,3 @@
+import { type SkillManifest } from "./schema.js";
+export declare function loadSkillManifest(skillDir: string): SkillManifest;
+export declare function loadAllSkillManifests(skillNames: string[], skillsDir: string): SkillManifest[];

package/dist/skills/loader.js

@@ -0,0 +1,20 @@
+import * as fs from "fs";
+import * as path from "path";
+import { SkillManifestSchema } from "./schema.js";
+export function loadSkillManifest(skillDir) {
+    const manifestPath = path.join(skillDir, "skill.json");
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Missing skill.json in ${skillDir}`);
+    }
+    const raw = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    return SkillManifestSchema.parse(raw);
+}
+export function loadAllSkillManifests(skillNames, skillsDir) {
+    return skillNames.map((name) => {
+        const skillDir = path.join(skillsDir, name);
+        if (!fs.existsSync(skillDir)) {
+            throw new Error(`Skill directory not found: "${name}" (expected at ${skillDir})`);
+        }
+        return loadSkillManifest(skillDir);
+    });
+}

package/dist/skills/schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const SkillManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SkillManifest = z.infer<typeof SkillManifestSchema>;

package/dist/skills/schema.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const SkillManifestSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    tools: z.array(z.string().min(1)).optional(),
+    prompt: z.string().min(1).optional(),
+});

package/dist/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Truncate a string to `max` characters, appending an ellipsis if trimmed.
+ */
+export declare function truncate(text: string, max: number): string;
+/**
+ * Returns a context string with the current date/time for injection into system prompts.
+ */
+export declare function dateContext(): string;

package/dist/text.js

@@ -0,0 +1,24 @@
+/**
+ * Truncate a string to `max` characters, appending an ellipsis if trimmed.
+ */
+export function truncate(text, max) {
+    return text.length > max ? text.slice(0, max) + "\u2026" : text;
+}
+/**
+ * Returns a context string with the current date/time for injection into system prompts.
+ */
+export function dateContext() {
+    const now = new Date();
+    const date = now.toLocaleDateString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+    });
+    const time = now.toLocaleTimeString("en-US", {
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: true,
+    });
+    return `Current date: ${date}. Current time: ${time}.`;
+}

package/dist/tools/builtin/index.d.ts

@@ -0,0 +1,21 @@
+import { ToolRegistry } from "../registry.js";
+import { readFileTool } from "./read-file.js";
+import { writeFileTool } from "./write-file.js";
+import { runCommandTool } from "./run-command.js";
+export { readFileTool, writeFileTool, runCommandTool };
+interface BuiltinRegistryOptions {
+    allowedCommands?: string[];
+    allowedPaths?: string[];
+    memoryConfig?: {
+        dbPath: string;
+        ollamaEndpoint: string;
+        ollamaModel: string;
+    };
+    webSearch?: {
+        provider?: "brave" | "grok";
+        grok?: {
+            model?: string;
+        };
+    };
+}
+export declare function createBuiltinRegistry(options?: BuiltinRegistryOptions): ToolRegistry;

package/dist/tools/builtin/index.js

@@ -0,0 +1,21 @@
+import { ToolRegistry } from "../registry.js";
+import { createReadFileTool, readFileTool } from "./read-file.js";
+import { createWriteFileTool, writeFileTool } from "./write-file.js";
+import { createRunCommandTool, runCommandTool } from "./run-command.js";
+import { createMemoryTools } from "./memory.js";
+import { createWebSearchTool } from "./web-search.js";
+export { readFileTool, writeFileTool, runCommandTool };
+export function createBuiltinRegistry(options = {}) {
+    const registry = new ToolRegistry();
+    registry.register(createReadFileTool(options.allowedPaths));
+    registry.register(createWriteFileTool(options.allowedPaths));
+    registry.register(createRunCommandTool(options.allowedCommands));
+    registry.register(createWebSearchTool(options.webSearch));
+    if (options.memoryConfig) {
+        const memoryTools = createMemoryTools(options.memoryConfig);
+        for (const tool of memoryTools) {
+            registry.register(tool);
+        }
+    }
+    return registry;
+}

package/dist/tools/builtin/memory.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "../types.js";
+interface MemoryToolsConfig {
+    dbPath: string;
+    ollamaEndpoint: string;
+    ollamaModel: string;
+}
+export declare function createMemoryTools(config: MemoryToolsConfig): Tool[];
+export {};

package/dist/tools/builtin/memory.js

@@ -0,0 +1,164 @@
+import { createDatabase, MemoryStore, HybridSearch, OllamaEmbeddingProvider } from "../../_memory/index.js";
+import * as os from "os";
+import * as path from "path";
+import * as fs from "fs";
+export function createMemoryTools(config) {
+    const provider = new OllamaEmbeddingProvider({
+        endpoint: config.ollamaEndpoint,
+        model: config.ollamaModel,
+    });
+    const resolvedPath = config.dbPath.startsWith("~")
+        ? path.join(os.homedir(), config.dbPath.slice(1))
+        : config.dbPath;
+    const dir = path.dirname(resolvedPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const db = createDatabase(resolvedPath, provider.dimensions);
+    const store = new MemoryStore(db, provider);
+    const search = new HybridSearch(db, provider);
+    const storeMemory = {
+        name: "store_memory",
+        description: "Store a new memory for future retrieval. Use for facts, preferences, decisions, learnings, or observations worth remembering across sessions.",
+        parameters: {
+            type: "object",
+            properties: {
+                content: { type: "string", description: "The memory content" },
+                type: {
+                    type: "string",
+                    enum: ["fact", "preference", "decision", "learning", "observation"],
+                    description: "Memory type",
+                },
+                namespace: { type: "string", description: "Scope: global, finance, dev/project-name, etc." },
+                agent_id: { type: "string", description: "Who is storing this" },
+                metadata: { type: "object", description: "Optional metadata" },
+            },
+            required: ["content", "type", "namespace", "agent_id"],
+        },
+        execute: async (args) => {
+            const result = await store.store({
+                content: args.content,
+                type: args.type,
+                namespace: args.namespace,
+                agent_id: args.agent_id,
+                metadata: args.metadata,
+            });
+            return JSON.stringify(result);
+        },
+    };
+    const searchMemory = {
+        name: "search_memory",
+        description: "Search stored memories using natural language. Returns semantically similar memories ranked by relevance.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                namespace: { type: "string", description: "Filter by namespace" },
+                agent_id: { type: "string", description: "Filter by agent" },
+                type: {
+                    type: "string",
+                    enum: ["fact", "preference", "decision", "learning", "observation"],
+                    description: "Filter by type",
+                },
+                limit: { type: "number", description: "Max results (default 10)" },
+                min_score: { type: "number", description: "Minimum relevance score 0-1 (default 0.1). Filters out noise" },
+            },
+            required: ["query"],
+        },
+        execute: async (args) => {
+            const results = await search.search({
+                query: args.query,
+                namespace: args.namespace,
+                agent_id: args.agent_id,
+                type: args.type,
+                limit: args.limit,
+                min_score: args.min_score,
+            });
+            return JSON.stringify(results, null, 2);
+        },
+    };
+    const getMemory = {
+        name: "get_memory",
+        description: "Retrieve a specific memory by its ID.",
+        parameters: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Memory ID" },
+            },
+            required: ["id"],
+        },
+        execute: async (args) => {
+            const memory = await store.get(args.id);
+            if (!memory)
+                return JSON.stringify({ error: "Memory not found" });
+            return JSON.stringify(memory, null, 2);
+        },
+    };
+    const updateMemory = {
+        name: "update_memory",
+        description: "Update an existing memory. Re-embeds if content changes.",
+        parameters: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Memory ID to update" },
+                content: { type: "string", description: "New content" },
+                type: {
+                    type: "string",
+                    enum: ["fact", "preference", "decision", "learning", "observation"],
+                    description: "New type",
+                },
+                metadata: { type: "object", description: "New metadata (replaces existing)" },
+            },
+            required: ["id"],
+        },
+        execute: async (args) => {
+            const { id, ...updates } = args;
+            const result = await store.update(id, updates);
+            return JSON.stringify(result);
+        },
+    };
+    const forgetMemory = {
+        name: "forget_memory",
+        description: "Soft-delete a memory. It will no longer appear in search results.",
+        parameters: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Memory ID to forget" },
+            },
+            required: ["id"],
+        },
+        execute: async (args) => {
+            const result = await store.forget(args.id);
+            return JSON.stringify(result);
+        },
+    };
+    const listMemories = {
+        name: "list_memories",
+        description: "Browse memories by scope, sorted by most recent first.",
+        parameters: {
+            type: "object",
+            properties: {
+                namespace: { type: "string", description: "Filter by namespace" },
+                agent_id: { type: "string", description: "Filter by agent" },
+                type: {
+                    type: "string",
+                    enum: ["fact", "preference", "decision", "learning", "observation"],
+                    description: "Filter by type",
+                },
+                limit: { type: "number", description: "Max results (default 50)" },
+                offset: { type: "number", description: "Pagination offset" },
+            },
+            required: [],
+        },
+        execute: async (args) => {
+            const results = await store.list({
+                namespace: args.namespace,
+                agent_id: args.agent_id,
+                type: args.type,
+                limit: args.limit,
+                offset: args.offset,
+            });
+            return JSON.stringify(results, null, 2);
+        },
+    };
+    return [storeMemory, searchMemory, getMemory, updateMemory, forgetMemory, listMemories];
+}

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

@@ -0,0 +1,3 @@
+import type { Tool } from "../types.js";
+export declare function createReadFileTool(allowedPaths?: string[]): Tool;
+export declare const readFileTool: Tool;

package/dist/tools/builtin/read-file.js

@@ -0,0 +1,30 @@
+import * as fs from "fs";
+import { validatePath } from "../sandbox.js";
+export function createReadFileTool(allowedPaths) {
+    return {
+        name: "read_file",
+        description: "Read the contents of a file from the filesystem",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Absolute path to the file" },
+            },
+            required: ["path"],
+        },
+        execute: async (args) => {
+            try {
+                const filePath = args.path;
+                const validation = validatePath(filePath, allowedPaths);
+                if (!validation.allowed) {
+                    return validation.error;
+                }
+                return fs.readFileSync(filePath, "utf-8");
+            }
+            catch (err) {
+                return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// Backwards-compatible default export (unrestricted)
+export const readFileTool = createReadFileTool();

package/dist/tools/builtin/run-command.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "../types.js";
+export declare function createRunCommandTool(allowedCommands?: string[]): Tool;
+export declare const runCommandTool: Tool;

package/dist/tools/builtin/run-command.js

@@ -0,0 +1,37 @@
+import { execSync } from "child_process";
+import { validateCommand } from "../sandbox.js";
+export function createRunCommandTool(allowedCommands) {
+    return {
+        name: "run_command",
+        description: "Execute a shell command and return the output",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "The shell command to run" },
+                timeout: { type: "number", description: "Timeout in seconds (default: 30)" },
+            },
+            required: ["command"],
+        },
+        execute: async (args) => {
+            const command = args.command;
+            const validation = validateCommand(command, allowedCommands);
+            if (!validation.allowed) {
+                return validation.error;
+            }
+            try {
+                const timeout = (args.timeout ?? 30) * 1000;
+                const output = execSync(command, {
+                    timeout,
+                    encoding: "utf-8",
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                return output;
+            }
+            catch (err) {
+                return err.stderr || err.stdout || `Error: ${err.message}`;
+            }
+        },
+    };
+}
+// Backwards-compatible default export (unrestricted)
+export const runCommandTool = createRunCommandTool();

package/dist/tools/builtin/spawn.d.ts

@@ -0,0 +1,15 @@
+import type { SpawnTarget, Config } from "../../config/schema.js";
+import type { AgentRegistry } from "../../multi/registry.js";
+import type { ToolRegistry } from "../registry.js";
+import type { Tool } from "../types.js";
+import type { UsageStore } from "../../usage/store.js";
+interface SpawnWrapperOptions {
+    target: SpawnTarget;
+    config: Config;
+    agentRegistry: AgentRegistry;
+    toolRegistry: ToolRegistry;
+    usageStore?: UsageStore;
+}
+export declare function createSpawnWrapperTool(options: SpawnWrapperOptions): Tool;
+export declare function registerSpawnWrappers(canSpawn: SpawnTarget[], config: Config, agentRegistry: AgentRegistry, toolRegistry: ToolRegistry, usageStore?: UsageStore): void;
+export {};

package/dist/tools/builtin/spawn.js

@@ -0,0 +1,59 @@
+import { resolveModelAlias, buildFallbacks } from "../../config/resolve.js";
+import { spawnAgent } from "../../multi/spawn.js";
+import { createLogger } from "../../logger.js";
+import { truncate } from "../../text.js";
+const log = createLogger("spawn");
+export function createSpawnWrapperTool(options) {
+    const { target, config, agentRegistry, toolRegistry } = options;
+    return {
+        name: target.tool,
+        description: target.description,
+        parameters: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "The task to delegate to the sub-agent",
+                },
+            },
+            required: ["task"],
+        },
+        execute: async (args) => {
+            const task = args.task;
+            const entry = agentRegistry.getAgent(target.agent);
+            if (!entry) {
+                log.error({ tool: target.tool, agent: target.agent }, "spawn target agent not found in registry");
+                return `Error: agent "${target.agent}" not found in registry`;
+            }
+            const model = resolveModelAlias(entry.model, config.models);
+            const fallbacks = buildFallbacks(model, config.models);
+            const tools = toolRegistry.resolve(entry.tools);
+            log.info({ tool: target.tool, agent: target.agent, task: truncate(task, 200) }, "spawning sub-agent");
+            const start = Date.now();
+            try {
+                const result = await spawnAgent({
+                    model,
+                    fallbacks,
+                    systemPrompt: entry.soul,
+                    task,
+                    tools,
+                    maxIterations: 10,
+                    label: target.agent,
+                    usageStore: options.usageStore,
+                });
+                log.info({ tool: target.tool, agent: target.agent, elapsed: Date.now() - start, snippet: truncate(result.text, 150) }, "sub-agent completed");
+                return result.text;
+            }
+            catch (err) {
+                log.error({ err, tool: target.tool, agent: target.agent, elapsed: Date.now() - start }, "sub-agent failed");
+                throw err;
+            }
+        },
+    };
+}
+export function registerSpawnWrappers(canSpawn, config, agentRegistry, toolRegistry, usageStore) {
+    for (const target of canSpawn) {
+        const tool = createSpawnWrapperTool({ target, config, agentRegistry, toolRegistry, usageStore });
+        toolRegistry.register(tool);
+    }
+}

package/dist/tools/builtin/web-search.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "../types.js";
+export interface WebSearchOptions {
+    provider?: "brave" | "grok";
+    grok?: {
+        model?: string;
+    };
+}
+export declare function createWebSearchTool(options?: WebSearchOptions): Tool;