loopengine 0.0.17 → 0.0.20

package/dist/core/system-tools/ask_user.js

@@ -0,0 +1,136 @@
+// The system ask_user tool (see this folder's own index.ts, and
+// run-agent.ts's tools merge) — lets a model pause mid-turn and ask the
+// human operator a genuinely ambiguous question instead of guessing, the
+// same reasoning WebApprover exists for permission 'ask' decisions
+// (web/web-approver.ts), just generalized from a fixed allow/deny to an open
+// answer. No companion skill the way read_file has
+// system-skills/composio-large-outputs — that skill exists to bridge an
+// *indirect* trigger (another tool's storedInFile result implying
+// read_file should be called); this tool's own description is a
+// complete, self-contained instruction with no such indirection to
+// bridge.
+//
+// A fresh tool per runAgent() call, not a static export like read_file —
+// it needs somewhere to register a pending question so a later
+// answerQuestion() call can find and resolve it, and its onPending hook
+// needs to close over that call's own onEvent — see createAskUserTool's
+// own doc comment, and web/web-approver.ts's createTrackedApprover for the
+// same reasoning applied to approvals.
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+// One shared, global registry — unlike WebApprover's pending approvals
+// (split across a shared instance and a fresh one per streamed turn, so
+// each turn's onPending can target its own SSE connection), a question
+// only ever needs *one* place to live: onPending here is just an optional
+// extra notification layered on top, not a routing key, so every
+// question — from any call, streamed or not — is always answerable via
+// answerQuestion()/listQuestions() below regardless of how it was raised.
+const questionsById = new Map();
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+/** Blocking terminal prompt — the same fallback actauth's own
+ * ConsoleApprover uses for a permission ask with nowhere else to go
+ * (see createAskUserTool below for when this applies). */
+async function promptOnConsole(question, options) {
+    console.log(`\n[ask_user] ${question}`);
+    if (options?.length)
+        console.log(`  options: ${options.join(', ')}`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question('> ')).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Builds the ask_user ToolDefinition for one runAgent() call.
+ *
+ * context identifies *whose* question this is (see PendingQuestion's own
+ * doc comment) — without it, listQuestions() would have no way to scope
+ * down to one agent/conversation, and every caller would see every
+ * pending question this whole process has ever raised.
+ *
+ * onPending, when given, is how a live caller (adapters/http.ts's
+ * streaming route passes `(q) => log('question:pending', q)`, which
+ * onEvent forwards straight onto that turn's SSE connection — see
+ * playground.ts's own inline card for it) finds out immediately instead
+ * of having to poll listQuestions(). It's a notification only, not a
+ * routing key: the question is registered in the same shared
+ * questionsById either way, so answerQuestion() works regardless of
+ * whether anything was listening for onPending in the first place.
+ *
+ * Omitted entirely (a plain CLI run, or any caller with no live channel
+ * of its own) falls back to a blocking terminal prompt instead of a
+ * pending entry nothing could ever answer — same reasoning
+ * ConsoleApprover exists for permission asks with nowhere else to go.
+ *
+ * Named `system_ask_user`, not the bare `ask_user` an agent author would
+ * naturally reach for on their own — see system-tools/read_file.ts's own
+ * doc comment on the same `system_` prefix for the full reasoning
+ * (unlikely to collide by accident, and run-agent.ts's own
+ * systemToolInstances gate bypass treats a same-named override as a
+ * deliberate opt-out when one does happen). It matters even more here
+ * than for read_file: this tool *is* a human's only way to answer the
+ * agent in the first place, so it can never be gated at all without a
+ * real deadlock, not just a redundant check — a name any other tool
+ * could plausibly reach for by accident would risk silently losing that
+ * guarantee, not just risk a surprising override. */
+export function createAskUserTool(context, onPending) {
+    return {
+        name: 'system_ask_user',
+        description: "Ask the human operator a clarifying question before proceeding, when the request is genuinely ambiguous and guessing risks doing the wrong thing. Don't use this for things you can reasonably infer or look up yourself — only for real ambiguity a human actually needs to resolve. Optionally suggest a fixed set of answers; the human can still respond with free text regardless. Blocks until answered (or timed out).",
+        input_schema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'The question to ask, in plain language.' },
+                options: { type: 'array', items: { type: 'string' }, description: 'Optional suggested answers to offer alongside free text.' },
+            },
+            required: ['question'],
+        },
+        execute: async (input) => {
+            const question = String(input.question);
+            const options = Array.isArray(input.options) ? input.options.map(String) : undefined;
+            if (!onPending)
+                return promptOnConsole(question, options);
+            const id = randomUUID();
+            const entry = { id, question, options, agent: context.agent, sessionId: context.sessionId, requestedAt: new Date().toISOString() };
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    questionsById.delete(id);
+                    resolve('(no answer — timed out)');
+                }, DEFAULT_TIMEOUT_MS);
+                questionsById.set(id, { entry, resolve, timer });
+                onPending(entry);
+            });
+        },
+    };
+}
+/** Oldest first, same ordering reasoning web/web-approver.ts's listApprovals
+ * uses — whichever question has been waiting longest surfaces first.
+ * Unfiltered (both omitted) returns every question pending anywhere in
+ * this process — real uses (an operator's own admin view, say) should
+ * filter, since that's every conversation's questions mixed together. */
+export function listQuestions(filter) {
+    return [...questionsById.values()]
+        .map((p) => p.entry)
+        .filter((q) => (!filter?.agent || q.agent === filter.agent) && (!filter?.sessionId || q.sessionId === filter.sessionId))
+        .sort((a, b) => a.requestedAt.localeCompare(b.requestedAt));
+}
+/** Peek at a pending question's own entry (its agent/sessionId, in
+ * particular) without answering it — adapters/http.ts needs this *before*
+ * calling answerQuestion() below, to know which turn's early-return race
+ * (see its own sessionTurns) to resume once this one's answered. */
+export function findQuestion(id) {
+    return questionsById.get(id)?.entry;
+}
+/** Returns false for an unknown/already-answered/timed-out id, so the
+ * caller can report that distinctly (a 404) instead of silently
+ * no-opping — same convention web/web-approver.ts's decideApproval uses. */
+export function answerQuestion(id, answer) {
+    const pending = questionsById.get(id);
+    if (!pending)
+        return false;
+    clearTimeout(pending.timer);
+    questionsById.delete(id);
+    pending.resolve(answer);
+    return true;
+}

