loopengine 0.1.15 → 0.1.24

package/dist/bin/{package-manager.js → ability-manager.js}

@@ -1,8 +1,8 @@
-// Backs `loopengine add-package|upgrade-package|remove-package` (see
-// bin/cli.ts) — the install/upgrade/remove mechanics PACKAGES.md
-// specifies for a "loopengine package": a bundle of tool files, skill
+// Backs `loopengine add-ability|upgrade-ability|remove-ability` (see
+// bin/cli.ts) — the install/upgrade/remove mechanics ABILITIES.md
+// specifies for a "loopengine ability": a bundle of tool files, skill
 // directories, and actauth rules, installed by *copying* files into an
-// agent's own tree (never an npm import) so a package's code is exactly
+// agent's own tree (never an npm import) so an ability's code is exactly
 // as reviewable/hand-editable as anything the Admin UI's HTTP tool
 // builder already generates (see web/http-tool-admin.ts's own header
 // comment on `generateToolCode` for that same "real code, not an opaque
@@ -14,7 +14,7 @@
 // `threeWayMerge`'s `git merge-file --diff3` — since `loopengine` and
 // `create-loopengine` are separate published packages and a runtime
 // depending on a scaffolding tool (or vice versa) isn't a dependency
-// direction worth introducing to share ~30 lines (see PACKAGES.md's
+// direction worth introducing to share ~30 lines (see ABILITIES.md's
 // "Upgrading" section).
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
@@ -26,29 +26,29 @@ import semver from 'semver';
 import { agentDir } from '../core/gateway-tools.js';
 import { addToolToIndex, removeToolFromIndex, toCamelCase } from '../web/http-tool-admin.js';
 import { addActauthRule, updateActauthRule, removeActauthRule, readActauthConfig } from '../web/actauth-admin.js';
