loopengine 0.1.22 → 0.1.27

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,11 +14,11 @@
 // `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';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
@@ -26,29 +26,99 @@ 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]+)*$/;
+/** Two abilities can each declare a skill with the same bare id (both
+ * ship a "web-search" skill, say) — refusing the second install outright
+ * would make them mutually exclusive for no real reason, since skills
+ * don't have to be globally unique the way a model-callable tool name
+ * does. Namespacing under the ability's own name only when the bare id
+ * is already taken — never unconditionally — keeps the common,
+ * no-conflict case's directory layout exactly as it's always been.
+ * Reuses SkillGarden's own nested-directory namespacing (discovery.ts:
+ * `deploy/web/SKILL.md` -> addressable as `deploy:web`) for free, so a
+ * namespaced skill just becomes addressable as `<abilityName>:<skillId>`
+ * with no changes needed on the loading side at all. */
+function namespacedSkillId(abilityName, skillId) {
+    // abilityName came off the ability's own package.json "name" — for a
+    // scoped npm name ("@company/pkg") this is two path segments, which is
+    // fine (SkillGarden namespaces however deep the nesting goes), but each
+    // segment still has to be a safe path component on its own: same
+    // '..'-as-a-path-segment guard TOOL_NAME_PATTERN/SKILL_ID_PATTERN's own
+    // comment above already explains the need for, just for a manifest's
+    // "name" field instead of a tool/skill declaration.
+    for (const segment of abilityName.split('/')) {
+        if (segment === '' || segment === '.' || segment === '..') {
+            throw new AbilityManifestError(`Ability name '${abilityName}' isn't safe to use as a skill namespace.`);
+        }
+    }
+    return `${abilityName}/${skillId}`;
+}
+// A tool name (unlike a skill id) is a flat identifier, not a path — it
+// has to satisfy TOOL_NAME_PATTERN on its own (it becomes both a file
+// basename and a JS identifier via toCamelCase), so an ability's raw
+// package.json "name" can't be used directly the way it can as a path
+// segment for a skill (hyphens, "@scope/", dots aren't valid there).
+// Collapsing every run of non-alphanumeric characters to a single "_"
+// and guaranteeing a leading letter (TOOL_NAME_PATTERN requires one)
+// always produces a safe result — never throws, unlike
+// namespacedSkillId, since there's no filesystem path to escape here.
+function sanitizeForToolName(name) {
+    const cleaned = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return cleaned.length > 0 && /^[a-z]/.test(cleaned) ? cleaned : `a_${cleaned}`;
+}
+/** Two abilities can each declare a tool with the same bare name too —
+ * but unlike a skill id, a tool's name is the literal, model-callable
+ * function name: run-agent.ts's own dedupeToolsByName keeps only the
+ * *last* same-named entry and silently drops the rest before the model
+ * ever sees them (its own doc comment: "a name collision would still
+ * show up twice in toolSchemas, confusing (or rejected outright by) a
+ * real model API"), so two same-named tools can never actually coexist
+ * as distinct, callable tools the way two same-named skills can — only
+ * namespacing the *name itself* avoids that silent drop. */
+function namespacedToolName(abilityName, toolName) {
+    return `${sanitizeForToolName(abilityName)}__${toolName}`;
+}
+/** Whether `manifestToolFile` (a bare path straight off a manifest, e.g.
+ * "tools/web_search.ts") is the file an installed `installedToolName`
+ * (bare, or namespaced under `abilityName` on a collision — see
+ * namespacedToolName) actually came from. Used by upgradeAbility to
+ * match a provenance-recorded, possibly-namespaced name back to the
+ * right manifest entry — comparing the *installed* name against a
+ * freshly-recomputed candidate, rather than trying to strip a namespace
+ * prefix back off `installedToolName` textually, since "<ability>__"
+ * isn't a structural separator the way a skill id's "/" is: a bare tool
+ * name could legitimately contain "__" on its own, so string-stripping
+ * it back off would be ambiguous in a way recomputing forward and
+ * comparing never is. */
+function matchesInstalledToolName(abilityName, manifestToolFile, installedToolName) {
+    const bareToolName = basename(manifestToolFile, '.ts');
+    return bareToolName === installedToolName || namespacedToolName(abilityName, bareToolName) === installedToolName;
+}
 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 +139,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 +155,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 declared = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!declared.loopengineVersion) {
+        throw new AbilityManifestError('loopengine.ability.json must have "loopengineVersion".');
     }
