kagent-ts 0.1.4 → 0.1.5

package/dist/subagent/subagent-loader.js

@@ -0,0 +1,155 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubAgentLoader = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const file_skill_loader_1 = require("../skills/file-skill-loader");
+const logger_1 = require("../logging/logger");
+/**
+ * Loads sub-agent definitions from a directory of AGENT.md files.
+ *
+ * Expected directory structure:
+ * ```
+ * subagents/
+ * ├── <agent-name>/
+ * │   └── AGENT.md       # Frontmatter (metadata) + body (system prompt)
+ * ├── <another-agent>/
+ * │   └── AGENT.md
+ * ```
+ *
+ * The AGENT.md format:
+ * ```markdown
+ * ---
+ * name: code-reviewer
+ * description: Reviews code for bugs and style issues
+ * tools: read_file, grep_search, glob_search
+ * skills: code-review
+ * ---
+ * You are a code review specialist...
+ * ```
+ */
+class SubAgentLoader {
+    directory;
+    agentFileName;
+    logger;
+    /**
+     * @param directory      Path to the sub-agents root directory.
+     * @param agentFileName  The markdown filename to look for (default: "AGENT.md").
+     * @param logger         Logger instance (defaults to ConsoleLogger).
+     */
+    constructor(directory, agentFileName, logger) {
+        this.directory = path.resolve(directory);
+        this.agentFileName = agentFileName ?? "AGENT.md";
+        this.logger = logger ?? new logger_1.ConsoleLogger();
+    }
+    /**
+     * Get the root directory path.
+     */
+    getDirectory() {
+        return this.directory;
+    }
+    /**
+     * Scan the directory and return SubAgentDefinition objects for each
+     * subdirectory that contains a valid AGENT.md file.
+     *
+     * Subdirectories without an AGENT.md or without a `name` in frontmatter
+     * are skipped with a warning.
+     */
+    scan() {
+        const definitions = [];
+        let entries;
+        try {
+            entries = fs.readdirSync(this.directory, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith("."))
+                continue;
+            const def = this.loadDefinition(entry.name);
+            if (def) {
+                definitions.push(def);
+            }
+        }
+        return definitions;
+    }
+    /**
+     * Load a single sub-agent definition by name (the subdirectory name).
+     */
+    loadDefinition(dirName) {
+        const agentPath = path.join(this.directory, dirName, this.agentFileName);
+        let raw;
+        try {
+            raw = fs.readFileSync(agentPath, "utf-8");
+        }
+        catch {
+            this.logger.warn("SubAgent", `Skipping "${dirName}": no ${this.agentFileName} found.`);
+            return null;
+        }
+        const { frontmatter, body } = (0, file_skill_loader_1.parseFrontmatter)(raw);
+        const name = frontmatter.name?.trim();
+        if (!name) {
+            this.logger.warn("SubAgent", `Skipping "${dirName}": no "name" in frontmatter.`);
+            return null;
+        }
+        const tools = parseCsvList(frontmatter.tools);
+        const skills = parseCsvList(frontmatter.skills);
+        return {
+            name,
+            description: frontmatter.description?.trim() ?? "",
+            systemPrompt: body,
+            tools,
+            skills,
+        };
+    }
+}
+exports.SubAgentLoader = SubAgentLoader;
+/**
+ * Parse a comma-separated string into a string array.
+ * Returns empty array for empty/absent input.
+ */
+function parseCsvList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=subagent-loader.js.map

package/dist/subagent/subagent-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-loader.js","sourceRoot":"","sources":["../../src/subagent/subagent-loader.ts"],"names":[],"mappings":"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"}

package/dist/subagent/subagent-manager.d.ts

