loopengine 0.0.17 → 0.0.20

package/README.md

@@ -4,7 +4,7 @@
 
 LoopEngine is a runtime for building AI agents: a persona, a set of tools,
 and permission rules, run through a transparent ReAct loop. No chain DSL,
-no hidden control flow — `run-agent.ts` is a single function you can read
+no hidden control flow — `core/run-agent.ts` is a single function you can read
 top to bottom. Run agents over a CLI, an HTTP API, or both.
 
 Once you define an agent, the loop turns it into something you can put in
@@ -37,7 +37,7 @@ npx create-loopengine@latest my-agents
 cd my-agents
 npm install
 cp .env.example .env   # fill in ANTHROPIC_API_KEY
-npm run dev             # HTTP server on :8787
+npm run dev             # HTTP server on :8787 — same as `npx loopengine dev`
 ```
 
 This scaffolds a standalone project — its own repo, with `loopengine` as
@@ -96,7 +96,7 @@ working examples.
 
 ### 1. The Loop
 
-`run-agent.ts` is the whole engine — a single, readable ReAct loop with no
+`core/run-agent.ts` is the whole engine — a single, readable ReAct loop with no
 hidden control flow: call the model, act on what it asks for, repeat.
 
 1. Call the model with the conversation so far.
@@ -258,7 +258,37 @@ A few things worth knowing before reaching for this:
   spends turns at every level (default 25 each) — a "simple" answer can
   cost far more than any one agent's own turn budget suggests.
 
-### 5. Tool permission and multi-tenancy
+### 5. Gateway tool sources — connecting external tools from a web page
+
+Beyond hand-written tools and subagents, an agent can pull tools from an
+external gateway — [Composio](https://composio.dev) today, with
+[`mcpplug`](https://www.npmjs.com/package/mcpplug)'s `ToolSource`
+interface designed so more providers (Nango, Arcade, Scalekit, ...) slot
+in later as thin adapters, same shape. Unlike hand-written tools, these
+are meant to be managed by an operator at runtime, not committed to code:
+run the HTTP adapter, open `/agents/config`, pick an agent, and switch to
+its "Gateway tools" tab — alongside "Overview" and "Actauth" — to see its
+connected sources and add or remove one.
+
+```bash
+npx tsx --env-file-if-exists=.env adapters/http.ts
+# open http://localhost:8787/agents/config
+```
+
+Adding a source (via the page, or `POST /agents/:name/gateway-tools` with
+`{ provider: 'composio', name: 'gh', slugs: [...] }`) writes
+`agents/<name>/gateway-tools.yml` — read fresh off disk on every request,
+same "no restart to see an edit" behavior `actauth.yml` already has.
+Composio's own OAuth is out of band: run `composio link <toolkit>` once
+on the machine running the server, then use the page purely to pick which
+already-authorized slugs to expose to which agent.
+
+A newly-added tool is **denied by default**, same "opt-in, not silently
+allowed" rule every tool in this repo follows — pass a `decision` when
+adding a source (or use the page's permission dropdown) to seed an
+`actauth.yml` rule for it instead, or add the rule by hand afterward.
+
+### 6. Tool permission and multi-tenancy
 
 Every tool call is gated by [`actauth`](https://www.npmjs.com/package/actauth):
 each rule in `AgentConfig.rules` maps a `scope` (tenant/environment) + tool
@@ -292,7 +322,7 @@ undefined` — from headers only, never the request body, since it feeds
 permission decisions directly. No `tenantFor` means every request is the
 `'default'` tenant.
 
-### 6. Sessions
+### 7. Sessions
 
 A session is one ongoing conversation. Message history persists between
 requests automatically — send a message, get a reply, come back later with
@@ -308,6 +338,37 @@ starting an anonymous session). Without it, the caller just supplies a
 
 ## Running an agent
 
