loopengine 0.0.17 → 0.0.18

package/README.md

@@ -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
@@ -317,7 +347,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/dist/cli.d.ts

@@ -8,7 +8,7 @@ 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
+ * 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. */
@@ -21,7 +21,7 @@ export declare function scaffoldAgent(baseDir: string, name: string): Promise<st
 /** 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

package/dist/cli.js

@@ -1,12 +1,16 @@
 #!/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.
+// 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, 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]+)*$/;
@@ -28,7 +32,7 @@ export const config: AgentConfig = {
 }
 /** 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. */
@@ -79,7 +83,7 @@ function resolveParentDir(baseDir, parent) {
 /** 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
@@ -113,6 +117,36 @@ async function pathExists(p) {
         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' });
+        child.on('exit', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(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') {
@@ -165,8 +199,52 @@ async function main() {
         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.
+    if (command === 'run') {
+        const [agent, ...forward] = rest;
+        if (!agent) {
+            console.error('Usage: loopengine run <agent> [--session <id>] "<message>"');
+            process.exitCode = 1;
+            return;
+        }
+        if (!(await requireAdapterFile('adapters/cli.ts')))
+            return;
+        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...forward]);
+        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, ...
+    if (command === 'dev') {
+        if (!(await requireAdapterFile('adapters/http.ts')))
+            return;
+        process.exitCode = await runTsx(['watch', '--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

package/dist/discover-agents.d.ts

@@ -8,7 +8,7 @@ export interface AgentModule {
 /** 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>/
+ * agent-as-tool.ts / loadSubagentAsTools) 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

package/dist/discover-agents.js

@@ -66,7 +66,7 @@ function resolveModulePath(dir, entry) {
 /** 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>/
+ * agent-as-tool.ts / loadSubagentAsTools) 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

package/dist/gateway-tools.d.ts

@@ -0,0 +1,194 @@
+import type { Decision } from 'actauth';
+import type { ToolDefinition } from './agent-config.js';
+export interface ComposioGatewayToolEntry {
+    provider: 'composio';
+    /** Namespaces every tool this source produces (`${name}_${slug}`,
+     * mcpplug's own convention) — must be unique among this agent's own
+     * sources. */
+    name: string;
+    slugs: string[];
+    /** Override for a non-default binary name, or a stand-in script in
+     * tests — see ComposioSourceOptions.cliCommand. Defaults to 'composio'. */
+    cliCommand?: string;
+}
+export type GatewayToolEntry = ComposioGatewayToolEntry;
+/** A top-level agent's real folder — exported so callers resolving other
+ * per-agent paths (adapters/http.ts's describeAgent, computing the same
+ * `dir` to hand to loadGatewayToolsFromDir) use the exact same base this
+ * module's own registry read/writes do, rather than re-deriving it (e.g.
+ * from process.cwd()) and risking the two drifting apart. */
+export declare function agentDir(agentName: string): string;
+/** `dir` is the agent's real folder — `agents/<name>` for a top-level
+ * agent, or the nested `agents/<parent>/subagents/<child>` a subagent
+ * actually lives in (see run-agent.ts's resolveSubagentConfig, which
+ * hit this exact same name-vs-folder distinction for tools/rules/
+ * skillsDirs). Missing file is just `[]`, same convention every other
+ * folder-form default in this repo gets. */
+export declare function readGatewayToolsFromDir(dir: string): GatewayToolEntry[];
+/** Convenience wrapper over readGatewayToolsFromDir for the common,
+ * top-level-agent case — what adapters/http.ts's admin routes actually
+ * call, since GET /agents/:name/gateway-tools only ever addresses a
+ * top-level agent (getEntry(name) has no notion of a subagent path). */
+export declare function readGatewayTools(agentName: string): GatewayToolEntry[];
+export declare class GatewayToolExistsError extends Error {
+}
+export declare class GatewayToolNotFoundError extends Error {
+}
+/** Whether a gateway tool's name reads as read-only (safe to
+ * auto-allow) rather than mutating (should stay at actauth's own
+ * default, typically 'ask' or 'deny', until a human explicitly grants
+ * it) — see addGatewayTool's 'auto' decision mode, which is what
+ * actually calls this. The first token that matches either list wins,
+ * scanned in order; a name with no recognized verb at all (an
+ * inconsistently-named action, or a toolkit this list hasn't seen yet)
+ * defaults to *not* read-only — an unclassifiable tool staying at
+ * actauth's default is the safe failure mode, the reverse would silently
+ * auto-allow something this heuristic simply doesn't understand. Exported
+ * for testing and because adapters/http.ts's picker UI may want to show
+ * the same classification before a tool is even added. */
+export declare function isReadOnlyToolName(toolName: string): boolean;
+/** 'auto' resolves per-tool via isReadOnlyToolName instead of one fixed
+ * decision for a whole batch — see addGatewayTool's own doc comment for
+ * why a single decision can't safely cover "select all" against a
+ * toolkit with dozens of actions of very different risk. */
+export type GatewayToolDecision = Decision | 'auto';
+/** Registers a new gateway tool for `agentName` (top-level only — see
+ * readGatewayTools), or, if a source with this exact `name` is already
+ * registered, merges `entry.slugs` into it (deduped) instead of
+ * rejecting the call — the name is just a namespace label, not a
+ * one-shot slot; reusing it to add more tools under the same source is
+ * the common case (picking a few more actions for an app you already
+ * added), not a conflict. It's only a real conflict when the existing
+ * entry is for a *different* provider — two different connection
+ * configs can't share one name. `decision`, if given, pre-seeds an
+ * actauth rule per tool in *this call's own* `entry.slugs` (see
+ * appendActauthRules) — not the merged list, so re-adding an
+ * already-registered slug doesn't also re-seed a duplicate rule for it.
+ * Omit `decision` to leave every new tool at actauth's own
+ * defaultDecision (typically 'deny'), the same "new tools are opt-in,
+ * not silently allowed" convention every other tool in this repo
+ * follows. `decision: 'auto'` — see appendActauthRules — resolves per
+ * tool instead of applying one decision to the whole batch. */
+export declare function addGatewayTool(agentName: string, entry: GatewayToolEntry, decision?: GatewayToolDecision): void;
+/** Removes a gateway tool's registration, along with any actauth rule
+ * appendActauthRules previously seeded for it (see
+ * removeAutoAddedActauthRules — a hand-authored rule referencing the
+ * same tool under a different name is never touched). Removing a tool
+ * is expected to remove the permission it was granted too, not leave a
+ * rule that governs nothing behind. */
+export declare function removeGatewayTool(agentName: string, sourceName: string): void;
+/** Removes one slug from an existing source — the per-tool remove icon
+ * in the Tools tab's Gateway Tools list, as opposed to removeGatewayTool
+ * above, which drops the whole source at once. Deletes the source
+ * entirely if that was its last slug: a source with zero slugs produces
+ * zero tools anyway (mcpplug's connectComposioSource loops per slug, see
+ * connectEntry), so there's nothing left worth keeping registered. Same
+ * "also remove any rule this tool was auto-granted" behavior as
+ * removeGatewayTool — see its own doc comment and
+ * removeAutoAddedActauthRules. */
+export declare function removeGatewayToolSlug(agentName: string, sourceName: string, slug: string): void;
+export interface GatewayToolStatus {
+    entry: GatewayToolEntry;
+    status: 'ok' | 'error';
+    tools: Array<{
+        name: string;
+        description: string;
+    }>;
+    error?: string;
+}
+/** The admin page's read model — every registered source for `agentName`,
+ * each actually connected to and reported on individually, same
+ * fail-open-per-source behavior loadGatewayToolsFromDir has (see its own
+ * doc comment). The difference is what happens with a failure: this
+ * function surfaces it explicitly, per source, since an operator looking
+ * at this page needs to know *which* source is broken and why — where
+ * loadGatewayToolsFromDir just logs and drops it, since runAgent() has no
+ * structured place to hand a per-source error to. Deliberately bypasses
+ * loadGatewayToolsFromDir's mtime cache — this is an occasional,
+ * deliberate operator action, not a per-turn hot path, so "always
+ * current" is worth more here than "cheap." */
+export declare function describeGatewayTools(agentName: string): Promise<GatewayToolStatus[]>;
+/** Resolves agents/<name>/gateway-tools.yml (or the equivalent nested path
+ * for a subagent — see readGatewayToolsFromDir) into real ToolDefinitions,
+ * for run-agent.ts to merge into the rest of an agent's tools. Missing
+ * file is `[]`, no cache entry created.
+ *
+ * Fails open per source: one broken/unreachable gateway (Composio down,
+ * a CLI not authenticated) is logged and contributes no tools, rather
+ * than rejecting the whole call — the same reasoning a single tool's own
+ * `execute()` failing doesn't crash runAgent's whole turn (ToolLane
+ * reports it as an is_error tool_result instead). Without this, an agent
+ * with an unrelated broken integration would fail *every* request, tools
+ * it actually needs included — confirmed live: a run-agent.test.ts test
+ * that reuses the real 'file-agent' name purely to exercise the
+ * skillsDirs default started silently depending on the real `composio`
+ * CLI/network the moment agents/file-agent/gateway-tools.yml existed,
+ * before this fix made a failed (or slow/unavailable) source harmless
+ * instead of fatal. */
+export declare function loadGatewayToolsFromDir(dir: string): Promise<ToolDefinition[]>;
+export interface ComposioConnection {
+    toolkit: string;
+    status: string;
+    alias: string | null;
+    wordId: string | null;
+}
+/** Flattens `composio connections list`'s own shape (a map of toolkit
+ * slug -> array of accounts) into one array — easier for a caller (the
+ * add-source picker) to filter/sort without knowing that shape itself.
+ * Every toolkit with at least one connected account appears, `status`
+ * and all; deciding what counts as "usable" (typically just `'ACTIVE'`)
+ * is left to the caller; a CLI/auth failure propagates as a normal
+ * rejection — see runComposioCli. */
+export declare function listComposioConnections(cliCommand?: string): Promise<ComposioConnection[]>;
+export interface ComposioToolInfo {
+    slug: string;
+    name: string;
+    description: string;
+}
+/** What `composio tools list <toolkit>` offers for one already-connected
+ * app — the picker's second step, once a toolkit is chosen from
+ * listComposioConnections. Every action a toolkit exposes, not just ones
+ * already registered as a gateway tool source — the picker's whole point
+ * is showing what's *available* to add. `--limit 1000` (the CLI's own
+ * max) is explicit rather than left to the CLI's own default: without
+ * it, `composio tools list github` silently caps at 30 results — out of
+ * GitHub's real ~900, and alphabetically sorted, so a picker session
+ * would only ever see a narrow, unrepresentative slice (every result
+ * starting with "A" — ABORT/ACCEPT/ADD/API/APPROVE/ASSIGN — almost all
+ * mutating verbs), not "every tool this toolkit has" the doc comment
+ * above already promises. Confirmed live against the real CLI: no
+ * --limit gave 30, --limit 1000 gave 893. */
+export declare function listComposioTools(toolkit: string, cliCommand?: string): Promise<ComposioToolInfo[]>;
+export interface ComposioAuthStatus {
+    connected: boolean;
+    email?: string;
+    org?: string;
+}
+/** Whether the composio CLI itself (not any one connected app — see
+ * listComposioConnections for that) is authenticated on this machine.
+ * `composio whoami` succeeds once `composio login` has run and fails
+ * otherwise, so a failure here is read as "not connected", not
+ * propagated as an error the way listComposioConnections' own CLI
+ * failures are — this is a normal, expected state for an environment
+ * that just hasn't been logged in yet, not a bug. Deliberately
+ * read-only: login is an interactive, machine-wide CLI session (opens a
+ * browser, affects every agent's gateway tools, not just one web
+ * request), so the global config page's Gateways panel that calls this
+ * only ever shows status + instructions, never drives login/logout
+ * itself. */
+export declare function getComposioAuthStatus(cliCommand?: string): Promise<ComposioAuthStatus>;
+/** `composio logout` — already non-interactive on its own (see its own
+ * --help), unlike login. Machine-wide: this deauthenticates the CLI for
+ * every agent's gateway tools on this machine, not just the browser tab
+ * that clicked Disconnect — same as running it in a terminal yourself.
+ *
+ * There's no connectComposioAccount counterpart: `composio login`'s only
+ * non-interactive path is `--user-api-key`, which turned out not to be
+ * what an operator actually has on hand — the key Composio's own
+ * dashboard hands out for MCP client auth (sent via an x-consumer-api-key
+ * header) isn't the same credential, and 401s against this flag.
+ * Composio's own documented path is plain, interactive `composio login`
+ * (opens a browser) after installing the CLI — not something a web
+ * request can drive, so the Gateways panel shows that as instructions
+ * instead of a form; see its own comment in adapters/global-config-page.ts. */
+export declare function disconnectComposioAccount(cliCommand?: string): Promise<void>;

