loopengine 0.1.10 → 0.1.12

package/dist/bin/cli.js

@@ -13,6 +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';
 const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 export class AgentNameError extends Error {
 }
@@ -230,6 +231,24 @@ async function requireAdapterFile(relPath) {
     process.exitCode = 1;
     return false;
 }
+// Shared by add-package/upgrade-package/remove-package 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
+// isn't worth a helper; three is).
+function extractFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return { value: undefined, rest: args };
+    const value = args[index + 1];
+    return { value, rest: [...args.slice(0, index), ...args.slice(index + 2)] };
+}
+function extractFlagPresence(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return { present: false, rest: args };
+    return { present: true, rest: [...args.slice(0, index), ...args.slice(index + 1)] };
+}
 async function main() {
     const [, , command, ...rest] = process.argv;
     if (command === 'add-agent') {
@@ -282,6 +301,88 @@ 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
+    // 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
+    // why). <spec> is whatever `npm pack` itself accepts.
+    if (command === 'add-package') {
+        const { value: agent, rest: withoutAgent } = extractFlagValue(rest, '--agent');
+        const [spec] = withoutAgent;
+        if (!spec || !agent) {
+            console.error('Usage: loopengine add-package <spec> --agent <name>');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const { installed } = await installPackage(agent, spec);
+            console.log(`Installed into agents/${agent}/:`);
+            for (const p of installed)
+                console.log(`  ${p}`);
+            console.log();
+            console.log('Already running under `npx loopengine dev`? The new tool becomes active automatically.');
+            console.log('Running under `serve` (or nothing yet)? Restart the server to pick it up.');
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Pulls in whatever <packageName> (or --spec, if the package 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') {
+        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>]');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const { files } = await upgradePackage(agent, packageName, spec ? { spec } : {});
+            for (const f of files)
+                console.log(`  ${f.status.padEnd(9)}${f.path}`);
+            const conflicts = files.filter((f) => f.status === 'conflict');
+            console.log(conflicts.length > 0 ? `${conflicts.length} file(s)/rule(s) need resolving by hand.` : 'No conflicts.');
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Removes a package'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') {
+        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]');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const { removed, refused } = removePackage(agent, packageName, force);
+            for (const p of removed)
+                console.log(`  removed  ${p}`);
+            for (const p of refused)
+                console.log(`  refused  ${p}  (hand-modified since install — pass --force to remove anyway)`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
     // One-shot: sends one message, prints the reply, exits — exactly
     // adapters/cli.ts's own contract (see its own header comment), not a
     // REPL. `rest` after `<agent>` is forwarded through as-is (--session,
@@ -362,6 +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 run <agent> [--session <id>] "<message>"');
     console.error('       loopengine serve');
     console.error('       loopengine dev');

package/dist/bin/package-manager.d.ts

@@ -0,0 +1,128 @@
+export declare class PackageManifestError extends Error {
+}
+export declare class PackageVersionError extends Error {
+}
+export declare class PackageCollisionError extends Error {
+}
+export declare class PackageNotInstalledError extends Error {
+}
+export declare class PackageAlreadyInstalledError extends Error {
+}
+export interface PackageEnvDecl {
+    name: string;
+    description?: string;
+    secret?: boolean;
+}
+export interface PackageManifest {
+    name: string;
+    version: string;
+    loopengineVersion: string;
+    tools?: string[];
+    skills?: string[];
+    actauth?: string;
+    env?: PackageEnvDecl[];
+}
+/** One agent's record of one installed package — 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,
+ * same role .create-loopengine.json already plays for template files. */
+export interface InstalledPackageRecord {
+    version: string;
+    tools: string[];
+    skills: string[];
+    actauthRules: string[];
+    env: PackageEnvDecl[];
+    /** relative path (e.g. "tools/foo.ts") -> sha256 hex, as of the last
+     * install/upgrade — remove-package's dirty-check compares against
+     * this rather than storing/refetching full content to diff. */
+    contentHashes: Record<string, string>;
+}
+/** `npm pack <spec>` + tar extract — generalized from
+ * create-loopengine's own `fetchPublishedTemplateDir` (that function
+ * only ever fetches the hardcoded `create-loopengine@<version>`; this
+ * 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;
+export interface FetchOptions {
+    fetchPackageDir?: (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
+     * this repo's own test suite: this repo's package.json has no
+     * self-dependency to check against (see that function's own doc
+     * comment), so every real test run would silently skip the check
+     * instead of exercising it. */
+    installedLoopengineRange?: string;
+}
+/** Installs `spec` (anything `npm pack` accepts) for `agentName`:
+ * writes each manifest-listed tool file and patches tools/index.ts
+ * (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/assets), and appends each actauth rule (addActauthRule).
+ *
+ * Deliberately does *not* attempt a live in-memory registry splice the
+ * way adapters/http.ts's own handleHttpToolPost does for an
+ * 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
+ * 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
+ * vanish the moment the process exits, having done nothing to the real
+ * running server. (Confirmed live: this used to import
+ * core/agent-registry.js, whose own discoverAgents does a top-level
+ * directory scan relative to *its own compiled file's location* —
+ * inside node_modules/loopengine when this runs there, not the
+ * consuming project's real agents/ at all, throwing ENOENT immediately.)
+ * Same reason add-agent/add-subagent above don't attempt this either —
+ * a new tool becomes active the same way a new agent does: the next
+ * request under `serve`, or automatically under `npx loopengine dev`'s
+ * file watcher once tools/index.ts's own edit is picked up.
+ *
+ * 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<{
+    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
+ * 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 `<spec>@<oldVersion>`; theirs =
+ * newly fetched) — identical technique to `create-loopengine upgrade`,
+ * just applied to package-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 "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 & {
+    spec?: string;
+}): Promise<{
+    files: UpgradeFileResult[];
+}>;
+/** Removes an installed package'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
+ * "refuses if any of them look hand-modified," cheaper than storing full
+ * content or refetching the package 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): {
+    removed: string[];
+    refused: string[];
+};

package/dist/bin/package-manager.js

@@ -0,0 +1,490 @@
+// 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
+// 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
+// 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
+// import" reasoning).
+//
+// Deliberately reimplements (rather than imports) the two techniques
+// create-loopengine's own `upgrade` command already has —
+// `fetchPublishedTemplateDir`'s npm-pack-and-extract, and
+// `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
+// "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 { tmpdir } from 'node:os';
+import { parse as parseYaml } from 'yaml';
+import semver from 'semver';
+import { agentDir } from '../core/gateway-tools.js';
+import { addToolToIndex, toCamelCase } from '../web/http-tool-admin.js';
+import { addActauthRule, updateActauthRule, removeActauthRule, readActauthConfig } from '../web/actauth-admin.js';
+export class PackageManifestError extends Error {
+}
+export class PackageVersionError extends Error {
+}
+export class PackageCollisionError extends Error {
+}
+export class PackageNotInstalledError extends Error {
+}
+export class PackageAlreadyInstalledError 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
+// segment (agents/<agent>/tools/<name>.ts, .../skills/<id>/): without
+// this, a package 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');
+}
+function readProvenance(agentName) {
+    const path = provenancePath(agentName);
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function writeProvenance(agentName, data) {
+    writeFileSync(provenancePath(agentName), JSON.stringify(data, null, 2) + '\n');
+}
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+// ---- Fetch ----
+/** `npm pack <spec>` + tar extract — generalized from
+ * create-loopengine's own `fetchPublishedTemplateDir` (that function
+ * only ever fetches the hardcoded `create-loopengine@<version>`; this
+ * 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-'));
+    execFileSync('npm', ['pack', spec, '--pack-destination', workDir], { stdio: 'pipe' });
+    const tarball = readdirSync(workDir).find((f) => f.endsWith('.tgz'));
+    if (!tarball) {
+        throw new Error(`Could not fetch '${spec}' — check the package exists and is reachable (registry auth / git credentials / local path).`);
+    }
+    // Absolute path, not the bare filename readdirSync returns — same
+    // "tar resolves a relative first argument against the calling
+    // process's own cwd, not workDir" gotcha fetchPublishedTemplateDir's
+    // own comment already documents.
+    execFileSync('tar', ['-xzf', join(workDir, tarball), '-C', workDir], { stdio: 'pipe' });
+    return join(workDir, 'package');
+}
+function readManifest(packageDir) {
+    const manifestPath = join(packageDir, 'loopengine.package.json');
+    if (!existsSync(manifestPath)) {
+        throw new PackageManifestError(`${packageDir} has no loopengine.package.json — not a valid loopengine package.`);
+    }
+    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".');
+    }
+    return manifest;
+}
+// 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
+// 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).
+function checkLoopengineVersion(manifest, installedRangeOverride) {
+    let installedRange = installedRangeOverride;
+    if (!installedRange) {
+        // process.cwd(), not core/agent-registry.ts's own projectDir() —
+        // that function resolves relative to *this compiled file's own
+        // location*, correct only when agents/ is compiled alongside
+        // dist/core/, which doesn't hold for a real scaffolded project
+        // (loopengine lives in node_modules/loopengine/dist/, but the
+        // project's own package.json is at the project root). Every other
+        // cwd-relative path in this CLI (bin/cli.ts's requireAdapterFile,
+        // core/gateway-tools.ts's own agentsRootDir, which agentDir() above
+        // already relies on throughout this file) already resolves this way
+        // — confirmed live: a real `npm pack file:...` install against this
+        // repo's own dist/bin/cli.js failed against projectDir() here before
+        // this fix, for exactly this reason.
+        const ownPkgPath = join(process.cwd(), 'package.json');
+        const ownPkg = JSON.parse(readFileSync(ownPkgPath, 'utf8'));
+        // A checkout of loopengine's own source (this repo, including its
+        // own test suite) has no "loopengine" entry to check against — it
+        // can't depend on itself. Same "detected by package.json's own
+        // name, not a flag to remember" distinction bin/cli.ts's own
+        // configImportSpecifier already makes for exactly this
+        // repo-vs-real-consumer-project case.
+        if (ownPkg.name === 'loopengine')
+            return;
+        installedRange = ownPkg.dependencies?.loopengine;
+        if (!installedRange) {
+            throw new PackageVersionError(`This project's package.json has no "loopengine" dependency — can't check compatibility.`);
+        }
+    }
+    // A non-registry dependency specifier (file:, git:, workspace:, ...) —
+    // common for local development against an unpublished loopengine
+    // build — isn't a semver range at all, so minVersion throws rather
+    // than returning null; nothing meaningful to compare against, so skip
+    // the check rather than crash the whole command on it (same "nothing
+    // to compare, nothing to refuse" reasoning the this-repo-itself skip
+    // above already uses).
+    let floor;
+    try {
+        floor = semver.minVersion(installedRange);
+    }
+    catch {
+        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.`);
+    }
+}
+function parseActauthRules(packageDir, manifest) {
+    if (!manifest.actauth)
+        return [];
+    const rulesPath = join(packageDir, manifest.actauth);
+    if (!existsSync(rulesPath)) {
+        throw new PackageManifestError(`Manifest references actauth file '${manifest.actauth}', which doesn't exist in the package.`);
+    }
+    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.`);
+    }
+    return parsed;
+}
+// ---- Install ----
+/** Installs `spec` (anything `npm pack` accepts) for `agentName`:
+ * writes each manifest-listed tool file and patches tools/index.ts
+ * (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/assets), and appends each actauth rule (addActauthRule).
+ *
+ * Deliberately does *not* attempt a live in-memory registry splice the
+ * way adapters/http.ts's own handleHttpToolPost does for an
+ * 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
+ * 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
+ * vanish the moment the process exits, having done nothing to the real
+ * running server. (Confirmed live: this used to import
+ * core/agent-registry.js, whose own discoverAgents does a top-level
+ * directory scan relative to *its own compiled file's location* —
+ * inside node_modules/loopengine when this runs there, not the
+ * consuming project's real agents/ at all, throwing ENOENT immediately.)
+ * Same reason add-agent/add-subagent above don't attempt this either —
+ * a new tool becomes active the same way a new agent does: the next
+ * request under `serve`, or automatically under `npx loopengine dev`'s
+ * file watcher once tools/index.ts's own edit is picked up.
+ *
+ * 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);
+    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.`);
+    }
+    const toolFiles = manifest.tools ?? [];
+    const skillDirs = manifest.skills ?? [];
+    const rules = parseActauthRules(packageDir, 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.
+    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).`);
+        }
+        toolNames.push(toolName);
+        if (existsSync(join(toolsDir, `${toolName}.ts`))) {
+            throw new PackageCollisionError(`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).`);
+        }
+        skillIds.push(skillId);
+        if (existsSync(join(skillsDirPath, skillId))) {
+            throw new PackageCollisionError(`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}'.`);
+        }
+    }
+    const contentHashes = {};
+    // Write tool files and patch tools/index.ts — pure filesystem
+    // operations, no dynamic import and no registry interaction (see this
+    // function's own doc comment for why: a CLI process can't live-splice
+    // into a separate, already-running server).
+    if (toolNames.length > 0) {
+        mkdirSync(toolsDir, { recursive: true });
+        const indexPath = join(toolsDir, 'index.ts');
+        for (const toolFile of toolFiles) {
+            const toolName = basename(toolFile, '.ts');
+            const code = readFileSync(join(packageDir, toolFile), 'utf8');
+            const destPath = join(toolsDir, `${toolName}.ts`);
+            writeFileSync(destPath, code);
+            contentHashes[`tools/${toolName}.ts`] = sha256(code);
+            const exportName = toCamelCase(toolName);
+            if (existsSync(indexPath)) {
+                addToolToIndex(indexPath, toolName, exportName);
+            }
+            else {
+                writeFileSync(indexPath, `import type { ToolDefinition } from 'loopengine'\nimport { ${exportName} } from './${toolName}.js'\n\nexport const tools: ToolDefinition[] = [${exportName}]\n`);
+            }
+        }
+    }
+    // Copy skill directories verbatim.
+    for (const skillDir of skillDirs) {
+        const skillId = basename(skillDir);
+        const srcPath = join(packageDir, skillDir);
+        const destPath = join(skillsDirPath, skillId);
+        mkdirSync(skillsDirPath, { recursive: true });
+        cpSync(srcPath, destPath, { recursive: true });
+        const skillMdPath = join(destPath, 'SKILL.md');
+        if (existsSync(skillMdPath)) {
+            contentHashes[`skills/${skillId}/SKILL.md`] = sha256(readFileSync(skillMdPath, 'utf8'));
+        }
+    }
+    // Append actauth rules.
+    for (const rule of rules) {
+        addActauthRule(agentName, rule);
+    }
+    provenance[manifest.name] = {
+        version: manifest.version,
+        tools: toolNames,
+        skills: skillIds,
+        actauthRules: rules.map((r) => r.name),
+        env: manifest.env ?? [],
+        contentHashes,
+    };
+    writeProvenance(agentName, provenance);
+    return { installed: [...toolNames.map((n) => `tools/${n}.ts`), ...skillIds.map((id) => `skills/${id}/`), ...rules.map((r) => `actauth:${r.name}`)] };
+}
+// ---- Upgrade ----
+// git merge-file's own exit code *is* its conflict count (0 = clean),
+// not a pass/fail signal — same distinction create-loopengine's own
+// 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 minePath = join(scratchDir, 'mine');
+    const basePath = join(scratchDir, 'base');
+    const theirsPath = join(scratchDir, 'theirs');
+    writeFileSync(minePath, mine);
+    writeFileSync(basePath, base);
+    writeFileSync(theirsPath, theirs);
+    let conflicted = false;
+    try {
+        execFileSync('git', ['merge-file', '--diff3', '-L', 'mine', '-L', 'base', '-L', 'latest', minePath, basePath, theirsPath], { stdio: 'pipe' });
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number') {
+            conflicted = true;
+        }
+        else {
+            throw new Error(`git merge-file failed — is git installed and on PATH? (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    const merged = readFileSync(minePath, 'utf8');
+    rmSync(scratchDir, { recursive: true, force: true });
+    return { merged, conflicted };
+}
+/** Upgrades an already-installed package to whatever `spec` (defaulting
+ * to `packageName`, 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 `<spec>@<oldVersion>`; theirs =
+ * newly fetched) — identical technique to `create-loopengine upgrade`,
+ * just applied to package-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 "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;
+    const provenance = readProvenance(agentName);
+    const record = provenance[packageName];
+    if (!record) {
+        throw new PackageNotInstalledError(`Package '${packageName}' isn't installed for '${agentName}'.`);
+    }
+    const spec = options.spec ?? packageName;
+    const oldDir = fetch(`${spec}@${record.version}`);
+    const newDir = fetch(spec);
+    const oldManifest = readManifest(oldDir);
+    const newManifest = readManifest(newDir);
+    checkLoopengineVersion(newManifest, options.installedLoopengineRange);
+    const results = [];
+    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);
+        if (!oldFile || !newFile) {
+            results.push({ path: relPath, status: 'unchanged' });
+            continue;
+        }
+        const base = readFileSync(join(oldDir, oldFile), 'utf8');
+        const theirs = readFileSync(join(newDir, newFile), 'utf8');
+        if (base === theirs) {
+            results.push({ path: relPath, status: 'unchanged' });
+            continue;
+        }
+        const minePath = join(agentDir(agentName), relPath);
+        const { merged, conflicted } = mergeFile(readFileSync(minePath, 'utf8'), base, theirs);
+        writeFileSync(minePath, merged);
+        if (!conflicted)
+            newContentHashes[relPath] = sha256(merged);
+        results.push({ path: relPath, status: conflicted ? 'conflict' : 'updated' });
+    }
+    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);
+        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)) {
+            results.push({ path: relPath, status: 'unchanged' });
+            continue;
+        }
+        const base = readFileSync(oldFile, 'utf8');
+        const theirs = readFileSync(newFile, 'utf8');
+        if (base === theirs) {
+            results.push({ path: relPath, status: 'unchanged' });
+            continue;
+        }
+        const minePath = join(agentDir(agentName), relPath);
+        const { merged, conflicted } = mergeFile(readFileSync(minePath, 'utf8'), base, theirs);
+        writeFileSync(minePath, merged);
+        if (!conflicted)
+            newContentHashes[relPath] = sha256(merged);
+        results.push({ path: relPath, status: conflicted ? 'conflict' : 'updated' });
+    }
+    const oldRules = parseActauthRules(oldDir, oldManifest);
+    const newRules = parseActauthRules(newDir, newManifest);
+    const currentRules = new Map(readActauthConfig(agentName).rules.map((r) => [r.name, r]));
+    for (const ruleName of record.actauthRules) {
+        const oldRule = oldRules.find((r) => r.name === ruleName);
+        const newRule = newRules.find((r) => r.name === ruleName);
+        const current = currentRules.get(ruleName);
+        const path = `actauth:${ruleName}`;
+        if (!oldRule || !newRule || !current) {
+            results.push({ path, status: 'unchanged' });
+            continue;
+        }
+        const unchangedSinceInstall = current.scope === oldRule.scope && current.tool === oldRule.tool && current.decision === oldRule.decision;
+        if (!unchangedSinceInstall) {
+            results.push({ path, status: 'conflict' });
+            continue;
+        }
+        if (oldRule.scope === newRule.scope && oldRule.tool === newRule.tool && oldRule.decision === newRule.decision) {
+            results.push({ path, status: 'unchanged' });
+            continue;
+        }
+        updateActauthRule(agentName, ruleName, { scope: newRule.scope, tool: newRule.tool, decision: newRule.decision });
+        results.push({ path, status: 'updated' });
+    }
+    provenance[packageName] = { ...record, version: newManifest.version, contentHashes: newContentHashes, env: newManifest.env ?? record.env };
+    writeProvenance(agentName, provenance);
+    return { files: results };
+}
+// ---- Remove ----
+function isDirty(path, recordedHash) {
+    if (!existsSync(path))
+        return false;
+    if (!recordedHash)
+        return true;
+    return sha256(readFileSync(path, 'utf8')) !== recordedHash;
+}
+/** Removes an installed package'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
+ * "refuses if any of them look hand-modified," cheaper than storing full
+ * content or refetching the package 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) {
+    const provenance = readProvenance(agentName);
+    const record = provenance[packageName];
+    if (!record) {
+        throw new PackageNotInstalledError(`Package '${packageName}' isn't installed for '${agentName}'.`);
+    }
+    const removed = [];
+    const refused = [];
+    const remainingTools = [];
+    const remainingSkills = [];
+    for (const toolName of record.tools) {
+        const relPath = `tools/${toolName}.ts`;
+        const fullPath = join(agentDir(agentName), relPath);
+        if (!force && isDirty(fullPath, record.contentHashes[relPath])) {
+            refused.push(relPath);
+            remainingTools.push(toolName);
+            continue;
+        }
+        rmSync(fullPath, { force: true });
+        removed.push(relPath);
+    }
+    for (const skillId of record.skills) {
+        const relPath = `skills/${skillId}/SKILL.md`;
+        const fullPath = join(agentDir(agentName), relPath);
+        if (!force && isDirty(fullPath, record.contentHashes[relPath])) {
+            refused.push(relPath);
+            remainingSkills.push(skillId);
+            continue;
+        }
+        rmSync(join(agentDir(agentName), 'skills', skillId), { recursive: true, force: true });
+        removed.push(`skills/${skillId}/`);
+    }
+    for (const ruleName of record.actauthRules) {
+        try {
+            removeActauthRule(agentName, ruleName);
+            removed.push(`actauth:${ruleName}`);
+        }
+        catch {
+            // Already gone (hand-removed since install) — not a failure.
+        }
+    }
+    if (refused.length === 0) {
+        delete provenance[packageName];
+    }
+    else {
+        provenance[packageName] = { ...record, tools: remainingTools, skills: remainingSkills, actauthRules: [] };
+    }
+    writeProvenance(agentName, provenance);
+    return { removed, refused };
+}

package/dist/index.d.ts

@@ -43,6 +43,8 @@ export { readSkill, writeSkill, deleteSkill, SkillInvalidIdError, SkillNotFoundE
 export type { SkillContent } from './web/skills-admin.js';
 export { listSkillgardenCatalog, readSkillgardenCatalogEntry, addSkillgardenSkillToAgent, SkillgardenUnavailableError } from './web/skillgarden-admin.js';
 export type { SkillgardenCatalogEntry, SkillgardenCatalogDetail } from './web/skillgarden-admin.js';
+export { listDeclaredEnvVars, setEnvVar, EnvVarNameError } from './web/env-admin.js';
+export type { DeclaredEnvVar } from './web/env-admin.js';
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export type { ActauthRuleInput, ActauthConfigView } from './web/actauth-admin.js';
 export { describeModelProviders, describeGateways } from './web/global-config.js';

package/dist/index.js

@@ -44,6 +44,7 @@ export { globalConfigPageHtml } from './web/global-config-page.js';
 export { playgroundHtml } from './web/playground.js';
 export { readSkill, writeSkill, deleteSkill, SkillInvalidIdError, SkillNotFoundError } from './web/skills-admin.js';
 export { listSkillgardenCatalog, readSkillgardenCatalogEntry, addSkillgardenSkillToAgent, SkillgardenUnavailableError } from './web/skillgarden-admin.js';
+export { listDeclaredEnvVars, setEnvVar, EnvVarNameError } from './web/env-admin.js';
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export { describeModelProviders, describeGateways } from './web/global-config.js';
 export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';

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

@@ -425,6 +425,8 @@ export const agentsConfigPageHtml = `<!doctype html>
   // Same idea, for the Actauth tab's own separately-fetched GET
   // .../actauth (see renderActauthTabPlaceholder's own doc comment).
   var actauthLoadedFor = null;
+  // Same idea again, for the Environment tab's own GET .../env.
+  var envLoadedFor = null;
   // The full /agents/:name/config response the currently-open agent was
   // last rendered from — kept around so refreshActauthDependentPanels/
   // refreshSkillsDependentPanels below can re-fetch and re-render just
@@ -1128,6 +1130,95 @@ 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
+  // 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
+  // opened). ----
+
+  function renderEnvTabPlaceholder() {
+    return '<section id="envSection"><div id="envContent"><p class="hint">Loading&hellip;</p></div></section>';
+  }
+
+  function renderEnvRow(v) {
+    return '<tr>' +
+      '<td><code>' + escapeHtml(v.name) + '</code></td>' +
+      '<td>' + escapeHtml(v.description || '') + '</td>' +
+      '<td class="hint">' + escapeHtml(v.packageName) + '</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>' +
+        '<button type="submit">Save</button>' +
+      '</form></td>' +
+      '</tr>';
+  }
+
+  function renderEnvConfigHtml(vars) {
+    if (!vars.length) return '<p class="hint">No installed package 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>';
+  }
+
+  function envContentEl() {
+    return detail.querySelector('#envContent');
+  }
+
+  function wireEnvHandlers(name) {
+    var content = envContentEl();
+    if (!content) return;
+    var forms = content.querySelectorAll('.env-var-form');
+    for (var i = 0; i < forms.length; i++) {
+      forms[i].addEventListener('submit', function (ev) {
+        ev.preventDefault();
+        var form = ev.currentTarget;
+        var varName = form.getAttribute('data-name');
+        var value = new FormData(form).get('value');
+        var submitBtn = form.querySelector('button[type="submit"]');
+        submitBtn.disabled = true;
+        fetch('/agents/' + encodeURIComponent(name) + '/env/' + encodeURIComponent(varName), {
+          method: 'PUT',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ value: value }),
+        })
+          .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, body: j }; }); })
+          .then(function (result) {
+            if (!result.ok) throw new Error(result.body.error || 'request failed');
+            loadEnvTab(name);
+          })
+          .catch(function (err) {
+            alert('Could not set value: ' + err.message);
+            submitBtn.disabled = false;
+          });
+      });
+    }
+  }
+
+  function applyEnvConfig(name, vars) {
+    var content = envContentEl();
+    if (!content) return;
+    content.innerHTML = renderEnvConfigHtml(vars);
+    wireEnvHandlers(name);
+    envLoadedFor = name;
+  }
+
+  function loadEnvTab(name) {
+    var content = envContentEl();
+    if (!content) return;
+    content.innerHTML = '<p class="hint">Loading&hellip;</p>';
+    fetch('/agents/' + encodeURIComponent(name) + '/env')
+      .then(function (r) { return r.json(); })
+      .then(function (vars) {
+        if (currentName !== name) return;
+        applyEnvConfig(name, vars);
+      })
+      .catch(function (err) {
+        if (currentName !== name) return;
+        content.innerHTML = '<p class="error">Could not load environment variables: ' + escapeHtml(err.message) + '</p>';
+      });
+  }
+
   // ---- Skills tab: editable — add/edit/delete SKILL.md files via
   // skills-admin.ts, restricted (see that file's own doc comment) to
   // flat, non-nested skill ids. Unlike the Tools tab's Gateway Tools
@@ -2088,6 +2179,9 @@ export const agentsConfigPageHtml = `<!doctype html>
     if (tab === 'actauth' && actauthLoadedFor !== currentName) {
       loadActauthTab(currentName);
     }
+    if (tab === 'env' && envLoadedFor !== currentName) {
+      loadEnvTab(currentName);
+    }
   }
 
   // Refreshes just Overview's own summary — used after anything that
@@ -2163,11 +2257,13 @@ export const agentsConfigPageHtml = `<!doctype html>
         '<button class="tab" data-tab="skills">Skills</button>' +
         '<button class="tab" data-tab="tools">Tools</button>' +
         '<button class="tab" data-tab="actauth">ActAuth</button>' +
+        '<button class="tab" data-tab="env">Environment</button>' +
       '</div>' +
       '<div class="tab-panel" data-tab-panel="overview">' + renderOverviewHtml(cfg) + '</div>' +
       '<div class="tab-panel" data-tab-panel="skills">' + renderSkillsTabHtml(cfg) + '</div>' +
       '<div class="tab-panel" data-tab-panel="tools">' + renderToolsTabHtml(cfg) + '</div>' +
-      '<div class="tab-panel" data-tab-panel="actauth">' + renderActauthTabPlaceholder() + '</div>';
+      '<div class="tab-panel" data-tab-panel="actauth">' + renderActauthTabPlaceholder() + '</div>' +
+      '<div class="tab-panel" data-tab-panel="env">' + renderEnvTabPlaceholder() + '</div>';
 
     var buttons = detail.querySelectorAll('.tabs button');
     for (var i = 0; i < buttons.length; i++) {
@@ -2191,6 +2287,7 @@ export const agentsConfigPageHtml = `<!doctype html>
     currentName = name;
     gatewayLoadedFor = null;
     actauthLoadedFor = null;
+    envLoadedFor = null;
     var items = agentList.querySelectorAll('li');
     for (var i = 0; i < items.length; i++) {
       items[i].classList.toggle('active', items[i].dataset.name === name);

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

@@ -0,0 +1,26 @@
+export declare class EnvVarNameError extends Error {
+}
+export interface DeclaredEnvVar {
+    name: string;
+    description?: string;
+    secret: boolean;
+    packageName: 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
+ * 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. */
+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
+ * (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. */
+export declare function setEnvVar(name: string, value: string): void;

package/dist/web/env-admin.js

@@ -0,0 +1,97 @@
+// 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
+// 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.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentDir } from '../core/gateway-tools.js';
+export class EnvVarNameError extends Error {
+}
+// Same shape web/http-tool-admin.ts's own ENV_VAR_PATTERN already
+// 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');
+}
+/** 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
+ * 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. */
+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 = [];
+    for (const [packageName, record] of Object.entries(provenance)) {
+        for (const decl of record.env) {
+            if (seen.has(decl.name))
+                continue;
+            seen.add(decl.name);
+            result.push({
+                name: decl.name,
+                description: decl.description,
+                secret: decl.secret === true,
+                packageName,
+                set: process.env[decl.name] !== undefined,
+            });
+        }
+    }
+    return result;
+}
+// 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
+// cwd too) — not core/agent-registry.ts's projectDir(), which resolves
+// relative to *that compiled file's own location* and would point at
+// node_modules/loopengine/dist/ in a real scaffolded project, not the
+// project's own root where .env actually lives.
+function envFilePath() {
+    return join(process.cwd(), '.env');
+}
+// Node's own --env-file parser (what bin/cli.ts's runTsx already passes
+// as --env-file-if-exists=.env) double-quotes a value containing
+// whitespace, '#', or a quote character — matched here so a value this
+// function writes reads back identically, not reinterpreted as a
+// comment or truncated at the first space.
+function serializeEnvValue(value) {
+    if (!/[\s#"'\\]/.test(value) && value !== '')
+        return value;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** 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
+ * (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. */
+export function setEnvVar(name, value) {
+    if (!ENV_VAR_NAME_PATTERN.test(name)) {
+        throw new EnvVarNameError(`"${name}" isn't a valid env var name (uppercase letters, digits, underscore, not starting with a digit).`);
+    }
+    const path = envFilePath();
+    const lines = existsSync(path) ? readFileSync(path, 'utf8').split('\n') : [];
+    const newLine = `${name}=${serializeEnvValue(value)}`;
+    const existingIndex = lines.findIndex((line) => line.startsWith(`${name}=`));
+    if (existingIndex === -1) {
+        // Drop a single trailing blank line (from the file's own final
+        // newline splitting into an empty last element) before appending,
+        // so this doesn't accumulate a growing gap of blank lines across
+        // repeated calls.
+        if (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+        lines.push(newLine);
+    }
+    else {
+        lines[existingIndex] = newLine;
+    }
+    writeFileSync(path, lines.join('\n') + '\n');
+    process.env[name] = value;
+}

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

@@ -36,6 +36,8 @@ export interface HttpToolSpec {
      * based on HTTP verb alone. */
     safe?: boolean;
 }
+export declare function toCamelCase(snakeCase: string): string;
+export declare function addToolToIndex(toolsIndexPath: string, toolFileName: string, exportName: 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

@@ -48,7 +48,7 @@ function tsStringLiteral(value) {
 // "lookup_order_status" -> "lookupOrderStatus" — matches every
 // hand-written tool file's own convention (see agents/customer-service/
 // tools/*.ts: issue_refund.ts exports `issueRefund`, etc.).
-function toCamelCase(snakeCase) {
+export function toCamelCase(snakeCase) {
     return snakeCase.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
 }
 // Escapes a literal segment for safe interpolation inside a generated
@@ -185,7 +185,7 @@ ${responseHandling}  },
 // 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.
-function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
+export function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
     const source = readFileSync(toolsIndexPath, 'utf8');
     const arrayMatch = source.match(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/);
     if (!arrayMatch) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -23,6 +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/core/run-agent.js",
     "dist/core/run-agent.d.ts",
     "dist/core/loop-events.js",
@@ -83,6 +85,7 @@
     "ioredis": "^6.0.0",
     "mcpplug": "^0.0.1",
     "openai": "^7.4.0",
+    "semver": "^7.8.5",
     "sessionknit": "^0.0.2",
     "skillgarden": "^0.0.9",
     "toollane": "^0.0.1",
@@ -91,6 +94,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
+    "@types/semver": "^7.8.0",
     "tsx": "^4.19.0",
     "vitest": "^2.1.9"
   }