@@ -0,0 +1,161 @@
+import { SubAgentDefinition, SubAgentResult } from "./subagent-types";
+import { LLMProvider } from "../llm/interface";
+import { ToolRegistry } from "../tools/tool-registry";
+import { ToolFilter } from "../tools/tool-filter";
+import { SkillManager } from "../skills/skill-manager";
+import { Logger } from "../logging/logger";
+/**
+ * Manages sub-agent definitions, spawning, and result collection.
+ *
+ * The SubAgentManager is owned by the main agent. It:
+ * 1. Loads sub-agent definitions from a directory (AGENT.md files)
+ * 2. Spawns sub-agents on demand (fire-and-forget)
+ * 3. Collects completed results for the main agent to pick up
+ *
+ * Sub-agents are standard ReActAgent instances with:
+ * - A shared LLM provider (from the main agent)
+ * - A filtered tool set (only tools declared in the definition)
+ * - Pre-activated skills (as declared)
+ * - NO spawn tool (prevents nested agent creation)
+ */
+export declare class SubAgentManager {
+    private logger;
+    /** Set the logger instance (called by the owning agent). */
+    setLogger(logger: Logger): void;
+    /** Registered definitions keyed by name. */
+    private definitions;
+    /** Currently pending (running) sub-agents. */
+    private pending;
+    /** Shared LLM provider injected by the main agent. */
+    private llmProvider?;
+    /**
+     * Optional LLM provider for sub-agents.
+     * When set, sub-agents use this instead of `llmProvider`.
+     * Enables model routing — use a different (e.g. cheaper) model for
+     * sub-agent tasks while keeping the main model for complex reasoning.
+     */
+    private subAgentLLM?;
+    /** Reference to the main agent's ToolRegistry for tool lookup. */
+    private toolRegistry?;
+    /** Reference to the main agent's SkillManager (fallback). */
+    private skillManager?;
+    /** Skills directory path for sub-agent skill loading. */
+    private skillsDir?;
+    /** Max wall-clock duration for a single sub-agent run (ms). Default: 5 min. */
+    private timeoutMs;
+    /**
+     * Default ToolFilter applied to every sub-agent's tool set.
+     * Useful for globally disallowing certain tools (e.g., sub-agent spawning).
+     * Per-definition `toolFilter` is applied on top of this one.
+     */
+    private defaultFilter?;
+    /** Counter for generating unique sub-agent run IDs. */
+    private runIdCounter;
+    /**
+     * Register sub-agent definitions from a directory of AGENT.md files.
+     */
+    registerFromDirectory(dir: string): number;
+    /**
+     * Register a single sub-agent definition programmatically.
+     */
+    register(definition: SubAgentDefinition): void;
+    /**
+     * Check whether any sub-agent definitions are registered.
+     *
+     * Used by the main agent to decide whether to include sub-agent delegation
+     * instructions in the system prompt.
+     */
+    hasDefinitions(): boolean;
+    /**
+     * Set shared resources from the main agent.
+     * Called once during agent init.
+     *
+     * @param defaultFilter Optional ToolFilter applied to all sub-agents.
+     *                      Use this to globally deny dangerous tools
+     *                      (e.g. `denylist("spawn_subagent")`).
+     * @param subAgentLLM   Optional LLM provider for sub-agents.
+     *                      When set, sub-agents use this instead of the main
+     *                      `llmProvider`. Enables model routing.
+     */
+    bind(llmProvider: LLMProvider, toolRegistry: ToolRegistry, skillManager: SkillManager, skillsDir?: string, timeoutMs?: number, defaultFilter?: ToolFilter, subAgentLLM?: LLMProvider): void;
+    /**
+     * Spawn a sub-agent by definition name. Returns immediately with a run ID;
+     * the sub-agent executes asynchronously.
+     *
+     * Multiple instances of the same definition can run concurrently — each
+     * gets a unique run ID. This enables orchestrator patterns where the same
+     * sub-agent type handles different inputs in parallel.
+     *
+     * @param name  The registered sub-agent definition name.
+     * @param input The task description passed to the sub-agent.
+     * @returns The unique run ID (used to correlate results later).
+     * @throws If the definition is unknown or the manager is not yet bound.
+     */
+    spawn(name: string, input: string): string;
+    /**
+     * Check all pending sub-agent runs for completion.
+     *
+     * Call this at the start of each ReAct iteration. Completed results
+     * are removed from the pending queue and returned; still-running
+     * entries remain queued.
+     *
+     * @returns Array of completed sub-agent results (empty if none finished).
+     */
+    pollCompleted(): Promise<SubAgentResult[]>;
+    /**
+     * Wait for all pending sub-agents to complete.
+     * Useful for graceful shutdown.
+     */
+    awaitAll(): Promise<SubAgentResult[]>;
+    /**
+     * Cancel all pending sub-agents without waiting for them to finish.
+     *
+     * Running sub-agents are marked as cancelled but their promises are
+     * kept alive. When the agent resumes, `collectOrphanedResults()` can
+     * recover completed results so the LLM sees sub-agent output instead
+     * of losing it forever.
+     */
+    cancelAll(): void;
+    /**
+     * Collect results from sub-agents that were cancelled mid-run.
+     *
+     * Call this after resuming a session to pick up any sub-agent results
+     * that completed while the agent was inactive. Results are removed from
+     * the pending queue and tagged so the LLM knows they were interrupted.
+     *
+     * @returns Completed results from cancelled sub-agents.
+     */
+    collectOrphanedResults(): SubAgentResult[];
+    hasRunning(): boolean;
+    getActiveCount(): number;
+    getDefinitions(): SubAgentDefinition[];
+    /**
+     * Build a formatted list of all registered sub-agents with their
+     * capabilities (returned by the `list_subagents` tool).
+     */
+    buildSubAgentList(): string;
+    /**
+     * Execute a sub-agent run and wrap the result in XML.
+     */
+    private executeRun;
+    private doExecute;
+    /**
+     * Build a ReActAgent instance from a sub-agent definition, with:
+     * - Filtered tool set (name allowlist + wildcard patterns → defaultFilter → definition.toolFilter)
+     * - Pre-activated skills (copied from main agent's SkillManager)
+     * - No spawn tool
+     * - Auto-detect disabled (skills are pre-activated)
+     *
+     * Tool name patterns support `*` as a wildcard. For example,
+     * `filesystem_*` matches all tools whose names start with `filesystem_`
+     * (e.g. MCP tools from the "filesystem" server).
+     */
+    private buildSubAgent;
+    /** Shared tail of buildSubAgent: wire up skills and return the agent. */
+    private finishBuildSubAgent;
+    /**
+     * Wrap the sub-agent output in an XML envelope for the main agent.
+     */
+    private wrapXml;
+}
+//# sourceMappingURL=subagent-manager.d.ts.map