-    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".');
+    // 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.`);
     }
-    return manifest;
+    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 +212,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 +230,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 +252,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 +260,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 +277,61 @@ 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).`);
+        const bareToolName = basename(toolFile, '.ts');
+        if (!TOOL_NAME_PATTERN.test(bareToolName)) {
+            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.`);
+        // The bare name if it's free; otherwise namespace under this
+        // ability's own name rather than refusing the install outright —
+        // see namespacedToolName's own doc comment for why this still
+        // leaves both tools genuinely callable, unlike a same-named actauth
+        // rule (below), which has no such option.
+        const installedToolName = existsSync(join(toolsDir, `${bareToolName}.ts`)) ? namespacedToolName(manifest.name, bareToolName) : bareToolName;
+        if (existsSync(join(toolsDir, `${installedToolName}.ts`))) {
+            throw new AbilityCollisionError(`agents/${agentName}/tools/${installedToolName}.ts already exists.`);
         }
+        toolNames.push(installedToolName);
     }
     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).`);
+        const bareSkillId = basename(skillDir);
+        if (!SKILL_ID_PATTERN.test(bareSkillId)) {
+            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.`);
+        // The bare id if it's free; otherwise namespace under this ability's
+        // own name rather than refusing the install outright — see
+        // namespacedSkillId's own doc comment for why this is safe to do
+        // (skills, unlike tools, don't need a single global namespace).
+        const installedSkillId = existsSync(join(skillsDirPath, bareSkillId)) ? namespacedSkillId(manifest.name, bareSkillId) : bareSkillId;
+        if (existsSync(join(skillsDirPath, installedSkillId))) {
+            throw new AbilityCollisionError(`agents/${agentName}/skills/${installedSkillId}/ already exists.`);
         }
+        skillIds.push(installedSkillId);
     }
     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 = {};
