loopengine 0.1.97 → 0.1.99

package/dist/bin/ability-manager.d.ts

@@ -1,4 +1,5 @@
 import type { EnvScope } from '../core/agent-env.js';
+import { type InstalledMcpRecord } from '../core/mcp-abilities.js';
 export declare class AbilityManifestError extends Error {
 }
 export declare class AbilityVersionError extends Error {
@@ -55,6 +56,9 @@ export interface AbilityManifest {
     version: string;
     loopengineVersion: string;
     tools?: string[];
+    /** Tools served by an MCP server instead of tool files — see
+     * core/mcp-abilities.ts's McpServerManifest. */
+    mcp?: unknown;
     skills?: string[];
     actauth?: string;
     env?: AbilityEnvDecl[];
@@ -86,6 +90,10 @@ export interface InstalledAbilityRecord {
      * has no recorded value — see oldContentSpec's own fallback. */
     spec?: string;
     tools: string[];
+    /** An MCP ability's server and tools (core/mcp-abilities.ts loads
+     * them at run time). Its tools have no files, so they aren't in
+     * `tools`. */
+    mcp?: InstalledMcpRecord;
     skills: string[];
     actauthRules: string[];
     env: AbilityEnvDecl[];
@@ -178,13 +186,24 @@ export interface FetchOptions {
  *
  * All-or-nothing: every collision check below runs, and the whole
  * install is refused, before a single file is written. */
-export declare function installAbility(agentName: string, spec: string, options?: FetchOptions): Promise<{
+/** For an ability that takes its tools from an MCP server: which of its
+ * server tools this agent gets (by the server's names), and each one's
+ * permission when it shouldn't be the ability's default. An app's ability
+ * (made from its server, listing every tool) given no choice gets just
+ * its read-only tools, those it allows by default. */
+export interface McpToolChoice {
+    mcpTools?: string[];
+    mcpDecisions?: Record<string, 'allow' | 'ask' | 'deny'>;
+}
+export declare function installAbility(agentName: string, spec: string, options?: FetchOptions & McpToolChoice): Promise<{
     installed: string[];
     dependencies: string[];
 }>;
 export interface UpgradeFileResult {
     path: string;
-    status: 'updated' | 'unchanged' | 'conflict';
+    /** added/removed: a rule the new version adds, or a tool file it no
+     * longer has (e.g. once its tools come from an MCP server). */
+    status: 'updated' | 'unchanged' | 'conflict' | 'added' | 'removed';
 }
 /** Upgrades an already-installed ability to whatever `spec` (defaulting
  * to `abilityName`, i.e. "latest") currently resolves to. Tool and skill
@@ -203,6 +222,20 @@ export declare function upgradeAbility(agentName: string, abilityName: string, o
 }): Promise<{
     files: UpgradeFileResult[];
 }>;
+/** Sets which of an MCP ability's server tools an agent has, and each
+ * one's permission for that agent. `abilityDir` is the ability's folder
+ * (an app's workspace copy), which lists every tool. A tool's permission
+ * is its first rule in the agent's actauth.yml (an agent's own rule for a
+ * tool is changed rather than shadowed); a tool with no rule gets the
+ * ability's. Rules the ability added for tools taken away go with them. */
+export declare function configureAgentMcpTools(agentName: string, abilityName: string, abilityDir: string, choice: {
+    remote: string;
+    decision: 'allow' | 'ask' | 'deny';
+}[]): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
 /** Removes an installed ability's tool and skill files, and its actauth
  * rules. A file whose content no longer matches the hash recorded at
  * install/last-upgrade is refused (reported in `refused`, left on disk)

package/dist/bin/ability-manager.js

@@ -26,6 +26,8 @@ import { parse as parseYaml } from 'yaml';
 import semver from 'semver';
 import { agentDir } from '../core/gateway-tools.js';
 import { abilityFetchAuth } from '../core/ability-sources.js';
+import { clearMcpSchemaCache, resolveMcpManifest, McpManifestError } from '../core/mcp-abilities.js';
+import { appRuleName } from '../core/mcp-ability-generator.js';
 import { addToolToIndex, removeToolFromIndex, toCamelCase } from '../web/http-tool-admin.js';
 import { addActauthRule, updateActauthRule, removeActauthRule, readActauthConfig } from '../web/actauth-admin.js';
 export class AbilityManifestError extends Error {
@@ -350,36 +352,16 @@ function parseActauthRules(abilityDir, manifest) {
     return parsed;
 }
 // ---- Install ----
-/** Installs `spec` (anything `npm pack` accepts) for `agentName`:
- * writes each manifest-listed tool file and patches tools/index.ts
- * (reusing addToolToIndex exactly as web/http-tool-admin.ts's own
- * createHttpTool does), copies each skill directory verbatim (a raw
- * cpSync, not skills-admin.ts's writeSkill — that regenerates
- * frontmatter from scratch and can't carry an ability's own
- * frontmatter/assets), and appends each actauth rule (addActauthRule).
- *
- * Deliberately does *not* attempt a live in-memory registry splice the
- * way adapters/http.ts's own handleHttpToolPost does for an
- * admin-created tool — that works there because the HTTP request
- * creating the tool runs *inside the same process* as the already-running
- * server, so updateAgent's mutation is visible to every later request in
- * that same process immediately. `add-ability` is a separate, one-off
- * CLI process with no connection to whatever server might be running
- * elsewhere — even a successful getEntry/updateAgent call here would
- * only mutate *this* CLI invocation's own throwaway registry, then
- * vanish the moment the process exits, having done nothing to the real
- * running server. (Confirmed live: this used to import
- * core/agent-registry.js, whose own discoverAgents does a top-level
- * directory scan relative to *its own compiled file's location* —
- * inside node_modules/loopengine when this runs there, not the
- * consuming project's real agents/ at all, throwing ENOENT immediately.)
- * Same reason add-agent/add-subagent above don't attempt this either —
- * a new tool becomes active the same way a new agent does: the next
- * request under `serve`, or automatically under `npx loopengine dev`'s
- * file watcher once tools/index.ts's own edit is picked up.
- *
- * All-or-nothing: every collision check below runs, and the whole
- * install is refused, before a single file is written. */
+function resolveMcp(manifest) {
+    try {
+        return resolveMcpManifest(manifest.name, manifest.mcp);
+    }
+    catch (err) {
+        if (err instanceof McpManifestError)
+            throw new AbilityManifestError(err.message);
+        throw err;
+    }
+}
 export async function installAbility(agentName, spec, options = {}) {
     const fetch = options.fetchAbilityDir ?? fetchAbilityDir;
     const abilityDir = fetch(spec);
@@ -391,7 +373,7 @@ export async function installAbility(agentName, spec, options = {}) {
     }
     const toolFiles = manifest.tools ?? [];
     const skillDirs = manifest.skills ?? [];
-    const rules = parseActauthRules(abilityDir, manifest);
+    let rules = parseActauthRules(abilityDir, manifest);
     const toolsDir = join(agentDir(agentName), 'tools');
     const skillsDirPath = join(agentDir(agentName), 'skills');
     // Collision checks — refuse the whole install before writing anything,
@@ -415,6 +397,39 @@ export async function installAbility(agentName, spec, options = {}) {
         }
         toolNames.push(installedToolName);
     }
+    const mcp = manifest.mcp === undefined ? undefined : resolveMcp(manifest);
+    if (mcp) {
+        const chosen = options.mcpTools ?? (manifest.generatedFrom ? mcp.tools.filter((t) => rules.some((r) => r.tool === t.name && r.decision === 'allow')).map((t) => t.remote) : undefined);
+        if (chosen) {
+            const unknown = chosen.filter((r) => !mcp.tools.some((t) => t.remote === r));
+            if (unknown.length)
+                throw new AbilityManifestError(`${manifest.name} has no tool named ${unknown.join(', ')}.`);
+            const dropped = new Set(mcp.tools.filter((t) => !chosen.includes(t.remote)).map((t) => t.name));
+            mcp.tools = mcp.tools.filter((t) => chosen.includes(t.remote));
+            if (!mcp.tools.length)
+                throw new AbilityManifestError(`Choose at least one of ${manifest.name}'s tools.`);
+            rules = rules.filter((r) => !dropped.has(r.tool));
+        }
+        for (const [remote, decision] of Object.entries(options.mcpDecisions ?? {})) {
+            const tool = mcp.tools.find((t) => t.remote === remote);
+            if (!tool)
+                continue;
+            const rule = rules.find((r) => r.tool === tool.name);
+            if (rule)
+                rule.decision = decision;
+            else
+                rules.push({ name: appRuleName(manifest.name, tool.name), scope: '*/*', tool: tool.name, decision });
+        }
+        // No namespacing fallback here, unlike tool files: the ability's own
+        // actauth rules name these tools, so a renamed tool would silently
+        // lose its rule.
+        const taken = new Set([...toolNames, ...Object.values(provenance).flatMap((r) => r.mcp?.tools.map((t) => t.name) ?? [])]);
+        for (const tool of mcp.tools) {
+            if (taken.has(tool.name) || existsSync(join(toolsDir, `${tool.name}.ts`))) {
+                throw new AbilityCollisionError(`Agent '${agentName}' already has a tool named '${tool.name}'.`);
+            }
+        }
+    }
     const skillIds = [];
     for (const skillDir of skillDirs) {
         const bareSkillId = basename(skillDir);
@@ -516,6 +531,7 @@ export async function installAbility(agentName, spec, options = {}) {
         version: manifest.version,
         spec,
         tools: toolNames,
+        ...(mcp ? { mcp } : {}),
         skills: skillIds,
         actauthRules: ruleNames,
         env: manifest.env ?? [],
@@ -523,8 +539,15 @@ export async function installAbility(agentName, spec, options = {}) {
         contentHashes,
     };
     writeProvenance(agentName, provenance);
+    if (mcp)
+        clearMcpSchemaCache(agentDir(agentName), manifest.name);
     return {
-        installed: [...toolNames.map((n) => `tools/${n}.ts`), ...skillIds.map((id) => `skills/${id}/`), ...ruleNames.map((n) => `actauth:${n}`)],
+        installed: [
+            ...toolNames.map((n) => `tools/${n}.ts`),
+            ...(mcp?.tools.map((t) => `mcp:${t.name}`) ?? []),
+            ...skillIds.map((id) => `skills/${id}/`),
+            ...ruleNames.map((n) => `actauth:${n}`),
+        ],
         dependencies: manifest.dependencies ?? [],
     };
 }
@@ -619,6 +642,7 @@ export async function upgradeAbility(agentName, abilityName, options = {}) {
     checkLoopengineVersion(newManifest, options.installedLoopengineRange);
     const results = [];
     const newContentHashes = { ...record.contentHashes };
+    const remainingTools = [];
     for (const toolName of record.tools) {
         const relPath = `tools/${toolName}.ts`;
         // matchesInstalledToolName, not a bare basename(f, '.ts') === toolName
@@ -627,7 +651,23 @@ export async function upgradeAbility(agentName, abilityName, options = {}) {
         // off textually the way a skill id's "/" is.
         const oldFile = (oldManifest.tools ?? []).find((f) => matchesInstalledToolName(abilityName, f, toolName));
         const newFile = (newManifest.tools ?? []).find((f) => matchesInstalledToolName(abilityName, f, toolName));
-        if (!oldFile || !newFile) {
+        // The new version no longer has this tool file (its tools may now come
+        // from an MCP server): an unedited copy goes, an edited one stays.
+        if (!newFile) {
+            const minePath = join(agentDir(agentName), relPath);
+            if (isDirty(minePath, record.contentHashes[relPath])) {
+                remainingTools.push(toolName);
+                results.push({ path: relPath, status: 'conflict' });
+                continue;
+            }
+            rmSync(minePath, { force: true });
+            removeToolFromIndex(join(agentDir(agentName), 'tools', 'index.ts'), toolName, toCamelCase(toolName));
+            delete newContentHashes[relPath];
+            results.push({ path: relPath, status: 'removed' });
+            continue;
+        }
+        remainingTools.push(toolName);
+        if (!oldFile) {
             results.push({ path: relPath, status: 'unchanged' });
             continue;
         }
@@ -699,8 +739,34 @@ export async function upgradeAbility(agentName, abilityName, options = {}) {
         updateActauthRule(agentName, ruleName, { scope: newRule.scope, tool: newRule.tool, decision: newRule.decision });
         results.push({ path, status: 'updated' });
     }
+    // Rules the new version adds (for tools it adds) are installed, unless
+    // the agent already has a rule for that tool.
+    const actauthRules = [...record.actauthRules];
+    for (const rule of newRules) {
+        if (record.actauthRules.some((name) => matchesInstalledRuleName(abilityName, rule.name, name)))
+            continue;
+        const rules = readActauthConfig(agentName).rules;
+        if (rules.some((r) => r.tool === rule.tool))
+            continue;
+        const taken = new Set(rules.map((r) => r.name));
+        const name = taken.has(rule.name) ? namespacedRuleName(abilityName, rule.name) : rule.name;
+        if (taken.has(name))
+            continue;
+        addActauthRule(agentName, { ...rule, name });
+        actauthRules.push(name);
+        results.push({ path: `actauth:${name}`, status: 'added' });
+    }
+    // An MCP ability's tools are data, not files, so there's nothing to
+    // merge: they take the new version's server and tool list as-is.
+    const { mcp: _oldMcp, ...rest } = record;
+    const newMcp = newManifest.mcp === undefined ? undefined : resolveMcp(newManifest);
+    for (const tool of newMcp?.tools ?? [])
+        results.push({ path: `mcp:${tool.name}`, status: record.mcp?.tools.some((t) => t.name === tool.name && t.remote === tool.remote) ? 'unchanged' : 'updated' });
     provenance[abilityName] = {
-        ...record,
+        ...rest,
+        ...(newMcp ? { mcp: newMcp } : {}),
+        tools: remainingTools,
+        actauthRules,
         version: newManifest.version,
         spec,
         contentHashes: newContentHashes,
@@ -708,8 +774,69 @@ export async function upgradeAbility(agentName, abilityName, options = {}) {
         dependencies: newManifest.dependencies ?? record.dependencies,
     };
     writeProvenance(agentName, provenance);
+    if (record.mcp || newMcp)
+        clearMcpSchemaCache(agentDir(agentName), abilityName);
     return { files: results };
 }
+// ---- An agent's MCP tools ----
+/** Sets which of an MCP ability's server tools an agent has, and each
+ * one's permission for that agent. `abilityDir` is the ability's folder
+ * (an app's workspace copy), which lists every tool. A tool's permission
+ * is its first rule in the agent's actauth.yml (an agent's own rule for a
+ * tool is changed rather than shadowed); a tool with no rule gets the
+ * ability's. Rules the ability added for tools taken away go with them. */
+export function configureAgentMcpTools(agentName, abilityName, abilityDir, choice) {
+    const provenance = readProvenance(agentName);
+    const record = provenance[abilityName];
+    if (!record?.mcp)
+        throw new AbilityNotInstalledError(`Ability '${abilityName}' isn't installed as an MCP ability for '${agentName}'.`);
+    const manifest = readManifest(abilityDir);
+    const all = resolveMcp(manifest);
+    const unknown = choice.filter((c) => !all.tools.some((t) => t.remote === c.remote)).map((c) => c.remote);
+    if (unknown.length)
+        throw new AbilityManifestError(`${abilityName} has no tool named ${unknown.join(', ')}.`);
+    const tools = all.tools.filter((t) => choice.some((c) => c.remote === t.remote));
+    if (!tools.length)
+        throw new AbilityManifestError(`Choose at least one of ${abilityName}'s tools, or remove it from the agent instead.`);
+    const before = new Set(record.mcp.tools.map((t) => t.name));
+    const after = new Set(tools.map((t) => t.name));
+    const added = [...after].filter((t) => !before.has(t));
+    const removed = [...before].filter((t) => !after.has(t));
+    const changed = [];
+    const ruleNames = [...record.actauthRules];
+    for (const name of record.actauthRules) {
+        const rule = readActauthConfig(agentName).rules.find((r) => r.name === name);
+        if (rule && removed.includes(rule.tool)) {
+            try {
+                removeActauthRule(agentName, name);
+            }
+            catch { }
+            ruleNames.splice(ruleNames.indexOf(name), 1);
+        }
+    }
+    for (const tool of tools) {
+        const decision = choice.find((c) => c.remote === tool.remote).decision;
+        const current = readActauthConfig(agentName).rules;
+        const rule = current.find((r) => r.tool === tool.name);
+        if (rule) {
+            if (rule.decision !== decision) {
+                updateActauthRule(agentName, rule.name, { scope: rule.scope, tool: rule.tool, decision });
+                changed.push(tool.name);
+            }
+            continue;
+        }
+        const taken = new Set(current.map((r) => r.name));
+        let name = appRuleName(abilityName, tool.name);
+        for (let i = 2; taken.has(name); i++)
+            name = `${appRuleName(abilityName, tool.name)}-${i}`;
+        addActauthRule(agentName, { name, scope: '*/*', tool: tool.name, decision });
+        ruleNames.push(name);
+    }
+    provenance[abilityName] = { ...record, mcp: { ...all, tools }, version: manifest.version, actauthRules: ruleNames };
+    writeProvenance(agentName, provenance);
+    clearMcpSchemaCache(agentDir(agentName), abilityName);
+    return { added, removed, changed };
+}
 // ---- Remove ----
 function isDirty(path, recordedHash) {
     if (!existsSync(path))
@@ -792,12 +919,18 @@ export function removeAbility(agentName, abilityName, force = false) {
             // Already gone (hand-removed since install) — not a failure.
         }
     }
+    // An MCP ability's tools have no files to be dirty, so they always go.
+    for (const tool of record.mcp?.tools ?? [])
+        removed.push(`mcp:${tool.name}`);
     if (refused.length === 0) {
         delete provenance[abilityName];
     }
     else {
-        provenance[abilityName] = { ...record, tools: remainingTools, skills: remainingSkills, actauthRules: [] };
+        const { mcp: _mcp, ...rest } = record;
+        provenance[abilityName] = { ...rest, tools: remainingTools, skills: remainingSkills, actauthRules: [] };
     }
     writeProvenance(agentName, provenance);
+    if (record.mcp)
+        clearMcpSchemaCache(agentDir(agentName), abilityName);
     return { removed, refused };
 }

package/dist/core/ability-details.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import ts from 'typescript';
 import { parse as parseYaml } from 'yaml';
+import { resolveMcpManifest } from './mcp-abilities.js';
 /** Throws when `dir` holds no loopengine.ability.json. */
 export function readAbilityDetails(dir) {
     const manifestPath = join(dir, 'loopengine.ability.json');
@@ -26,6 +27,16 @@ export function readAbilityDetails(dir) {
         const listed = found.length ? found : [{ name: basename(file).replace(/\.[cm]?[jt]s$/, ''), description: '' }];
         return listed.map((tool) => (decisions[tool.name] ? { ...tool, decision: decisions[tool.name] } : tool));
     });
+    // An MCP ability's tools are named from its allowlist; descriptions
+    // come from the server, so they're unknown until it's connected.
+    if (manifest.mcp !== undefined) {
+        try {
+            for (const tool of resolveMcpManifest(pkg.name || basename(dir), manifest.mcp).tools) {
+                tools.push(decisions[tool.name] ? { name: tool.name, description: '', decision: decisions[tool.name] } : { name: tool.name, description: '' });
+            }
+        }
+        catch { }
+    }
     const skills = strings(manifest.skills).map((skillDir) => readSkill(join(dir, skillDir), skillDir));
     return { name: pkg.name || basename(dir), version: pkg.version || '', description: pkg.description || '', tools, skills, settings: readSettings(manifest) };
 }

package/dist/core/mcp-abilities.d.ts

@@ -0,0 +1,91 @@
+import type { AgentEnv, ToolDefinition } from './agent-config.js';
+/** How the adapter authenticates to a remote server. `key` sends an
+ * agent setting as a header (`Authorization: Bearer <value>` by
+ * default). OAuth isn't supported yet. */
+export type McpAuth = {
+    type: 'none';
+} | {
+    type: 'key';
+    env: string;
+    header?: string;
+    prefix?: string;
+};
+/** The `mcp` block of loopengine.ability.json. Exactly one of `url`
+ * (a remote server) or `command` (a local server, started as a child
+ * process) is set. String values in `headers`, `args` and `env` may use
+ * `${NAME}` to read an agent setting. */
+export interface McpServerManifest {
+    url?: string;
+    /** `streamable-http` (the default) or the older `sse` transport. */
+    transport?: 'streamable-http' | 'sse';
+    headers?: Record<string, string>;
+    auth?: McpAuth;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** The server's tool names to expose — nothing else on the server is. */
+    tools: string[];
+    /** Prefix for the installed tool names (`<prefix>_<tool>`). Defaults to
+     * the ability's name without `lp-`. */
+    prefix?: string;
+    /** Longest tool result passed back to the model, in characters. */
+    maxOutputChars?: number;
+    /** Tool inputs filled from the agent's settings when a call leaves them
+     * out, e.g. a default repository: `{ "repo": "${GITHUB_REPO}" }`, or a
+     * part of one setting, `{ "owner": { "env": "GITHUB_DEFAULT_REPO",
+     * "split": "/", "part": 0 } }`. An input with a default is no longer
+     * required in the schema the model sees, which says what it defaults to. */
+    defaults?: Record<string, McpDefault>;
+}
+export type McpDefault = string | {
+    env: string;
+    split?: string;
+    part?: number;
+};
+/** What add-ability records for an MCP ability: the server block, and
+ * each installed tool name with the server tool it calls. */
+export interface InstalledMcpRecord {
+    server: Omit<McpServerManifest, 'tools' | 'prefix'>;
+    tools: Array<{
+        name: string;
+        remote: string;
+    }>;
+}
+export declare class McpManifestError extends Error {
+}
+/** Checks an ability's `mcp` block and works out its installed tool
+ * names. Throws McpManifestError on anything unusable, so a bad
+ * manifest fails at add-ability, not on the agent's first run. */
+export declare function resolveMcpManifest(abilityName: string, mcp: unknown): InstalledMcpRecord;
+/** An installed tool's name: `<prefix>_<tool>` in snake_case, or just the
+ * tool's own name when it already carries the prefix as a word
+ * (`web_search_exa` stays as is for prefix `exa`). */
+export declare function mcpToolName(prefix: string, remote: string): string;
+/** Closes every open server connection (and stops local servers). */
+export declare function closeMcpConnections(): Promise<void>;
+/** Whether a connection failed because the server wants (other)
+ * credentials: an HTTP 401/403, or the SDK's own UnauthorizedError. */
+export declare function isMcpAuthError(err: unknown): boolean;
+/** A server tool as listed, for choosing tools before an ability exists. */
+export interface McpToolInfo {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** The server's own hints (MCP tool annotations), when it gives them. */
+    readOnly?: boolean;
+    destructive?: boolean;
+}
+/** Every tool a server offers, over a one-off connection (closed after).
+ * `server` is an `mcp` block without its allowlist; settings in it are
+ * read from `env`. */
+export declare function listMcpServerTools(server: InstalledMcpRecord['server'], env: AgentEnv): Promise<McpToolInfo[]>;
+/** Drops an ability's cached schemas — add-ability and upgrade-ability
+ * call this so a new version's tools are fetched fresh. */
+export declare function clearMcpSchemaCache(dir: string, abilityName: string): void;
+export declare function mcpAbilityLoadError(dir: string, abilityName: string): string | undefined;
+/** Every tool of every MCP ability installed in `dir` (an agent's
+ * folder). An ability whose schemas aren't cached yet is connected to
+ * once to fetch them; if that fails (no key yet, server down) its tools
+ * are left out and the reason is kept for mcpAbilityLoadError, rather
+ * than failing the whole agent. */
+export declare function loadMcpAbilityTools(dir: string, agentName: string): Promise<ToolDefinition[]>;