loopengine 0.0.14 → 0.0.17

package/dist/agent-as-tool.d.ts

@@ -0,0 +1,7 @@
+import type { AgentConfig, ToolDefinition } from '#agent-config.js';
+import { type ModelCall } from '#run-agent.js';
+/** `createModelCall` is a factory, not a shared instance — the same
+ * `AgentModule.createModelCall` contract discover-agents.ts already
+ * uses, so each call to the returned tool gets its own ModelCall rather
+ * than sharing one across concurrent invocations. */
+export declare function agentAsTool(config: AgentConfig, createModelCall: () => ModelCall): ToolDefinition;

package/dist/agent-as-tool.js

@@ -0,0 +1,32 @@
+import { runAgent } from '#run-agent.js';
+/** `createModelCall` is a factory, not a shared instance — the same
+ * `AgentModule.createModelCall` contract discover-agents.ts already
+ * uses, so each call to the returned tool gets its own ModelCall rather
+ * than sharing one across concurrent invocations. */
+export function agentAsTool(config, createModelCall) {
+    if (!config.toolDescription) {
+        throw new Error(`agentAsTool('${config.name}') requires AgentConfig.toolDescription — see its own doc comment. ` +
+            `systemPrompt is instructions for '${config.name}' itself, not a description a caller can use to decide when to invoke it.`);
+    }
+    return {
+        name: config.name,
+        description: config.toolDescription,
+        input_schema: {
+            type: 'object',
+            properties: {
+                request: { type: 'string', description: 'What to ask this agent to do.' },
+            },
+            required: ['request'],
+        },
+        // Deliberately no `safe: true` here: this agent may itself call
+        // unsafe tools, and agentAsTool has no way to know that from the
+        // outside — declaring it safe would be a claim about side effects
+        // this function isn't in a position to make. Callers that know their
+        // specific subagent is read-only can still set `safe: true` on the
+        // returned object themselves.
+        execute: async (input) => {
+            const result = await runAgent(config, createModelCall(), String(input.request));
+            return result.text;
+        },
+    };
+}

package/dist/agent-config.d.ts

