loopengine 0.0.10 → 0.0.16

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

@@ -1,5 +1,36 @@
-import type { Rule, Decision, Scope, Approver } from 'actauth';
+import type { Rule, Decision, Approver } from 'actauth';
 import type { SafetyClassifier } from 'toollane';
+/** Declares which real ModelCall an agent module wants built for it, so
+ * the module doesn't have to export its own `createModelCall` —
+ * `discoverAgents` synthesizes one instead (see `discover-agents.ts`),
+ * lazily and memoized, the same pattern
+ * `agents/customer-service/index.ts`'s own hand-written `createModelCall`
+ * used before this existed. Each provider's own `createXModelCall`
+ * factory (`model-calls/*.ts`) still exists and still works standalone —
+ * this is a convenience for the common case, not a replacement; still
+ * export your own `createModelCall` for anything this can't express (a
+ * canned/simulated `ModelCall` for a demo, a custom SDK client, a
+ * provider this doesn't list). `model` is required for `openai`/
+ * `deepseek` (no safe hardcoded default — a flagship model name changes
+ * too often to bake one in) but optional for `anthropic` (defaults to
+ * `'claude-sonnet-5'`), mirroring each factory's own options exactly. */
+export type AgentModelConfig = {
+    provider: 'anthropic';
+    model?: string;
+    apiKey?: string;
+    maxTokens?: number;
+} | {
+    provider: 'openai';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+} | {
+    provider: 'deepseek';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    baseURL?: string;
+};
 export interface ToolSchema {
     name: string;
     description: string;
@@ -8,21 +39,105 @@ export interface ToolSchema {
 }
 export interface ToolDefinition extends ToolSchema {
     execute: (input: Record<string, unknown>) => Promise<unknown>;
+    /** Safe to run in ToolLane's parallel lane alongside other safe calls —
+     * true for a read-only tool with no side effects and no shared mutable
+     * state (a lookup, a search), false/omitted for anything that mutates
+     * something (a refund, an email, a write). Only consulted as a default
+     * when `AgentConfig.isSafeTool` isn't set — see that field's own doc
+     * comment for why a classifier function (call-level, agent-level) is
+     * the more powerful of the two and takes full precedence when given. */
+    safe?: boolean;
 }
 export interface AgentConfig {
     /** Also doubles as the ActAuth scope.agent segment. */
     name: string;
     systemPrompt: string;
-    /** Hand-written tools. Default []. */
+    /** 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. */
+    model?: AgentModelConfig;
+    /** Hand-written tools. An explicit array (including `[]`) is used as-is.
+     * Omit entirely and it defaults to importing
+     * `agents/<name>/tools/index.{ts,js}` and using its exported `tools` —
+     * this repo's own aggregation-file convention (see
+     * `agents/customer-service/tools/index.ts`), resolved next to
+     * `run-agent.ts` itself (not `process.cwd()`, unlike `skillsDirs`/
+     * `rules` — that file is real compiled code, not data, so it has to be
+     * found next to whichever build of `run-agent.ts` is actually running).
+     * A missing file there is just `[]`, not an error — same
+     * 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.
+     *
+     * 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, e.g. { scopePattern: 'default/production/customer-service', tool: 'issue_refund', decision: 'ask' } */
-    rules: Rule[];
-    /** Decision when no rule matches. Default 'ask' — new tools are opt-in, not silently allowed. */
+    /** ActAuth rules — either inline (handy for tests and small/synthetic
+     * configs) or a path to an `actauth.yml` file (same shape as
+     * `examples/actauth.yml` in the actauth package: top-level
+     * `default_decision` + a `rules:` list with `scope`/`tool`/`decision`/
+     * optional `when`), resolved against `process.cwd()` the same way
+     * `skillsDirs` is. A real agent with more than a couple of rules should
+     * use the file form — see agents/customer-service/actauth.yml — since a
+     * permission story with `when` conditions and per-tenant/environment
+     * scoping reads better as data than as a TypeScript array literal.
+     * `defaultDecision` below only applies to the inline-array form; the
+     * file form carries its own `default_decision` and ignores it.
+     *
+     * Omit entirely and it defaults to `agents/<name>/actauth.yml` — same
+     * folder-form convention `skillsDirs` defaults to. Unlike `skillsDirs`,
+     * a missing file there doesn't silently mean "no rules apply" as if
+     * every tool were pre-approved — it falls back to an empty ruleset
+     * governed by `defaultDecision` (default `'deny'` here, stricter than
+     * the inline-array form's `'ask'` default: no file at all means this
+     * agent's permission story was never written, not just incomplete), so
+     * an agent with no `actauth.yml` yet refuses every tool outright,
+     * rather than either crashing or silently allowing/asking. */
+    rules?: Rule[] | string;
+    /** Decision when no rule matches, for the inline-array `rules` form only.
+     * Default 'ask' — new tools are opt-in, not silently allowed. */
     defaultDecision?: Decision;
     /** Default ConsoleApprover (blocks on stdin) — pass e.g. a Slack-backed Approver for unattended agents. */
     approver?: Approver;
-    scope?: Partial<Omit<Scope, 'agent'>>;
-    /** SKILL.md directories this agent can discover and invoke. Omit if the agent has no skills. */
+    /** Resolves the ActAuth tenant for a request, from headers (never the
+     * body: tenant feeds permission decisions directly, so it has to come
+     * from something verified — an Authorization/API-key header checked
+     * against your own mapping — never a raw client-asserted body field
+     * that would let any caller claim to be any tenant and inherit that
+     * tenant's rules). Only `adapters/http.ts` can actually call this (it
+     * alone has a request's headers to call it with) — `run-agent.ts`
+     * itself never sees a request, so `runAgent()`'s standalone/CLI callers
+     * always get the `'default'` tenant, the same as omitting this field
+     * entirely. Returning `undefined` is a real auth failure
+     * (`adapters/http.ts` responds `401`), not "fall back to `'default'`"
+     * — if "no header at all" should resolve to `'default'` rather than a
+     * rejection, the resolver itself must return `'default'` explicitly.
+     *
+     * There's no equivalent `environment` field: environment is a
+     * deployment-wide setting (`LOOPENGINE_ENV`, default `'production'`),
+     * not something that varies by agent or by request. */
+    tenantFor?: (headers: Record<string, string | string[] | undefined>, body: Record<string, unknown>) => string | undefined;
+    /** SKILL.md directories this agent can discover and invoke, resolved
+     * against `process.cwd()` (not this config's own file location). Omit
+     * entirely and it defaults to `agents/<name>/skills` — this repo's own
+     * folder-form convention (see `agents/customer-service/skills/`) — which
+     * is harmless even if that folder doesn't exist (a flat-file agent with
+     * no skills at all just gets an empty index, not an error). Pass `[]`
+     * explicitly instead of omitting the field to opt out of that default. */
     skillsDirs?: string[];
     skillIndexBudgetTokens?: number;
     contextBudgetTokens?: number;
@@ -34,7 +149,13 @@ export interface AgentConfig {
      * RunAgentResult.stopReason set to 'max_turns' so a caller can tell the
      * difference from a normal finish. */
     maxTurns?: number;
-    /** Which tools ToolLane may run in a parallel lane. Default: none (every tool runs solo). */
+    /** Which tools ToolLane may run in a parallel lane. Takes full
+     * precedence over each tool's own `ToolDefinition.safe` flag when set —
+     * it's strictly more powerful (a function of the whole call, not just
+     * the tool's static definition, so it can vary by agent or, if you
+     * thread args through, by the call's own input). Omit it to fall back
+     * to each called tool's own `safe` flag instead (looked up by name);
+     * omit both and every tool runs solo. */
     isSafeTool?: SafetyClassifier;
     /** How adapters/http.ts derives a session key from a request body — this
      * is business logic ("what counts as one conversation" is agent-
@@ -43,6 +164,15 @@ export interface AgentConfig {
      * adapter. Return undefined to signal "this body doesn't identify a
      * session" (the adapter responds 400). Omit entirely to use the
      * adapter's default — a client-supplied `sessionId` field, the same
-     * shape adapters/cli.ts's --session flag already uses. */
+     * shape adapters/cli.ts's --session flag already uses.
+     *
+     * Body-only, unlike `tenantFor` above — a spoofed session key only lets
+     * someone read/continue the wrong *conversation*; it doesn't grant
+     * elevated tool permissions the way a spoofed tenant would. Real
+     * verified-identity session keys (deriving this from an auth header
+     * instead of a client-asserted body field like customerEmail) are a
+     * legitimate future need, but nothing in this repo has a concrete use
+     * for it yet — no sense widening this signature speculatively before
+     * there's a real consumer to shape it around. */
     sessionIdFor?: (body: Record<string, unknown>) => string | undefined;
 }

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,174 @@
+#!/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 { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+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;
+}
+// Only run when executed directly — not when scaffoldAgent is imported
+// for testing.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+    main();
+}

