loopengine 0.1.74 → 0.1.76

package/dist/core/discover-agents.d.ts

@@ -5,26 +5,6 @@ export interface AgentModule {
     /** Factory, not a shared instance — a fresh ModelCall per request/session. */
     createModelCall: () => ModelCall;
 }
-/** Builds a lazy, memoized createModelCall from AgentConfig.model, for a
- * module that doesn't export its own — see that field's own doc comment.
- * The provider's SDK module is imported here, eagerly, but that's cheap
- * and safe with no API key at all: importing model-calls/*.ts only
- * defines functions, it never constructs a client at module top level
- * (see e.g. createAnthropicModelCall's own body) — so this can't fail
- * discovery the way eagerly building the actual client would. The real
- * client is only built the first time the returned function is actually
- * called, and reused after that, the same "don't crash the whole server
- * over one agent's missing API key, don't rebuild per call" reasoning
- * agents/customer-service/index.ts's own hand-written createModelCall
- * used before this existed.
- *
- * Exported so a caller updating an *already-registered* agent's model
- * (see agent-file-admin.ts's editAgentFile, applied live via
- * core/agent-registry.ts's updateAgent) can rebuild just this one closure
- * without re-importing the whole module — Node's ESM loader caches an
- * already-imported module forever, so there's no supported way to
- * re-import a changed agent file's own createModelCall directly; this is
- * the one piece of it that's meaningfully regenerable on its own. */
 export declare function synthesizeCreateModelCall(model: AgentModelConfig): Promise<() => ModelCall>;
 /** Imports one agent module at `path` and resolves it to an AgentModule —
  * the single-file version of what discoverAgents does over a whole

package/dist/core/discover-agents.js

@@ -37,30 +37,55 @@ function isRawAgentModule(mod) {
  * already-imported module forever, so there's no supported way to
  * re-import a changed agent file's own createModelCall directly; this is
  * the one piece of it that's meaningfully regenerable on its own. */
+// The env var each provider's key defaults to (same names as
+// web/global-config.ts's Models page).
+const PROVIDER_KEY_ENV = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+    kimi: 'MOONSHOT_API_KEY',
+    glm: 'GLM_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+};
 export async function synthesizeCreateModelCall(model) {
-    let cached;
+    let build;
     if (model.provider === 'anthropic') {
         const { createAnthropicModelCall } = await import('./model-calls/anthropic-model-call.js');
-        return () => (cached ??= createAnthropicModelCall(model));
+        build = () => createAnthropicModelCall(model);
     }
-    if (model.provider === 'openai') {
+    else if (model.provider === 'openai') {
         const { createOpenAIModelCall } = await import('./model-calls/openai-model-call.js');
-        return () => (cached ??= createOpenAIModelCall(model));
+        build = () => createOpenAIModelCall(model);
     }
-    if (model.provider === 'deepseek') {
+    else if (model.provider === 'deepseek') {
         const { createDeepSeekModelCall } = await import('./model-calls/deepseek-model-call.js');
-        return () => (cached ??= createDeepSeekModelCall(model));
+        build = () => createDeepSeekModelCall(model);
     }
-    if (model.provider === 'kimi') {
+    else if (model.provider === 'kimi') {
         const { createKimiModelCall } = await import('./model-calls/kimi-model-call.js');
-        return () => (cached ??= createKimiModelCall(model));
+        build = () => createKimiModelCall(model);
     }
-    if (model.provider === 'glm') {
+    else if (model.provider === 'glm') {
         const { createGlmModelCall } = await import('./model-calls/glm-model-call.js');
-        return () => (cached ??= createGlmModelCall(model));
+        build = () => createGlmModelCall(model);
+    }
+    else {
+        const { createGeminiModelCall } = await import('./model-calls/gemini-model-call.js');
+        build = () => createGeminiModelCall(model);
     }
-    const { createGeminiModelCall } = await import('./model-calls/gemini-model-call.js');
-    return () => (cached ??= createGeminiModelCall(model));
+    // Rebuilt when the key it was built with changes, so a key saved or
+    // replaced on the console's Models page applies to the next call
+    // without a restart. An explicit `apiKey` in the config never changes.
+    let cached;
+    let cachedKey;
+    return () => {
+        const key = model.apiKey ?? process.env[PROVIDER_KEY_ENV[model.provider]];
+        if (!cached || key !== cachedKey) {
+            cached = build();
+            cachedKey = key;
+        }
+        return cached;
+    };
 }
 /** Resolves one directory entry to an agent module's path, or undefined if
  * this entry isn't one — a `.ts`/`.js` file directly (the common case), or

package/dist/core/trusted-proxy.d.ts

@@ -4,6 +4,12 @@ export interface ProxyIdentity {
     sub: string;
     workspace?: string;
     role: string;
+    /** The person's email, when the proxy knows it (shown in the console's
+     * sidebar). */
+    email?: string;
+    /** Where the person manages this workspace on the host, shown as the
+     * console's "Dashboard" link. */
+    dashboardUrl?: string;
     /** Expiry, Unix seconds. */
     exp: number;
 }

package/dist/core/version.d.ts

@@ -0,0 +1 @@
+export declare function loopengineVersion(): string;

package/dist/core/version.js

@@ -0,0 +1,24 @@
+// The installed loopengine version, for the console's Settings section.
+// package.json sits one level above core/ in this repo, and two above
+// dist/core/ in the published package (dist/package.json is only the
+// module-resolution stub the build writes, with no version).
+import { existsSync, readFileSync } from 'node:fs';
+let cached;
+export function loopengineVersion() {
+    if (cached)
+        return cached;
+    for (const rel of ['../package.json', '../../package.json']) {
+        const url = new URL(rel, import.meta.url);
+        if (!existsSync(url))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(url, 'utf8'));
+            if (pkg.name === 'loopengine' && pkg.version)
+                return (cached = pkg.version);
+        }
+        catch {
+            // Not loopengine's package.json; try the next.
+        }
+    }
+    return (cached = 'unknown');
+}

package/dist/index.d.ts

@@ -78,6 +78,8 @@ export type { InstalledAbilityRecord, AbilityEnvDecl, UpgradeFileResult } from '
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';
 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

@@ -69,5 +69,7 @@ export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule
 export { installAbility, upgradeAbility, removeAbility, listInstalledAbilities, backfillDependencies, AbilityManifestError, AbilityVersionError, AbilityCollisionError, AbilityAlreadyInstalledError, AbilityNotInstalledError, } from './bin/ability-manager.js';
 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/console-shell.js

@@ -25,6 +25,8 @@ export const consoleSidebarHtml = `<aside class="le-sidebar" aria-label="Console
   <nav class="le-foot" aria-label="Settings">
     <a href="/config?section=models" data-le-nav="models">Models</a>
     <a href="/config?section=gateways" data-le-nav="integrations">Integrations</a>
+    <a href="/config?section=settings" data-le-nav="settings">Settings</a>
+    <div class="le-who" id="leWho" hidden></div>
   </nav>
 </aside>`;
 export const consoleShellScript = `<script>
@@ -156,12 +158,33 @@ export const consoleShellScript = `<script>
     renderList();
   }
 
