loopengine 0.0.17 → 0.0.20

package/dist/core/client.d.ts

@@ -0,0 +1,113 @@
+import type { LoopEvent } from './loop-events.js';
+import type { Message } from './run-agent.js';
+export interface RequestOptions {
+    /** Resumes an existing conversation — omit for a fresh one; see
+     * adapters/http.ts's own sessionIdFor for how the server derives one
+     * when omitted. */
+    sessionId?: string;
+    /** Extra headers on top of 'content-type: application/json' — e.g. HTTP
+     * Basic Auth (LOOPENGINE_ADMIN_AUTH) or an AgentConfig.tenantFor header. */
+    headers?: Record<string, string>;
+    /** Merged into the request body alongside `message`/`sessionId` — for an
+     * AgentConfig with its own sessionIdFor/tenantFor reading extra fields
+     * (see adapters/http.ts's own resolveTenant). */
+    body?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/** POST /agents/:name/messages's own 200 response — the turn finished,
+ * genuinely or via a synthetic stopReason (see loop-events.ts's own
+ * DoneEvent). `events` is every LoopEvent this turn produced, start to
+ * finish — the same array a streamed turn delivers frame-by-frame. */
+export interface SendMessageResult {
+    text: string;
+    sessionId: string;
+    events: LoopEvent[];
+    stopReason?: 'max_turns' | 'denied';
+}
+interface PendingResultBase {
+    pending: true;
+    id: string;
+    sessionId: string;
+    events: LoopEvent[];
+    /** GET this to rehydrate the conversation (and re-discover this same
+     * pending item) if the caller navigates away before deciding it. */
+    statusUrl: string;
+}
+/** POST /agents/:name/messages's own 202 response when the turn needs a
+ * human 'ask' decision before it can continue — resolve it with
+ * approveCall/denyCall below, both of which return this same
+ * MessageResult union, so a caller can treat approve/deny/answer and the
+ * original send as one uniform decide-or-finish loop. */
+export interface PendingApprovalResult extends PendingResultBase {
+    type: 'approval';
+    tool: string;
+    args: Record<string, unknown>;
+    scope: {
+        tenant: string;
+        environment: string;
+        agent: string;
+    };
+    reason: string;
+    approveUrl: string;
+    denyUrl: string;
+}
+/** Same as PendingApprovalResult, for the system ask_user tool's own
+ * open-ended question instead of a fixed allow/deny — resolve with
+ * answerQuestion below. */
+export interface PendingQuestionResult extends PendingResultBase {
+    type: 'question';
+    question: string;
+    options?: string[];
+    answerUrl: string;
+}
+export type PendingResult = PendingApprovalResult | PendingQuestionResult;
+export type MessageResult = SendMessageResult | PendingResult;
+/** The non-streaming half of the protocol — one request, one response,
+ * either done (SendMessageResult) or needing a decision (PendingResult).
+ * Reach for this over streamMessage() when the caller doesn't need live,
+ * frame-by-frame updates (a bot integration, a batch job, a callback-
+ * style webhook handler) — same underlying turn, same event vocabulary in
+ * `events`, just delivered all at once instead of incrementally. */
+export declare function sendMessage(baseUrl: string, agent: string, message: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function approveCall(baseUrl: string, id: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function denyCall(baseUrl: string, id: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function answerQuestion(baseUrl: string, id: string, answer: string, options?: RequestOptions): Promise<MessageResult>;
+/** GET /agents/:name/sessions/:id — rehydrates a conversation's stored
+ * history, e.g. after a page reload lost whatever in-memory state a React/
+ * Vue app was holding (mirrors web/playground.ts's own resumeSession). */
+export declare function getSessionHistory(baseUrl: string, agent: string, sessionId: string, options?: Pick<RequestOptions, 'headers' | 'signal'>): Promise<{
+    sessionId: string;
+    history: Message[];
+}>;
+/** The streaming half of the protocol — an async generator yielding one
+ * LoopEvent per SSE frame as it arrives, always starting with `session`
+ * and ending with `done` or `error` (see loop-events.ts's own header
+ * comment). `for await` is the natural fit for a React effect or Vue
+ * composable driving off this directly:
+ *
+ *   for await (const event of streamMessage(baseUrl, agent, text, { signal })) {
+ *     setEvents((prev) => [...prev, event])
+ *     if (event.type === 'done' || event.type === 'error') break
+ *   }
+ *
+ * Pass an AbortController's signal to let the caller cancel mid-stream
+ * (a React effect's own cleanup, a Vue component's onUnmounted) — the
+ * underlying fetch is aborted and the generator simply stops yielding,
+ * same as any other AbortSignal-aware fetch call.
+ */
+export declare function streamMessage(baseUrl: string, agent: string, message: string, options?: RequestOptions): AsyncGenerator<LoopEvent, void, void>;
+export interface StreamMessageCallbacks {
+    onEvent?: (event: LoopEvent) => void;
+    onDone?: (event: Extract<LoopEvent, {
+        type: 'done';
+    }>) => void;
+    onError?: (event: Extract<LoopEvent, {
+        type: 'error';
+    }>) => void;
+}
+/** Callback-flavored wrapper over streamMessage() for a caller that would
+ * rather pass handlers into a `useEffect`/lifecycle hook than manage a
+ * `for await` loop and its own break condition by hand. Resolves once the
+ * stream ends (a 'done'/'error' event, or the connection just closing). */
+export declare function streamMessageWithCallbacks(baseUrl: string, agent: string, message: string, options: RequestOptions, callbacks: StreamMessageCallbacks): Promise<void>;
+export {};

package/dist/core/client.js

@@ -0,0 +1,123 @@
+async function postJson(url, body, options = {}) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...options.headers },
+        body: JSON.stringify(body),
+        signal: options.signal,
+    });
+    const parsed = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
+    if (!res.ok)
+        throw new Error(parsed.error ?? `HTTP ${res.status}`);
+    return parsed;
+}
+function messageBody(message, options) {
+    return { message, ...(options.sessionId ? { sessionId: options.sessionId } : {}), ...options.body };
+}
+/** The non-streaming half of the protocol — one request, one response,
+ * either done (SendMessageResult) or needing a decision (PendingResult).
+ * Reach for this over streamMessage() when the caller doesn't need live,
+ * frame-by-frame updates (a bot integration, a batch job, a callback-
+ * style webhook handler) — same underlying turn, same event vocabulary in
+ * `events`, just delivered all at once instead of incrementally. */
+export function sendMessage(baseUrl, agent, message, options = {}) {
+    return postJson(`${baseUrl}/agents/${encodeURIComponent(agent)}/messages`, messageBody(message, options), options);
+}
+export function approveCall(baseUrl, id, options = {}) {
+    return postJson(`${baseUrl}/approvals/${encodeURIComponent(id)}/approve`, undefined, options);
+}
+export function denyCall(baseUrl, id, options = {}) {
+    return postJson(`${baseUrl}/approvals/${encodeURIComponent(id)}/deny`, undefined, options);
+}
+export function answerQuestion(baseUrl, id, answer, options = {}) {
+    return postJson(`${baseUrl}/questions/${encodeURIComponent(id)}/answer`, { answer }, options);
+}
+/** GET /agents/:name/sessions/:id — rehydrates a conversation's stored
+ * history, e.g. after a page reload lost whatever in-memory state a React/
+ * Vue app was holding (mirrors web/playground.ts's own resumeSession). */
+export async function getSessionHistory(baseUrl, agent, sessionId, options = {}) {
+    const res = await fetch(`${baseUrl}/agents/${encodeURIComponent(agent)}/sessions/${encodeURIComponent(sessionId)}`, {
+        headers: options.headers,
+        signal: options.signal,
+    });
+    const body = (await res.json());
+    if (!res.ok)
+        throw new Error(body.error ?? `HTTP ${res.status}`);
+    return body;
+}
+function parseSseFrame(frame) {
+    let dataLine = '';
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('data: '))
+            dataLine = line.slice('data: '.length);
+    }
+    if (!dataLine)
+        return undefined;
+    try {
+        return JSON.parse(dataLine);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The streaming half of the protocol — an async generator yielding one
+ * LoopEvent per SSE frame as it arrives, always starting with `session`
+ * and ending with `done` or `error` (see loop-events.ts's own header
+ * comment). `for await` is the natural fit for a React effect or Vue
+ * composable driving off this directly:
+ *
+ *   for await (const event of streamMessage(baseUrl, agent, text, { signal })) {
+ *     setEvents((prev) => [...prev, event])
+ *     if (event.type === 'done' || event.type === 'error') break
+ *   }
+ *
+ * Pass an AbortController's signal to let the caller cancel mid-stream
+ * (a React effect's own cleanup, a Vue component's onUnmounted) — the
+ * underlying fetch is aborted and the generator simply stops yielding,
+ * same as any other AbortSignal-aware fetch call.
+ */
+export async function* streamMessage(baseUrl, agent, message, options = {}) {
+    const res = await fetch(`${baseUrl}/agents/${encodeURIComponent(agent)}/messages/stream`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...options.headers },
+        body: JSON.stringify(messageBody(message, options)),
+        signal: options.signal,
+    });
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('text/event-stream')) {
+        const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
+        yield { type: 'error', error: body.error ?? `HTTP ${res.status}` };
+        return;
+    }
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buffer.indexOf('\n\n')) !== -1) {
+            const frame = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 2);
+            const event = parseSseFrame(frame);
+            if (event)
+                yield event;
+        }
+    }
+}
+/** Callback-flavored wrapper over streamMessage() for a caller that would
+ * rather pass handlers into a `useEffect`/lifecycle hook than manage a
+ * `for await` loop and its own break condition by hand. Resolves once the
+ * stream ends (a 'done'/'error' event, or the connection just closing). */
+export async function streamMessageWithCallbacks(baseUrl, agent, message, options, callbacks) {
+    for await (const event of streamMessage(baseUrl, agent, message, options)) {
+        callbacks.onEvent?.(event);
+        if (event.type === 'done')
+            callbacks.onDone?.(event);
+        else if (event.type === 'error')
+            callbacks.onError?.(event);
+    }
+}

