loopengine 0.1.75 → 0.1.76

package/dist/index.d.ts

@@ -79,6 +79,7 @@ export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilitie
 export type { PublicAbilitySearchResult } from './web/abilities-admin.js';
 export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError } from './web/global-config.js';
 export { loopengineVersion } from './core/version.js';
+export { describeUpgrade, runUpgrade, UpgradeError } from './web/upgrade-admin.js';
 export type { ModelProviderInfo, AgentModelUsage, ModelsView, GatewayProviderInfo, GatewaysView } from './web/global-config.js';
 export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
 export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';

package/dist/index.js

@@ -70,5 +70,6 @@ export { installAbility, upgradeAbility, removeAbility, listInstalledAbilities,
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';
 export { describeModelProviders, describeGateways, setModelProviderKey, clearModelProviderKey, ModelKeyError } from './web/global-config.js';
 export { loopengineVersion } from './core/version.js';
+export { describeUpgrade, runUpgrade, UpgradeError } from './web/upgrade-admin.js';
 export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
 export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';

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

@@ -302,9 +302,108 @@ ${consoleShellScript}
     ];
     return '<section><table><thead><tr><th>Setting</th><th>Value</th></tr></thead><tbody>' +
       rows.map(function (r) { return '<tr><td>' + r[0] + '</td><td>' + r[1] + '</td></tr>'; }).join('') +
-      '</tbody></table></section>';
+      '</tbody></table></section>' +
+      '<section><h3>Updates</h3><div class="source" id="upgradeBox"><p class="hint">Checking for a newer LoopEngine' + String.fromCharCode(8230) + '</p></div></section>';
   }
 
