loopengine 0.1.24 → 0.1.28

package/dist/bin/ability-manager.js

@@ -18,8 +18,8 @@
 // "Upgrading" section).
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { basename, join } from 'node:path';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
 import semver from 'semver';
@@ -47,6 +47,76 @@ export class AbilityAlreadyInstalledError extends Error {
 // 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-abilities.json');
 }
@@ -227,25 +297,36 @@ export async function installAbility(agentName, spec, options = {}) {
     // tool, just applied ability-wide.
     const toolNames = [];
     for (const toolFile of toolFiles) {
-        const toolName = basename(toolFile, '.ts');
-        if (!TOOL_NAME_PATTERN.test(toolName)) {
+        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 AbilityCollisionError(`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)) {
+        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 AbilityCollisionError(`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) {
@@ -261,27 +342,51 @@ export async function installAbility(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');
+        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, `${toolName}.ts`);
+            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);
+    // 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)) {
@@ -397,8 +502,12 @@ export async function upgradeAbility(agentName, abilityName, 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;
@@ -418,8 +527,13 @@ export async function upgradeAbility(agentName, abilityName, 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)) {
@@ -525,6 +639,20 @@ export function removeAbility(agentName, abilityName, force = false) {
         }
         rmSync(join(agentDir(agentName), 'skills', skillId), { recursive: true, force: true });
         removed.push(`skills/${skillId}/`);
+        // A namespaced skillId ("<ability-name>/<id>", see namespacedSkillId)
+        // leaves its own now-empty "<ability-name>/" namespace directory
+        // behind — best-effort cleanup, not "refuse rather than guess": rmdir
+        // itself already refuses (ENOTEMPTY) if another skill from this same
+        // ability is still namespaced under it, which is exactly the case
+        // this should leave alone.
+        if (skillId.includes('/')) {
+            try {
+                rmdirSync(join(agentDir(agentName), 'skills', dirname(skillId)));
+            }
+            catch {
+                // Not empty, or already gone — either way, nothing to do.
+            }
+        }
     }
     for (const ruleName of record.actauthRules) {
         try {

package/dist/web/agents-config-page.js

@@ -1123,10 +1123,19 @@ export const agentsConfigPageHtml = `<!doctype html>
   }
 
   function renderEnvRow(v) {
+    // More than one ability declaring the same name doesn't get resolved
+    // here — there's one .env per project, so both read whatever single
+    // value ends up set, whether that's actually correct or a coincidence
+    // (see env-admin.ts's own doc comment). Listing every ability instead
+    // of just the first one seen at least makes that visible to whoever's
+    // looking, instead of silently hiding all but one.
+    var sharedNote = v.abilityNames.length > 1
+      ? ' <span class="hint" title="More than one installed ability declares this name — there is only one value for it project-wide, so check whether they actually need the same one.">(shared)</span>'
+      : '';
     return '<tr>' +
       '<td><code>' + escapeHtml(v.name) + '</code></td>' +
       '<td>' + escapeHtml(v.description || '') + '</td>' +
-      '<td class="hint">' + escapeHtml(v.abilityName) + '</td>' +
+      '<td class="hint">' + escapeHtml(v.abilityNames.join(', ')) + sharedNote + '</td>' +
       '<td>' + (v.set ? '<span class="hint">set</span>' : '<span class="error">not set</span>') + '</td>' +
       '<td><form class="add-source env-var-form" data-name="' + escapeHtml(v.name) + '">' +
         '<input type="' + (v.secret ? 'password' : 'text') + '" name="value" placeholder="' + (v.set ? 'unchanged unless you type a new value' : 'value') + '" required>' +
@@ -1138,7 +1147,7 @@ export const agentsConfigPageHtml = `<!doctype html>
   function renderEnvConfigHtml(vars) {
     if (!vars.length) return '<p class="hint">No installed ability has declared any environment variables for this agent yet.</p>';
     var rows = vars.map(renderEnvRow).join('');
-    return '<table><thead><tr><th>Name</th><th>Description</th><th>Ability</th><th>Status</th><th>Set value</th></tr></thead><tbody>' + rows + '</tbody></table>';
+    return '<table><thead><tr><th>Name</th><th>Description</th><th>Required by</th><th>Status</th><th>Set value</th></tr></thead><tbody>' + rows + '</tbody></table>';
   }
 
   function envContentEl() {

package/dist/web/env-admin.d.ts

@@ -4,17 +4,36 @@ export interface DeclaredEnvVar {
     name: string;
     description?: string;
     secret: boolean;
-    abilityName: string;
+    /** Every ability that declares this name, in install order — usually
+     * one, but see listDeclaredEnvVars's own doc comment for why this is
+     * an array, not a single name. */
+    abilityNames: string[];
     set: boolean;
 }
 /** Every env var any ability installed for `agentName` declared it
- * needs, deduplicated by name — ABILITIES.md's own open question on
- * cross-ability name collisions applies here too (one .env per
- * *project*, not per agent, so two unrelated abilities declaring the
- * same name can't actually be told apart; the first one seen wins the
- * description shown). `set` is read live off `process.env`, not cached,
- * so it reflects whatever the last `setEnvVar` call — or a plain
- * restart picking up `.env` — actually did. */
+ * needs, merged by name. There's one .env per *project*, not per agent
+ * or per ability, so this can't actually resolve a genuine cross-ability
+ * name collision (two abilities declaring, say, "API_KEY" for two
+ * unrelated services still both read whichever single value ends up
+ * set — there is no per-ability slot to give them) — unlike a tool or
+ * skill name collision (see ability-manager.ts's namespacedToolName/
+ * namespacedSkillId), an env var name is a literal `process.env.X`
+ * reference baked into the ability's own code, not a label loopengine's
+ * own generated glue controls, so there's nothing here to safely rename.
+ * What this *can* do, and used to not: surface every ability that
+ * declares a given name (`abilityNames`, plural) instead of silently
+ * keeping only the first one seen and hiding the rest — turns a
+ * collision from invisible into something a human looking at the
+ * Environment tab can actually notice and judge (a real conflict
+ * needing one ability's own env var renamed, or a coincidence that's
+ * actually fine because both intentionally share one real credential).
+ * `secret` is true if *any* declaring ability marked it secret — the
+ * safer default, since treating a real secret as non-secret because a
+ * different ability's own declaration happened to be checked first
+ * would be the one direction genuinely worth avoiding. `set` is read
+ * live off `process.env`, not cached, so it reflects whatever the last
+ * `setEnvVar` call — or a plain restart picking up `.env` — actually
+ * did. */
 export declare function listDeclaredEnvVars(agentName: string): DeclaredEnvVar[];
 /** Upserts `NAME=VALUE` into the project's `.env` file — preserving
  * every other line (comments, blank lines, unrelated keys) — and

package/dist/web/env-admin.js

@@ -16,35 +16,53 @@ function provenancePath(agentName) {
     return join(agentDir(agentName), '.loopengine-abilities.json');
 }
 /** Every env var any ability installed for `agentName` declared it
- * needs, deduplicated by name — ABILITIES.md's own open question on
- * cross-ability name collisions applies here too (one .env per
- * *project*, not per agent, so two unrelated abilities declaring the
- * same name can't actually be told apart; the first one seen wins the
- * description shown). `set` is read live off `process.env`, not cached,
- * so it reflects whatever the last `setEnvVar` call — or a plain
- * restart picking up `.env` — actually did. */
+ * needs, merged by name. There's one .env per *project*, not per agent
+ * or per ability, so this can't actually resolve a genuine cross-ability
+ * name collision (two abilities declaring, say, "API_KEY" for two
+ * unrelated services still both read whichever single value ends up
+ * set — there is no per-ability slot to give them) — unlike a tool or
+ * skill name collision (see ability-manager.ts's namespacedToolName/
+ * namespacedSkillId), an env var name is a literal `process.env.X`
+ * reference baked into the ability's own code, not a label loopengine's
+ * own generated glue controls, so there's nothing here to safely rename.
+ * What this *can* do, and used to not: surface every ability that
+ * declares a given name (`abilityNames`, plural) instead of silently
+ * keeping only the first one seen and hiding the rest — turns a
+ * collision from invisible into something a human looking at the
+ * Environment tab can actually notice and judge (a real conflict
+ * needing one ability's own env var renamed, or a coincidence that's
+ * actually fine because both intentionally share one real credential).
+ * `secret` is true if *any* declaring ability marked it secret — the
+ * safer default, since treating a real secret as non-secret because a
+ * different ability's own declaration happened to be checked first
+ * would be the one direction genuinely worth avoiding. `set` is read
+ * live off `process.env`, not cached, so it reflects whatever the last
+ * `setEnvVar` call — or a plain restart picking up `.env` — actually
+ * did. */
 export function listDeclaredEnvVars(agentName) {
     const path = provenancePath(agentName);
     if (!existsSync(path))
         return [];
     const provenance = JSON.parse(readFileSync(path, 'utf8'));
-    const seen = new Set();
-    const result = [];
+    const byName = new Map();
     for (const [abilityName, record] of Object.entries(provenance)) {
         for (const decl of record.env) {
-            if (seen.has(decl.name))
+            const existing = byName.get(decl.name);
+            if (existing) {
+                existing.abilityNames.push(abilityName);
+                existing.secret = existing.secret || decl.secret === true;
                 continue;
-            seen.add(decl.name);
-            result.push({
+            }
+            byName.set(decl.name, {
                 name: decl.name,
                 description: decl.description,
                 secret: decl.secret === true,
-                abilityName,
+                abilityNames: [abilityName],
                 set: process.env[decl.name] !== undefined,
             });
         }
     }
-    return result;
+    return [...byName.values()];
 }
 // process.cwd(), matching exactly where bin/cli.ts's own runTsx passes
 // --env-file-if-exists=.env (Node's own --env-file resolves relative to

package/dist/web/http-tool-admin.d.ts

@@ -37,18 +37,29 @@ export interface HttpToolSpec {
     safe?: boolean;
 }
 export declare function toCamelCase(snakeCase: string): string;
-export declare function addToolToIndex(toolsIndexPath: string, toolFileName: string, exportName: string): void;
-/** addToolToIndex's own undo — removes the named tool's import line and
- * array entry. Best-effort, not "refuse rather than guess" like
- * addToolToIndex: this only ever runs against a tool ability-manager.ts
- * itself installed (so the exact shape addToolToIndex wrote is known),
- * and the caller (removeAbility) has already deleted the tool's .ts
- * file — leaving a stale entry behind, the previous behavior, means a
- * dangling import that fails the next build, which is strictly worse
- * than a no-op here if the file turns out not to match (hand-edited
- * since). No-ops (rather than throwing) when the file is missing
- * entirely, or the expected import/array-entry shape isn't found. */
-export declare function removeToolFromIndex(toolsIndexPath: string, toolFileName: string, exportName: string): void;
+export declare function addToolToIndex(toolsIndexPath: string, toolFileName: string, importSpecifier: string, arrayExpression?: string, preamble?: string): void;
+/** addToolToIndex's own undo — removes the named tool's import line,
+ * wrapper `const` (if a namespaced install added one), and array entry.
+ * Best-effort, not "refuse rather than guess" like addToolToIndex: this
+ * only ever runs against a tool ability-manager.ts itself installed (so
+ * the exact shape addToolToIndex wrote is known), and the caller
+ * (removeAbility) has already deleted the tool's .ts file — leaving a
+ * stale entry behind, the previous behavior, means a dangling import
+ * that fails the next build, which is strictly worse than a no-op here
+ * if the file turns out not to match (hand-edited since). No-ops (rather
+ * than throwing) when the file is missing entirely, or the expected
+ * import/array-entry shape isn't found.
+ *
+ * `arrayExpression` (not the raw import specifier) — same value
+ * addToolToIndex's own `arrayExpression` was called with, since that's
+ * what actually appears in the array literal and (for a namespaced
+ * install) names the wrapper `const` too. The import line is matched by
+ * `toolFileName` alone, not by the exact imported binding: a namespaced
+ * install aliases its import (`X as Y`), so matching on the file path —
+ * which uniquely identifies this one tool either way — is what makes
+ * this work for both shapes without the caller having to say which one
+ * it originally was. */
+export declare function removeToolFromIndex(toolsIndexPath: string, toolFileName: string, arrayExpression: string): void;
 /** Generates agents/<agentName>/tools/<spec.name>.ts, registers it in
  * that agent's tools/index.ts, then imports the file it just wrote and
  * returns the real, callable ToolDefinition object — so the route

package/dist/web/http-tool-admin.js

@@ -179,13 +179,29 @@ ${responseHandling}  },
 // across every real example in this repo (agents/customer-service/
 // tools/index.ts, create-loopengine's own template) — a handful of
 // named imports, then one `export const tools: ToolDefinition[] = [...]`
-// array literal. This patches that exact shape with two small string
-// edits (one new import line, one new array entry) rather than a full
-// TS-AST rewrite; if the file has been hand-edited into something this
-// pattern doesn't recognize, it refuses instead of risking corrupting it
-// — same "refuse rather than guess" discipline agent-file-admin.ts's own
-// doc comment already establishes for index.ts edits.
-export function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
+// array literal. This patches that exact shape with small string edits
+// (one new import line, one new array entry, and — only for a namespaced
+// ability install, see ability-manager.ts's namespacedToolName — one
+// `const` line between them) rather than a full TS-AST rewrite; if the
+// file has been hand-edited into something this pattern doesn't
+// recognize, it refuses instead of risking corrupting it — same "refuse
+// rather than guess" discipline agent-file-admin.ts's own doc comment
+// already establishes for index.ts edits.
+//
+// `importSpecifier` and `arrayExpression` are deliberately separate
+// parameters, not always the same string: the common case (this
+// function's only caller until ability-manager.ts's own namespacing)
+// has them identical (a bare `import { X }`, then bare `X` in the
+// array), but a namespaced tool install needs an *aliased* import (two
+// abilities' own files can both export a same-named top-level `const` —
+// e.g. both literally `webSearch` — which would collide as two
+// identically-named imports in this one file even though the source
+// files differ) feeding into a small wrapper `const` that overrides the
+// object's own `name` field (aliasing the import only renames the JS
+// binding, never the `ToolDefinition.name` string the model actually
+// calls by) — `preamble` is that wrapper line, and `arrayExpression` is
+// its name, not the raw import's.
+export function addToolToIndex(toolsIndexPath, toolFileName, importSpecifier, arrayExpression = importSpecifier, preamble) {
     const source = readFileSync(toolsIndexPath, 'utf8');
     const arrayMatch = source.match(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/);
     if (!arrayMatch) {
@@ -201,40 +217,54 @@ export function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
         .split(',')
         .map((e) => e.trim())
         .filter(Boolean);
-    if (arrayEntries.includes(exportName))
+    if (arrayEntries.includes(arrayExpression))
         return;
-    const importLine = `import { ${exportName} } from './${toolFileName}.js'\n`;
+    const importLine = `import { ${importSpecifier} } from './${toolFileName}.js'\n`;
     const lastImportMatch = [...source.matchAll(/^import .+\n/gm)].pop();
     const insertAt = lastImportMatch ? lastImportMatch.index + lastImportMatch[0].length : 0;
-    const withImport = source.slice(0, insertAt) + importLine + source.slice(insertAt);
-    const newEntries = [...arrayEntries, exportName].join(', ');
+    const preambleBlock = preamble ? `${preamble}\n` : '';
+    const withImport = source.slice(0, insertAt) + importLine + preambleBlock + source.slice(insertAt);
+    const newEntries = [...arrayEntries, arrayExpression].join(', ');
     const withEntry = withImport.replace(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/, `export const tools: ToolDefinition[] = [${newEntries}]`);
     writeFileSync(toolsIndexPath, withEntry);
 }
-/** addToolToIndex's own undo — removes the named tool's import line and
- * array entry. Best-effort, not "refuse rather than guess" like
- * addToolToIndex: this only ever runs against a tool ability-manager.ts
- * itself installed (so the exact shape addToolToIndex wrote is known),
- * and the caller (removeAbility) has already deleted the tool's .ts
- * file — leaving a stale entry behind, the previous behavior, means a
- * dangling import that fails the next build, which is strictly worse
- * than a no-op here if the file turns out not to match (hand-edited
- * since). No-ops (rather than throwing) when the file is missing
- * entirely, or the expected import/array-entry shape isn't found. */
-export function removeToolFromIndex(toolsIndexPath, toolFileName, exportName) {
+/** addToolToIndex's own undo — removes the named tool's import line,
+ * wrapper `const` (if a namespaced install added one), and array entry.
+ * Best-effort, not "refuse rather than guess" like addToolToIndex: this
+ * only ever runs against a tool ability-manager.ts itself installed (so
+ * the exact shape addToolToIndex wrote is known), and the caller
+ * (removeAbility) has already deleted the tool's .ts file — leaving a
+ * stale entry behind, the previous behavior, means a dangling import
+ * that fails the next build, which is strictly worse than a no-op here
+ * if the file turns out not to match (hand-edited since). No-ops (rather
+ * than throwing) when the file is missing entirely, or the expected
+ * import/array-entry shape isn't found.
+ *
+ * `arrayExpression` (not the raw import specifier) — same value
+ * addToolToIndex's own `arrayExpression` was called with, since that's
+ * what actually appears in the array literal and (for a namespaced
+ * install) names the wrapper `const` too. The import line is matched by
+ * `toolFileName` alone, not by the exact imported binding: a namespaced
+ * install aliases its import (`X as Y`), so matching on the file path —
+ * which uniquely identifies this one tool either way — is what makes
+ * this work for both shapes without the caller having to say which one
+ * it originally was. */
+export function removeToolFromIndex(toolsIndexPath, toolFileName, arrayExpression) {
     if (!existsSync(toolsIndexPath))
         return;
-    const source = readFileSync(toolsIndexPath, 'utf8');
-    const importLineRe = new RegExp(`^import \\{ ${exportName} \\} from '\\./${toolFileName}\\.js'\\n`, 'm');
-    const withoutImport = source.replace(importLineRe, '');
-    const arrayMatch = withoutImport.match(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/);
+    let source = readFileSync(toolsIndexPath, 'utf8');
+    const importLineRe = new RegExp(`^import \\{ [^}]+ \\} from '\\./${toolFileName}\\.js'\\n`, 'm');
+    source = source.replace(importLineRe, '');
+    const preambleRe = new RegExp(`^const ${arrayExpression}: ToolDefinition = \\{[^\\n]*\\}\\n`, 'm');
+    source = source.replace(preambleRe, '');
+    const arrayMatch = source.match(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/);
     if (!arrayMatch)
         return;
     const remainingEntries = arrayMatch[1]
         .split(',')
         .map((e) => e.trim())
-        .filter((e) => e && e !== exportName);
-    const withEntry = withoutImport.replace(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/, `export const tools: ToolDefinition[] = [${remainingEntries.join(', ')}]`);
+        .filter((e) => e && e !== arrayExpression);
+    const withEntry = source.replace(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/, `export const tools: ToolDefinition[] = [${remainingEntries.join(', ')}]`);
     writeFileSync(toolsIndexPath, withEntry);
 }
 // The spec is persisted alongside the generated .ts file, under the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.24",
+  "version": "0.1.28",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",