-export class PackageManifestError extends Error {
+export class AbilityManifestError extends Error {
 }
-export class PackageVersionError extends Error {
+export class AbilityVersionError extends Error {
 }
-export class PackageCollisionError extends Error {
+export class AbilityCollisionError extends Error {
 }
-export class PackageNotInstalledError extends Error {
+export class AbilityNotInstalledError extends Error {
 }
-export class PackageAlreadyInstalledError extends Error {
+export class AbilityAlreadyInstalledError extends Error {
 }
 // Same character sets tool names / skill ids are already validated
 // against elsewhere (web/http-tool-admin.ts's TOOL_NAME_PATTERN,
 // web/skills-admin.ts's SKILL_ID_PATTERN) — re-checked here because a
-// name derived from an untrusted package's own manifest becomes a path
+// name derived from an untrusted ability's own manifest becomes a path
 // segment (agents/<agent>/tools/<name>.ts, .../skills/<id>/): without
-// this, a package declaring a skill dir literally named ".." would have
+// this, an ability declaring a skill dir literally named ".." would have
 // `basename('..')` hand back `'..'` unchanged (path.basename does not
 // strip it), and the later `cpSync` would land one directory up, inside
 // the agent's own root instead of its skills/ folder.
 const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
 const SKILL_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 function provenancePath(agentName) {
-    return join(agentDir(agentName), '.loopengine-packages.json');
+    return join(agentDir(agentName), '.loopengine-abilities.json');
 }
 function readProvenance(agentName) {
     const path = provenancePath(agentName);
@@ -69,10 +69,10 @@ function sha256(content) {
  * accepts anything `npm pack` does: a public/private registry spec, a
  * git URL (`github:org/repo`, `git+ssh://...`), or a local `file:../path`
  * — the last of which is what this module's own tests point at, so no
- * real network call is needed there; see PACKAGES.md's "Publishing a
- * package" section). */
-export function fetchPackageDir(spec) {
-    const workDir = mkdtempSync(join(tmpdir(), 'loopengine-package-'));
+ * real network call is needed there; see ABILITIES.md's "Publishing an
+ * ability" section). */
+export function fetchAbilityDir(spec) {
+    const workDir = mkdtempSync(join(tmpdir(), 'loopengine-ability-'));
     execFileSync('npm', ['pack', spec, '--pack-destination', workDir], { stdio: 'pipe' });
     const tarball = readdirSync(workDir).find((f) => f.endsWith('.tgz'));
     if (!tarball) {
@@ -85,22 +85,33 @@ export function fetchPackageDir(spec) {
     execFileSync('tar', ['-xzf', join(workDir, tarball), '-C', workDir], { stdio: 'pipe' });
     return join(workDir, 'package');
 }
-function readManifest(packageDir) {
-    const manifestPath = join(packageDir, 'loopengine.package.json');
+function readManifest(abilityDir) {
+    const manifestPath = join(abilityDir, 'loopengine.ability.json');
     if (!existsSync(manifestPath)) {
-        throw new PackageManifestError(`${packageDir} has no loopengine.package.json — not a valid loopengine package.`);
+        throw new AbilityManifestError(`${abilityDir} has no loopengine.ability.json — not a valid loopengine ability.`);
     }
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    if (!manifest.name || !manifest.version || !manifest.loopengineVersion) {
-        throw new PackageManifestError('loopengine.package.json must have "name", "version", and "loopengineVersion".');
+    const declared = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!declared.loopengineVersion) {
+        throw new AbilityManifestError('loopengine.ability.json must have "loopengineVersion".');
     }
-    return manifest;
+    // name/version come from package.json, not loopengine.ability.json —
+    // see AbilityManifest's own doc comment for why duplicating them here
+    // would just be two numbers to keep in sync instead of one.
+    const pkgJsonPath = join(abilityDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        throw new AbilityManifestError(`${abilityDir} has no package.json — every loopengine ability needs one (name/version), even though its own metadata lives in loopengine.ability.json.`);
+    }
+    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    if (!pkgJson.name || !pkgJson.version) {
+        throw new AbilityManifestError(`${pkgJsonPath} must have "name" and "version".`);
+    }
+    return { ...declared, name: pkgJson.name, version: pkgJson.version };
 }
 // The installing project's own dependencies.loopengine is itself a
 // range (e.g. "^0.1.10"), not a concrete installed version — checking
 // the *floor* of that range against the manifest's required range is
 // the conservative choice: if even the lowest version the range could
-// resolve to wouldn't satisfy the package, refuse now rather than risk
+// resolve to wouldn't satisfy the ability, refuse now rather than risk
 // the exact silent-failure gap the Parallel-safe checkbox already hit
 // (a feature that imports an export an *actually installed* older
 // version doesn't have yet, with no error, just quietly not working).
@@ -131,7 +142,7 @@ function checkLoopengineVersion(manifest, installedRangeOverride) {
             return;
         installedRange = ownPkg.dependencies?.loopengine;
         if (!installedRange) {
-            throw new PackageVersionError(`This project's package.json has no "loopengine" dependency — can't check compatibility.`);
+            throw new AbilityVersionError(`This project's package.json has no "loopengine" dependency — can't check compatibility.`);
         }
     }
     // A non-registry dependency specifier (file:, git:, workspace:, ...) —
@@ -149,19 +160,19 @@ function checkLoopengineVersion(manifest, installedRangeOverride) {
         return;
     }
     if (!floor || !semver.satisfies(floor, manifest.loopengineVersion)) {
-        throw new PackageVersionError(`Package '${manifest.name}' needs loopengine ${manifest.loopengineVersion}, but this project depends on loopengine ${installedRange} — bump the dependency first.`);
+        throw new AbilityVersionError(`Ability '${manifest.name}' needs loopengine ${manifest.loopengineVersion}, but this project depends on loopengine ${installedRange} — bump the dependency first.`);
     }
 }
-function parseActauthRules(packageDir, manifest) {
+function parseActauthRules(abilityDir, manifest) {
     if (!manifest.actauth)
         return [];
-    const rulesPath = join(packageDir, manifest.actauth);
+    const rulesPath = join(abilityDir, manifest.actauth);
     if (!existsSync(rulesPath)) {
-        throw new PackageManifestError(`Manifest references actauth file '${manifest.actauth}', which doesn't exist in the package.`);
+        throw new AbilityManifestError(`Manifest references actauth file '${manifest.actauth}', which doesn't exist in the ability.`);
     }
     const parsed = parseYaml(readFileSync(rulesPath, 'utf8'));
     if (!Array.isArray(parsed)) {
-        throw new PackageManifestError(`'${manifest.actauth}' must be a YAML array of {name, scope, tool, decision} rules.`);
+        throw new AbilityManifestError(`'${manifest.actauth}' must be a YAML array of {name, scope, tool, decision} rules.`);
     }
     return parsed;
 }
@@ -171,7 +182,7 @@ function parseActauthRules(packageDir, manifest) {
  * (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 a package's own
+ * 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
@@ -179,7 +190,7 @@ function parseActauthRules(packageDir, manifest) {
  * 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-package` is a separate, one-off
+ * 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
@@ -196,50 +207,50 @@ function parseActauthRules(packageDir, manifest) {
  *
  * All-or-nothing: every collision check below runs, and the whole
  * install is refused, before a single file is written. */
-export async function installPackage(agentName, spec, options = {}) {
-    const fetch = options.fetchPackageDir ?? fetchPackageDir;
-    const packageDir = fetch(spec);
-    const manifest = readManifest(packageDir);
+export async function installAbility(agentName, spec, options = {}) {
+    const fetch = options.fetchAbilityDir ?? fetchAbilityDir;
+    const abilityDir = fetch(spec);
+    const manifest = readManifest(abilityDir);
     checkLoopengineVersion(manifest, options.installedLoopengineRange);
     const provenance = readProvenance(agentName);
     if (provenance[manifest.name]) {
-        throw new PackageAlreadyInstalledError(`Package '${manifest.name}' is already installed for '${agentName}' — use upgrade-package instead.`);
+        throw new AbilityAlreadyInstalledError(`Ability '${manifest.name}' is already installed for '${agentName}' — use upgrade-ability instead.`);
     }
     const toolFiles = manifest.tools ?? [];
     const skillDirs = manifest.skills ?? [];
-    const rules = parseActauthRules(packageDir, manifest);
+    const 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,
     // same "refuse rather than guess" rule HttpToolExistsError/
     // HttpToolIndexShapeError already enforce for a single admin-created
-    // tool, just applied package-wide.
+    // tool, just applied ability-wide.
     const toolNames = [];
     for (const toolFile of toolFiles) {
         const toolName = basename(toolFile, '.ts');
         if (!TOOL_NAME_PATTERN.test(toolName)) {
-            throw new PackageManifestError(`Tool file '${toolFile}' doesn't name a valid tool (must be lowercase snake_case).`);
+            throw new AbilityManifestError(`Tool file '${toolFile}' doesn't name a valid tool (must be lowercase snake_case).`);
         }
         toolNames.push(toolName);
         if (existsSync(join(toolsDir, `${toolName}.ts`))) {
-            throw new PackageCollisionError(`agents/${agentName}/tools/${toolName}.ts already exists.`);
+            throw new AbilityCollisionError(`agents/${agentName}/tools/${toolName}.ts already exists.`);
         }
     }
     const skillIds = [];
     for (const skillDir of skillDirs) {
         const skillId = basename(skillDir);
         if (!SKILL_ID_PATTERN.test(skillId)) {
-            throw new PackageManifestError(`Skill directory '${skillDir}' doesn't name a valid skill id (must be lowercase, hyphen-separated).`);
+            throw new AbilityManifestError(`Skill directory '${skillDir}' doesn't name a valid skill id (must be lowercase, hyphen-separated).`);
         }
         skillIds.push(skillId);
         if (existsSync(join(skillsDirPath, skillId))) {
-            throw new PackageCollisionError(`agents/${agentName}/skills/${skillId}/ already exists.`);
+            throw new AbilityCollisionError(`agents/${agentName}/skills/${skillId}/ already exists.`);
         }
     }
     const existingRuleNames = new Set(readActauthConfig(agentName).rules.map((r) => r.name));
     for (const rule of rules) {
         if (existingRuleNames.has(rule.name)) {
-            throw new PackageCollisionError(`An actauth rule named '${rule.name}' already exists for '${agentName}'.`);
+            throw new AbilityCollisionError(`An actauth rule named '${rule.name}' already exists for '${agentName}'.`);
         }
     }
     const contentHashes = {};
@@ -252,7 +263,7 @@ export async function installPackage(agentName, spec, options = {}) {
         const indexPath = join(toolsDir, 'index.ts');
         for (const toolFile of toolFiles) {
             const toolName = basename(toolFile, '.ts');
-            const code = readFileSync(join(packageDir, toolFile), 'utf8');
+            const code = readFileSync(join(abilityDir, toolFile), 'utf8');
             const destPath = join(toolsDir, `${toolName}.ts`);
             writeFileSync(destPath, code);
             contentHashes[`tools/${toolName}.ts`] = sha256(code);
@@ -268,7 +279,7 @@ export async function installPackage(agentName, spec, options = {}) {
     // Copy skill directories verbatim.
     for (const skillDir of skillDirs) {
         const skillId = basename(skillDir);
-        const srcPath = join(packageDir, skillDir);
+        const srcPath = join(abilityDir, skillDir);
         const destPath = join(skillsDirPath, skillId);
         mkdirSync(skillsDirPath, { recursive: true });
         cpSync(srcPath, destPath, { recursive: true });
@@ -299,7 +310,7 @@ export async function installPackage(agentName, spec, options = {}) {
 // threeWayMerge already documents. Operates on a disposable scratch
 // copy, never the real project file directly.
 function mergeFile(mine, base, theirs) {
-    const scratchDir = mkdtempSync(join(tmpdir(), 'loopengine-package-merge-'));
+    const scratchDir = mkdtempSync(join(tmpdir(), 'loopengine-ability-merge-'));
     const minePath = join(scratchDir, 'mine');
     const basePath = join(scratchDir, 'base');
     const theirsPath = join(scratchDir, 'theirs');
@@ -341,13 +352,13 @@ const PINNED_SPEC = /^(git\+|git:|https?:|file:|\.\.?\/|\/)/;
  * would still resolve there today. A git/file/URL spec is returned
  * as-is — see PINNED_SPEC's own doc comment for why appending "@version"
  * to one of those breaks instead of pinning. `recordedSpec` is only
- * absent for a package installed before InstalledPackageRecord.spec
- * existed; falling back to `packageName` there reproduces this
+ * absent for an ability installed before InstalledAbilityRecord.spec
+ * existed; falling back to `abilityName` there reproduces this
  * function's own old (buggy for a git/file install) behavior exactly —
- * no worse than before, and only for a package that hasn't upgraded
+ * no worse than before, and only for an ability that hasn't upgraded
  * since. */
-function oldContentSpec(recordedSpec, packageName, version) {
-    const base = recordedSpec ?? packageName;
+function oldContentSpec(recordedSpec, abilityName, version) {
+    const base = recordedSpec ?? abilityName;
     if (PINNED_SPEC.test(base))
         return base;
     // Strip any version/tag the spec already carries (a scoped name's own
@@ -357,27 +368,27 @@ function oldContentSpec(recordedSpec, packageName, version) {
     const bareName = base.startsWith('@') ? `@${base.slice(1).split('@')[0]}` : base.split('@')[0];
     return `${bareName}@${version}`;
 }
-/** Upgrades an already-installed package to whatever `spec` (defaulting
- * to `packageName`, i.e. "latest") currently resolves to. Tool and skill
+/** Upgrades an already-installed ability to whatever `spec` (defaulting
+ * to `abilityName`, i.e. "latest") currently resolves to. Tool and skill
  * files get a real three-way merge (mine = current file, possibly
  * hand-edited since install; base = the version recorded at
  * install/last-upgrade, refetched via oldContentSpec; theirs = newly
  * fetched) — identical technique to `create-loopengine upgrade`, just
- * applied to package-managed files instead of template files. actauth
+ * applied to ability-managed files instead of template files. actauth
  * rules upgrade per-rule instead: the target actauth.yml holds rules
- * from other packages and hand-written ones too, so there's no coherent
+ * from other abilities and hand-written ones too, so there's no coherent
  * "whole file" base/theirs to merge — a rule unchanged since install
  * updates cleanly; a hand-edited one is left alone and reported as a
  * conflict rather than overwritten. */
-export async function upgradePackage(agentName, packageName, options = {}) {
-    const fetch = options.fetchPackageDir ?? fetchPackageDir;
+export async function upgradeAbility(agentName, abilityName, options = {}) {
+    const fetch = options.fetchAbilityDir ?? fetchAbilityDir;
     const provenance = readProvenance(agentName);
-    const record = provenance[packageName];
+    const record = provenance[abilityName];
     if (!record) {
-        throw new PackageNotInstalledError(`Package '${packageName}' isn't installed for '${agentName}'.`);
+        throw new AbilityNotInstalledError(`Ability '${abilityName}' isn't installed for '${agentName}'.`);
     }
-    const spec = options.spec ?? packageName;
-    const oldDir = fetch(oldContentSpec(record.spec, packageName, record.version));
+    const spec = options.spec ?? abilityName;
+    const oldDir = fetch(oldContentSpec(record.spec, abilityName, record.version));
     const newDir = fetch(spec);
     const oldManifest = readManifest(oldDir);
     const newManifest = readManifest(newDir);
@@ -452,7 +463,7 @@ export async function upgradePackage(agentName, packageName, options = {}) {
         updateActauthRule(agentName, ruleName, { scope: newRule.scope, tool: newRule.tool, decision: newRule.decision });
         results.push({ path, status: 'updated' });
     }
-    provenance[packageName] = { ...record, version: newManifest.version, spec, contentHashes: newContentHashes, env: newManifest.env ?? record.env };
+    provenance[abilityName] = { ...record, version: newManifest.version, spec, contentHashes: newContentHashes, env: newManifest.env ?? record.env };
     writeProvenance(agentName, provenance);
     return { files: results };
 }
@@ -464,21 +475,21 @@ function isDirty(path, recordedHash) {
         return true;
     return sha256(readFileSync(path, 'utf8')) !== recordedHash;
 }
-/** Removes an installed package's tool and skill files, and its actauth
+/** 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)
- * unless `force` is passed — a concrete implementation of PACKAGES.md's
+ * unless `force` is passed — a concrete implementation of ABILITIES.md's
  * "refuses if any of them look hand-modified," cheaper than storing full
- * content or refetching the package to diff. Does not patch
+ * content or refetching the ability to diff. Does not patch
  * tools/index.ts to remove the now-dangling import — same "refuse
  * rather than guess a second time" doctrine addToolToIndex's own doc
  * comment already applies; a stale import surfaces as a clear build
  * error, not a silent break. */
-export function removePackage(agentName, packageName, force = false) {
+export function removeAbility(agentName, abilityName, force = false) {
     const provenance = readProvenance(agentName);
-    const record = provenance[packageName];
+    const record = provenance[abilityName];
     if (!record) {
-        throw new PackageNotInstalledError(`Package '${packageName}' isn't installed for '${agentName}'.`);
+        throw new AbilityNotInstalledError(`Ability '${abilityName}' isn't installed for '${agentName}'.`);
     }
     const removed = [];
     const refused = [];
@@ -494,10 +505,10 @@ export function removePackage(agentName, packageName, force = false) {
             continue;
         }
         rmSync(fullPath, { force: true });
-        // Undoes installPackage's own addToolToIndex call — without this, a
+        // Undoes installAbility's own addToolToIndex call — without this, a
         // deleted tool's import survives in tools/index.ts, and either fails
         // the next build (a dangling import to a file that no longer exists)
-        // or, worse, silently duplicates on a later add-package of the same
+        // or, worse, silently duplicates on a later add-ability of the same
         // tool (addToolToIndex used to have no idempotence check at all —
         // now it does, but this is the actual fix: the stale entry shouldn't
         // be there to begin with).
@@ -525,10 +536,10 @@ export function removePackage(agentName, packageName, force = false) {
         }
     }
     if (refused.length === 0) {
-        delete provenance[packageName];
+        delete provenance[abilityName];
     }
     else {
-        provenance[packageName] = { ...record, tools: remainingTools, skills: remainingSkills, actauthRules: [] };
+        provenance[abilityName] = { ...record, tools: remainingTools, skills: remainingSkills, actauthRules: [] };
     }
     writeProvenance(agentName, provenance);
     return { removed, refused };

package/dist/bin/cli.js

@@ -13,7 +13,7 @@ import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { installPackage, upgradePackage, removePackage } from './package-manager.js';
+import { installAbility, upgradeAbility, removeAbility } from './ability-manager.js';
 const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 export class AgentNameError extends Error {
 }
@@ -231,7 +231,7 @@ async function requireAdapterFile(relPath) {
     process.exitCode = 1;
     return false;
 }
-// Shared by add-package/upgrade-package/remove-package below — pulls a
+// Shared by add-ability/upgrade-ability/remove-ability below — pulls a
 // `--flag value` pair out of argv, same inline style `run`'s own
 // `--input` handling already uses, factored out only because three
 // commands need the identical `--agent <name>` extraction (a single use
@@ -301,22 +301,22 @@ async function main() {
         console.log(`Run the top-level agent: npx tsx adapters/cli.ts --agent ${parent.split('/')[0]} "hello"`);
         return;
     }
-    // Installs a loopengine package (see PACKAGES.md) — a bundle of tool
+    // Installs a loopengine ability (see ABILITIES.md) — a bundle of tool
     // files, skill directories, and actauth rules published as an ordinary
     // npm package (public, private-registry, git, or a local file: path),
     // copied into the target agent's own tree rather than added as a
-    // node_modules import (see package-manager.ts's own header comment for
+    // node_modules import (see ability-manager.ts's own header comment for
     // why). <spec> is whatever `npm pack` itself accepts.
-    if (command === 'add-package') {
+    if (command === 'add-ability') {
         const { value: agent, rest: withoutAgent } = extractFlagValue(rest, '--agent');
         const [spec] = withoutAgent;
         if (!spec || !agent) {
-            console.error('Usage: loopengine add-package <spec> --agent <name>');
+            console.error('Usage: loopengine add-ability <spec> --agent <name>');
             process.exitCode = 1;
             return;
         }
         try {
-            const { installed } = await installPackage(agent, spec);
+            const { installed } = await installAbility(agent, spec);
             console.log(`Installed into agents/${agent}/:`);
             for (const p of installed)
                 console.log(`  ${p}`);
@@ -330,23 +330,23 @@ async function main() {
         }
         return;
     }
-    // Pulls in whatever <packageName> (or --spec, if the package moved)
+    // Pulls in whatever <abilityName> (or --spec, if the ability moved)
     // currently resolves to, three-way-merging each tool/skill file it
     // manages against what changed upstream since install — a hand-edit
     // survives a clean merge; a real conflict leaves <<<<<<< markers to
     // resolve by hand, same as create-loopengine upgrade already does for
     // template files.
-    if (command === 'upgrade-package') {
+    if (command === 'upgrade-ability') {
         const { value: agent, rest: withoutAgent } = extractFlagValue(rest, '--agent');
         const { value: spec, rest: withoutSpec } = extractFlagValue(withoutAgent, '--spec');
-        const [packageName] = withoutSpec;
-        if (!packageName || !agent) {
-            console.error('Usage: loopengine upgrade-package <packageName> --agent <name> [--spec <spec>]');
+        const [abilityName] = withoutSpec;
+        if (!abilityName || !agent) {
+            console.error('Usage: loopengine upgrade-ability <abilityName> --agent <name> [--spec <spec>]');
             process.exitCode = 1;
             return;
         }
         try {
-            const { files } = await upgradePackage(agent, packageName, spec ? { spec } : {});
+            const { files } = await upgradeAbility(agent, abilityName, spec ? { spec } : {});
             for (const f of files)
                 console.log(`  ${f.status.padEnd(9)}${f.path}`);
             const conflicts = files.filter((f) => f.status === 'conflict');
@@ -358,20 +358,20 @@ async function main() {
         }
         return;
     }
-    // Removes a package's tool/skill files and actauth rules — refuses a
+    // Removes an ability's tool/skill files and actauth rules — refuses a
     // file whose content no longer matches what was recorded at
     // install/last-upgrade (a hand-edit since) unless --force is given.
-    if (command === 'remove-package') {
+    if (command === 'remove-ability') {
         const { value: agent, rest: withoutAgent } = extractFlagValue(rest, '--agent');
         const { present: force, rest: withoutForce } = extractFlagPresence(withoutAgent, '--force');
-        const [packageName] = withoutForce;
-        if (!packageName || !agent) {
-            console.error('Usage: loopengine remove-package <packageName> --agent <name> [--force]');
+        const [abilityName] = withoutForce;
+        if (!abilityName || !agent) {
+            console.error('Usage: loopengine remove-ability <abilityName> --agent <name> [--force]');
             process.exitCode = 1;
             return;
         }
         try {
-            const { removed, refused } = removePackage(agent, packageName, force);
+            const { removed, refused } = removeAbility(agent, abilityName, force);
             for (const p of removed)
                 console.log(`  removed  ${p}`);
             for (const p of refused)
@@ -463,9 +463,9 @@ async function main() {
     }
     console.error('Usage: loopengine add-agent <name>');
     console.error('       loopengine add-subagent <parent> <name>');
-    console.error('       loopengine add-package <spec> --agent <name>');
-    console.error('       loopengine upgrade-package <packageName> --agent <name> [--spec <spec>]');
-    console.error('       loopengine remove-package <packageName> --agent <name> [--force]');
+    console.error('       loopengine add-ability <spec> --agent <name>');
+    console.error('       loopengine upgrade-ability <abilityName> --agent <name> [--spec <spec>]');
+    console.error('       loopengine remove-ability <abilityName> --agent <name> [--force]');
     console.error('       loopengine run <agent> [--session <id>] "<message>"');
     console.error('       loopengine serve');
     console.error('       loopengine dev');

package/dist/core/agent-config.d.ts

@@ -1,6 +1,6 @@
 import type { Rule, Decision, Scope } from 'actauth';
 import type { Redis } from 'ioredis';
-import type { SafetyClassifier } from 'toollane';
+import type { SafetyClassifier } from './toollane.js';
 import type { Summarizer } from './compaction.js';
 /** Which channel a runAgent() call is on — the value RunAgentOptions.channel
  * carries, checked against directly by AgentConfig.httpNotifier's own

package/dist/core/gateway-tools.js

@@ -1,7 +1,7 @@
 // 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
+// Nango, Arcade, Scalekit are meant to slot in later as thin
+// mcpplug.ts 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
@@ -12,7 +12,7 @@ import { join } from 'node:path';
 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';
+import { connectComposioSource } from './mcpplug.js';
 const execFileAsync = promisify(execFile);
 // gateway-tools.yml is plain data (see this file's own header comment),
 // not compiled code — same "resolved against process.cwd(), like

package/dist/core/mcpplug.d.ts

@@ -0,0 +1,23 @@
+import type { ToolDefinition } from './agent-config.js';
+/** One connection to one external tool gateway (Composio today; a raw MCP
+ * client is a later, separate source). `name` is used to namespace every
+ * tool it produces, so two sources never collide. */
+export interface ToolSource {
+    name: string;
+    loadTools(): Promise<ToolDefinition[]>;
+    close(): Promise<void>;
+}
+export interface ComposioSourceOptions {
+    /** Composio tool slugs to expose, e.g.
+     * "GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER". Explicit, not
+     * auto-discovered — same reasoning actauth rules are opt-in per tool
+     * rather than a blanket allow; an agent should only see the Composio
+     * actions its config actually lists. */
+    slugs: string[];
+    /** Defaults to 'composio' — override to point at a stand-in binary in tests. */
+    cliCommand?: string;
+}
+/** Sources ToolDefinitions from the Composio CLI — already-authenticated
+ * (`composio link <toolkit>`) tool execution across 1000+ apps, so this
+ * source needs no OAuth code of its own; Composio owns that entirely. */
+export declare function connectComposioSource(name: string, options: ComposioSourceOptions): Promise<ToolSource>;

package/dist/core/mcpplug.js

@@ -0,0 +1,64 @@
+// Formerly the standalone `mcpplug` package — folded in here since it
+// had exactly one real consumer (gateway-tools.ts, below) and the
+// "usable by any agent runtime" framing it shipped with was aspirational,
+// never actually exercised by a second host. Reuses this repo's own
+// ToolDefinition (agent-config.ts) directly instead of mcpplug's own
+// parallel-but-identical copy — that duplication only existed to keep
+// mcpplug import-free of loopengine, which stopped mattering once it
+// moved in.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+function humanize(slug) {
+    return slug.toLowerCase().split('_').join(' ');
+}
+async function runCli(cliCommand, args) {
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await run(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}`);
+    }
+}
+/** Sources ToolDefinitions from the Composio CLI — already-authenticated
+ * (`composio link <toolkit>`) tool execution across 1000+ apps, so this
+ * source needs no OAuth code of its own; Composio owns that entirely. */
+export async function connectComposioSource(name, options) {
+    const cliCommand = options.cliCommand ?? 'composio';
+    return {
+        name,
+        async loadTools() {
+            const tools = [];
+            for (const slug of options.slugs) {
+                const schema = await runCli(cliCommand, ['execute', slug, '--get-schema']);
+                const inputSchema = schema.inputSchema ?? {};
+                tools.push({
+                    name: `${name}_${slug}`,
+                    description: humanize(slug),
+                    input_schema: inputSchema,
+                    execute: async (input) => {
+                        const result = await runCli(cliCommand, ['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;
+                    },
+                });
+            }
+            return tools;
+        },
+        // Each call is its own subprocess — nothing held open between calls,
+        // so there's nothing to tear down. Kept for symmetry with sources
+        // that do hold a live connection (e.g. a future raw MCP client).
+        close: async () => { },
+    };
+}

package/dist/core/run-agent.js

@@ -8,10 +8,10 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { Gate, RuleSet, ConsoleApprover } from 'actauth';
-import { SkillGarden } from 'skillgarden';
+import { SkillGarden } from './skillgarden/index.js';
 import { BudgetTracker } from './budget.js';
 import { Compactor } from './compaction.js';
-import { ToolLane } from 'toollane';
+import { ToolLane } from './toollane.js';
 import { Recovery } from './recovery.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';

package/dist/core/session-store.d.ts

@@ -1,5 +1,5 @@
 import { Redis } from 'ioredis';
-import { type Storage } from 'sessionknit';
+import { type Storage } from './sessionknit.js';
 import type { Message } from '#core/run-agent.js';
 export interface SessionResult<T> {
     /** Exactly what this turn added — durably appended as-is, in order.