+`adapters/cli.ts` and `adapters/http.ts` are files your own scaffolded
+project owns (see "Quick start" above), not something hidden inside the
+`loopengine` package — run them directly with `tsx`, or through shorter
+`loopengine` commands that just call the same files for you:
+
+```bash
+npx loopengine run customer-service --session s1 "order A-1001 arrived broken"
+npx loopengine run customer-service --session s1 --input "order A-1001 arrived broken"
+npx loopengine serve   # HTTP server on :8787
+npx loopengine dev     # same server, restarts on file changes (tsx watch)
+```
+
+`--session <id>` is just an arbitrary string you pick — `s1` above isn't
+special, it's only a label. Omit it entirely for a fresh, one-off
+conversation each call; reuse the same value on a later call to continue
+that exact conversation (the id is printed to stderr if you omit it, so
+you can capture it for next time). `--input "<message>"` is an
+alternative to the trailing positional message, for scripts that build
+the argument list programmatically and would rather not depend on the
+message always being the last argument.
+
+`run`/`serve`/`dev` are thin wrappers, not a separate implementation —
+each shells out to your project's own `adapters/cli.ts` or
+`adapters/http.ts` via `npx tsx` (so it's always *your* copy that runs,
+edits included, resolved from your project's own `node_modules`), and
+fails with a clear message pointing at `create-loopengine` if that file
+doesn't exist yet. `.env` is loaded automatically for all three,
+equivalent to passing `--env-file-if-exists=.env` to `tsx` yourself.
+
+The same thing, spelled out without the wrapper:
+
 **CLI:**
 
 ```bash
@@ -317,7 +378,7 @@ npx tsx adapters/cli.ts --agent customer-service --session s1 "order A-1001 arri
 **HTTP:**
 
 ```bash
-npx tsx adapters/http.ts
+npx tsx --env-file-if-exists=.env adapters/http.ts
 curl -X POST localhost:8787/agents/customer-service/messages \
   -H 'content-type: application/json' \
   -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'

package/core/system-skills/composio-large-outputs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: composio-large-outputs
+description: How to retrieve a gateway tool's real output when its result says storedInFile is true instead of returning the data inline.
+---
+
+# Gateway tools with a large result
+
+Some gateway tools (Composio-sourced ones in particular) return a small
+pointer object instead of their real output when the actual result is
+too large to return inline:
+
+```
+{
+  "successful": true,
+  "storedInFile": true,
+  "tokenCount": 10234,
+  "outputFilePath": "/tmp/.../SOME_TOOL_OUTPUT_xxxxx.json"
+}
+```
+
+When you see `storedInFile: true` in a tool result, the real data is
+**not** in that object — it's in the file at `outputFilePath`. Call
+`system_read_file` with that exact path to retrieve the actual content
+before answering. Don't guess at an answer, summarize from the pointer
+alone, or claim you don't have the data — read the file first.

package/dist/{cli.d.ts → bin/cli.d.ts}

@@ -5,23 +5,43 @@ export declare class AgentExistsError extends Error {
 }
 export declare class AgentNotFoundError extends Error {
 }
-export declare function agentIndexTemplate(name: string): string;
+export declare class AgentModelError extends Error {
+}
+type Provider = 'anthropic' | 'openai' | 'deepseek';
+export interface AgentTemplateOptions {
+    systemPrompt?: string;
+    model?: {
+        provider: Provider;
+        model?: string;
+    };
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export declare function agentIndexTemplate(name: string, options?: AgentTemplateOptions, importSpecifier?: 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
+ * loadSubagentAsTools 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;
+export declare function subagentIndexTemplate(name: string, importSpecifier?: 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>;
+ * README's own "simplest possible agent" example. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export declare function scaffoldAgent(baseDir: string, name: string, options?: AgentTemplateOptions): 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
+ * loadSubagentAsTools 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
@@ -29,3 +49,4 @@ export declare function scaffoldAgent(baseDir: string, name: string): Promise<st
  * 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>;
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+// The `loopengine` bin. add-agent/add-subagent generate 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. run/serve/dev are shorter muscle-
+// memory commands for what a scaffolded project's own adapters/cli.ts
+// and adapters/http.ts already do — see runTsx's own doc comment for why
+// these stay thin wrappers around those files rather than a built-in
+// runner/server this package hides inside itself.
+import { realpathSync } from 'node:fs';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+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 class AgentModelError extends Error {
+}
+const MODEL_ENV_VAR = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+};
+// Escapes a value for safe interpolation into a single-quoted TS string
+// literal in generated code — an operator-supplied systemPrompt (from
+// the admin UI's Create new agent form, say) containing a literal quote
+// or backslash would otherwise produce invalid, or silently different,
+// generated TypeScript.
+function tsStringLiteral(value) {
+    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+}
+/** 'loopengine' for a real consumer project — the only thing that ever
+ * resolves once this package is genuinely installed as a dependency. A
+ * checkout of this repo itself has no such install (see this repo's own
+ * git history around the reverted self-link attempt: pointing
+ * node_modules/loopengine back at itself collides with tsc trying to
+ * write dist/ while also reading it as an input), so a file scaffolded
+ * *into this repo* — an agent created via `loopengine dev`'s admin UI
+ * while hacking on loopengine itself, say — needs the same internal
+ * alias every hand-maintained demo agent here already uses instead.
+ * Detected by baseDir's own package.json name rather than a flag the
+ * caller has to remember to pass, so this can never drift out of sync
+ * with which project is actually being scaffolded into. */
+async function configImportSpecifier(baseDir) {
+    try {
+        const raw = await readFile(path.join(baseDir, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return pkg.name === 'loopengine' ? '#core/agent-config.js' : 'loopengine';
+    }
+    catch {
+        return 'loopengine';
+    }
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export function agentIndexTemplate(name, options = {}, importSpecifier = 'loopengine') {
+    const systemPrompt = options.systemPrompt?.trim() || 'You are ...';
+    const provider = options.model?.provider ?? 'anthropic';
+    const modelName = options.model?.model?.trim() || (provider === 'anthropic' ? 'claude-sonnet-5' : '');
+    return `import type { AgentConfig } from '${importSpecifier}'
+
+export const config: AgentConfig = {
+  name: '${name}',
+  systemPrompt: ${tsStringLiteral(systemPrompt)},
+  model: { provider: '${provider}', model: ${tsStringLiteral(modelName)} }, // reads ${MODEL_ENV_VAR[provider]}
+}
+`;
+}
+/** Same shape as agentIndexTemplate, plus `toolDescription` — the one
+ * field a subagent needs that a top-level agent doesn't. run-agent.ts's
+ * loadSubagentAsTools 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, importSpecifier = 'loopengine') {
+    return `import type { AgentConfig } from '${importSpecifier}'
+
+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. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export async function scaffoldAgent(baseDir, name, options = {}) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new AgentNameError(`Agent name must be lowercase, alphanumeric, hyphen-separated (e.g. "weather-agent") — got "${name}"`);
+    }
+    const provider = options.model?.provider ?? 'anthropic';
+    if (provider !== 'anthropic' && !options.model?.model?.trim()) {
+        throw new AgentModelError(`A model name is required for provider '${provider}' — only anthropic has a default (claude-sonnet-5).`);
+    }
+    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, options, await configImportSpecifier(baseDir)));
+    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
+ * loadSubagentAsTools 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, await configImportSpecifier(baseDir)));
+    return indexPath;
+}
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Runs `tsx <args>` in the current project (process.cwd()) — via `npx`,
+ * not a bundled copy, so it resolves *that project's own*
+ * node_modules/.bin/tsx (the version create-loopengine's own template
+ * package.json pins), the same binary "npm run dev"/"npm run cli"
+ * already invoke there. Inherits stdio so a REPL-like session, streamed
+ * SSE-style logs, or Ctrl+C all behave exactly like running the tsx
+ * command by hand — this is that command, just shorter to type. Resolves
+ * with the child's own exit code (1 if the process couldn't even start)
+ * rather than throwing, so `loopengine run <agent>`'s own exit code
+ * mirrors adapters/cli.ts's, not this wrapper's. */
+function runTsx(args) {
+    return new Promise((resolve) => {
+        const child = spawn('npx', ['tsx', ...args], { cwd: process.cwd(), stdio: 'inherit' });
+        // `stdio: 'inherit'` with no `detached` puts this child in the same
+        // foreground process group as this process itself — so a terminal's
+        // Ctrl+C delivers SIGINT to *both* at once, not just to this process
+        // for it to relay. Node's default disposition for an unhandled
+        // SIGINT/SIGTERM is to terminate immediately — without a listener,
+        // this process would die right then, before ever observing the
+        // child's own 'exit' below. That's a real bug, not cosmetic: this
+        // process is the shell's *direct* child, so the shell returns control
+        // as soon as it exits — but the child (tsx watch, itself possibly
+        // still killing *its* own child, adapters/http.ts) can still be alive
+        // for a moment after, orphaned but still attached to the same TTY.
+        // A plain no-op listener is enough to opt out of that default
+        // immediate-termination behavior — the child already gets the same
+        // signal directly (same process group), nothing needs forwarding —
+        // so this just keeps this process alive long enough to actually see
+        // the child finish, and exit in step with it instead of ahead of it.
+        const noop = () => { };
+        process.on('SIGINT', noop);
+        process.on('SIGTERM', noop);
+        function settle(result) {
+            process.off('SIGINT', noop);
+            process.off('SIGTERM', noop);
+            resolve(result);
+        }
+        child.on('exit', (code) => settle(code ?? 1));
+        child.on('error', () => settle(1));
+    });
+}
+/** run/serve/dev all delegate to a file the *project* owns (created by
+ * create-loopengine's own scaffold — see its template/adapters/), not
+ * one loopengine bundles — so a project that deleted or never had that
+ * file needs a clear, actionable error here, not tsx's own generic
+ * "cannot find module" a few layers down. */
+async function requireAdapterFile(relPath) {
+    if (await pathExists(path.join(process.cwd(), relPath)))
+        return true;
+    console.error(`${relPath} not found in this project.`);
+    console.error('Run "npx create-loopengine@latest" to scaffold one, or add your own at that path.');
+    process.exitCode = 1;
+    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;
+    }
+    // One-shot: sends one message, prints the reply, exits — exactly
+    // adapters/cli.ts's own contract (see its own header comment), not a
+    // REPL. `rest` after `<agent>` is forwarded through as-is (--session,
+    // the message, and any future flag that file grows), so this wrapper
+    // never needs to change in step with adapters/cli.ts's own arg parsing
+    // — except --input, which is this wrapper's own convenience flag, not
+    // adapters/cli.ts's: that file only understands --agent/--session plus
+    // one trailing positional message (see its own parseArgs, which joins
+    // every non-flag arg back into one string), so --input's value is
+    // translated into that positional form before forwarding, rather than
+    // taught to adapters/cli.ts itself. Exists for callers building the
+    // arg list programmatically, where getting a trailing positional's
+    // exact position right (after --session, after --agent, ...) is easy
+    // to get wrong; an explicit flag has no position to get wrong.
+    if (command === 'run') {
+        const [agent, ...forward] = rest;
+        if (!agent) {
+            console.error('Usage: loopengine run <agent> [--session <id>] "<message>"');
+            console.error('       loopengine run <agent> [--session <id>] --input "<message>"');
+            process.exitCode = 1;
+            return;
+        }
+        if (!(await requireAdapterFile('adapters/cli.ts')))
+            return;
+        let finalArgs = forward;
+        const inputIndex = forward.indexOf('--input');
+        if (inputIndex !== -1) {
+            const message = forward[inputIndex + 1];
+            if (message === undefined) {
+                console.error('--input requires a value.');
+                process.exitCode = 1;
+                return;
+            }
+            finalArgs = [...forward.slice(0, inputIndex), ...forward.slice(inputIndex + 2), message];
+        }
+        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...finalArgs]);
+        return;
+    }
+    // Serves every registered agent at once (adapters/http.ts has no
+    // notion of "just one agent") — same command the create-loopengine
+    // template's own "npm run dev" script already runs, see runTsx's own
+    // doc comment.
+    if (command === 'serve') {
+        if (!(await requireAdapterFile('adapters/http.ts')))
+            return;
+        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
+        return;
+    }
+    // Same server as `serve`, via `tsx watch` instead of plain `tsx` — tsx
+    // itself doesn't hot-reload by default (see playground.ts's own dev
+    // instructions in the README, which use plain tsx), so without this,
+    // editing an agent's tools/rules/skills mid-session would need a
+    // manual restart to take effect. gateway-tools.yml/actauth.yml already
+    // read fresh off disk every call regardless (no restart needed for
+    // those even under plain `serve`) — this is for the TS source itself:
+    // a new tool file, an edited AgentConfig, ...
+    //
+    // --include 'agents/*/index.ts' is deliberately narrow, not a blanket
+    // 'agents/**' — tsx watch on its own only tracks the actual ES module
+    // graph, so a *new* agents/<name>/index.ts (e.g. from the admin UI's
+    // "Create new agent," or from `loopengine add-agent`) wouldn't
+    // otherwise trigger a restart at all: core/agent-registry.ts discovers
+    // agents once via a top-level `readdirSync` (see discover-agents.ts),
+    // not an import, so tsx's watcher has no static edge to that new file
+    // until this flag adds one. A wider 'agents/**' would also match
+    // gateway-tools.yml/actauth.yml/skills/*.md — restarting the whole
+    // server (dropping in-flight sessions) on every admin-UI edit to
+    // those, which is exactly the "no restart needed" behavior this repo
+    // went out of its way to build for them elsewhere. Confirmed live
+    // (both directions) before landing this: editing gateway-tools.yml
+    // under this exact glob triggers no restart; adding a new
+    // agents/<name>/index.ts does.
+    if (command === 'dev') {
+        if (!(await requireAdapterFile('adapters/http.ts')))
+            return;
+        process.exitCode = await runTsx(['watch', '--include', 'agents/*/index.ts', '--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
+        return;
+    }
+    console.error('Usage: loopengine add-agent <name>');
+    console.error('       loopengine add-subagent <parent> <name>');
+    console.error('       loopengine run <agent> [--session <id>] "<message>"');
+    console.error('       loopengine serve');
+    console.error('       loopengine dev');
+    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/{agent-as-tool.d.ts → core/agent-as-tool.d.ts}

@@ -1,5 +1,5 @@
-import type { AgentConfig, ToolDefinition } from '#agent-config.js';
-import { type ModelCall } from '#run-agent.js';
+import type { AgentConfig, ToolDefinition } from '#core/agent-config.js';
+import { type ModelCall } from '#core/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

package/dist/{agent-as-tool.js → core/agent-as-tool.js}

@@ -1,4 +1,4 @@
-import { runAgent } from '#run-agent.js';
+import { runAgent } from '#core/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