@@ -250,27 +342,51 @@ export async function installPackage(agentName, spec, options = {}) {
     if (toolNames.length > 0) {
         mkdirSync(toolsDir, { recursive: true });
         const indexPath = join(toolsDir, 'index.ts');
-        for (const toolFile of toolFiles) {
-            const toolName = basename(toolFile, '.ts');
-            const code = readFileSync(join(packageDir, toolFile), 'utf8');
-            const destPath = join(toolsDir, `${toolName}.ts`);
+        for (const [i, toolFile] of toolFiles.entries()) {
+            const bareToolName = basename(toolFile, '.ts');
+            const installedToolName = toolNames[i];
+            const code = readFileSync(join(abilityDir, toolFile), 'utf8');
+            const destPath = join(toolsDir, `${installedToolName}.ts`);
             writeFileSync(destPath, code);
-            contentHashes[`tools/${toolName}.ts`] = sha256(code);
-            const exportName = toCamelCase(toolName);
+            contentHashes[`tools/${installedToolName}.ts`] = sha256(code);
+            // Plain case: the file's own export is imported and used as-is,
+            // exactly as before. Namespaced case: the file's own internal
+            // export name is untouched (still whatever the ability itself
+            // authored — importing it under that same bare name from two
+            // different abilities' files would be a duplicate top-level
+            // identifier), so the import gets aliased, and a small wrapper
+            // `const` overrides the actual model-facing `name` field, which
+            // the JS identifier alone has no effect on. See addToolToIndex's
+            // own doc comment for why `importSpecifier`/`arrayExpression` are
+            // separate parameters.
+            const sourceExportName = toCamelCase(bareToolName);
+            const namespaced = installedToolName !== bareToolName;
+            const arrayExpression = namespaced ? toCamelCase(installedToolName) : sourceExportName;
+            const importSpecifier = namespaced ? `${sourceExportName} as ${arrayExpression}Source` : sourceExportName;
+            const preamble = namespaced ? `const ${arrayExpression}: ToolDefinition = { ...${arrayExpression}Source, name: '${installedToolName}' }` : undefined;
             if (existsSync(indexPath)) {
-                addToolToIndex(indexPath, toolName, exportName);
+                addToolToIndex(indexPath, installedToolName, importSpecifier, arrayExpression, preamble);
             }
             else {
-                writeFileSync(indexPath, `import type { ToolDefinition } from 'loopengine'\nimport { ${exportName} } from './${toolName}.js'\n\nexport const tools: ToolDefinition[] = [${exportName}]\n`);
+                const preambleBlock = preamble ? `${preamble}\n\n` : '';
+                writeFileSync(indexPath, `import type { ToolDefinition } from 'loopengine'\nimport { ${importSpecifier} } from './${installedToolName}.js'\n\n${preambleBlock}export const tools: ToolDefinition[] = [${arrayExpression}]\n`);
             }
         }
     }
-    // Copy skill directories verbatim.
-    for (const skillDir of skillDirs) {
-        const skillId = basename(skillDir);
-        const srcPath = join(packageDir, skillDir);
+    // Copy skill directories verbatim — skillIds[i] is skillDirs[i]'s
+    // already-resolved installed id (bare, or namespaced under this
+    // ability's own name if the bare id collided — computed once, above,
+    // not recomputed here, so this loop can't disagree with the collision
+    // check that already ran against it).
+    for (const [i, skillDir] of skillDirs.entries()) {
+        const skillId = skillIds[i];
+        const srcPath = join(abilityDir, skillDir);
         const destPath = join(skillsDirPath, skillId);
-        mkdirSync(skillsDirPath, { recursive: true });
+        // dirname(destPath), not skillsDirPath — a namespaced skillId
+        // ("<abilityName>/<skillId>") needs its own intermediate directory
+        // created first; cpSync creates destPath itself but not necessarily
+        // parents beyond that.
+        mkdirSync(dirname(destPath), { recursive: true });
         cpSync(srcPath, destPath, { recursive: true });
         const skillMdPath = join(destPath, 'SKILL.md');
         if (existsSync(skillMdPath)) {
@@ -299,7 +415,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 +457,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 +473,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);
@@ -386,8 +502,12 @@ export async function upgradePackage(agentName, packageName, options = {}) {
     const newContentHashes = { ...record.contentHashes };
     for (const toolName of record.tools) {
         const relPath = `tools/${toolName}.ts`;
-        const oldFile = (oldManifest.tools ?? []).find((f) => basename(f, '.ts') === toolName);
-        const newFile = (newManifest.tools ?? []).find((f) => basename(f, '.ts') === toolName);
+        // matchesInstalledToolName, not a bare basename(f, '.ts') === toolName
+        // comparison — toolName may be namespaced (see namespacedToolName),
+        // and "<ability>__" isn't a structural separator safe to strip back
+        // 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) {
             results.push({ path: relPath, status: 'unchanged' });
             continue;
@@ -407,8 +527,13 @@ export async function upgradePackage(agentName, packageName, options = {}) {
     }
     for (const skillId of record.skills) {
         const relPath = `skills/${skillId}/SKILL.md`;
-        const oldSkillDir = (oldManifest.skills ?? []).find((s) => basename(s) === skillId);
-        const newSkillDir = (newManifest.skills ?? []).find((s) => basename(s) === skillId);
+        // basename(skillId), not skillId itself — a namespaced install
+        // ("<abilityName>/<skillId>") still has to match against the
+        // manifest's own bare skill dir names, which never carry the
+        // namespace (that's only ever added at install time, on collision).
+        const bareSkillId = basename(skillId);
+        const oldSkillDir = (oldManifest.skills ?? []).find((s) => basename(s) === bareSkillId);
+        const newSkillDir = (newManifest.skills ?? []).find((s) => basename(s) === bareSkillId);
         const oldFile = oldSkillDir ? join(oldDir, oldSkillDir, 'SKILL.md') : null;
         const newFile = newSkillDir ? join(newDir, newSkillDir, 'SKILL.md') : null;
         if (!oldFile || !newFile || !existsSync(oldFile) || !existsSync(newFile)) {
@@ -452,7 +577,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 +589,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 +619,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 +650,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 };