-  var foot = page === 'config' ? (params.get('section') === 'gateways' ? 'integrations' : 'models') : '';
+  var section = params.get('section');
+  var foot = page === 'config' ? (section === 'gateways' ? 'integrations' : section === 'settings' ? 'settings' : 'models') : '';
   var footLinks = document.querySelectorAll('[data-le-nav]');
   for (var i = 0; i < footLinks.length; i++) {
     if (footLinks[i].getAttribute('data-le-nav') === foot) footLinks[i].setAttribute('aria-current', 'page');
   }
 
+  // Who is signed in: the email and a link back to the dashboard when a
+  // hosting router signs requests, otherwise how this server is protected.
+  var who = document.getElementById('leWho');
+  if (who) {
+    fetch('/config/settings')
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (s) {
+        if (!s || !s.signIn) return;
+        var si = s.signIn;
+        if (si.mode === 'hosted') {
+          who.innerHTML = '<span class="le-who-name" title="' + esc(si.email || '') + '">' + esc(si.email || 'Signed in') + '</span>' +
+            (si.dashboardUrl ? '<a href="' + esc(si.dashboardUrl) + '">Dashboard</a>' : '');
+        } else {
+          who.innerHTML = '<span class="le-who-name">' + (si.mode === 'basic' ? 'Signed in with Basic Auth' : 'No sign-in configured') + '</span>';
+        }
+        who.hidden = false;
+      })
+      .catch(function () {});
+  }
+
   document.addEventListener('click', function (ev) {
     if (!app) return;
     if (ev.target.closest('[data-le-menu]')) { app.classList.toggle('nav-open'); return; }

package/dist/web/dev-ui-styles.js

@@ -130,6 +130,11 @@ export const devUiCss = `
   .le-foot a { padding: 7px 8px; border-radius: 6px; color: var(--ink-muted); text-decoration: none; }
   .le-foot a:hover { background: var(--surface-2); color: var(--ink); }
   .le-foot a[aria-current="page"] { background: var(--accent-soft); color: var(--ink); }
+  .le-who { padding: 10px 8px 4px; font-size: 12px; color: var(--ink-faint); display: flex; justify-content: space-between; align-items: center; gap: 8px; min-width: 0; }
+  .le-who[hidden] { display: none; }
+  .le-who-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+  .le-foot .le-who a { padding: 0; flex: none; color: var(--accent-ink); }
+  .le-foot .le-who a:hover { background: none; text-decoration: underline; }
   .le-main { display: flex; flex-direction: column; min-width: 0; min-height: 0; overflow: hidden; }
   .le-scroll { flex: 1; min-height: 0; overflow-y: auto; }
   .le-page { padding: 24px; max-width: 1100px; display: grid; gap: 24px; }

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

@@ -83,6 +83,11 @@ ${consoleSidebarHtml}
       <div><h1>Integrations</h1><p>Outside tool sources (such as Composio) that agents can add tools from.</p></div></div></div>
     <div class="le-scroll"><div class="le-page" style="display:block"><div id="gatewaysContent"><p class="hint">Loading&hellip;</p></div></div></div>
   </div>
+  <div class="section-panel" data-section-panel="settings" style="display:none">
+    <div class="le-head plain"><div class="le-title"><button type="button" class="le-menu-btn" data-le-menu aria-label="Open navigation">&#9776;</button>
+      <div><h1>Settings</h1><p>How this server is set up. These come from its deployment, not from this page.</p></div></div></div>
+    <div class="le-scroll"><div class="le-page" style="display:block"><div id="settingsContent"><p class="hint">Loading&hellip;</p></div></div></div>
+  </div>
 </main>
 </div>
 ${consoleShellScript}
@@ -277,6 +282,142 @@ ${consoleShellScript}
       });
   }
 
+  // ---- Settings section ----
+
+  function renderSettings(d) {
+    var si = d.signIn || {};
+    var signIn = si.mode === 'hosted'
+      ? 'Managed by your LoopEngine Cloud account' + (si.email ? ' (' + escapeHtml(si.email) + ')' : '') +
+        (si.dashboardUrl ? ' &middot; <a href="' + escapeHtml(si.dashboardUrl) + '">Dashboard</a>' : '')
+      : si.mode === 'basic'
+        ? 'Basic Auth (<code>LOOPENGINE_ADMIN_AUTH</code>)'
+        : '<span class="error">None: anyone who can reach this server can use it. Set <code>LOOPENGINE_ADMIN_AUTH</code>.</span>';
+    var rows = [
+      ['Admin sign-in', signIn],
+      ['LoopEngine version', '<code>' + escapeHtml(d.version) + '</code>'],
+      ['Environment name', '<code>' + escapeHtml(d.environment) + '</code> <span class="hint">(LOOPENGINE_ENV)</span>'],
+      ['Public address', d.publicUrl ? '<code>' + escapeHtml(d.publicUrl) + '</code>' : '<span class="hint">Not set (LOOPENGINE_PUBLIC_URL); links in notifications use the address saved with each notifier</span>'],
+      ['Scheduled tasks', d.scheduler === 'off' ? 'Off on this server (LOOPENGINE_SCHEDULER=off)' : 'Run by this server'],
+      ['Theme', 'Follows your system'],
+    ];
+    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>' +
+      '<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')
+      .then(function (r) { return r.json(); })
+      .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>';
+      });
+  }
+
   // ---- Section switching ----
 
   function switchSection(section) {
@@ -290,6 +431,7 @@ ${consoleShellScript}
     }
     if (section === 'models' && !loadedSections.models) loadModels();
     if (section === 'gateways' && !loadedSections.gateways) loadGateways();
+    if (section === 'settings' && !loadedSections.settings) loadSettings();
   }
 
   for (var i = 0; i < sectionButtons.length; i++) {
@@ -301,7 +443,7 @@ ${consoleShellScript}
   // real section, same "trust the query param only if it's valid"
   // caution playground.ts's own ?agent= handling already uses.
   var requestedSection = new URLSearchParams(location.search).get('section');
-  var initialSection = requestedSection === 'gateways' || requestedSection === 'models' ? requestedSection : currentSection;
+  var initialSection = requestedSection === 'gateways' || requestedSection === 'models' || requestedSection === 'settings' ? requestedSection : currentSection;
   switchSection(initialSection);
 })();
 </script>

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.74",
+  "version": "0.1.76",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -26,6 +26,8 @@
     "dist/bin/ability-manager.js",
     "dist/bin/ability-manager.d.ts",
     "dist/core/run-agent.js",
+    "dist/core/version.js",
+    "dist/core/version.d.ts",
     "dist/core/run-agent.d.ts",
     "dist/core/known-urls.js",
     "dist/core/known-urls.d.ts",