loopengine 0.0.18 → 0.0.21

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');

package/dist/{gateway-tools.d.ts → core/gateway-tools.d.ts}

@@ -1,5 +1,10 @@
 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}`,
@@ -10,6 +15,18 @@ export interface ComposioGatewayToolEntry {
     /** 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
@@ -103,11 +120,26 @@ export interface GatewayToolStatus {
  * 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[]>;
+ * 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
@@ -190,5 +222,5 @@ export declare function getComposioAuthStatus(cliCommand?: string): Promise<Comp
  * 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. */
+ * instead of a form; see its own comment in web/global-config-page.ts. */
 export declare function disconnectComposioAccount(cliCommand?: string): Promise<void>;

package/dist/{gateway-tools.js → core/gateway-tools.js}

@@ -15,12 +15,13 @@ 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');
+// Same "one level up from this file, not process.cwd()" reasoning
+// run-agent.ts's own agentsRootDir uses (this file lives in core/
+// alongside it, with agents/ one level up at repo root either way) — 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');
 }
@@ -56,6 +57,28 @@ function writeGatewayToolsFile(dir, sources) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(gatewayToolsPath(dir), stringifyYaml({ sources }));
 }
+// Re-reads and writes gateway-tools.yml fresh, not off whatever snapshot
+// the caller (connectEntry/describeGatewayTools) originally read — a
+// live resolution can take real seconds (mcpplug's per-slug CLI round
+// trips), long enough for an admin-UI edit (add/remove a slug) to land
+// in between. Merged into the source's existing `resolved`, not
+// replaced, so two overlapping resolutions of different slug subsets
+// (e.g. connectEntry resolving one newly-added slug while
+// describeGatewayTools resolves another) don't clobber each other.
+// Silently a no-op if the source itself is gone by the time this runs —
+// nothing left to persist onto.
+function persistResolvedTools(dir, sourceName, newlyResolved) {
+    if (!Object.keys(newlyResolved).length)
+        return;
+    const sources = readGatewayToolsFromDir(dir);
+    const index = sources.findIndex((s) => s.name === sourceName);
+    if (index === -1)
+        return;
+    const existing = sources[index];
+    const updated = [...sources];
+    updated[index] = { ...existing, resolved: { ...existing.resolved, ...newlyResolved } };
+    writeGatewayToolsFile(dir, updated);
+}
 export class GatewayToolExistsError extends Error {
 }
 export class GatewayToolNotFoundError extends Error {
@@ -304,21 +327,86 @@ export function removeGatewayToolSlug(agentName, sourceName, slug) {
         throw new GatewayToolNotFoundError(`No gateway tool '${slug}' registered under '${sourceName}' for '${agentName}'.`);
     }
     const remainingSlugs = sources[index].slugs.filter((s) => s !== slug);
+    // Drops the removed slug's own resolved entry too — leaving it behind
+    // would just be dead weight (nothing in `slugs` references it anymore,
+    // so it can never be read back), and would silently reappear if the
+    // exact same slug were ever re-added later, skipping what should be a
+    // fresh resolution. Omitted entirely (not `resolved: {}`) once empty —
+    // a source that never had any resolved slugs shouldn't gain a stray
+    // empty field just because one was removed from it.
+    const { [slug]: _removed, ...remainingResolved } = sources[index].resolved ?? {};
     const updated = remainingSlugs.length === 0
         ? sources.filter((_, i) => i !== index)
-        : sources.map((s, i) => (i === index ? { ...s, slugs: remainingSlugs } : s));
+        : sources.map((s, i) => {
+            if (i !== index)
+                return s;
+            const next = { ...s, slugs: remainingSlugs };
+            if (Object.keys(remainingResolved).length)
+                next.resolved = remainingResolved;
+            else
+                delete next.resolved;
+            return next;
+        });
     writeGatewayToolsFile(dir, updated);
     removeAutoAddedActauthRules(dir, [`${sources[index].name}_${slug}`]);
 }
-async function connectEntry(entry) {
+// Builds a ToolDefinition straight from gateway-tools.yml's own persisted
+// `resolved` entry — no CLI call at all for the schema/description, since
+// those are exactly what's already cached. execute() itself still always
+// shells out fresh (mirrors mcpplug's composio-source.ts own execute
+// closure exactly — resolving *what a tool is* is cacheable, actually
+// *running* it never is).
+function toolFromResolved(slug, resolved, cliCommand) {
+    return {
+        name: resolved.name,
+        description: resolved.description,
+        input_schema: resolved.input_schema,
+        execute: async (input) => {
+            const result = (await runComposioCli(cliCommand ?? 'composio', ['execute', slug, '-d', JSON.stringify(input)]));
+            if (result.successful === false || result.error) {
+                throw new Error(`composio tool ${slug} failed: ${JSON.stringify(result.error ?? result)}`);
+            }
+            return result.data ?? result;
+        },
+    };
+}
+// The only thing that still needs mcpplug/a live Composio round trip —
+// slugs with no persisted resolution yet (just registered, or a `force`
+// re-check). Returns [] without touching the CLI at all when there's
+// nothing left to resolve, which is the common case once a source's
+// slugs have all been resolved once.
+async function fetchUnresolvedSlugs(entry, slugs) {
+    if (!slugs.length)
+        return [];
+    const source = await connectComposioSource(entry.name, { slugs, cliCommand: entry.cliCommand });
+    try {
+        return await source.loadTools();
+    }
+    finally {
+        await source.close();
+    }
+}
+/** Resolves `entry` into real ToolDefinitions for run-agent.ts to merge
+ * in, preferring gateway-tools.yml's own persisted `resolved` data (see
+ * ComposioGatewayToolEntry's own doc comment) over asking Composio again —
+ * mcpplug's connectComposioSource (and the ~3s-per-slug CLI round trip it
+ * costs) is only ever invoked for slugs that aren't resolved yet. Newly
+ * resolved slugs are persisted back before returning, so the *next* call
+ * (even after a restart) skips the live fetch entirely too. */
+async function connectEntry(entry, dir) {
     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();
+        const resolved = entry.resolved ?? {};
+        const cachedTools = entry.slugs.filter((slug) => resolved[slug]).map((slug) => toolFromResolved(slug, resolved[slug], entry.cliCommand));
+        const unresolvedSlugs = entry.slugs.filter((slug) => !resolved[slug]);
+        const freshTools = await fetchUnresolvedSlugs(entry, unresolvedSlugs);
+        if (freshTools.length) {
+            const newlyResolved = {};
+            freshTools.forEach((tool, i) => {
+                newlyResolved[unresolvedSlugs[i]] = { name: tool.name, description: tool.description, input_schema: tool.input_schema };
+            });
+            persistResolvedTools(dir, entry.name, newlyResolved);
         }
+        return [...cachedTools, ...freshTools];
     }
     // Unreachable while GatewayToolEntry is a union of one — the check (and
     // the cast it needs) starts earning its keep the moment a second
@@ -334,9 +422,10 @@ async function connectEntry(entry) {
  * <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
+ * describeGatewayTools specifically — only paid once per slug, right
+ * before persisting it (see ComposioGatewayToolEntry's own `resolved`
+ * doc comment), not on every load. 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
@@ -378,18 +467,41 @@ async function withRealComposioDescriptions(tools, slugs, cliCommand) {
  * 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) {
+ * 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 async function describeGatewayTools(agentName, options = {}) {
+    const dir = agentDir(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;
+            const resolved = entry.resolved ?? {};
+            const cachedTools = options.force ? [] : entry.slugs.filter((slug) => resolved[slug]).map((slug) => toolFromResolved(slug, resolved[slug], entry.cliCommand));
+            const unresolvedSlugs = options.force ? entry.slugs : entry.slugs.filter((slug) => !resolved[slug]);
+            const rawFreshTools = await fetchUnresolvedSlugs(entry, unresolvedSlugs);
+            const freshTools = entry.provider === 'composio' ? await withRealComposioDescriptions(rawFreshTools, unresolvedSlugs, entry.cliCommand) : rawFreshTools;
+            if (freshTools.length) {
+                const newlyResolved = {};
+                freshTools.forEach((tool, i) => {
+                    newlyResolved[unresolvedSlugs[i]] = { name: tool.name, description: tool.description, input_schema: tool.input_schema };
+                });
+                persistResolvedTools(dir, entry.name, newlyResolved);
+            }
+            const tools = [...cachedTools, ...freshTools];
             return { entry, status: 'ok', tools: tools.map((t) => ({ name: t.name, description: t.description })) };
         }
         catch (err) {
@@ -435,7 +547,7 @@ export async function loadGatewayToolsFromDir(dir) {
     const entries = readGatewayToolsFromDir(dir);
     const resolved = await Promise.all(entries.map(async (entry) => {
         try {
-            return await connectEntry(entry);
+            return await connectEntry(entry, dir);
         }
         catch (err) {
             console.error(`[gateway-tools] source '${entry.name}' (${entry.provider}) failed to load, skipping: ${err instanceof Error ? err.message : String(err)}`);
@@ -542,7 +654,7 @@ export async function getComposioAuthStatus(cliCommand = 'composio') {
  * 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. */
+ * instead of a form; see its own comment in web/global-config-page.ts. */
 export async function disconnectComposioAccount(cliCommand = 'composio') {
     await execFileAsync(cliCommand, ['logout']);
 }