package/dist/core/system-tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../agent-config.js';
+export declare const systemTools: ToolDefinition[];
+export { createAskUserTool, listQuestions, answerQuestion, findQuestion, type PendingQuestion } from './ask_user.js';

package/dist/core/system-tools/index.js

@@ -0,0 +1,12 @@
+// Aggregates every system tool into one place, the same one-file-per-tool
+// + index.ts convention agents/file-agent/tools/index.ts already follows.
+// systemTools is the *static* set (fixed closures, no per-call state
+// needed) that run-agent.ts spreads directly into every agent's tools —
+// see its own doc comment there for the merge/precedence rules. Not every
+// system tool fits that shape, though: ask_user needs a fresh instance
+// per runAgent() call (its onPending hook closes over that call's own
+// onEvent — see ask_user.ts's own doc comment), so its *builder* is
+// re-exported here instead of an instance.
+import { readFile } from './read_file.js';
+export const systemTools = [readFile];
+export { createAskUserTool, listQuestions, answerQuestion, findQuestion } from './ask_user.js';

package/dist/core/system-tools/read_file.d.ts

@@ -0,0 +1,28 @@
+import type { ToolDefinition } from '../agent-config.js';
+/** A path-restricted read_file, auto-available to every agent (see
+ * run-agent.ts's own dedupeToolsByName + tools merge) — narrowly scoped
+ * to the OS temp directory, which is where a gateway tool's real result
+ * lands when a call returns `storedInFile: true` instead of the data
+ * itself (confirmed live against the real composio CLI: `composio
+ * execute`'s own outputFilePath always lands under os.tmpdir()).
+ *
+ * Deliberately *not* the same unscoped tool agents/file-agent/tools/
+ * read_file.ts already has (arbitrary path, no restriction at all,
+ * predates this): making arbitrary-path file reads available to *every*
+ * agent by default — including ones wired to less-trusted gateway tools
+ * or end-user-facing flows — would be a real, unbounded new capability,
+ * not just a convenience. Resolving symlinks (realpathSync) on both the
+ * allowed root and the requested path closes the obvious bypass (a
+ * symlink inside the temp dir pointing outside it).
+ *
+ * Named `system_read_file`, not the bare `read_file` an agent author
+ * would naturally reach for on their own (file-agent's own tool included)
+ * — a `system_`-prefixed name is unlikely enough to collide by accident
+ * that dedupeToolsByName's "an agent's own tool of the same name always
+ * wins" rule stays a deliberate, rare opt-out rather than something a
+ * completely unrelated tool name silently triggers. It also matters for
+ * run-agent.ts's own systemToolInstances gate bypass (see there): once an
+ * agent's own tool *does* collide on this exact name, gating goes back to
+ * normal for it, on purpose — a name this specific is what makes that
+ * an intentional choice on the agent author's part, not an accident. */
+export declare const readFile: ToolDefinition;

package/dist/core/system-tools/read_file.js