@@ -52,6 +52,15 @@ export interface AgentConfig {
     /** Also doubles as the ActAuth scope.agent segment. */
     name: string;
     systemPrompt: string;
+    /** Required only when this agent is wrapped with `agentAsTool` (see
+     * agent-as-tool.ts) — the ToolDefinition.description shown to a
+     * *parent* agent's model, so it knows when to delegate here.
+     * `systemPrompt` isn't a substitute: it's instructions for this agent
+     * itself, not a pitch to a caller deciding whether to invoke it.
+     * `agentAsTool` throws if this is missing. Irrelevant for an agent
+     * that's only ever run directly (via runAgent/CLI/HTTP), so it's
+     * optional here rather than required on every AgentConfig. */
+    toolDescription?: string;
     /** See AgentModelConfig's own doc comment. Omit entirely and the module
      * must export its own `createModelCall` instead — `discoverAgents`
      * throws at startup on a module with neither. */
@@ -68,7 +77,14 @@ export interface AgentConfig {
      * missing-is-fine treatment `skillsDirs` gets. An agent that needs to
      * merge in tools from somewhere else too (e.g.
      * `agents/file-agent/index.ts`'s Composio-sourced ones) can't rely on
-     * this default and still needs to set `tools` explicitly. */
+     * this default and still needs to set `tools` explicitly.
+     *
+     * Unlike this field, `agents/<name>/subagents/*` (see
+     * agent-as-tool.ts) is *always* merged in on top of whatever `tools`
+     * resolves to, explicit array or default alike — subagents are a
+     * distinct concern (delegation) from hand-written tools (integration
+     * code), so setting `tools` explicitly doesn't opt an agent out of its
+     * own subagents/ folder the way it opts out of the tools/ default. */
     tools?: ToolDefinition[];
     /** ActAuth rules — either inline (handy for tests and small/synthetic
      * configs) or a path to an `actauth.yml` file (same shape as

package/dist/cli.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+export declare class AgentNameError extends Error {
+}
+export declare class AgentExistsError extends Error {
+}
+export declare class AgentNotFoundError extends Error {
+}
+export declare function agentIndexTemplate(name: string): string;
+/** Same shape as agentIndexTemplate, plus `toolDescription` — the one
+ * field a subagent needs that a top-level agent doesn't. run-agent.ts's
+ * loadSubagentTools wraps this config with agentAsTool, which throws
+ * without a real toolDescription: it's what the parent agent's model
+ * reads to decide when to delegate here, and systemPrompt (instructions
+ * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
+export declare function subagentIndexTemplate(name: string): string;
+/** Writes agents/<name>/index.ts under baseDir and returns its path.
+ * Only that one file — tools, rules, and skillsDirs are left to their
+ * smart defaults (see AgentConfig's own doc comments), the same as the
+ * README's own "simplest possible agent" example. */
+export declare function scaffoldAgent(baseDir: string, name: string): Promise<string>;
+/** Writes <parentDir>/subagents/<name>/index.ts under baseDir and
+ * returns its path, where <parentDir> is `parent` resolved by
+ * resolveParentDir — the folder convention run-agent.ts's
+ * loadSubagentTools auto-discovers, so this subagent becomes one of
+ * `parent`'s tools with no further edits: no import, no
+ * AgentConfig.tools entry, nothing to register by hand. Requires
+ * `parent` to already exist (its own index.ts) — a subagent without a
+ * parent to nest under is just a regular top-level agent, which
+ * scaffoldAgent already covers. Nesting more than one level is just
+ * `parent` itself being a path — see resolveParentDir. */
+export declare function scaffoldSubagent(baseDir: string, parent: string, name: string): Promise<string>;

package/dist/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// The `loopengine` bin — distinct from adapters/cli.ts, which runs an
+// agent, not scaffolds one. Generates the agents/<name>/index.ts
+// boilerplate the folder convention expects (see agent-config.ts's own
+// doc comments, or the README's "Define your first agent"), so using
+// that convention doesn't mean memorizing its shape and hand-writing it
+// every time.
+import { realpathSync } from 'node:fs';
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export class AgentNameError extends Error {
+}
+export class AgentExistsError extends Error {
+}
+export class AgentNotFoundError extends Error {
+}
+export function agentIndexTemplate(name) {
+    return `import type { AgentConfig } from 'loopengine'
+
+export const config: AgentConfig = {
+  name: '${name}',
+  systemPrompt: 'You are ...',
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
+}
+`;
+}
+/** Same shape as agentIndexTemplate, plus `toolDescription` — the one
+ * field a subagent needs that a top-level agent doesn't. run-agent.ts's
+ * loadSubagentTools wraps this config with agentAsTool, which throws
+ * without a real toolDescription: it's what the parent agent's model
+ * reads to decide when to delegate here, and systemPrompt (instructions
+ * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
+export function subagentIndexTemplate(name) {
+    return `import type { AgentConfig } from 'loopengine'
+
+export const config: AgentConfig = {
+  name: '${name}',
+  systemPrompt: 'You are ...',
+  toolDescription: 'Call this when ...',
+  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
+}
+`;
+}
+/** Writes agents/<name>/index.ts under baseDir and returns its path.
+ * Only that one file — tools, rules, and skillsDirs are left to their
+ * smart defaults (see AgentConfig's own doc comments), the same as the
+ * README's own "simplest possible agent" example. */
+export async function scaffoldAgent(baseDir, name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new AgentNameError(`Agent name must be lowercase, alphanumeric, hyphen-separated (e.g. "weather-agent") — got "${name}"`);
+    }
+    const dir = path.join(baseDir, 'agents', name);
+    const indexPath = path.join(dir, 'index.ts');
+    if (await pathExists(indexPath)) {
+        throw new AgentExistsError(`agents/${name}/index.ts already exists — pick a different name or edit it directly.`);
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(indexPath, agentIndexTemplate(name));
+    return indexPath;
+}
+/** Resolves `parent` — a single agent name, or a `/`-joined path of
+ * names for nesting more than one level deep (e.g.
+ * "support-orchestrator/billing-agent" to scaffold a subagent under an
+ * *existing subagent*) — to the real directory that agent's index.ts
+ * lives in: agents/<seg0>/subagents/<seg1>/subagents/<seg2>/... Every
+ * segment gets the same lowercase-hyphen validation a plain agent name
+ * does; there's no separate "path" naming rule. */
+function resolveParentDir(baseDir, parent) {
+    const segments = parent.split('/');
+    for (const segment of segments) {
+        if (!NAME_PATTERN.test(segment)) {
+            throw new AgentNameError(`Parent must be a lowercase, alphanumeric, hyphen-separated agent name, or several joined by '/' for nesting (e.g. "support-orchestrator/billing-agent") — got "${parent}"`);
+        }
+    }
+    return segments.slice(1).reduce((dir, segment) => path.join(dir, 'subagents', segment), path.join(baseDir, 'agents', segments[0]));
+}
+/** Writes <parentDir>/subagents/<name>/index.ts under baseDir and
+ * returns its path, where <parentDir> is `parent` resolved by
+ * resolveParentDir — the folder convention run-agent.ts's
+ * loadSubagentTools auto-discovers, so this subagent becomes one of
+ * `parent`'s tools with no further edits: no import, no
+ * AgentConfig.tools entry, nothing to register by hand. Requires
+ * `parent` to already exist (its own index.ts) — a subagent without a
+ * parent to nest under is just a regular top-level agent, which
+ * scaffoldAgent already covers. Nesting more than one level is just
+ * `parent` itself being a path — see resolveParentDir. */
+export async function scaffoldSubagent(baseDir, parent, name) {
+    const parentDir = resolveParentDir(baseDir, parent);
+    if (!NAME_PATTERN.test(name)) {
+        throw new AgentNameError(`Subagent name must be lowercase, alphanumeric, hyphen-separated (e.g. "billing-agent") — got "${name}"`);
+    }
+    const parentIndexPath = path.join(parentDir, 'index.ts');
+    if (!(await pathExists(parentIndexPath))) {
+        throw new AgentNotFoundError(`'${parent}' doesn't exist yet (expected ${parentIndexPath}) — create it first.`);
+    }
+    const dir = path.join(parentDir, 'subagents', name);
+    const indexPath = path.join(dir, 'index.ts');
+    if (await pathExists(indexPath)) {
+        throw new AgentExistsError(`A subagent named '${name}' already exists under '${parent}' (${indexPath}) — pick a different name or edit it directly.`);
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(indexPath, subagentIndexTemplate(name));
+    return indexPath;
+}
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    if (command === 'add-agent') {
+        const [name] = rest;
+        if (!name) {
+            console.error('Usage: loopengine add-agent <name>');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            await scaffoldAgent(process.cwd(), name);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Created agents/${name}/index.ts`);
+        console.log();
+        console.log('tools, rules, and skillsDirs are all omitted — they default to:');
+        console.log(`  agents/${name}/tools/index.ts   (no tools until you add one)`);
+        console.log(`  agents/${name}/actauth.yml      (denies every tool until you add one)`);
+        console.log(`  agents/${name}/skills/          (no skills until you add one)`);
+        console.log();
+        console.log(`Run it: npx tsx adapters/cli.ts --agent ${name} "hello"`);
+        return;
+    }
+    if (command === 'add-subagent') {
+        const [parent, name] = rest;
+        if (!parent || !name) {
+            console.error('Usage: loopengine add-subagent <parent> <name>');
+            console.error('       <parent> can be a single agent name, or several joined by \'/\' to nest deeper (e.g. "support-orchestrator/billing-agent")');
+            process.exitCode = 1;
+            return;
+        }
+        let indexPath;
+        try {
+            indexPath = await scaffoldSubagent(process.cwd(), parent, name);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Created ${path.relative(process.cwd(), indexPath)}`);
+        console.log();
+        console.log(`Auto-registered as a tool on '${parent}' — no import, no tools array edit needed.`);
+        console.log(`Fill in toolDescription: it's what '${parent}'s model reads to decide when to call '${name}'.`);
+        console.log();
+        console.log(`Run the top-level agent: npx tsx adapters/cli.ts --agent ${parent.split('/')[0]} "hello"`);
+        return;
+    }
+    console.error('Usage: loopengine add-agent <name>');
+    console.error('       loopengine add-subagent <parent> <name>');
+    process.exitCode = 1;
+}
+// A package-manager shim (npx, node_modules/.bin) invokes this file
+// through a symlink, not its real path — process.argv[1] is the
+// symlink's path, while Node resolves import.meta.url to the real path
+// when loading an ES module. Comparing the raw argv[1] against the
+// resolved module URL fails in exactly that case and main() silently
+// never runs — realpath argv[1] first so both sides are resolved. (Same
+// bug, same fix, as create-loopengine's own cli.ts — see its git history
+// for the live symlink repro, and skillgarden's CLI before that.)
+function isMain() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain())
+    main();

package/dist/discover-agents.d.ts

@@ -1,10 +1,19 @@
-import type { AgentConfig } from './agent-config.js';
-import type { ModelCall } from './run-agent.js';
+import type { AgentConfig } from '#agent-config.js';
+import type { ModelCall } from '#run-agent.js';
 export interface AgentModule {
     config: AgentConfig;
     /** Factory, not a shared instance — a fresh ModelCall per request/session. */
     createModelCall: () => ModelCall;
 }
+/** Imports one agent module at `path` and resolves it to an AgentModule —
+ * the single-file version of what discoverAgents does over a whole
+ * directory, factored out so run-agent.ts's subagent loader (see
+ * agent-as-tool.ts / loadSubagentTools) can load one `subagents/<name>/
+ * index.ts` at a time without duplicating this resolution logic.
+ * `label` is only used in error messages — discoverAgents passes
+ * `'<file> in <dir>'`, callers loading a single known path can just pass
+ * that path. */
+export declare function loadAgentModule(path: string, label: string): Promise<AgentModule>;
 /** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
  * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
  * each expected to export `config`, and either its own `createModelCall`

package/dist/discover-agents.js

@@ -63,6 +63,28 @@ function resolveModulePath(dir, entry) {
     }
     return undefined;
 }
+/** Imports one agent module at `path` and resolves it to an AgentModule —
+ * the single-file version of what discoverAgents does over a whole
+ * directory, factored out so run-agent.ts's subagent loader (see
+ * agent-as-tool.ts / loadSubagentTools) can load one `subagents/<name>/
+ * index.ts` at a time without duplicating this resolution logic.
+ * `label` is only used in error messages — discoverAgents passes
+ * `'<file> in <dir>'`, callers loading a single known path can just pass
+ * that path. */
+export async function loadAgentModule(path, label) {
+    const mod = await import(pathToFileURL(path).href);
+    if (!isRawAgentModule(mod) || !mod.config) {
+        throw new Error(`${label} does not export 'config' — every agent module must.`);
+    }
+    let createModelCall = mod.createModelCall;
+    if (typeof createModelCall !== 'function') {
+        if (!mod.config.model) {
+            throw new Error(`${label} exports 'config' but neither 'createModelCall' nor 'config.model' — every agent module must have one or the other.`);
+        }
+        createModelCall = await synthesizeCreateModelCall(mod.config.model);
+    }
+    return { config: mod.config, createModelCall };
+}
 /** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
  * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
  * each expected to export `config`, and either its own `createModelCall`
@@ -76,22 +98,12 @@ export async function discoverAgents(dir) {
         const resolved = resolveModulePath(dir, dirent);
         if (!resolved)
             continue;
-        const mod = await import(pathToFileURL(resolved.path).href);
-        if (!isRawAgentModule(mod) || !mod.config) {
-            throw new Error(`${resolved.label} in ${dir} does not export 'config' — every agent module must.`);
-        }
-        let createModelCall = mod.createModelCall;
-        if (typeof createModelCall !== 'function') {
-            if (!mod.config.model) {
-                throw new Error(`${resolved.label} in ${dir} exports 'config' but neither 'createModelCall' nor 'config.model' — every agent module must have one or the other.`);
-            }
-            createModelCall = await synthesizeCreateModelCall(mod.config.model);
-        }
-        const name = mod.config.name;
+        const agentModule = await loadAgentModule(resolved.path, `${resolved.label} in ${dir}`);
+        const name = agentModule.config.name;
         if (entries.has(name)) {
             throw new Error(`Duplicate agent name '${name}' — ${resolved.label} in ${dir} isn't the first module to declare AgentConfig.name '${name}'.`);
         }
-        entries.set(name, { config: mod.config, createModelCall });
+        entries.set(name, agentModule);
     }
     return entries;
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { runAgent } from './run-agent.js';
-export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from './run-agent.js';
-export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition } from './agent-config.js';
+export { runAgent } from '#run-agent.js';
+export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from '#run-agent.js';
+export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition } from '#agent-config.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
 export type { SessionStore, SessionResult, RedisSessionStoreOptions } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
@@ -11,5 +11,6 @@ export { createOpenAIModelCall } from './model-calls/openai-model-call.js';
 export type { OpenAIModelCallOptions } from './model-calls/openai-model-call.js';
 export { createDeepSeekModelCall } from './model-calls/deepseek-model-call.js';
 export type { DeepSeekModelCallOptions } from './model-calls/deepseek-model-call.js';
-export { discoverAgents } from './discover-agents.js';
+export { discoverAgents, loadAgentModule } from './discover-agents.js';
 export type { AgentModule } from './discover-agents.js';
+export { agentAsTool } from './agent-as-tool.js';

package/dist/index.js

@@ -3,10 +3,11 @@
 // `adapters/*.ts`, and the Dockerfile are this repo's own reference app
 // built on top of this surface, not part of it — see the README section
 // "Using loopengine as a library" for the boundary and why.
-export { runAgent } from './run-agent.js';
+export { runAgent } from '#run-agent.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
 export { createAnthropicModelCall } from './model-calls/anthropic-model-call.js';
 export { createOpenAIModelCall } from './model-calls/openai-model-call.js';
 export { createDeepSeekModelCall } from './model-calls/deepseek-model-call.js';
-export { discoverAgents } from './discover-agents.js';
+export { discoverAgents, loadAgentModule } from './discover-agents.js';
+export { agentAsTool } from './agent-as-tool.js';

package/dist/model-calls/anthropic-model-call.d.ts

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import type { ModelCall } from '../run-agent.js';
+import type { ModelCall } from '#run-agent.js';
 export interface AnthropicModelCallOptions {
     /** Defaults to the ANTHROPIC_API_KEY env var, same as the SDK itself. */
     apiKey?: string;

package/dist/model-calls/deepseek-model-call.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { ModelCall } from '../run-agent.js';
+import type { ModelCall } from '#run-agent.js';
 export interface DeepSeekModelCallOptions {
     /** Defaults to the DEEPSEEK_API_KEY env var. */
     apiKey?: string;

package/dist/model-calls/openai-model-call.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { Message, ModelCall, ModelResponse } from '../run-agent.js';
+import type { Message, ModelCall, ModelResponse } from '#run-agent.js';
 type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export interface OpenAIModelCallOptions {
     /** Defaults to the OPENAI_API_KEY env var, same as the SDK itself. */

package/dist/run-agent.d.ts

@@ -1,4 +1,5 @@
-import type { AgentConfig, ToolSchema } from './agent-config.js';
+import { RuleSet } from 'actauth';
+import type { AgentConfig, ToolDefinition, ToolSchema } from '#agent-config.js';
 export interface ModelContentBlock {
     type: string;
     /** text blocks. */
@@ -66,4 +67,26 @@ export interface RunAgentResult {
      * not something the model said. Absent on a normal finish. */
     stopReason?: 'max_turns';
 }
+/** Resolves AgentConfig.rules the same way skillsDirs resolves its own
+ * default: an inline array is used as-is (full 3-segment scopePattern,
+ * unchanged — see loadYamlRules for why only the YAML form gets the
+ * agent segment auto-appended); omitted entirely defaults to
+ * `agents/<name>/actauth.yml`, this repo's own folder-form convention.
+ * Unlike skillsDirs, a missing *default* file falls back to an empty
+ * ruleset rather than propagating the raw ENOENT — permissions failing
+ * shouldn't crash the whole call. That fallback defaults to `'deny'`, not
+ * the inline-array form's `'ask'`: no `actauth.yml` at all means this
+ * agent's permission story was never actually written, which is a
+ * stricter unknown than "written, but this one tool has no rule" — 'ask'
+ * still runs an Approver that could auto-approve, while 'deny' refuses
+ * outright until real rules exist. `defaultDecision`, if set, still wins
+ * over that. An *explicitly* given path that doesn't exist is a real
+ * configuration bug, though, and still throws — only the silent, implicit
+ * default gets this forgiveness.
+ *
+ * Exported (alongside loadDefaultTools below) so adapters/http.ts's
+ * GET /agents/:name/config route can show the same rules runAgent() would
+ * actually enforce, not a re-derived guess at them. */
+export declare function loadRules(config: AgentConfig): RuleSet;
+export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/run-agent.js

@@ -3,7 +3,7 @@
 // differ. runAgent itself does no I/O and holds no state between calls:
 // callers own conversation history, which is what lets the same function
 // serve a one-shot CLI invocation and a long-lived chat session.
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
@@ -12,6 +12,8 @@ import { SkillGarden } from 'skillgarden';
 import { ContextClipper } from 'contextclip';
 import { ToolLane } from 'toollane';
 import { Reflow } from 'reflowkit';
+import { loadAgentModule } from './discover-agents.js';
+import { agentAsTool } from './agent-as-tool.js';
 // Resolved relative to *this file's own location* (via import.meta.url),
 // not process.cwd() — the same reasoning agent-registry.ts's own
 // agentsDir uses. In dev (tsx), this file and agents/ are both source
@@ -85,8 +87,12 @@ function loadYamlRules(path, agentName) {
  * outright until real rules exist. `defaultDecision`, if set, still wins
  * over that. An *explicitly* given path that doesn't exist is a real
  * configuration bug, though, and still throws — only the silent, implicit
- * default gets this forgiveness. */
-function loadRules(config) {
+ * default gets this forgiveness.
+ *
+ * Exported (alongside loadDefaultTools below) so adapters/http.ts's
+ * GET /agents/:name/config route can show the same rules runAgent() would
+ * actually enforce, not a re-derived guess at them. */
+export function loadRules(config) {
     if (Array.isArray(config.rules))
         return new RuleSet(config.rules, config.defaultDecision ?? 'ask');
     const usingDefaultPath = config.rules === undefined;
@@ -112,8 +118,7 @@ function loadRules(config) {
  * this default) just gets `[]`, same as if it had explicitly set that. A
  * module that *does* exist but throws while importing, or doesn't export
  * `tools` at all, is a real bug and is not swallowed. */
-async function loadDefaultTools(config) {
-    const toolsDir = join(agentsRootDir, config.name, 'tools');
+async function loadToolsFromDir(toolsDir) {
     for (const indexName of ['index.ts', 'index.js']) {
         const indexPath = join(toolsDir, indexName);
         if (!existsSync(indexPath))
@@ -126,6 +131,90 @@ async function loadDefaultTools(config) {
     }
     return [];
 }
+export async function loadDefaultTools(config) {
+    return loadToolsFromDir(join(agentsRootDir, config.name, 'tools'));
+}
+/** Every other folder-form default in this file (loadDefaultTools,
+ * loadRules, the skillsDirs default below) resolves against
+ * `agents/<name>/` — correct for a top-level agent, where that's exactly
+ * where its module lives, but wrong for a subagent: its `config` only
+ * carries its own bare name (e.g. 'billing-agent'), not the nested folder
+ * loadSubagentTools actually found it in
+ * (`agents/support-orchestrator/subagents/billing-agent/`). Left alone,
+ * an omitted `tools`/`rules`/`skillsDirs` on a subagent would silently
+ * resolve against `agents/billing-agent/...` instead — empty, if no such
+ * top-level folder exists, or worse, some *unrelated* top-level agent's
+ * tools/rules/skills, if one happens to share the same name.
+ *
+ * This patches exactly those three fields — only when the subagent's own
+ * config left them unset — to resolve against `dir`, its real folder,
+ * before it's ever handed to agentAsTool/runAgent. An explicit value on
+ * the subagent's own config (its author opted out on purpose) is always
+ * left untouched. `rules` gets the same "missing file is fine, empty
+ * deny-everything ruleset" fallback loadRules's own default path gets —
+ * computed here instead of left to loadRules, since leaving `rules`
+ * unset would have it fall through to loadRules's *own* (wrong,
+ * name-based) default path instead of this one. */
+async function resolveSubagentConfig(config, dir) {
+    const resolved = { ...config };
+    if (resolved.tools === undefined) {
+        resolved.tools = await loadToolsFromDir(join(dir, 'tools'));
+    }
+    if (resolved.rules === undefined) {
+        const rulesPath = join(dir, 'actauth.yml');
+        if (existsSync(rulesPath)) {
+            resolved.rules = rulesPath;
+        }
+        else {
+            resolved.rules = [];
+            resolved.defaultDecision = resolved.defaultDecision ?? 'deny';
+        }
+    }
+    if (resolved.skillsDirs === undefined) {
+        resolved.skillsDirs = [join(dir, 'skills')];
+    }
+    return resolved;
+}
+/** Auto-loads agents/<name>/subagents/<child>/index.{ts,js} — each one a
+ * full AgentConfig, wrapped with agentAsTool and merged into `config`'s
+ * own tools, no import or AgentConfig.tools edit required. Unlike
+ * loadDefaultTools, this always runs regardless of whether `config.tools`
+ * was left to its own default or set explicitly — see AgentConfig.tools's
+ * own doc comment for why subagents are a distinct concern from
+ * hand-written tools. A missing subagents/ folder is just `[]`, same
+ * missing-is-fine treatment tools/ and skills/ get; a subdirectory with
+ * neither index.ts nor index.js is skipped, same as resolveModulePath's
+ * own handling in discover-agents.ts.
+ *
+ * Each subagent is loaded via loadAgentModule — the same per-module
+ * resolution discoverAgents itself uses — then patched by
+ * resolveSubagentConfig (see its own doc comment for why) before being
+ * wrapped. Its own `config` goes through this exact same function again
+ * the next time *it* runs (inside agentAsTool's execute, via runAgent).
+ * That's what makes nesting (a subagent with its own subagents/ folder)
+ * work with no extra recursion code: it's just this function being
+ * called again, one level down. A folder can't be its own ancestor, so
+ * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
+ * elsewhere could. */
+async function loadSubagentTools(config) {
+    const subagentsDir = join(agentsRootDir, config.name, 'subagents');
+    if (!existsSync(subagentsDir))
+        return [];
+    const tools = [];
+    for (const dirent of readdirSync(subagentsDir, { withFileTypes: true })) {
+        if (!dirent.isDirectory())
+            continue;
+        const dir = join(subagentsDir, dirent.name);
+        const indexPath = ['index.ts', 'index.js'].map((n) => join(dir, n)).find((p) => existsSync(p));
+        if (!indexPath)
+            continue;
+        const label = `agents/${config.name}/subagents/${dirent.name}/index`;
+        const subagent = await loadAgentModule(indexPath, label);
+        const subagentConfig = await resolveSubagentConfig(subagent.config, dir);
+        tools.push(agentAsTool(subagentConfig, subagent.createModelCall));
+    }
+    return tools;
+}
 export async function runAgent(config, modelCall, userMessage, history = [], options = {}) {
     const log = options.onEvent ?? (() => { });
     // tenant: resolved by the caller (adapters/http.ts calls
@@ -140,7 +229,10 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // (including `[]`) is used as-is; omitted entirely defaults to
     // importing agents/<name>/tools/index.{ts,js} — see loadDefaultTools's
     // own doc comment for the full reasoning and the cases that can't use it.
-    const tools = config.tools ?? (await loadDefaultTools(config));
+    // agents/<name>/subagents/* is merged in on top either way — see
+    // loadSubagentTools's own doc comment for why that one isn't gated by
+    // whether `tools` was explicit.
+    const tools = [...(config.tools ?? (await loadDefaultTools(config))), ...(await loadSubagentTools(config))];
     // Omitted entirely (undefined): default to this agent's own
     // agents/<name>/skills — the folder-form convention every agent in
     // this repo already follows (see agent-config.ts's skillsDirs doc

package/dist/session-store.d.ts

@@ -1,6 +1,6 @@
 import { Redis } from 'ioredis';
 import { type Storage } from 'sessionknit';
-import type { Message } from './run-agent.js';
+import type { Message } from '#run-agent.js';
 export interface SessionResult<T> {
     /** Exactly what this turn added — durably appended as-is, in order.
      * This has to come from the caller explicitly (runAgent's own