loopengine 0.1.22 → 0.1.24

package/README.md

@@ -25,10 +25,10 @@ top to bottom. Run agents over a CLI, an HTTP API, or both.
 - **Sessions persist automatically.** Send a message, get a reply, come
   back later with the same session id and continue — no database to wire
   up yourself, and it survives a crash mid-turn cleanly.
-- **A package system for reusable capabilities.** Install a bundle of
+- **An ability system for reusable capabilities.** Install a bundle of
   tools, a skill, and the permission rules that gate them with one command
   — real, reviewable files in your own repo, not an opaque dependency. See
-  [Package system](#package-system) below.
+  [Ability system](#ability-system) below.
 - **Does real work, safely.** Tools can hit a database, send emails, call
   GitHub/Slack, anything with an `execute` function. Permission rules gate
   what happens without a human: safe reads auto-run, risky actions get
@@ -118,7 +118,7 @@ redeploy needed for most of it:
 | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
 | **Tools** | Local hand-written tools, gateway-sourced tools (e.g. [Composio](https://composio.dev)), and subagents-as-tools, in one place. Connect a new external gateway source or add/remove a tool without touching a file. |
 | **ActAuth** | Add, edit, and delete permission rules — scope, tool, condition, decision — and change `default_decision`, live. |
-| **Environment** | Every env var a package (see [Package system](#package-system)) declared it needs, across everything installed for this agent — which ones are set, which are missing, and a form to set one. A value is never echoed back once set. |
+| **Environment** | Every env var an ability (see [Ability system](#ability-system)) declared it needs, across everything installed for this agent — which ones are set, which are missing, and a form to set one. A value is never echoed back once set. |
 
 Every tab is backed by a real API (`GET /agents/:name/config`, `.../actauth`,
 `.../env`, ...) that reuses the exact same resolution `runAgent()` itself
@@ -170,15 +170,15 @@ click, a webhook HMAC signature, a magic-link token) ship under
 live and durable, worked examples, and how resumption actually works
 under the hood.
 
-## Package system
+## Ability system
 
 Giving an agent a new capability is usually three separate, hand-authored
 things: a tool file, a `SKILL.md` teaching the model when to use it, and
-an `actauth` rule allowing it to actually run. A **loopengine package**
+an `actauth` rule allowing it to actually run. A **loopengine ability**
 bundles all three into one installable unit:
 
 ```bash
-npx loopengine add-package <spec> --agent customer-service
+npx loopengine add-ability <spec> --agent customer-service
 ```
 
 `<spec>` is anything `npm pack` understands — a public or private npm
@@ -189,17 +189,17 @@ dependency — reviewable, diffable, and editable the same as anything you
 would have hand-written, not an opaque black box.
 
 ```bash
-npx loopengine upgrade-package <packageName> --agent customer-service
-npx loopengine remove-package <packageName> --agent customer-service
+npx loopengine upgrade-ability <abilityName> --agent customer-service
+npx loopengine remove-ability <abilityName> --agent customer-service
 ```
 
 Upgrading does a real three-way merge per file — a hand-edit since install
 survives, a genuine conflict leaves `<<<<<<<` markers to resolve by hand
 instead of silently overwriting either side. Removing refuses a file
-that's been modified since install unless you pass `--force`. A package
+that's been modified since install unless you pass `--force`. An ability
 can also declare the env vars its tools need, which then show up in the
 Admin UI's [Environment tab](#admin-ui) automatically once installed. See
-[`PACKAGES.md`](PACKAGES.md) for the full design — format, publishing,
+[`ABILITIES.md`](ABILITIES.md) for the full design — format, publishing,
 and how the merge/upgrade mechanics work in detail.
 
 ## Running an agent

package/dist/bin/{package-manager.d.ts → ability-manager.d.ts}

@@ -1,48 +1,54 @@
-export declare class PackageManifestError extends Error {
+export declare class AbilityManifestError extends Error {
 }
-export declare class PackageVersionError extends Error {
+export declare class AbilityVersionError extends Error {
 }
-export declare class PackageCollisionError extends Error {
+export declare class AbilityCollisionError extends Error {
 }
-export declare class PackageNotInstalledError extends Error {
+export declare class AbilityNotInstalledError extends Error {
 }
-export declare class PackageAlreadyInstalledError extends Error {
+export declare class AbilityAlreadyInstalledError extends Error {
 }
-export interface PackageEnvDecl {
+export interface AbilityEnvDecl {
     name: string;
     description?: string;
     secret?: boolean;
 }
-export interface PackageManifest {
+/** `name`/`version` deliberately aren't declared here — they're read off
+ * the ability's own sibling `package.json` instead (see readManifest),
+ * which already has to exist and already has to carry real, valid values
+ * for `npm pack` to treat the directory as a fetchable package at all.
+ * loopengine.ability.json only ever needs to declare what npm has no
+ * vocabulary for. */
+export interface AbilityManifest {
     name: string;
     version: string;
     loopengineVersion: string;
     tools?: string[];
     skills?: string[];
     actauth?: string;
-    env?: PackageEnvDecl[];
+    env?: AbilityEnvDecl[];
 }
-/** One agent's record of one installed package — the merge base a
+/** One agent's record of one installed ability — the merge base a
  * future upgrade needs, what remove needs to know is safe to delete,
  * and (env) what the Admin UI's secrets section reads to know which
- * vars to prompt for. Written to agents/<agent>/.loopengine-packages.json,
+ * vars to prompt for. Written to agents/<agent>/.loopengine-abilities.json,
  * same role .create-loopengine.json already plays for template files. */
-export interface InstalledPackageRecord {
+export interface InstalledAbilityRecord {
     version: string;
     /** The exact spec (bare registry name, "name@version", a git+ssh/
      * git+https URL with a #committish, a file: path, ...) last used to
-     * successfully install or upgrade this package — see
-     * oldContentSpec's own doc comment for why upgradePackage needs this
-     * stored verbatim rather than reconstructed from `packageName`.
-     * Optional only because a package installed before this field existed
+     * successfully install or upgrade this ability — see
+     * oldContentSpec's own doc comment for why upgradeAbility needs this
+     * stored verbatim rather than reconstructed from `abilityName`.
+     * Optional only because an ability installed before this field existed
      * has no recorded value — see oldContentSpec's own fallback. */
     spec?: string;
     tools: string[];
     skills: string[];
     actauthRules: string[];
-    env: PackageEnvDecl[];
+    env: AbilityEnvDecl[];
     /** relative path (e.g. "tools/foo.ts") -> sha256 hex, as of the last
-     * install/upgrade — remove-package's dirty-check compares against
+     * install/upgrade — remove-ability's dirty-check compares against
      * this rather than storing/refetching full content to diff. */
     contentHashes: Record<string, string>;
 }
@@ -52,11 +58,11 @@ export interface InstalledPackageRecord {
  * 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 declare function fetchPackageDir(spec: string): string;
+ * real network call is needed there; see ABILITIES.md's "Publishing an
+ * ability" section). */
+export declare function fetchAbilityDir(spec: string): string;
 export interface FetchOptions {
-    fetchPackageDir?: (spec: string) => string;
+    fetchAbilityDir?: (spec: string) => string;
     /** Test-only override for the installing project's own "loopengine"
      * dependency range — defaults to a real package.json read. Without
      * this, checkLoopengineVersion's refusal path is unreachable from
@@ -71,7 +77,7 @@ export interface FetchOptions {
  * (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
@@ -79,7 +85,7 @@ export interface FetchOptions {
  * 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
@@ -96,41 +102,41 @@ export interface FetchOptions {
  *
  * All-or-nothing: every collision check below runs, and the whole
  * install is refused, before a single file is written. */
-export declare function installPackage(agentName: string, spec: string, options?: FetchOptions): Promise<{
+export declare function installAbility(agentName: string, spec: string, options?: FetchOptions): Promise<{
     installed: string[];
 }>;
 export interface UpgradeFileResult {
     path: string;
     status: 'updated' | 'unchanged' | 'conflict';
 }
-/** 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 declare function upgradePackage(agentName: string, packageName: string, options?: FetchOptions & {
+export declare function upgradeAbility(agentName: string, abilityName: string, options?: FetchOptions & {
     spec?: string;
 }): Promise<{
     files: UpgradeFileResult[];
 }>;
-/** 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 declare function removePackage(agentName: string, packageName: string, force?: boolean): {
+export declare function removeAbility(agentName: string, abilityName: string, force?: boolean): {
     removed: string[];
     refused: string[];
 };

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/web/agents-config-page.js

@@ -1110,9 +1110,9 @@ export const agentsConfigPageHtml = `<!doctype html>
       });
   }
 
-  // ---- Environment tab: every env var a package (see PACKAGES.md,
-  // bin/package-manager.ts) declared it needs for this agent, across
-  // every package installed — status only, a value is never shown once
+  // ---- Environment tab: every env var an ability (see ABILITIES.md,
+  // bin/ability-manager.ts) declared it needs for this agent, across
+  // every ability installed — status only, a value is never shown once
   // set, matching env-admin.ts's own never-echo-a-secret rule. Lazily
   // loaded the same way Actauth is, for the same reason (avoid a
   // redundant fetch on every agent switch for a tab that isn't always
@@ -1126,7 +1126,7 @@ export const agentsConfigPageHtml = `<!doctype html>
     return '<tr>' +
       '<td><code>' + escapeHtml(v.name) + '</code></td>' +
       '<td>' + escapeHtml(v.description || '') + '</td>' +
-      '<td class="hint">' + escapeHtml(v.packageName) + '</td>' +
+      '<td class="hint">' + escapeHtml(v.abilityName) + '</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>' +
@@ -1136,9 +1136,9 @@ export const agentsConfigPageHtml = `<!doctype html>
   }
 
   function renderEnvConfigHtml(vars) {
-    if (!vars.length) return '<p class="hint">No installed package has declared any environment variables for this agent yet.</p>';
+    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>Package</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>Ability</th><th>Status</th><th>Set value</th></tr></thead><tbody>' + rows + '</tbody></table>';
   }
 
   function envContentEl() {

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

@@ -4,13 +4,13 @@ export interface DeclaredEnvVar {
     name: string;
     description?: string;
     secret: boolean;
-    packageName: string;
+    abilityName: string;
     set: boolean;
 }
-/** Every env var any package installed for `agentName` declared it
- * needs, deduplicated by name — PACKAGES.md's own open question on
- * cross-package name collisions applies here too (one .env per
- * *project*, not per agent, so two unrelated packages declaring the
+/** 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
@@ -19,7 +19,7 @@ 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
  * applies it to *this* running process immediately via `process.env`,
- * so a newly-installed package's tools work without a restart. Callers
+ * so a newly-installed ability's tools work without a restart. Callers
  * (the PUT route in adapters/http.ts) are responsible for refusing to
  * call this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this
  * function itself has no notion of HTTP auth, it just writes. */

package/dist/web/env-admin.js

@@ -1,6 +1,6 @@
-// Backs the Admin UI's "Environment" section — every env var a package
-// (see PACKAGES.md, bin/package-manager.ts) declared as required,
-// across every package installed for an agent, with set/not-set status
+// Backs the Admin UI's "Environment" section — every env var an ability
+// (see ABILITIES.md, bin/ability-manager.ts) declared as required,
+// across every ability installed for an agent, with set/not-set status
 // only. A value marked `secret` is never echoed back once set — same
 // never-echo-a-secret rule web/http-tool-admin.ts's own `{{ENV_VAR}}`
 // header handling already establishes for a tool's own secrets.
@@ -13,12 +13,12 @@ export class EnvVarNameError extends Error {
 // validates a {{ENV_VAR}} header reference against.
 const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 function provenancePath(agentName) {
-    return join(agentDir(agentName), '.loopengine-packages.json');
+    return join(agentDir(agentName), '.loopengine-abilities.json');
 }
-/** Every env var any package installed for `agentName` declared it
- * needs, deduplicated by name — PACKAGES.md's own open question on
- * cross-package name collisions applies here too (one .env per
- * *project*, not per agent, so two unrelated packages declaring the
+/** 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
@@ -30,7 +30,7 @@ export function listDeclaredEnvVars(agentName) {
     const provenance = JSON.parse(readFileSync(path, 'utf8'));
     const seen = new Set();
     const result = [];
-    for (const [packageName, record] of Object.entries(provenance)) {
+    for (const [abilityName, record] of Object.entries(provenance)) {
         for (const decl of record.env) {
             if (seen.has(decl.name))
                 continue;
@@ -39,7 +39,7 @@ export function listDeclaredEnvVars(agentName) {
                 name: decl.name,
                 description: decl.description,
                 secret: decl.secret === true,
-                packageName,
+                abilityName,
                 set: process.env[decl.name] !== undefined,
             });
         }
@@ -68,7 +68,7 @@ function serializeEnvValue(value) {
 /** Upserts `NAME=VALUE` into the project's `.env` file — preserving
  * every other line (comments, blank lines, unrelated keys) — and
  * applies it to *this* running process immediately via `process.env`,
- * so a newly-installed package's tools work without a restart. Callers
+ * so a newly-installed ability's tools work without a restart. Callers
  * (the PUT route in adapters/http.ts) are responsible for refusing to
  * call this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this
  * function itself has no notion of HTTP auth, it just writes. */

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

@@ -40,9 +40,9 @@ 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 package-manager.ts
+ * addToolToIndex: this only ever runs against a tool ability-manager.ts
  * itself installed (so the exact shape addToolToIndex wrote is known),
- * and the caller (removePackage) has already deleted the tool's .ts
+ * 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

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

@@ -191,8 +191,8 @@ export function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
     if (!arrayMatch) {
         throw new HttpToolIndexShapeError(`${toolsIndexPath} doesn't match the expected "export const tools: ToolDefinition[] = [...]" shape — add this tool to it by hand instead.`);
     }
-    // Idempotent — a caller that adds the same tool twice (e.g. package-
-    // manager.ts's removePackage not having cleaned up this same file
+    // Idempotent — a caller that adds the same tool twice (e.g. ability-
+    // manager.ts's removeAbility not having cleaned up this same file
     // before a re-add, or simply calling this twice by mistake) gets a
     // no-op the second time instead of a duplicate `import { X }`
     // declaration, which is a TypeScript syntax error ("Duplicate
@@ -213,9 +213,9 @@ export function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
 }
 /** 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 package-manager.ts
+ * addToolToIndex: this only ever runs against a tool ability-manager.ts
  * itself installed (so the exact shape addToolToIndex wrote is known),
- * and the caller (removePackage) has already deleted the tool's .ts
+ * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -23,8 +23,8 @@
     "dist/index.d.ts",
     "dist/bin/cli.js",
     "dist/bin/cli.d.ts",
-    "dist/bin/package-manager.js",
-    "dist/bin/package-manager.d.ts",
+    "dist/bin/ability-manager.js",
+    "dist/bin/ability-manager.d.ts",
     "dist/core/run-agent.js",
     "dist/core/run-agent.d.ts",
     "dist/core/loop-events.js",