@@ -0,0 +1,64 @@
+// Tools every agent gets automatically (see run-agent.ts's own tools
+// merge, and this folder's own index.ts) — not something an agent opts
+// into, the way its own agents/<name>/tools/ or a gateway-tools.yml
+// source is. Kept to the one thing that's genuinely required
+// infrastructure, not a convenience: a gateway tool (Composio's,
+// confirmed live) that reports `storedInFile: true` instead of returning
+// its real output inline is otherwise a dead end for an agent that never
+// happened to define its own file-reading tool.
+import { readFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, sep } from 'node:path';
+// Resolved once, at import time — os.tmpdir() itself doesn't change at
+// runtime, and resolving it through realpathSync up front (not per call)
+// means a symlink in the OS temp path itself (e.g. macOS's /tmp ->
+// /private/tmp) is accounted for once, not re-resolved on every call.
+const ALLOWED_ROOT = realpathSync(tmpdir());
+function isWithinAllowedRoot(path) {
+    return path === ALLOWED_ROOT || path.startsWith(ALLOWED_ROOT + sep);
+}
+/** A path-restricted read_file, auto-available to every agent (see
+ * run-agent.ts's own dedupeToolsByName + tools merge) — narrowly scoped
+ * to the OS temp directory, which is where a gateway tool's real result
+ * lands when a call returns `storedInFile: true` instead of the data
+ * itself (confirmed live against the real composio CLI: `composio
+ * execute`'s own outputFilePath always lands under os.tmpdir()).
+ *
+ * Deliberately *not* the same unscoped tool agents/file-agent/tools/
+ * read_file.ts already has (arbitrary path, no restriction at all,
+ * predates this): making arbitrary-path file reads available to *every*
+ * agent by default — including ones wired to less-trusted gateway tools
+ * or end-user-facing flows — would be a real, unbounded new capability,
+ * not just a convenience. Resolving symlinks (realpathSync) on both the
+ * allowed root and the requested path closes the obvious bypass (a
+ * symlink inside the temp dir pointing outside it).
+ *
+ * Named `system_read_file`, not the bare `read_file` an agent author
+ * would naturally reach for on their own (file-agent's own tool included)
+ * — a `system_`-prefixed name is unlikely enough to collide by accident
+ * that dedupeToolsByName's "an agent's own tool of the same name always
+ * wins" rule stays a deliberate, rare opt-out rather than something a
+ * completely unrelated tool name silently triggers. It also matters for
+ * run-agent.ts's own systemToolInstances gate bypass (see there): once an
+ * agent's own tool *does* collide on this exact name, gating goes back to
+ * normal for it, on purpose — a name this specific is what makes that
+ * an intentional choice on the agent author's part, not an accident. */
+export const readFile = {
+    name: 'system_read_file',
+    description: "Read a text file from the OS temp directory — this is where a gateway tool's real output lands when its result says storedInFile: true instead of returning the data directly (see the outputFilePath it gives you). Not for reading arbitrary project or system files.",
+    input_schema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    execute: async (input) => {
+        const requested = resolve(String(input.path));
+        let real;
+        try {
+            real = realpathSync(requested);
+        }
+        catch {
+            throw new Error(`No such file: ${requested}`);
+        }
+        if (!isWithinAllowedRoot(real)) {
+            throw new Error(`system_read_file can only read files under the OS temp directory (${ALLOWED_ROOT}) — got ${real}.`);
+        }
+        return readFileSync(real, 'utf8');
+    },
+};

package/dist/index.d.ts

@@ -1,16 +1,19 @@
-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 './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';
+export { runAgent } from '#core/run-agent.js';
+export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from '#core/run-agent.js';
+export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition } from '#core/agent-config.js';
+export type * from './core/loop-events.js';
+export { streamMessage, streamMessageWithCallbacks, sendMessage, approveCall, denyCall, answerQuestion, getSessionHistory, } from './core/client.js';
+export type { RequestOptions, SendMessageResult, PendingApprovalResult, PendingQuestionResult, PendingResult, MessageResult, StreamMessageCallbacks, } from './core/client.js';
+export { FileSessionStore, RedisSessionStore, createSessionStore } from './core/session-store.js';
+export type { SessionStore, SessionResult, RedisSessionStoreOptions } from './core/session-store.js';
+export { VectorIndex, embed, cosineSimilarity } from './core/vector-index.js';
+export type { Document, ScoredDocument } from './core/vector-index.js';
+export { createAnthropicModelCall } from './core/model-calls/anthropic-model-call.js';
+export type { AnthropicModelCallOptions } from './core/model-calls/anthropic-model-call.js';
+export { createOpenAIModelCall } from './core/model-calls/openai-model-call.js';
+export type { OpenAIModelCallOptions } from './core/model-calls/openai-model-call.js';
+export { createDeepSeekModelCall } from './core/model-calls/deepseek-model-call.js';
+export type { DeepSeekModelCallOptions } from './core/model-calls/deepseek-model-call.js';
+export { discoverAgents, loadAgentModule } from './core/discover-agents.js';
+export type { AgentModule } from './core/discover-agents.js';
+export { agentAsTool } from './core/agent-as-tool.js';