package/dist/subagent/subagent-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-manager.d.ts","sourceRoot":"","sources":["../../src/subagent/subagent-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAc,MAAM,kBAAkB,CAAC;AAGlF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAmB1D;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAA+B;IAE7C,4DAA4D;IAC5D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,4CAA4C;IAC5C,OAAO,CAAC,WAAW,CAA8C;IAEjE,8CAA8C;IAC9C,OAAO,CAAC,OAAO,CAAoB;IAEnC,sDAAsD;IACtD,OAAO,CAAC,WAAW,CAAC,CAAc;IAElC;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAC,CAAc;IAElC,kEAAkE;IAClE,OAAO,CAAC,YAAY,CAAC,CAAe;IAEpC,6DAA6D;IAC7D,OAAO,CAAC,YAAY,CAAC,CAAe;IAEpC,yDAAyD;IACzD,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAyB;IAE1C;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAC,CAAa;IAEnC,uDAAuD;IACvD,OAAO,CAAC,YAAY,CAAK;IAIzB;;OAEG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAqB1C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAO9C;;;;;OAKG;IACH,cAAc,IAAI,OAAO;IAIzB;;;;;;;;;;OAUG;IACH,IAAI,CACF,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,UAAU,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,IAAI;IAYP;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAkD1C;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAyBhD;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAQ3C;;;;;;;OAOG;IACH,SAAS,IAAI,IAAI;IAcjB;;;;;;;;OAQG;IACH,sBAAsB,IAAI,cAAc,EAAE;IAsB1C,UAAU,IAAI,OAAO;IAIrB,cAAc,IAAI,MAAM;IAIxB,cAAc,IAAI,kBAAkB,EAAE;IAItC;;;OAGG;IACH,iBAAiB,IAAI,MAAM;IAiB3B;;OAEG;YACW,UAAU;YAgCV,SAAS;IAmBvB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAkFrB,yEAAyE;IACzE,OAAO,CAAC,mBAAmB;IAuC3B;;OAEG;IACH,OAAO,CAAC,OAAO;CAahB"}