package/dist/discover-agents.d.ts

@@ -1,16 +1,24 @@
-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;
 }
-/** Scans `dir`'s direct files only (not subdirectories — put shared,
- * non-agent code in a subdirectory to keep it out of discovery, no
- * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
- * expected to export `config` and `createModelCall` — the same shape
- * every agents/*.ts file in this repo's own reference app already
- * exports. Throws, rather than skipping, on a file that doesn't match
- * that shape or a duplicate AgentConfig.name — both are almost always a
- * bug in the agent file, not something to silently ignore. */
+/** 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`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
 export declare function discoverAgents(dir: string): Promise<Map<string, AgentModule>>;

package/dist/discover-agents.js

@@ -11,38 +11,99 @@
 // silently collide in ActAuth's rules today regardless of this helper;
 // surfacing that collision loudly here, at discovery time, is a real
 // safety property this adds, not just convenience.
-import { readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-function isAgentModule(mod) {
-    return (typeof mod === 'object' &&
-        mod !== null &&
-        'config' in mod &&
-        'createModelCall' in mod &&
-        typeof mod.createModelCall === 'function');
+function isRawAgentModule(mod) {
+    return typeof mod === 'object' && mod !== null && 'config' in mod;
 }
-/** Scans `dir`'s direct files only (not subdirectories — put shared,
- * non-agent code in a subdirectory to keep it out of discovery, no
- * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
- * expected to export `config` and `createModelCall` — the same shape
- * every agents/*.ts file in this repo's own reference app already
- * exports. Throws, rather than skipping, on a file that doesn't match
- * that shape or a duplicate AgentConfig.name — both are almost always a
- * bug in the agent file, not something to silently ignore. */
+/** Builds a lazy, memoized createModelCall from AgentConfig.model, for a
+ * module that doesn't export its own — see that field's own doc comment.
+ * The provider's SDK module is imported here, eagerly, but that's cheap
+ * and safe with no API key at all: importing model-calls/*.ts only
+ * defines functions, it never constructs a client at module top level
+ * (see e.g. createAnthropicModelCall's own body) — so this can't fail
+ * discovery the way eagerly building the actual client would. The real
+ * client is only built the first time the returned function is actually
+ * called, and reused after that, the same "don't crash the whole server
+ * over one agent's missing API key, don't rebuild per call" reasoning
+ * agents/customer-service/index.ts's own hand-written createModelCall
+ * used before this existed. */
+async function synthesizeCreateModelCall(model) {
+    let cached;
+    if (model.provider === 'anthropic') {
+        const { createAnthropicModelCall } = await import('./model-calls/anthropic-model-call.js');
+        return () => (cached ??= createAnthropicModelCall(model));
+    }
+    if (model.provider === 'openai') {
+        const { createOpenAIModelCall } = await import('./model-calls/openai-model-call.js');
+        return () => (cached ??= createOpenAIModelCall(model));
+    }
+    const { createDeepSeekModelCall } = await import('./model-calls/deepseek-model-call.js');
+    return () => (cached ??= createDeepSeekModelCall(model));
+}
+/** Resolves one directory entry to an agent module's path, or undefined if
+ * this entry isn't one — a `.ts`/`.js` file directly (the common case), or
+ * a subdirectory containing an `index.ts`/`index.js` (the same "a
+ * directory can be a module" convention Node's own `require()` resolution
+ * already uses — no new mental model to learn). A subdirectory with
+ * neither is ordinary supporting code living alongside an agent's own
+ * folder (a `tools.ts` split out of a large agent, say), not an agent
+ * itself, and is silently skipped rather than treated as an error. */
+function resolveModulePath(dir, entry) {
+    if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+        return { path: resolve(dir, entry.name), label: entry.name };
+    }
+    if (entry.isDirectory()) {
+        for (const indexName of ['index.ts', 'index.js']) {
+            const indexPath = join(dir, entry.name, indexName);
+            if (existsSync(indexPath))
+                return { path: resolve(indexPath), label: `${entry.name}/${indexName}` };
+        }
+    }
+    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`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
 export async function discoverAgents(dir) {
     const entries = new Map();
-    const files = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts'));
-    for (const file of files) {
-        const modulePath = resolve(dir, file.name);
-        const mod = await import(pathToFileURL(modulePath).href);
-        if (!isAgentModule(mod)) {
-            throw new Error(`${file.name} in ${dir} does not export both 'config' and 'createModelCall' — every agent module must.`);
-        }
-        const name = mod.config.name;
+    for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+        const resolved = resolveModulePath(dir, dirent);
+        if (!resolved)
+            continue;
+        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}' — ${file.name} in ${dir} isn't the first file to declare AgentConfig.name '${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, mod);
+        entries.set(name, agentModule);
     }
     return entries;
 }

package/dist/index.d.ts

@@ -1,15 +1,16 @@
-export { runAgent } from './run-agent.js';
-export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from './run-agent.js';
-export type { AgentConfig, 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';
 export type { Document, ScoredDocument } from './vector-index.js';
-export { createAnthropicModelCall } from './anthropic-model-call.js';
-export type { AnthropicModelCallOptions } from './anthropic-model-call.js';
-export { createOpenAIModelCall } from './openai-model-call.js';
-export type { OpenAIModelCallOptions } from './openai-model-call.js';
-export { createDeepSeekModelCall } from './deepseek-model-call.js';
-export type { DeepSeekModelCallOptions } from './deepseek-model-call.js';
-export { discoverAgents } from './discover-agents.js';
+export { createAnthropicModelCall } from './model-calls/anthropic-model-call.js';
+export type { AnthropicModelCallOptions } from './model-calls/anthropic-model-call.js';
+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, 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 './anthropic-model-call.js';
-export { createOpenAIModelCall } from './openai-model-call.js';
-export { createDeepSeekModelCall } from './deepseek-model-call.js';
-export { discoverAgents } from './discover-agents.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, loadAgentModule } from './discover-agents.js';
+export { agentAsTool } from './agent-as-tool.js';