package/dist/index.js

@@ -1,13 +1,20 @@
 // The public API — everything a consumer building on loopengine needs to
-// define and run their own agent. `agents/*.ts`, `agent-registry.ts`,
+// define and run their own agent. `agents/*.ts`, `core/agent-registry.ts`,
 // `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 { 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, loadAgentModule } from './discover-agents.js';
-export { agentAsTool } from './agent-as-tool.js';
+export { runAgent } from '#core/run-agent.js';
+// The framework-agnostic browser client for adapters/http.ts's own wire
+// protocol (see client.ts's own header comment) — this, not a deep
+// subpath import, is how a consumer's React/Vue/etc. chat UI is meant to
+// reach it: this package has no "exports" map, so every other module here
+// is re-exported through this single entry point too, and client.ts is no
+// exception.
+export { streamMessage, streamMessageWithCallbacks, sendMessage, approveCall, denyCall, answerQuestion, getSessionHistory, } from './core/client.js';
+export { FileSessionStore, RedisSessionStore, createSessionStore } from './core/session-store.js';
+export { VectorIndex, embed, cosineSimilarity } from './core/vector-index.js';
+export { createAnthropicModelCall } from './core/model-calls/anthropic-model-call.js';
+export { createOpenAIModelCall } from './core/model-calls/openai-model-call.js';
+export { createDeepSeekModelCall } from './core/model-calls/deepseek-model-call.js';
+export { discoverAgents, loadAgentModule } from './core/discover-agents.js';
+export { agentAsTool } from './core/agent-as-tool.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.17",
+  "version": "0.0.20",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -12,7 +12,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "loopengine": "dist/cli.js"
+    "loopengine": "dist/bin/cli.js"
   },
   "imports": {
     "#*": "./*"
@@ -20,37 +20,45 @@
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
-    "dist/cli.js",
-    "dist/cli.d.ts",
-    "dist/run-agent.js",
-    "dist/run-agent.d.ts",
-    "dist/agent-config.js",
-    "dist/agent-config.d.ts",
-    "dist/session-store.js",
-    "dist/session-store.d.ts",
-    "dist/vector-index.js",
-    "dist/vector-index.d.ts",
-    "dist/model-calls/anthropic-model-call.js",
-    "dist/model-calls/anthropic-model-call.d.ts",
-    "dist/model-calls/openai-model-call.js",
-    "dist/model-calls/openai-model-call.d.ts",
-    "dist/model-calls/deepseek-model-call.js",
-    "dist/model-calls/deepseek-model-call.d.ts",
-    "dist/discover-agents.js",
-    "dist/discover-agents.d.ts",
-    "dist/agent-as-tool.js",
-    "dist/agent-as-tool.d.ts",
+    "dist/bin/cli.js",
+    "dist/bin/cli.d.ts",
+    "dist/core/run-agent.js",
+    "dist/core/run-agent.d.ts",
+    "dist/core/loop-events.js",
+    "dist/core/loop-events.d.ts",
+    "dist/core/client.js",
+    "dist/core/client.d.ts",
+    "dist/core/agent-config.js",
+    "dist/core/agent-config.d.ts",
+    "dist/core/session-store.js",
+    "dist/core/session-store.d.ts",
+    "dist/core/vector-index.js",
+    "dist/core/vector-index.d.ts",
+    "dist/core/model-calls/anthropic-model-call.js",
+    "dist/core/model-calls/anthropic-model-call.d.ts",
+    "dist/core/model-calls/openai-model-call.js",
+    "dist/core/model-calls/openai-model-call.d.ts",
+    "dist/core/model-calls/deepseek-model-call.js",
+    "dist/core/model-calls/deepseek-model-call.d.ts",
+    "dist/core/discover-agents.js",
+    "dist/core/discover-agents.d.ts",
+    "dist/core/agent-as-tool.js",
+    "dist/core/agent-as-tool.d.ts",
+    "dist/core/gateway-tools.js",
+    "dist/core/gateway-tools.d.ts",
+    "dist/core/system-tools",
+    "core/system-skills",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/cli.js",
+    "build": "tsc; s=$?; chmod +x dist/bin/cli.js; exit $s",
     "prepublishOnly": "npm run build",
-    "start": "node dist/adapters/http.js",
+    "start": "node --env-file-if-exists=.env dist/adapters/http.js",
     "test": "vitest run"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.116.0",
-    "actauth": "^0.0.2",
+    "actauth": "^0.0.7",
     "contextclip": "^0.0.1",
     "ioredis": "^6.0.0",
     "mcpplug": "^0.0.1",

package/dist/cli.js

@@ -1,191 +0,0 @@
-#!/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,24 +0,0 @@
-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`
- * 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>>;