package/dist/core/discover-agents.d.ts

@@ -0,0 +1,45 @@
+import type { AgentConfig, AgentModelConfig } from '#core/agent-config.js';
+import type { ModelCall } from '#core/run-agent.js';
+export interface AgentModule {
+    config: AgentConfig;
+    /** Factory, not a shared instance — a fresh ModelCall per request/session. */
+    createModelCall: () => ModelCall;
+}
+/** Builds a lazy, memoized createModelCall from AgentConfig.model, for a
+ * module that doesn't export its own — see that field's own doc comment.
+ * The provider's SDK module is imported here, eagerly, but that's cheap
+ * and safe with no API key at all: importing model-calls/*.ts only
+ * defines functions, it never constructs a client at module top level
+ * (see e.g. createAnthropicModelCall's own body) — so this can't fail
+ * discovery the way eagerly building the actual client would. The real
+ * client is only built the first time the returned function is actually
+ * called, and reused after that, the same "don't crash the whole server
+ * over one agent's missing API key, don't rebuild per call" reasoning
+ * agents/customer-service/index.ts's own hand-written createModelCall
+ * used before this existed.
+ *
+ * Exported so a caller updating an *already-registered* agent's model
+ * (see agent-file-admin.ts's editAgentFile, applied live via
+ * core/agent-registry.ts's updateAgent) can rebuild just this one closure
+ * without re-importing the whole module — Node's ESM loader caches an
+ * already-imported module forever, so there's no supported way to
+ * re-import a changed agent file's own createModelCall directly; this is
+ * the one piece of it that's meaningfully regenerable on its own. */
+export declare function synthesizeCreateModelCall(model: AgentModelConfig): Promise<() => 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 / 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
+ * that path. */
+export declare function loadAgentModule(path: string, label: string): Promise<AgentModule>;
+/** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
+ * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
+ * each expected to export `config`, and either its own `createModelCall`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
+export declare function discoverAgents(dir: string): Promise<Map<string, AgentModule>>;

package/dist/{discover-agents.js → core/discover-agents.js}

@@ -1,7 +1,7 @@
 // Scans a directory for agent modules and builds a name -> module map from
 // it — the thing that makes "drop a new file in agents/" enough to
 // register an agent, no hand-written import-and-add-one-line edit needed
-// anywhere else. See agent-registry.ts for the one place this repo's own
+// anywhere else. See core/agent-registry.ts for the one place this repo's own
 // reference app actually calls it.
 //
 // Keyed by AgentConfig.name, not the filename — that's the same identity
@@ -28,8 +28,16 @@ function isRawAgentModule(mod) {
  * called, and reused after that, the same "don't crash the whole server
  * over one agent's missing API key, don't rebuild per call" reasoning
  * agents/customer-service/index.ts's own hand-written createModelCall
- * used before this existed. */
-async function synthesizeCreateModelCall(model) {
+ * used before this existed.
+ *
+ * Exported so a caller updating an *already-registered* agent's model
+ * (see agent-file-admin.ts's editAgentFile, applied live via
+ * core/agent-registry.ts's updateAgent) can rebuild just this one closure
+ * without re-importing the whole module — Node's ESM loader caches an
+ * already-imported module forever, so there's no supported way to
+ * re-import a changed agent file's own createModelCall directly; this is
+ * the one piece of it that's meaningfully regenerable on its own. */
+export async function synthesizeCreateModelCall(model) {
     let cached;
     if (model.provider === 'anthropic') {
         const { createAnthropicModelCall } = await import('./model-calls/anthropic-model-call.js');
@@ -66,7 +74,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/core/gateway-tools.d.ts

@@ -0,0 +1,226 @@
+import type { Decision } from 'actauth';
+import type { ToolDefinition } from './agent-config.js';
+export interface ResolvedGatewayTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+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;
+    /** {name, description, input_schema} per slug, once resolved — see
+     * connectEntry/describeGatewayTools. Populated lazily (a slug just
+     * added via addGatewayTool has no entry here yet) and persisted back
+     * into this same file (see persistResolvedTools), not held in memory —
+     * so a schema, once resolved, survives a server restart instead of
+     * costing another ~3s Composio round trip on the next load. Keyed by
+     * slug, not by the derived tool name (`${name}_${slug}`), since the
+     * slug is what's stable if this source were ever renamed. Hand-editing
+     * this is never expected — treat it as generated, the same as
+     * describeGatewayTools' own in-memory result used to be before this
+     * existed. */
+    resolved?: Record<string, ResolvedGatewayTool>;
+}
+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.
+ *
+ * No in-memory cache here (or anywhere in this file, for this) — the
+ * cache *is* gateway-tools.yml's own `resolved` field (see
+ * ComposioGatewayToolEntry's own doc comment and connectEntry, which this
+ * shares that field with), so it survives a restart instead of being
+ * lost on one. Only genuinely-unresolved slugs pay for a live fetch, and
+ * for those this still enriches with Composio's real catalog description
+ * (see withRealComposioDescriptions) before persisting — unlike
+ * connectEntry, which doesn't (see that function's own reasoning), this
+ * is an occasional operator action, not runAgent()'s hot path, so paying
+ * for the better description once, at resolution time, is worth it here.
+ * Pass `force: true` (the admin page's own "Refresh" button) to treat
+ * every slug as unresolved and overwrite their persisted entries with a
+ * fresh live check — e.g. after reconnecting an account, or on the rare
+ * chance a schema changed upstream without gateway-tools.yml itself
+ * changing. */
+export declare function describeGatewayTools(agentName: string, options?: {
+    force?: boolean;
+}): 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 web/global-config-page.ts. */
+export declare function disconnectComposioAccount(cliCommand?: string): Promise<void>;