package/dist/gateway-tools.js

@@ -0,0 +1,548 @@
+// Lets an operator register external tool gateways (Composio today —
+// Nango, Arcade, Scalekit are meant to slot in later as thin mcpplug
+// ToolSource adapters, same shape, once this mechanism is proven) against
+// an agent, without hand-writing a tools/index.ts. The registry is
+// agents/<name>/gateway-tools.yml — plain data, read fresh off disk every
+// call, same "no restart to see an edit" behavior actauth.yml already
+// has (see run-agent.ts's loadRules). adapters/http.ts's admin routes are
+// the only intended writer of that file; loadGatewayToolsFromDir is what
+// run-agent.ts calls to actually resolve it into ToolDefinitions.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { parse as parseYaml, parseDocument, stringify as stringifyYaml } from 'yaml';
+import { connectComposioSource } from 'mcpplug';
+const execFileAsync = promisify(execFile);
+// Same "next to this file, not process.cwd()" reasoning run-agent.ts's
+// own agentsRootDir uses — real code (an actauth.yml write, a
+// gateway-tools.yml write) needs to land in the same place a built dist/
+// would look for it, not wherever the process happened to be launched
+// from.
+const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), 'agents');
+function gatewayToolsPath(dir) {
+    return join(dir, 'gateway-tools.yml');
+}
+/** A top-level agent's real folder — exported so callers resolving other
+ * per-agent paths (adapters/http.ts's describeAgent, computing the same
+ * `dir` to hand to loadGatewayToolsFromDir) use the exact same base this
+ * module's own registry read/writes do, rather than re-deriving it (e.g.
+ * from process.cwd()) and risking the two drifting apart. */
+export function agentDir(agentName) {
+    return join(agentsRootDir, agentName);
+}
+/** `dir` is the agent's real folder — `agents/<name>` for a top-level
+ * agent, or the nested `agents/<parent>/subagents/<child>` a subagent
+ * actually lives in (see run-agent.ts's resolveSubagentConfig, which
+ * hit this exact same name-vs-folder distinction for tools/rules/
+ * skillsDirs). Missing file is just `[]`, same convention every other
+ * folder-form default in this repo gets. */
+export function readGatewayToolsFromDir(dir) {
+    const path = gatewayToolsPath(dir);
+    if (!existsSync(path))
+        return [];
+    const raw = (parseYaml(readFileSync(path, 'utf8')) ?? {});
+    return raw.sources ?? [];
+}
+/** Convenience wrapper over readGatewayToolsFromDir for the common,
+ * top-level-agent case — what adapters/http.ts's admin routes actually
+ * call, since GET /agents/:name/gateway-tools only ever addresses a
+ * top-level agent (getEntry(name) has no notion of a subagent path). */
+export function readGatewayTools(agentName) {
+    return readGatewayToolsFromDir(agentDir(agentName));
+}
+function writeGatewayToolsFile(dir, sources) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(gatewayToolsPath(dir), stringifyYaml({ sources }));
+}
+export class GatewayToolExistsError extends Error {
+}
+export class GatewayToolNotFoundError extends Error {
+}
+// A toolkit's own action-naming convention, not this repo's — Composio
+// slugs are consistently VERB_REST (LIST_REPOS, CREATE_ISSUE, ...), just
+// not consistently *which* verb, so this is a heuristic, not a spec.
+// Scans every underscore-separated token (not just the first) since the
+// verb isn't always right after the toolkit prefix — GITHUB_LIST_REPOS
+// and github_GITHUB_LIST_REPOS (the ${entry.name}_${slug} form
+// appendActauthRules actually calls this with) both still hit LIST.
+const READ_ONLY_VERBS = new Set([
+    'LIST',
+    'GET',
+    'FETCH',
+    'FIND',
+    'SEARCH',
+    'READ',
+    'RETRIEVE',
+    'VIEW',
+    'CHECK',
+    'SHOW',
+    'DESCRIBE',
+    'QUERY',
+    'COUNT',
+    'EXPORT',
+]);
+const MUTATING_VERBS = new Set([
+    'CREATE',
+    'ADD',
+    'UPDATE',
+    'EDIT',
+    'MODIFY',
+    'DELETE',
+    'REMOVE',
+    'SEND',
+    'POST',
+    'WRITE',
+    'SET',
+    'PUT',
+    'PATCH',
+    'PUBLISH',
+    'UPLOAD',
+    'INVITE',
+    'ASSIGN',
+    'MERGE',
+    'CLOSE',
+    'CANCEL',
+    'ARCHIVE',
+    'RESTORE',
+    'ENABLE',
+    'DISABLE',
+    'GRANT',
+    'REVOKE',
+    'EXECUTE',
+    'RUN',
+    'TRIGGER',
+    'START',
+    'STOP',
+    'PAY',
+    'CHARGE',
+    'REFUND',
+    'TRANSFER',
+    'IMPORT',
+    'MOVE',
+    'COPY',
+    'DUPLICATE',
+    'CLONE',
+    'RESET',
+    'REPLACE',
+    'ATTACH',
+    'DETACH',
+    'LOCK',
+    'UNLOCK',
+    'BLOCK',
+    'UNBLOCK',
+    'BAN',
+]);
+/** Whether a gateway tool's name reads as read-only (safe to
+ * auto-allow) rather than mutating (should stay at actauth's own
+ * default, typically 'ask' or 'deny', until a human explicitly grants
+ * it) — see addGatewayTool's 'auto' decision mode, which is what
+ * actually calls this. The first token that matches either list wins,
+ * scanned in order; a name with no recognized verb at all (an
+ * inconsistently-named action, or a toolkit this list hasn't seen yet)
+ * defaults to *not* read-only — an unclassifiable tool staying at
+ * actauth's default is the safe failure mode, the reverse would silently
+ * auto-allow something this heuristic simply doesn't understand. Exported
+ * for testing and because adapters/http.ts's picker UI may want to show
+ * the same classification before a tool is even added. */
+export function isReadOnlyToolName(toolName) {
+    const tokens = toolName.toUpperCase().split('_');
+    for (const token of tokens) {
+        if (READ_ONLY_VERBS.has(token))
+            return true;
+        if (MUTATING_VERBS.has(token))
+            return false;
+    }
+    return false;
+}
+/** Seeds one exact-match actauth rule per tool this source produces —
+ * ActAuth's own `tool` matching is exact-string, not glob (only `scope`
+ * supports wildcards), so "allow everything gh_* produces" isn't
+ * expressible as one rule; each `${entry.name}_${slug}` tool name gets
+ * its own. Computed from `entry` directly (never a live call to the
+ * gateway) so adding a source doesn't require the CLI/provider to be
+ * reachable at that exact moment — only actually loading tools later
+ * does. Creates agents/<name>/actauth.yml (default_decision: deny) if it
+ * doesn't exist yet, same fallback loadRules' own default gets.
+ *
+ * `decision: 'auto'` seeds an explicit 'allow' rule for tools
+ * isReadOnlyToolName reads as safe, and an explicit 'ask' rule for
+ * everything else — never no rule at all. Relying on "no rule falls
+ * through to actauth's own default_decision" was the first cut of this,
+ * but that ties a mutating tool's actual governing decision to whatever
+ * default_decision happens to be *at the time someone reads it*: change
+ * default_decision later (say from 'ask' to 'allow' for an unrelated
+ * reason) and every mutating tool added this way silently becomes
+ * allowed too, with nothing in actauth.yml showing that ever happened.
+ * An explicit 'ask' rule can't drift like that. This is what the
+ * picker's own "select all" uses instead of forcing one decision onto a
+ * batch that might mix GITHUB_LIST_REPOS with GITHUB_DELETE_REPO.
+ *
+ * Edits via `yaml`'s Document API (parse → mutate the CST → toString),
+ * not parse-into-a-plain-object → re-stringify — the latter silently
+ * drops every comment in the file, which for a real, hand-maintained
+ * actauth.yml (see agents/customer-service/actauth.yml's own extensive
+ * rule-by-rule reasoning) would mean adding one gateway tool wipes out
+ * documentation an operator wrote for entirely unrelated rules. */
+function appendActauthRules(dir, toolNames, decision, provider) {
+    const path = join(dir, 'actauth.yml');
+    const doc = existsSync(path) ? parseDocument(readFileSync(path, 'utf8')) : parseDocument('default_decision: deny\nrules: []\n');
+    if (doc.get('rules') == null)
+        doc.set('rules', []);
+    const rules = doc.get('rules');
+    for (const tool of toolNames) {
+        const resolved = decision === 'auto' ? (isReadOnlyToolName(tool) ? 'allow' : 'ask') : decision;
+        // Prefixed with the *provider* (e.g. 'composio'), not the source's
+        // own local `name` (e.g. 'github') — `tool` already embeds the
+        // source name (`${entry.name}_${slug}`), so repeating it in the
+        // rule name too would be redundant; the provider is the one piece
+        // of context `tool` doesn't already carry.
+        rules.add(doc.createNode({ name: `${provider}-${tool}-web-added`, scope: '*/*', tool, decision: resolved }));
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, doc.toString());
+}
+/** The inverse of appendActauthRules — strips any rule it previously
+ * wrote for one of `toolNames`, recognized by the exact `-web-added`
+ * name suffix that function always writes, so a hand-authored rule that
+ * happens to reference the same tool (a different name, no suffix) is
+ * never touched. Called from removeGatewayTool/removeGatewayToolSlug so
+ * removing a tool also removes the permission it was granted, rather
+ * than leaving a rule that now governs nothing. A no-op, not an error,
+ * if actauth.yml doesn't exist or has no matching rule — removing a tool
+ * that was never given a seeded rule (decision omitted when it was
+ * added) is a completely normal case, not a problem to report. */
+function removeAutoAddedActauthRules(dir, toolNames) {
+    const path = join(dir, 'actauth.yml');
+    if (!existsSync(path))
+        return;
+    const doc = parseDocument(readFileSync(path, 'utf8'));
+    const rules = doc.get('rules');
+    if (!rules)
+        return;
+    const before = rules.items.length;
+    rules.items = rules.items.filter((rule) => {
+        const name = rule.get('name');
+        const tool = rule.get('tool');
+        return !(typeof name === 'string' && name.endsWith('-web-added') && typeof tool === 'string' && toolNames.includes(tool));
+    });
+    if (rules.items.length === before)
+        return;
+    writeFileSync(path, doc.toString());
+}
+function toolNamesFor(entry) {
+    return entry.slugs.map((slug) => `${entry.name}_${slug}`);
+}
+/** Registers a new gateway tool for `agentName` (top-level only — see
+ * readGatewayTools), or, if a source with this exact `name` is already
+ * registered, merges `entry.slugs` into it (deduped) instead of
+ * rejecting the call — the name is just a namespace label, not a
+ * one-shot slot; reusing it to add more tools under the same source is
+ * the common case (picking a few more actions for an app you already
+ * added), not a conflict. It's only a real conflict when the existing
+ * entry is for a *different* provider — two different connection
+ * configs can't share one name. `decision`, if given, pre-seeds an
+ * actauth rule per tool in *this call's own* `entry.slugs` (see
+ * appendActauthRules) — not the merged list, so re-adding an
+ * already-registered slug doesn't also re-seed a duplicate rule for it.
+ * Omit `decision` to leave every new tool at actauth's own
+ * defaultDecision (typically 'deny'), the same "new tools are opt-in,
+ * not silently allowed" convention every other tool in this repo
+ * follows. `decision: 'auto'` — see appendActauthRules — resolves per
+ * tool instead of applying one decision to the whole batch. */
+export function addGatewayTool(agentName, entry, decision) {
+    const dir = agentDir(agentName);
+    const sources = readGatewayToolsFromDir(dir);
+    const existingIndex = sources.findIndex((s) => s.name === entry.name);
+    if (existingIndex === -1) {
+        writeGatewayToolsFile(dir, [...sources, entry]);
+    }
+    else {
+        const existing = sources[existingIndex];
+        if (existing.provider !== entry.provider) {
+            throw new GatewayToolExistsError(`A gateway tool named '${entry.name}' already exists for '${agentName}' with a different provider ('${existing.provider}' vs '${entry.provider}') — pick a different name or remove it first.`);
+        }
+        const mergedSlugs = Array.from(new Set([...existing.slugs, ...entry.slugs]));
+        const updated = [...sources];
+        updated[existingIndex] = { ...existing, ...entry, slugs: mergedSlugs };
+        writeGatewayToolsFile(dir, updated);
+    }
+    if (decision)
+        appendActauthRules(dir, toolNamesFor(entry), decision, entry.provider);
+}
+/** Removes a gateway tool's registration, along with any actauth rule
+ * appendActauthRules previously seeded for it (see
+ * removeAutoAddedActauthRules — a hand-authored rule referencing the
+ * same tool under a different name is never touched). Removing a tool
+ * is expected to remove the permission it was granted too, not leave a
+ * rule that governs nothing behind. */
+export function removeGatewayTool(agentName, sourceName) {
+    const dir = agentDir(agentName);
+    const sources = readGatewayToolsFromDir(dir);
+    const existing = sources.find((s) => s.name === sourceName);
+    if (!existing) {
+        throw new GatewayToolNotFoundError(`No gateway tool named '${sourceName}' for '${agentName}'.`);
+    }
+    writeGatewayToolsFile(dir, sources.filter((s) => s.name !== sourceName));
+    removeAutoAddedActauthRules(dir, toolNamesFor(existing));
+}
+/** Removes one slug from an existing source — the per-tool remove icon
+ * in the Tools tab's Gateway Tools list, as opposed to removeGatewayTool
+ * above, which drops the whole source at once. Deletes the source
+ * entirely if that was its last slug: a source with zero slugs produces
+ * zero tools anyway (mcpplug's connectComposioSource loops per slug, see
+ * connectEntry), so there's nothing left worth keeping registered. Same
+ * "also remove any rule this tool was auto-granted" behavior as
+ * removeGatewayTool — see its own doc comment and
+ * removeAutoAddedActauthRules. */
+export function removeGatewayToolSlug(agentName, sourceName, slug) {
+    const dir = agentDir(agentName);
+    const sources = readGatewayToolsFromDir(dir);
+    const index = sources.findIndex((s) => s.name === sourceName);
+    if (index === -1 || !sources[index].slugs.includes(slug)) {
+        throw new GatewayToolNotFoundError(`No gateway tool '${slug}' registered under '${sourceName}' for '${agentName}'.`);
+    }
+    const remainingSlugs = sources[index].slugs.filter((s) => s !== slug);
+    const updated = remainingSlugs.length === 0
+        ? sources.filter((_, i) => i !== index)
+        : sources.map((s, i) => (i === index ? { ...s, slugs: remainingSlugs } : s));
+    writeGatewayToolsFile(dir, updated);
+    removeAutoAddedActauthRules(dir, [`${sources[index].name}_${slug}`]);
+}
+async function connectEntry(entry) {
+    if (entry.provider === 'composio') {
+        const source = await connectComposioSource(entry.name, { slugs: entry.slugs, cliCommand: entry.cliCommand });
+        try {
+            return await source.loadTools();
+        }
+        finally {
+            await source.close();
+        }
+    }
+    // Unreachable while GatewayToolEntry is a union of one — the check (and
+    // the cast it needs) starts earning its keep the moment a second
+    // provider is added and a stale gateway-tools.yml entry from before
+    // that provider existed needs a real error, not a silent skip.
+    throw new Error(`Unknown gateway tool provider '${entry.provider}'.`);
+}
+/** mcpplug's own connectComposioSource fills each ToolDefinition's
+ * description with a mechanically humanized slug (e.g. "abort repository
+ * migration") — the only thing it has to work with is `composio execute
+ * <slug> --get-schema`, which has no top-level description field, only
+ * per-input ones. Composio's own catalog (`composio tools list
+ * <toolkit>`) has a genuinely useful one instead (e.g. "Tool to abort a
+ * repository migration that is queued or in progress. Use when you need
+ * to cancel an ongoing migration operation.") — worth fetching for
+ * describeGatewayTools specifically (see its own "always current worth
+ * more than cheap" doc comment), an occasional, deliberate admin action.
+ * Deliberately *not* applied inside connectEntry itself, even though
+ * that would also improve what the model actually sees at runtime —
+ * connectEntry is loadGatewayToolsFromDir's hot path, and that function's
+ * own doc comment already explicitly rejects paying any extra
+ * reconnect/network cost there beyond what's unavoidable; confirmed live
+ * that adding one more CLI call per distinct toolkit on every cache-miss
+ * measurably slowed it down enough to blow real test timeouts.
+ *
+ * Toolkit is derived from each slug's own TOOLKIT_ACTION naming
+ * convention, not from `entry.name` — that's just a local namespace
+ * label an operator can set to anything (see ComposioGatewayToolEntry's
+ * own doc comment), so it can't be trusted to name a real toolkit.
+ * Best-effort per toolkit: a lookup failing (unusual slug shape, a
+ * toolkit no longer connected) just leaves those tools at their
+ * humanize() fallback rather than failing the whole call — same
+ * fail-open reasoning loadGatewayToolsFromDir's own doc comment already
+ * uses for a broken source. */
+async function withRealComposioDescriptions(tools, slugs, cliCommand) {
+    const toolkits = Array.from(new Set(slugs.map((slug) => slug.split('_')[0].toLowerCase())));
+    const descriptions = new Map();
+    await Promise.all(toolkits.map(async (toolkit) => {
+        try {
+            const catalog = await listComposioTools(toolkit, cliCommand);
+            for (const t of catalog)
+                descriptions.set(t.slug, t.description);
+        }
+        catch {
+            // Best-effort — see this function's own doc comment.
+        }
+    }));
+    return tools.map((tool, i) => {
+        const real = descriptions.get(slugs[i]);
+        return real ? { ...tool, description: real } : tool;
+    });
+}
+/** The admin page's read model — every registered source for `agentName`,
+ * each actually connected to and reported on individually, same
+ * fail-open-per-source behavior loadGatewayToolsFromDir has (see its own
+ * doc comment). The difference is what happens with a failure: this
+ * function surfaces it explicitly, per source, since an operator looking
+ * at this page needs to know *which* source is broken and why — where
+ * loadGatewayToolsFromDir just logs and drops it, since runAgent() has no
+ * structured place to hand a per-source error to. Deliberately bypasses
+ * loadGatewayToolsFromDir's mtime cache — this is an occasional,
+ * deliberate operator action, not a per-turn hot path, so "always
+ * current" is worth more here than "cheap." */
+export async function describeGatewayTools(agentName) {
+    const entries = readGatewayTools(agentName);
+    return Promise.all(entries.map(async (entry) => {
+        try {
+            const rawTools = await connectEntry(entry);
+            // See withRealComposioDescriptions' own doc comment for why this
+            // enrichment happens here, not inside connectEntry itself.
+            const tools = entry.provider === 'composio' ? await withRealComposioDescriptions(rawTools, entry.slugs, entry.cliCommand) : rawTools;
+            return { entry, status: 'ok', tools: tools.map((t) => ({ name: t.name, description: t.description })) };
+        }
+        catch (err) {
+            return { entry, status: 'error', tools: [], error: err instanceof Error ? err.message : String(err) };
+        }
+    }));
+}
+/** In-memory, keyed by the registry file's own mtime — cheap to check
+ * every call (one stat), and correct: it can only go stale if the file
+ * changes without its mtime changing, which no real filesystem does.
+ * Real cost here is connectEntry's own CLI subprocess-per-slug (see
+ * mcpplug's composio-source.ts) — reconnecting on every single
+ * runAgent() turn would be a real, unnecessary latency tax the rest of
+ * this repo's folder-form defaults (loadDefaultTools, loadRules) don't
+ * have to worry about, since those are plain reads/imports, not a
+ * network/subprocess round trip. */
+const cache = new Map();
+/** Resolves agents/<name>/gateway-tools.yml (or the equivalent nested path
+ * for a subagent — see readGatewayToolsFromDir) into real ToolDefinitions,
+ * for run-agent.ts to merge into the rest of an agent's tools. Missing
+ * file is `[]`, no cache entry created.
+ *
+ * Fails open per source: one broken/unreachable gateway (Composio down,
+ * a CLI not authenticated) is logged and contributes no tools, rather
+ * than rejecting the whole call — the same reasoning a single tool's own
+ * `execute()` failing doesn't crash runAgent's whole turn (ToolLane
+ * reports it as an is_error tool_result instead). Without this, an agent
+ * with an unrelated broken integration would fail *every* request, tools
+ * it actually needs included — confirmed live: a run-agent.test.ts test
+ * that reuses the real 'file-agent' name purely to exercise the
+ * skillsDirs default started silently depending on the real `composio`
+ * CLI/network the moment agents/file-agent/gateway-tools.yml existed,
+ * before this fix made a failed (or slow/unavailable) source harmless
+ * instead of fatal. */
+export async function loadGatewayToolsFromDir(dir) {
+    const path = gatewayToolsPath(dir);
+    if (!existsSync(path))
+        return [];
+    const mtimeMs = statSync(path).mtimeMs;
+    const cached = cache.get(path);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.tools;
+    const entries = readGatewayToolsFromDir(dir);
+    const resolved = await Promise.all(entries.map(async (entry) => {
+        try {
+            return await connectEntry(entry);
+        }
+        catch (err) {
+            console.error(`[gateway-tools] source '${entry.name}' (${entry.provider}) failed to load, skipping: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }));
+    const tools = resolved.flat();
+    cache.set(path, { mtimeMs, tools });
+    return tools;
+}
+// ----- Discovery: what's already connected, what a connected app offers
+// -----
+//
+// The add-a-source form used to ask an operator to already know a
+// toolkit's exact slug strings by heart — real friction, and the only
+// reason was that nothing in this file had actually shelled out to check
+// what `composio connections list` / `composio tools list <toolkit>`
+// return. Both work off the same `composio link <toolkit>` auth
+// connectComposioSource already assumes — no extra "developer project"
+// setup (`composio dev init`) needed, confirmed against a real CLI
+// before building this.
+async function runComposioCli(cliCommand, args) {
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await execFileAsync(cliCommand, args));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`composio CLI call failed (${args.join(' ')}): ${message}`);
+    }
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`composio CLI returned non-JSON output for ${args.join(' ')}: ${stdout}`);
+    }
+}
+/** Flattens `composio connections list`'s own shape (a map of toolkit
+ * slug -> array of accounts) into one array — easier for a caller (the
+ * add-source picker) to filter/sort without knowing that shape itself.
+ * Every toolkit with at least one connected account appears, `status`
+ * and all; deciding what counts as "usable" (typically just `'ACTIVE'`)
+ * is left to the caller; a CLI/auth failure propagates as a normal
+ * rejection — see runComposioCli. */
+export async function listComposioConnections(cliCommand = 'composio') {
+    const raw = (await runComposioCli(cliCommand, ['connections', 'list']));
+    const connections = [];
+    for (const [toolkit, accounts] of Object.entries(raw)) {
+        for (const account of accounts) {
+            connections.push({ toolkit, status: account.status, alias: account.alias ?? null, wordId: account.word_id ?? null });
+        }
+    }
+    return connections;
+}
+/** What `composio tools list <toolkit>` offers for one already-connected
+ * app — the picker's second step, once a toolkit is chosen from
+ * listComposioConnections. Every action a toolkit exposes, not just ones
+ * already registered as a gateway tool source — the picker's whole point
+ * is showing what's *available* to add. `--limit 1000` (the CLI's own
+ * max) is explicit rather than left to the CLI's own default: without
+ * it, `composio tools list github` silently caps at 30 results — out of
+ * GitHub's real ~900, and alphabetically sorted, so a picker session
+ * would only ever see a narrow, unrepresentative slice (every result
+ * starting with "A" — ABORT/ACCEPT/ADD/API/APPROVE/ASSIGN — almost all
+ * mutating verbs), not "every tool this toolkit has" the doc comment
+ * above already promises. Confirmed live against the real CLI: no
+ * --limit gave 30, --limit 1000 gave 893. */
+export async function listComposioTools(toolkit, cliCommand = 'composio') {
+    const raw = (await runComposioCli(cliCommand, ['tools', 'list', toolkit, '--limit', '1000']));
+    return raw.map((t) => ({ slug: t.slug, name: t.name, description: t.description }));
+}
+/** Whether the composio CLI itself (not any one connected app — see
+ * listComposioConnections for that) is authenticated on this machine.
+ * `composio whoami` succeeds once `composio login` has run and fails
+ * otherwise, so a failure here is read as "not connected", not
+ * propagated as an error the way listComposioConnections' own CLI
+ * failures are — this is a normal, expected state for an environment
+ * that just hasn't been logged in yet, not a bug. Deliberately
+ * read-only: login is an interactive, machine-wide CLI session (opens a
+ * browser, affects every agent's gateway tools, not just one web
+ * request), so the global config page's Gateways panel that calls this
+ * only ever shows status + instructions, never drives login/logout
+ * itself. */
+export async function getComposioAuthStatus(cliCommand = 'composio') {
+    try {
+        const raw = (await runComposioCli(cliCommand, ['whoami']));
+        return { connected: true, email: raw.email, org: raw.current_org_name };
+    }
+    catch {
+        return { connected: false };
+    }
+}
+/** `composio logout` — already non-interactive on its own (see its own
+ * --help), unlike login. Machine-wide: this deauthenticates the CLI for
+ * every agent's gateway tools on this machine, not just the browser tab
+ * that clicked Disconnect — same as running it in a terminal yourself.
+ *
+ * There's no connectComposioAccount counterpart: `composio login`'s only
+ * non-interactive path is `--user-api-key`, which turned out not to be
+ * what an operator actually has on hand — the key Composio's own
+ * dashboard hands out for MCP client auth (sent via an x-consumer-api-key
+ * header) isn't the same credential, and 401s against this flag.
+ * Composio's own documented path is plain, interactive `composio login`
+ * (opens a browser) after installing the CLI — not something a web
+ * request can drive, so the Gateways panel shows that as instructions
+ * instead of a form; see its own comment in adapters/global-config-page.ts. */
+export async function disconnectComposioAccount(cliCommand = 'composio') {
+    await execFileAsync(cliCommand, ['logout']);
+}

package/dist/run-agent.d.ts

@@ -89,4 +89,26 @@ export interface RunAgentResult {
  * actually enforce, not a re-derived guess at them. */
 export declare function loadRules(config: AgentConfig): RuleSet;
 export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefinition[]>;
+/** Auto-loads agents/<name>/subagents/<child>/index.{ts,js} — each one a
+ * full AgentConfig, wrapped with agentAsTool and merged into `config`'s
+ * own tools, no import or AgentConfig.tools edit required. Unlike
+ * loadDefaultTools, this always runs regardless of whether `config.tools`
+ * was left to its own default or set explicitly — see AgentConfig.tools's
+ * own doc comment for why subagents are a distinct concern from
+ * hand-written tools. A missing subagents/ folder is just `[]`, same
+ * missing-is-fine treatment tools/ and skills/ get; a subdirectory with
+ * neither index.ts nor index.js is skipped, same as resolveModulePath's
+ * own handling in discover-agents.ts.
+ *
+ * Each subagent is loaded via loadAgentModule — the same per-module
+ * resolution discoverAgents itself uses — then patched by
+ * resolveSubagentConfig (see its own doc comment for why) before being
+ * wrapped. Its own `config` goes through this exact same function again
+ * the next time *it* runs (inside agentAsTool's execute, via runAgent).
+ * That's what makes nesting (a subagent with its own subagents/ folder)
+ * work with no extra recursion code: it's just this function being
+ * called again, one level down. A folder can't be its own ancestor, so
+ * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
+ * elsewhere could. */
+export declare function loadSubagentAsTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/run-agent.js

@@ -14,6 +14,7 @@ import { ToolLane } from 'toollane';
 import { Reflow } from 'reflowkit';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
+import { loadGatewayToolsFromDir } from './gateway-tools.js';
 // Resolved relative to *this file's own location* (via import.meta.url),
 // not process.cwd() — the same reasoning agent-registry.ts's own
 // agentsDir uses. In dev (tsx), this file and agents/ are both source
@@ -139,7 +140,7 @@ export async function loadDefaultTools(config) {
  * `agents/<name>/` — correct for a top-level agent, where that's exactly
  * where its module lives, but wrong for a subagent: its `config` only
  * carries its own bare name (e.g. 'billing-agent'), not the nested folder
- * loadSubagentTools actually found it in
+ * loadSubagentAsTools actually found it in
  * (`agents/support-orchestrator/subagents/billing-agent/`). Left alone,
  * an omitted `tools`/`rules`/`skillsDirs` on a subagent would silently
  * resolve against `agents/billing-agent/...` instead — empty, if no such
@@ -154,12 +155,19 @@ export async function loadDefaultTools(config) {
  * deny-everything ruleset" fallback loadRules's own default path gets —
  * computed here instead of left to loadRules, since leaving `rules`
  * unset would have it fall through to loadRules's *own* (wrong,
- * name-based) default path instead of this one. */
+ * name-based) default path instead of this one.
+ *
+ * `gateway-tools.yml` (see gateway-tools.ts) gets the same dir-correctness
+ * fix, but merged in unconditionally rather than gated on `tools` being
+ * unset — same reasoning loadSubagentAsTools' own unconditional merge into
+ * the top-level tools line has: gateway-registered tools are an
+ * operator/admin concern, distinct from hand-written `tools`, so setting
+ * `tools` explicitly shouldn't opt a subagent out of its own
+ * gateway-tools.yml the way it opts out of the tools/ folder default. */
 async function resolveSubagentConfig(config, dir) {
     const resolved = { ...config };
-    if (resolved.tools === undefined) {
-        resolved.tools = await loadToolsFromDir(join(dir, 'tools'));
-    }
+    const baseTools = resolved.tools === undefined ? await loadToolsFromDir(join(dir, 'tools')) : resolved.tools;
+    resolved.tools = [...baseTools, ...(await loadGatewayToolsFromDir(dir))];
     if (resolved.rules === undefined) {
         const rulesPath = join(dir, 'actauth.yml');
         if (existsSync(rulesPath)) {
@@ -196,7 +204,7 @@ async function resolveSubagentConfig(config, dir) {
  * called again, one level down. A folder can't be its own ancestor, so
  * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
  * elsewhere could. */
-async function loadSubagentTools(config) {
+export async function loadSubagentAsTools(config) {
     const subagentsDir = join(agentsRootDir, config.name, 'subagents');
     if (!existsSync(subagentsDir))
         return [];
@@ -229,10 +237,15 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     // (including `[]`) is used as-is; omitted entirely defaults to
     // importing agents/<name>/tools/index.{ts,js} — see loadDefaultTools's
     // own doc comment for the full reasoning and the cases that can't use it.
-    // agents/<name>/subagents/* is merged in on top either way — see
-    // loadSubagentTools's own doc comment for why that one isn't gated by
+    // agents/<name>/subagents/* and agents/<name>/gateway-tools.yml (see
+    // gateway-tools.ts) are both merged in on top either way — see
+    // loadSubagentAsTools's own doc comment for why neither is gated by
     // whether `tools` was explicit.
-    const tools = [...(config.tools ?? (await loadDefaultTools(config))), ...(await loadSubagentTools(config))];
+    const tools = [
+        ...(config.tools ?? (await loadDefaultTools(config))),
+        ...(await loadSubagentAsTools(config)),
+        ...(await loadGatewayToolsFromDir(join(agentsRootDir, config.name))),
+    ];
     // Omitted entirely (undefined): default to this agent's own
     // agents/<name>/skills — the folder-form convention every agent in
     // this repo already follows (see agent-config.ts's skillsDirs doc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -40,12 +40,14 @@
     "dist/discover-agents.d.ts",
     "dist/agent-as-tool.js",
     "dist/agent-as-tool.d.ts",
+    "dist/gateway-tools.js",
+    "dist/gateway-tools.d.ts",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc && chmod +x dist/cli.js",
     "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": {