loopengine 0.1.22 → 0.1.27

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[];
 };