@oddessentials/agent-guild 0.1.1 → 0.3.0

package/src/manager/providers.mjs

@@ -11,8 +11,9 @@ import { EventEmitter } from 'node:events';
 import { fileURLToPath } from 'node:url';
 import { resolveCommand, resolveAllCommands, pathKey, buildSpawnSpec, runSpec } from './command-resolver.mjs';
 import { compareVersions, probeVersion, fetchManifest, latestVersion, DEFAULT_NPM_REGISTRY } from './versions.mjs';
-import { CHANNEL_LABELS, classifyInstall, formatCommand, helpDescribes, knownLaunchers, listInstallations, platformDependency } from './install-channels.mjs';
+import { CHANNEL_LABELS, classifyInstall, expandHome, formatCommand, helpDescribes, knownLaunchers, listInstallations, platformDependency } from './install-channels.mjs';
 import { weavePaths } from './shell-env.mjs';
+import { paths } from './config.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const DEFAULTS_FILE = path.resolve(here, '../../config/providers.default.json');
@@ -86,6 +87,50 @@ function normalizeChannels(raw) {
   return out;
 }
 
+function normalizeHooks(raw) {
+  if (!raw || typeof raw !== 'object' || typeof raw.path !== 'string' || typeof raw.example !== 'string') return null;
+  const parts = raw.path.split(/[\\/]+/);
+  if (parts.some((part) => part === '' || part === '.' || part === '..') || !/^[A-Za-z0-9._-]+$/.test(raw.example)) return null;
+  return { path: parts.join('/'), example: raw.example };
+}
+
+const DEFAULT_ACCOUNT = 'default';
+
+function normalizeAccounts(raw, id, homeVar, warnings) {
+  const accounts = [{ id: DEFAULT_ACCOUNT, label: 'Default', dir: null }];
+  if (raw === undefined || raw === null) return accounts;
+  if (!Array.isArray(raw)) {
+    warnings.push(`provider "${id}": ignored accounts; it must be an array`);
+    return accounts;
+  }
+  if (!homeVar && raw.length > 0) {
+    warnings.push(`provider "${id}": ignored accounts; the provider has no homeVar`);
+    return accounts;
+  }
+  for (const entry of raw) {
+    const item = typeof entry === 'string' ? { id: entry } : entry;
+    const accountId = item && typeof item === 'object' ? String(item.id ?? '') : '';
+    if (!ID_RE.test(accountId)) {
+      warnings.push(`provider "${id}": skipped account with invalid id ${JSON.stringify(item?.id ?? entry)}`);
+      continue;
+    }
+    const label = typeof item.label === 'string' && item.label.trim() ? item.label.trim().slice(0, 40) : accountId.charAt(0).toUpperCase() + accountId.slice(1);
+    const dir = typeof item.dir === 'string' && item.dir.trim() ? item.dir.trim() : null;
+    const existing = accounts.find((a) => a.id === accountId);
+    if (existing) {
+      if (accountId !== DEFAULT_ACCOUNT) {
+        warnings.push(`provider "${id}": skipped duplicate account "${accountId}"`);
+        continue;
+      }
+      existing.label = label;
+      if (dir) warnings.push(`provider "${id}": ignored dir of the default account; it uses the tool's own home folder`);
+      continue;
+    }
+    accounts.push({ id: accountId, label, dir });
+  }
+  return accounts;
+}
+
 function httpsUrl(value, field, id, warnings) {
   if (value === undefined || value === null || value === '') return null;
   try {
@@ -99,6 +144,7 @@ function httpsUrl(value, field, id, warnings) {
 function normalize(raw, platform, warnings) {
   const merged = { ...raw, ...(raw[platform] || {}) };
   for (const key of PLATFORM_KEYS) delete merged[key];
+  const homeVar = typeof merged.homeVar === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(merged.homeVar) ? merged.homeVar : null;
   return {
     id: merged.id,
     vendor: String(merged.vendor || merged.id),
@@ -111,6 +157,10 @@ function normalize(raw, platform, warnings) {
     args: Array.isArray(merged.args) ? merged.args.map(String) : [],
     resumeArgs: Array.isArray(merged.resumeArgs) ? merged.resumeArgs.map(String) : [],
     env: normalizeEnv(merged.env),
+    homeVar,
+    accountEnv: normalizeEnv(merged.accountEnv),
+    hooks: normalizeHooks(merged.hooks),
+    accounts: normalizeAccounts(merged.accounts, merged.id, homeVar, warnings),
     color: String(merged.color || '#64748B'),
     monogram: String(merged.monogram || String(merged.vendor || merged.id).charAt(0)).slice(0, 2),
     icon: merged.icon ? String(merged.icon) : null,
@@ -172,10 +222,12 @@ export class ProviderRegistry extends EventEmitter {
    * @param {string} [opts.registryUrl]   npm registry for lookups and installs; default: npm's own configuration
    * @param {boolean} [opts.checkUpdates] false skips registry lookups entirely
    * @param {Function} [opts.fetchImpl]
+   * @param {string} [opts.accountsDir]  where accounts without a dir get their home folders
    */
-  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null } = {}) {
+  constructor({ userFile, env, platform = process.platform, iconDir, registryUrl = null, checkUpdates = true, fetchImpl, pathReader = null, accountsDir = paths.accounts } = {}) {
     super();
     this.userFile = userFile;
+    this.accountsDir = accountsDir;
     this.env = env || process.env;
     this.platform = platform;
     this.iconDir = iconDir;
@@ -184,6 +236,7 @@ export class ProviderRegistry extends EventEmitter {
     this.fetchImpl = fetchImpl;
     this.pathReader = pathReader;
     this._pathReadAt = 0;
+    this._pathPending = null;
     this._installs = new Map();
     this.versions = new Map();
     this._refreshing = null;
@@ -209,6 +262,8 @@ export class ProviderRegistry extends EventEmitter {
   npmRegistryUrl() {
     if (this.registryUrl) return Promise.resolve(this.registryUrl);
     this._npmRegistry ??= (async () => {
+      // PATH discovery in flight may change which npm is found; wait for it.
+      await this._pathPending;
       const npm = this.resolveNpm();
       if (!npm) return DEFAULT_NPM_REGISTRY;
       try {
@@ -236,11 +291,18 @@ export class ProviderRegistry extends EventEmitter {
     return pending;
   }
 
-  async refreshPath({ force = false } = {}) {
-    if (!this.pathReader) return false;
+  /** Resolves to true when the PATH changed. A concurrent caller waits for the read already in flight. */
+  refreshPath({ force = false } = {}) {
+    if (!this.pathReader) return Promise.resolve(false);
     const now = Date.now();
-    if (!force && now - this._pathReadAt < PATH_REFRESH_MS) return false;
+    if (!force && now - this._pathReadAt < PATH_REFRESH_MS) return this._pathPending ?? Promise.resolve(false);
     this._pathReadAt = now;
+    const pending = this._readPath().finally(() => { if (this._pathPending === pending) this._pathPending = null; });
+    this._pathPending = pending;
+    return pending;
+  }
+
+  async _readPath() {
     const discovered = await Promise.resolve().then(() => this.pathReader()).catch(() => null);
     if (!discovered) return false;
     const key = pathKey(this.env, this.platform);
@@ -462,6 +524,27 @@ export class ProviderRegistry extends EventEmitter {
     return this.providers.find((p) => p.id === id) || null;
   }
 
+  accountFor(provider, account) {
+    if (account.id === DEFAULT_ACCOUNT || !provider.homeVar) return { id: account.id, label: account.label, dir: null, env: {} };
+    const p = this.platform === 'win32' ? path.win32 : path.posix;
+    const own = account.dir ? expandHome(account.dir, this.env, this.platform) : null;
+    const dir = own && p.isAbsolute(own) ? p.normalize(own) : p.join(this.accountsDir, provider.id, own || account.id);
+    const env = { [provider.homeVar]: dir };
+    for (const [key, value] of Object.entries(provider.accountEnv)) env[key] = value.replaceAll('{dir}', dir);
+    return { id: account.id, label: account.label, dir, env };
+  }
+
+  accountsFor(provider) {
+    return provider.accounts.map((account) => this.accountFor(provider, account));
+  }
+
+  account(provider, id = null) {
+    const wanted = id === null || id === undefined || id === '' ? DEFAULT_ACCOUNT : String(id);
+    const found = provider.accounts.find((a) => a.id === wanted);
+    if (!found) throw refusal(404, 'unknown_account', `${provider.tool} has no account "${wanted}"`);
+    return this.accountFor(provider, found);
+  }
+
   commandFor(provider) {
     return provider.command === '@shell' ? defaultShell(this.env, this.platform) : provider.command;
   }
@@ -529,6 +612,7 @@ export class ProviderRegistry extends EventEmitter {
       warnings: this.installWarnings(provider, installs),
       npmNote: provider.npmNote,
       usageSource: provider.usage === null ? null : typeof provider.usage === 'string' ? provider.usage : 'command',
+      accounts: provider.accounts.map(({ id, label }) => ({ id, label })),
       modelPattern: provider.modelPattern,
       color: provider.color,
       monogram: provider.monogram,

package/src/manager/self-update.mjs

@@ -0,0 +1,205 @@
+// The manager's own version against the npm registry, and the npm session
+// that upgrades it. The running process keeps its code after an upgrade:
+// the new version is used once the manager is restarted.
+
+import fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { compareVersions, fetchManifest } from './versions.mjs';
+import { formatCommand } from './install-channels.mjs';
+import { buildSpawnSpec } from './command-resolver.mjs';
+
+const CHECK_TTL_MS = 60 * 60 * 1000;
+const FAILED_CHECK_TTL_MS = 5 * 60 * 1000;
+
+/** Shown as the provider of the upgrade session. */
+export const SELF_PROVIDER = Object.freeze({
+  id: 'agent-guild',
+  vendor: 'Agent Guild',
+  tool: 'Agent Guild',
+  color: '#5B5BD6',
+  monogram: 'AG',
+  iconUrl: null,
+  modelPattern: null,
+  env: {},
+});
+
+/** True for a build that is not a published release, such as a git checkout. */
+export function isDevelopmentBuild(version) {
+  return !version || /^0\.0\.0(?:-|$)/.test(String(version));
+}
+
+function refusal(status, code, message) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+export class SelfUpdate extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.pkg            the manager's npm package name
+   * @param {string} opts.version        the running version
+   * @param {string|null} [opts.packageFile]  the package.json the manager runs from; read again after an install
+   * @param {import('./providers.mjs').ProviderRegistry} opts.registry  for the registry URL, npm, and fetch
+   */
+  constructor({ pkg, version, packageFile = null, registry }) {
+    super();
+    this.pkg = pkg;
+    this.version = version;
+    this.packageFile = packageFile;
+    this.registry = registry;
+    this.latest = null;
+    this.error = null;
+    this.checkedAt = 0;
+    this.lastInstall = null;
+    /** True from the start of an upgrade session until its npm process has exited. */
+    this.installing = false;
+    /** The on-disk version a failed upgrade left behind, not to be trusted until an upgrade completes. */
+    this.suspectVersion = null;
+    this._refreshing = null;
+  }
+
+  /** Ask the registry for the latest release, hourly unless `force`. Emits "updated" on a change. */
+  refresh({ force = false } = {}) {
+    const run = () => this._refresh(force);
+    const pending = this._refreshing ? this._refreshing.then(run, run) : run();
+    this._refreshing = pending;
+    pending.finally(() => { if (this._refreshing === pending) this._refreshing = null; }).catch(() => {});
+    return pending;
+  }
+
+  async _refresh(force) {
+    if (!this.registry.checkUpdates || isDevelopmentBuild(this.version)) return;
+    const now = Date.now();
+    const ttl = this.error ? FAILED_CHECK_TTL_MS : CHECK_TTL_MS;
+    if (!force && now - this.checkedAt < ttl) return;
+    this.checkedAt = now;
+    const registryUrl = await this.registry.npmRegistryUrl();
+    const { manifest, error } = await fetchManifest(this.pkg, 'latest', { registryUrl, fetchImpl: this.registry.fetchImpl });
+    // A failed check keeps the release already known; it is still published.
+    const latest = manifest?.version ?? this.latest;
+    const changed = latest !== this.latest || error !== this.error;
+    this.latest = latest;
+    this.error = error;
+    if (changed) this.emit('updated');
+  }
+
+  /** Forget an upgrade's outcome once a newer release or a different install supersedes it. */
+  _pruneLastInstall(installed) {
+    const last = this.lastInstall;
+    if (last && (last.version !== this.latest || last.installedVersion !== installed)) this.lastInstall = null;
+  }
+
+  /** The version of the package files on disk, or null when unreadable (for example mid-install). */
+  installedVersion() {
+    if (!this.packageFile) return null;
+    try {
+      const version = JSON.parse(fs.readFileSync(this.packageFile, 'utf8')).version;
+      return typeof version === 'string' ? version : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * True while the files on disk are what an upgrade that did not finish
+   * left behind: npm may have replaced package.json before it was stopped.
+   * Kept apart from `lastInstall`, which a newer release supersedes; the
+   * files stay suspect until an upgrade completes or they change again.
+   */
+  _diskSuspect(installed) {
+    return this.suspectVersion !== null && installed === this.suspectVersion;
+  }
+
+  /** A version installed on disk that the running manager does not use yet, or null. */
+  pendingVersion(installed = this.installedVersion()) {
+    if (this._diskSuspect(installed)) return null;
+    return installed && installed !== this.version && compareVersions(installed, this.version) > 0 ? installed : null;
+  }
+
+  /** True when the latest release is newer than the running manager and not yet, or not reliably, on disk. */
+  available(installed = this.installedVersion()) {
+    if (!this.latest || compareVersions(this.latest, this.version) <= 0) return false;
+    return this._diskSuspect(installed) || compareVersions(this.latest, installed || this.version) > 0;
+  }
+
+  args() {
+    return this.registry.npmArgs({ args: ['install', '-g'], package: this.pkg }, this.latest);
+  }
+
+  /** The npm command that performs the upgrade, or null without npm on PATH or a known release. */
+  command() {
+    const npm = this.registry.resolveNpm();
+    return npm && this.latest ? formatCommand(npm, this.args()) : null;
+  }
+
+  /** Public description, sent in `/info`, `hello` and `manager.upgrade`. */
+  describe() {
+    // While npm runs, the files on disk are in flux: package.json may already
+    // be new while dependencies are still being written, so nothing is
+    // offered or announced until the process has exited.
+    if (this.installing) {
+      return {
+        version: this.version, latestVersion: this.latest, available: false, command: null, guidance: null,
+        pendingVersion: null, installing: true, lastInstall: null,
+      };
+    }
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    const available = this.available(installed);
+    const command = available ? this.command() : null;
+    return {
+      version: this.version,
+      latestVersion: this.latest,
+      available,
+      command,
+      guidance: available && !command ? `npm was not found on PATH. Install Node.js from https://nodejs.org, then run: npm install -g ${this.pkg}@${this.latest}` : null,
+      pendingVersion: this.pendingVersion(installed),
+      installing: false,
+      lastInstall: this.lastInstall,
+    };
+  }
+
+  /** Spawn spec for the upgrade session and the version it installs, or throws with a user-facing message. */
+  async spec() {
+    if (this.installing) throw refusal(409, 'upgrade_in_progress', 'Agent Guild is already being upgraded');
+    if (isDevelopmentBuild(this.version)) {
+      throw refusal(400, 'not_updatable', `This is a development build of Agent Guild (${this.version}); it is not upgraded from the registry.`);
+    }
+    if (!this.registry.checkUpdates) {
+      throw refusal(400, 'not_updatable', 'Version checks are off (AGENT_GUILD_NO_UPDATE_CHECK), so Agent Guild cannot upgrade itself.');
+    }
+    await this.refresh();
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    if (!this.available(installed)) {
+      throw refusal(400, 'not_updatable', this.latest
+        ? `Agent Guild ${this.latest} is the latest release${this.pendingVersion(installed) ? ' and is installed; restart the manager to use it' : ''}.`
+        : `Could not read the latest Agent Guild release${this.error ? `: ${this.error}` : ''}. Nothing was changed.`);
+    }
+    const npm = this.registry.resolveNpm();
+    if (!npm) {
+      throw refusal(409, 'npm_unavailable', 'npm was not found on PATH. Install Node.js from https://nodejs.org and restart the session manager.');
+    }
+    // buildSpawnSpec wraps npm.cmd in cmd.exe on Windows, which a PTY needs.
+    return { spec: buildSpawnSpec(npm, this.args(), this.registry.env, this.registry.platform), version: this.latest };
+  }
+
+  /** An upgrade session started; hold the lock until finishInstall. Emits "updated". */
+  beginInstall() {
+    this.installing = true;
+    this.emit('updated');
+  }
+
+  /** Record how the upgrade session ended, once its process has exited. The files on disk say whether the running copy was replaced. */
+  finishInstall({ exitCode = null, version = this.latest } = {}) {
+    this.installing = false;
+    const installed = this.installedVersion();
+    let outcome;
+    if (exitCode !== 0) outcome = 'failed';
+    else if (installed && version && compareVersions(installed, version) >= 0) outcome = 'installed';
+    else outcome = 'unchanged';
+    if (outcome === 'failed') this.suspectVersion = installed;
+    else if (outcome === 'installed') this.suspectVersion = null;
+    this.lastInstall = { outcome, exitCode, version, installedVersion: installed, at: Date.now() };
+    this.emit('updated');
+  }
+}

package/src/manager/server.mjs

@@ -100,14 +100,17 @@ export function createManagerServer({
   manager,
   registry,
   usage,
+  modelStats,
   token,
   host = '127.0.0.1',
   port = 0,
   webDir,
   version = '0.0.0',
+  selfUpdate = null,
   extraOrigins = [],
   onShutdownRequest = () => {},
 }) {
+  const upgradeInfo = () => (selfUpdate ? selfUpdate.describe() : null);
   const startedAt = new Date().toISOString();
   const vendor = vendorFiles();
   let boundPort = port;
@@ -197,6 +200,7 @@ export function createManagerServer({
     requireAuth(req, url);
 
     if (route === '/info' && method === 'GET') {
+      selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {
         name: 'agent-guild',
         version,
@@ -204,8 +208,13 @@ export function createManagerServer({
         platform: process.platform,
         startedAt,
         warnings: registry.warnings,
+        upgrade: upgradeInfo(),
       });
     }
+    if (route === '/upgrade' && method === 'POST') {
+      const session = await manager.upgrade();
+      return sendJson(res, 201, { session: session.toJSON() });
+    }
     if (route === '/providers' && method === 'GET') {
       registry.refreshVersions().catch(() => {});
       return sendJson(res, 200, { providers: registry.list() });
@@ -218,6 +227,9 @@ export function createManagerServer({
     if (route === '/usage' && method === 'GET') {
       return sendJson(res, 200, { usage: await usage.all() });
     }
+    if (route === '/model-stats' && method === 'GET') {
+      return sendJson(res, 200, await modelStats.snapshot(manager.list()));
+    }
     const installMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/install$/);
     if (installMatch && method === 'POST') {
       const body = await readJsonBody(req);
@@ -329,10 +341,11 @@ export function createManagerServer({
   }
   manager.on('event', broadcast);
   registry.on('updated', () => broadcast({ type: 'providers.updated', providers: registry.list() }));
+  selfUpdate?.on('updated', () => broadcast({ type: 'manager.upgrade', upgrade: upgradeInfo() }));
 
   function handleEvents(ws) {
     eventClients.add(ws);
-    safeSend(ws, { type: 'hello', version, sessions: manager.list() });
+    safeSend(ws, { type: 'hello', version, upgrade: upgradeInfo(), sessions: manager.list() });
     ws.on('close', () => eventClients.delete(ws));
     ws.on('message', () => { /* events socket is server -> client only */ });
   }

package/src/manager/session-manager.mjs

@@ -6,11 +6,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { Session, newId, clampDimension } from './session.mjs';
+import { fileURLToPath } from 'node:url';
+import { Session, newId, clampDimension, cleanName } from './session.mjs';
 import { prependPath } from './report-shims.mjs';
 import { CHANNEL_LABELS } from './install-channels.mjs';
+import { SELF_PROVIDER } from './self-update.mjs';
 
 export const MAX_SESSIONS = 32;
+const examplesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../examples');
 
 function httpError(status, message, code) {
   return Object.assign(new Error(message), { status, code });
@@ -46,14 +49,16 @@ export class SessionManager extends EventEmitter {
    * @param {() => string} opts.getApiUrl  base URL handed to tools for reporting
    * @param {object} [opts.sessionDefaults] passed through to Session
    * @param {string|null} [opts.shimDir]  folder with the agent-guild-report launchers, put first on PATH
+   * @param {import('./self-update.mjs').SelfUpdate|null} [opts.selfUpdate]  the manager's own upgrade
    */
-  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null }) {
+  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null }) {
     super();
     this.registry = registry;
     this.baseEnv = baseEnv;
     this.getApiUrl = getApiUrl;
     this.sessionDefaults = sessionDefaults;
     this.shimDir = shimDir;
+    this.selfUpdate = selfUpdate;
     this.sessions = new Map();
     /** Removed sessions whose process has not exited yet. */
     this.exiting = new Set();
@@ -83,21 +88,44 @@ export class SessionManager extends EventEmitter {
     return dir;
   }
 
-  create({ providerId, cwd, cols, rows, name, args, resume } = {}) {
+  create({ providerId, cwd, cols, rows, name, args, resume, account } = {}) {
     const provider = this.registry.get(String(providerId || ''));
     if (!provider) throw httpError(404, `unknown provider "${providerId}"`, 'unknown_provider');
     if (args !== undefined && (!Array.isArray(args) || args.some((a) => typeof a !== 'string'))) {
       throw httpError(400, 'args must be an array of strings', 'bad_args');
     }
+    if (account !== undefined && account !== null && typeof account !== 'string') throw httpError(400, 'account must be a string', 'bad_account');
     const resumeId = cleanResumeId(resume);
     const workDir = this.resolveCwd(cwd);
+    const signIn = this.registry.account(provider, account);
     const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId);
-    const session = this._spawn({ provider, spawnSpec, cwd: workDir, cols, rows, name, resume: resumeId });
+    this.prepareAccount(provider, signIn);
+    const sessionName = cleanName(name) || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null);
+    const session = this._spawn({ provider, spawnSpec, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn });
     const model = modelFromArgs([...provider.args, ...(args || [])]);
     if (model) session.setModel({ name: model }, 'args');
     return session;
   }
 
+  prepareAccount(provider, account) {
+    if (!account.dir) return;
+    try {
+      fs.mkdirSync(account.dir, { recursive: true, mode: 0o700 });
+      if (!provider.hooks) return;
+      const target = path.join(account.dir, ...provider.hooks.path.split('/'));
+      const example = path.join(examplesDir, provider.hooks.example);
+      if (fs.existsSync(target)) return;
+      if (!fs.existsSync(example)) {
+        console.warn(`[accounts] no hooks example ${example} for ${provider.tool}; ${target} was not written`);
+        return;
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+      fs.copyFileSync(example, target, fs.constants.COPYFILE_EXCL);
+    } catch (err) {
+      throw httpError(500, `could not prepare the ${account.label} account folder ${account.dir}: ${err.message}`, 'account_unavailable');
+    }
+  }
+
   /**
    * Refuses while sessions of that provider are running unless `force` is
    * set, because replacing a tool under a running process can break it.
@@ -140,6 +168,29 @@ export class SessionManager extends EventEmitter {
     return n;
   }
 
+  /**
+   * Upgrade the manager itself: a visible session running npm. Sessions
+   * keep running; the new version is used once the manager is restarted.
+   */
+  async upgrade() {
+    if (!this.selfUpdate) throw httpError(400, 'this manager cannot upgrade itself', 'not_updatable');
+    if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
+    const inProgress = () => httpError(409, 'Agent Guild is already being upgraded', 'upgrade_in_progress');
+    if (this.selfUpdate.installing) throw inProgress();
+    const { spec, version } = await this.selfUpdate.spec();
+    if (this.selfUpdate.installing) throw inProgress();
+    const session = this._spawn({
+      provider: SELF_PROVIDER, description: SELF_PROVIDER, spawnSpec: spec,
+      cwd: os.homedir(), name: `Upgrade Agent Guild to ${version}`, task: 'upgrade',
+    });
+    // The lock is held until the npm process has exited, not until the
+    // session is removed: a removed session's process may still be writing
+    // the package, and two installers must not touch it at once.
+    this.selfUpdate.beginInstall();
+    session.exited.then(() => this.selfUpdate.finishInstall({ exitCode: session.exitCode, version }));
+    return session;
+  }
+
   runningFor(providerId) {
     let n = 0;
     for (const s of this.sessions.values()) if (s.status === 'running' && s.task === null && s.provider.id === providerId) n++;
@@ -153,18 +204,17 @@ export class SessionManager extends EventEmitter {
     return n;
   }
 
-  _spawn({ provider, spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null }) {
+  _spawn({ provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, account = null }) {
     if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
     if (this.sessions.size >= MAX_SESSIONS) {
       throw httpError(429, `session limit reached (${MAX_SESSIONS}); remove finished sessions first`, 'too_many_sessions');
     }
-    const description = this.registry.describe(provider);
     const id = newId();
     const reportToken = crypto.randomBytes(16).toString('hex');
 
     // The tool's hooks run `agent-guild-report` by name, so the launchers
     // go first on PATH, after any provider PATH override.
-    const env = prependPath(mergeEnv([this.baseEnv, provider.env, {
+    const env = prependPath(mergeEnv([this.baseEnv, provider.env, account?.env, {
       TERM: 'xterm-256color',
       COLORTERM: 'truecolor',
       AGENT_GUILD_SESSION_ID: id,
@@ -194,6 +244,7 @@ export class SessionManager extends EventEmitter {
         reportToken,
         resume,
         task,
+        account: account ? { id: account.id, label: account.label } : null,
       });
     } catch (err) {
       throw httpError(500, `could not start ${provider.tool}: ${err.message}`, 'spawn_failed');

package/src/manager/session.mjs

@@ -54,7 +54,8 @@ export class Session extends EventEmitter {
    * @param {number} opts.rows
    * @param {string} [opts.name]
    * @param {string|null} [opts.resume]  id of the tool's own session being resumed
-   * @param {string|null} [opts.task]    "install" for a package install, else null
+   * @param {string|null} [opts.task]    "install" for a package install, "upgrade" for the manager's own, else null
+   * @param {{id: string, label: string}|null} [opts.account]  the tool sign-in the session runs under
    * @param {string} opts.reportToken
    * @param {number} [opts.scrollback]
    * @param {number} [opts.activityIdleMs]
@@ -68,6 +69,7 @@ export class Session extends EventEmitter {
     this.name = cleanName(opts.name) || opts.provider.tool;
     this.resume = opts.resume ?? null;
     this.task = opts.task ?? null;
+    this.account = opts.account ?? null;
     this.cwd = opts.cwd;
     this.cols = opts.cols;
     this.rows = opts.rows;
@@ -505,6 +507,7 @@ export class Session extends EventEmitter {
       cwd: this.cwd,
       resume: this.resume,
       task: this.task,
+      account: this.account,
       pid: this.pid,
       status: this.status,
       exitCode: this.exitCode,