+  // ---- Upgrade ----
+
+  var UPGRADE_NOTE = 'Updates this server' + String.fromCharCode(8217) + 's LoopEngine code and restarts it, which takes a minute or two. ' +
+    'Your agents, abilities, conversations, approvals, schedules and settings are kept. ' +
+    'A template file you edited (such as adapters/http.ts) is left exactly as it is.';
+
+  function upgradeBox() { return document.getElementById('upgradeBox'); }
+
+  function renderUpgrade(u) {
+    var box = upgradeBox();
+    if (!box) return;
+    if (u.unavailableReason && !u.updateAvailable) {
+      box.innerHTML = '<p class="hint">' + escapeHtml(u.unavailableReason) + '</p>';
+    } else if (!u.updateAvailable) {
+      box.innerHTML = '<p>You' + String.fromCharCode(8217) + 're on the latest version, <code>' + escapeHtml(u.current) + '</code>.</p>';
+    } else if (u.unavailableReason) {
+      box.innerHTML = '<p>LoopEngine <code>' + escapeHtml(u.latest) + '</code> is available (this server runs <code>' + escapeHtml(u.current) + '</code>).</p><p class="hint">' + escapeHtml(u.unavailableReason) + '</p>';
+    } else if (!u.canUpgrade) {
+      box.innerHTML = '<p>LoopEngine <code>' + escapeHtml(u.latest) + '</code> is available (this server runs <code>' + escapeHtml(u.current) + '</code>).</p><p class="hint">Set LOOPENGINE_ADMIN_AUTH to upgrade from here, or run <code>npx create-loopengine@latest upgrade</code>.</p>';
+    } else {
+      box.innerHTML = '<p>LoopEngine <code>' + escapeHtml(u.latest) + '</code> is available (this server runs <code>' + escapeHtml(u.current) + '</code>).</p>' +
+        '<p class="hint">' + UPGRADE_NOTE + (u.restartsItself ? '' : ' This server has nothing to restart it, so restart it yourself afterwards.') + '</p>' +
+        '<p><button type="button" class="primary" id="upgradeBtn">Upgrade to ' + escapeHtml(u.latest) + '</button></p>' +
+        '<div id="upgradeMsg" class="hint"></div>';
+    }
+  }
+
+  function loadUpgrade() {
+    fetch('/config/upgrade')
+      .then(function (r) { return r.json(); })
+      .then(renderUpgrade)
+      .catch(function (err) {
+        var box = upgradeBox();
+        if (box) box.innerHTML = '<p class="error">Could not check for updates: ' + escapeHtml(err.message) + '</p>';
+      });
+  }
+
+  function upgradeMsg(html, bad) {
+    var el = document.getElementById('upgradeMsg');
+    if (!el) return;
+    el.innerHTML = html;
+    el.className = bad ? 'error' : 'hint';
+  }
+
+  // After a successful upgrade the server restarts: wait for it to answer
+  // again on the new version, then reload so the page runs the new code.
+  function waitForRestart(target, tries) {
+    if (tries > 90) { upgradeMsg('The server hasn' + String.fromCharCode(8217) + 't come back yet. Reload this page in a minute.', true); return; }
+    setTimeout(function () {
+      fetch('/config/settings', { cache: 'no-store' })
+        .then(function (r) { return r.ok ? r.json() : null; })
+        .then(function (s) {
+          if (s && s.version === target) location.reload();
+          else waitForRestart(target, tries + 1);
+        })
+        .catch(function () { waitForRestart(target, tries + 1); });
+    }, 2000);
+  }
+
+  document.getElementById('settingsContent').addEventListener('click', function (ev) {
+    var btn = ev.target.closest('#upgradeBtn');
+    if (!btn) return;
+    if (btn.getAttribute('data-armed') !== '1') {
+      btn.setAttribute('data-armed', '1');
+      btn.textContent = 'Click again to upgrade';
+      return;
+    }
+    btn.disabled = true;
+    btn.textContent = 'Upgrading' + String.fromCharCode(8230);
+    upgradeMsg('Installing the new version. This takes a minute or two; keep this page open.', false);
+    fetch('/config/upgrade', { method: 'POST' })
+      .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, body: j }; }); })
+      .then(function (r) {
+        if (!r.ok) throw new Error(r.body.error || 'upgrade failed');
+        var o = r.body.outcome;
+        var changed = o.files.filter(function (f) { return f.status === 'updated'; }).map(function (f) { return f.file; });
+        var kept = o.files.filter(function (f) { return f.status === 'kept'; }).map(function (f) { return f.file; });
+        var deps = o.dependencies.map(function (d) { return d.name + ' ' + d.from + ' ' + String.fromCharCode(8594) + ' ' + d.to; });
+        var target = (o.dependencies.filter(function (d) { return d.name === 'loopengine'; })[0] || {}).to;
+        var summary = (deps.length ? 'Installed ' + escapeHtml(deps.join(', ')) + '. ' : '') +
+          (changed.length ? 'Updated ' + escapeHtml(changed.join(', ')) + '. ' : '') +
+          (kept.length ? 'Left as you edited them: ' + escapeHtml(kept.join(', ')) + '. ' : '');
+        btn.textContent = 'Upgraded';
+        if (r.body.restarting && target) {
+          upgradeMsg(summary + 'Restarting' + String.fromCharCode(8230), false);
+          waitForRestart(target.replace(/[^0-9.]/g, ''), 0);
+        } else {
+          upgradeMsg(summary + 'Restart the server to finish.', false);
+        }
+      })
+      .catch(function (err) {
+        btn.disabled = false;
+        btn.removeAttribute('data-armed');
+        btn.textContent = 'Try again';
+        upgradeMsg(escapeHtml(err.message) + ' Nothing was changed.', true);
+      });
+  });
+
   function loadSettings() {
     var content = document.getElementById('settingsContent');
     fetch('/config/settings')
@@ -312,6 +411,7 @@ ${consoleShellScript}
       .then(function (d) {
         content.innerHTML = renderSettings(d);
         loadedSections.settings = true;
+        loadUpgrade();
       })
       .catch(function (err) {
         content.innerHTML = '<p class="error">Could not load settings: ' + escapeHtml(err.message) + '</p>';

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

@@ -0,0 +1,43 @@
+export declare class UpgradeError extends Error {
+}
+export interface UpgradeStatus {
+    current: string;
+    /** Latest loopengine on npm; null when npm couldn't be reached. */
+    latest: string | null;
+    updateAvailable: boolean;
+    /** The create-loopengine version this project was scaffolded or last
+     * upgraded from (.create-loopengine.json); null when the project
+     * wasn't made by create-loopengine, which the button can't upgrade. */
+    templateVersion: string | null;
+    /** Why the button is off, when it is. */
+    unavailableReason?: string;
+    running: boolean;
+}
+export interface UpgradeOutcome {
+    fromVersion: string;
+    toVersion: string;
+    files: {
+        file: string;
+        status: string;
+    }[];
+    dependencies: {
+        name: string;
+        from: string;
+        to: string;
+    }[];
+}
+type Runner = (cmd: string, args: string[], cwd: string, timeoutMs: number) => Promise<string>;
+/** Tests replace npm/npx with a fake. */
+export declare function setUpgradeRunner(next: Runner | undefined): void;
+export declare function describeUpgrade(projectDir?: string): Promise<UpgradeStatus>;
+/**
+ * Runs the upgrade. `busy` is checked first: upgrading under a running
+ * chat turn or scheduled run would restart the server mid-reply. Resolves
+ * with what changed; throws UpgradeError (with everything restored) when
+ * it couldn't finish.
+ */
+export declare function runUpgrade(options: {
+    busy: () => boolean;
+    projectDir?: string;
+}): Promise<UpgradeOutcome>;
+export {};

package/dist/web/upgrade-admin.js

@@ -0,0 +1,172 @@
+// Backs the console's Upgrade button (Settings section): updates a
+// create-loopengine project in place to the latest loopengine and
+// template, the same as running `npx create-loopengine@latest upgrade`
+// by hand, then the server restarts itself on the new code.
+//
+// Only template-owned files (adapters/, agent-registry.ts, tsconfig.json,
+// .gitignore) and package.json change. Agents, abilities, conversations
+// (.sessions/), approvals (.checkpoints/), schedules (.scheduler/) and
+// every .env are never touched. A template file the project edited is
+// left exactly as it was (`--keep-edited`), so an unattended upgrade can
+// never leave conflict markers that stop the server from starting. The
+// files it may change are backed up first and restored if it fails.
+import { execFile } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import semver from 'semver';
+import { loopengineVersion } from '../core/version.js';
+/** Everything `create-loopengine upgrade` may rewrite. */
+const UPGRADED_FILES = ['adapters/http.ts', 'adapters/cli.ts', 'agent-registry.ts', 'tsconfig.json', '.gitignore', 'package.json', 'package-lock.json', '.create-loopengine.json'];
+const BACKUP_DIR = '.upgrade-backups';
+const KEEP_BACKUPS = 3;
+export class UpgradeError extends Error {
+}
+function realRun(cmd, args, cwd, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { cwd, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, env: process.env }, (err, stdout, stderr) => {
+            if (err)
+                reject(Object.assign(err, { stdout: String(stdout), stderr: String(stderr) }));
+            else
+                resolve(String(stdout));
+        });
+    });
+}
+let run = realRun;
+/** Tests replace npm/npx with a fake. */
+export function setUpgradeRunner(next) {
+    run = next ?? realRun;
+    latestCache = undefined;
+}
+let latestCache;
+async function latestLoopengine(projectDir) {
+    if (latestCache && latestCache.until > Date.now())
+        return latestCache.value;
+    let value = null;
+    try {
+        value = (await run('npm', ['view', 'loopengine', 'version'], projectDir, 15_000)).trim() || null;
+    }
+    catch {
+        value = null;
+    }
+    latestCache = { value, until: Date.now() + (value ? 10 * 60_000 : 60_000) };
+    return value;
+}
+function templateVersion(projectDir) {
+    const path = join(projectDir, '.create-loopengine.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8')).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+let running = false;
+export async function describeUpgrade(projectDir = process.cwd()) {
+    const current = loopengineVersion();
+    const latest = await latestLoopengine(projectDir);
+    const template = templateVersion(projectDir);
+    const status = {
+        current,
+        latest,
+        updateAvailable: Boolean(latest && semver.valid(current) && semver.gt(latest, current)),
+        templateVersion: template,
+        running,
+    };
+    if (!template)
+        status.unavailableReason = 'This project has no .create-loopengine.json, so it was not made by create-loopengine; upgrade it by hand.';
+    else if (!latest)
+        status.unavailableReason = 'Could not reach npm to check for a newer version.';
+    return status;
+}
+function backup(projectDir) {
+    const dir = join(projectDir, BACKUP_DIR, new Date().toISOString().replace(/[:.]/g, '-'));
+    for (const file of UPGRADED_FILES) {
+        const from = join(projectDir, file);
+        if (!existsSync(from))
+            continue;
+        mkdirSync(dirname(join(dir, file)), { recursive: true });
+        copyFileSync(from, join(dir, file));
+    }
+    // Keep the newest few.
+    const all = readdirSync(join(projectDir, BACKUP_DIR)).filter((name) => name !== 'pending').sort();
+    for (const old of all.slice(0, Math.max(0, all.length - KEEP_BACKUPS)))
+        rmSync(join(projectDir, BACKUP_DIR, old), { recursive: true, force: true });
+    return dir;
+}
+function restore(projectDir, dir) {
+    for (const file of UPGRADED_FILES) {
+        const saved = join(dir, file);
+        if (existsSync(saved))
+            copyFileSync(saved, join(projectDir, file));
+    }
+}
+/**
+ * Runs the upgrade. `busy` is checked first: upgrading under a running
+ * chat turn or scheduled run would restart the server mid-reply. Resolves
+ * with what changed; throws UpgradeError (with everything restored) when
+ * it couldn't finish.
+ */
+export async function runUpgrade(options) {
+    const projectDir = options.projectDir ?? process.cwd();
+    if (running)
+        throw new UpgradeError('An upgrade is already running.');
+    if (options.busy())
+        throw new UpgradeError('An agent is replying or a scheduled task is running; try again when it finishes.');
+    if (!templateVersion(projectDir))
+        throw new UpgradeError('This project was not made by create-loopengine, so it can only be upgraded by hand.');
+    running = true;
+    const saved = backup(projectDir);
+    try {
+        let stdout;
+        try {
+            stdout = await run('npx', ['-y', 'create-loopengine@latest', 'upgrade', '--json', '--keep-edited'], projectDir, 10 * 60_000);
+        }
+        catch (err) {
+            stdout = err.stdout ?? '';
+            if (!stdout.trim())
+                throw new UpgradeError(`The upgrade could not run: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+        }
+        const line = stdout.trim().split('\n').pop() ?? '';
+        let result;
+        try {
+            result = JSON.parse(line);
+        }
+        catch {
+            throw new UpgradeError('The upgrade returned something unexpected; nothing was changed.');
+        }
+        if (result.error)
+            throw new UpgradeError(result.error);
+        if (result.npmInstall && !result.npmInstall.ok)
+            throw new UpgradeError(`Installing the new packages failed: ${result.npmInstall.error ?? 'unknown error'}`);
+        // package.json may already allow the latest version while an older
+        // one stays installed (the lockfile keeps it); install it outright.
+        const latest = await latestLoopengine(projectDir);
+        const current = loopengineVersion();
+        if (latest && semver.valid(current) && semver.gt(latest, current) && !result.dependencies.some((d) => d.name === 'loopengine')) {
+            try {
+                await run('npm', ['install', '--no-audit', '--no-fund', `loopengine@^${latest}`], projectDir, 10 * 60_000);
+            }
+            catch (err) {
+                throw new UpgradeError(`Installing loopengine ${latest} failed: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+            }
+            result.dependencies.push({ name: 'loopengine', from: current, to: `^${latest}` });
+        }
+        // Lets the workspace's start script put the backup back if the new
+        // code can't start (see loopengine-cloud's entrypoint); removed by it
+        // once the new version has stayed up.
+        writeFileSync(join(projectDir, BACKUP_DIR, 'pending'), basename(saved) + '\n');
+        latestCache = undefined;
+        return { fromVersion: result.fromVersion, toVersion: result.toVersion, files: result.files, dependencies: result.dependencies };
+    }
+    catch (err) {
+        restore(projectDir, saved);
+        // package.json is back; put node_modules back in line with it.
+        await run('npm', ['install', '--no-audit', '--no-fund'], projectDir, 10 * 60_000).catch(() => { });
+        throw err instanceof UpgradeError ? err : new UpgradeError(err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        running = false;
+    }
+}

package/package.json

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