@oddessentials/agent-guild 0.2.0 → 0.3.0

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,

package/src/manager/usage.mjs

@@ -19,6 +19,10 @@ const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 
 export class UsageError extends Error {}
 
+function notSignedIn(message) {
+  return Object.assign(new UsageError(message), { notSignedIn: true });
+}
+
 function shortPath(file) {
   const home = os.homedir();
   return file.startsWith(home) ? `~${file.slice(home.length)}` : file;
@@ -112,7 +116,7 @@ export async function readClaudeCredentials({
     try {
       raw = await fs.promises.readFile(file, 'utf8');
     } catch {
-      throw new UsageError(`Claude Code is not signed in on this machine (no ${keychain ? 'keychain item or ' : ''}${shortPath(file)})`);
+      throw notSignedIn(`Claude Code is not signed in on this machine (no ${keychain ? 'keychain item or ' : ''}${shortPath(file)})`);
     }
   }
   let creds;
@@ -195,7 +199,7 @@ export async function readCodexCredentials({ file = codexAuthFile() } = {}) {
   try {
     raw = await fs.promises.readFile(file, 'utf8');
   } catch {
-    throw new UsageError(`Codex CLI is not signed in on this machine (no ${shortPath(file)})`);
+    throw notSignedIn(`Codex CLI is not signed in on this machine (no ${shortPath(file)})`);
   }
   let auth;
   try { auth = JSON.parse(raw); } catch { throw new UsageError('Codex CLI credentials could not be parsed'); }
@@ -260,11 +264,37 @@ export function geminiCredentialsFile(env = process.env) {
   return path.join(env.GEMINI_CLI_HOME || os.homedir(), '.gemini', 'oauth_creds.json');
 }
 
+export function geminiKeychainFile(env = process.env) {
+  return path.join(env.GEMINI_CLI_HOME || os.homedir(), '.gemini', 'gemini-credentials.json');
+}
+
+export function geminiFileKey({ hostname = os.hostname(), username = os.userInfo().username } = {}) {
+  return crypto.scryptSync(GEMINI_KEYCHAIN_SERVICE, `${hostname}-${username}-gemini-cli`, 32);
+}
+
 /**
- * Gemini CLI keeps its OAuth token in the OS keychain (service
- * "gemini-cli-oauth", account "main-account") and, before it did, in
- * oauth_creds.json. Its encrypted-file fallback cannot be read from here.
+ * The item Gemini CLI keeps in its own encrypted file when it does not use
+ * the OS keychain: AES-256-GCM as iv:tag:ciphertext in hex, over a JSON
+ * map of service to account to secret.
  */
+export async function readGeminiFileKeychain(file, { key = geminiFileKey() } = {}) {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const [iv, tag, encrypted] = raw.trim().split(':').map((part) => Buffer.from(part, 'hex'));
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+    decipher.setAuthTag(tag);
+    const json = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+    return JSON.parse(json)?.[GEMINI_KEYCHAIN_SERVICE]?.[GEMINI_KEYCHAIN_ACCOUNT] ?? null;
+  } catch {
+    throw new UsageError(`Gemini CLI credentials file ${shortPath(file)} could not be decrypted`);
+  }
+}
+
 export function geminiKeychainLookup(platform) {
   if (platform === 'darwin') return { file: 'security', args: ['find-generic-password', '-s', GEMINI_KEYCHAIN_SERVICE, '-a', GEMINI_KEYCHAIN_ACCOUNT, '-w'] };
   // keytar stores libsecret items with the attributes "service" and "account".
@@ -272,18 +302,54 @@ export function geminiKeychainLookup(platform) {
   return null;
 }
 
-function readGeminiKeychainItem(platform) {
+/**
+ * What the OS keychain holds for Gemini CLI: the item, or that it is
+ * absent, that there is no keychain to ask (so the tool keeps its own
+ * encrypted file instead), or that it is one this manager cannot read.
+ */
+export async function readGeminiKeychainItem(platform) {
   const spec = geminiKeychainLookup(platform);
-  if (!spec) return Promise.resolve(null);
-  return runSpec(spec, { timeoutMs: 30000 }).then((r) => r.stdout, () => null);
+  if (!spec) return { status: platform === 'win32' ? 'unreadable' : 'unavailable' };
+  try {
+    const { stdout } = await runSpec(spec, { timeoutMs: 30000 });
+    return stdout.trim() ? { status: 'found', item: stdout } : { status: 'absent' };
+  } catch (err) {
+    // security exits 44 for a missing item; secret-tool exits 1 for one and
+    // says why on stderr when it has no Secret Service at all.
+    if (platform === 'darwin' && err.code === 44) return { status: 'absent' };
+    if (platform === 'linux' && err.code === 1 && !String(err.stderr || '').trim()) return { status: 'absent' };
+    return { status: 'unavailable' };
+  }
 }
 
+/** Gemini CLI's own storage choice, read from the environment the tool runs with. */
+export function geminiStorageMode(env = process.env) {
+  return { encrypted: env.GEMINI_FORCE_ENCRYPTED_FILE_STORAGE === 'true', fileStorage: env.GEMINI_FORCE_FILE_STORAGE === 'true' };
+}
+
+/**
+ * Reads the sign-in from where Gemini CLI keeps it: oauth_creds.json, or
+ * with GEMINI_FORCE_ENCRYPTED_FILE_STORAGE the OS keychain item, or its
+ * encrypted file when GEMINI_FORCE_FILE_STORAGE is set or there is no
+ * keychain. An absent item falls back to oauth_creds.json, as the tool
+ * itself migrates it from there.
+ */
 export async function readGeminiCredentials({
   file = geminiCredentialsFile(),
+  keychainFile = geminiKeychainFile(),
   platform = process.platform,
+  encrypted = false,
+  fileStorage = false,
   readKeychain = readGeminiKeychainItem,
+  readFileKeychain = readGeminiFileKeychain,
 } = {}) {
-  const raw = await readKeychain(platform);
+  let raw = null;
+  if (encrypted) {
+    const keychain = fileStorage ? { status: 'unavailable' } : await readKeychain(platform);
+    if (keychain.status === 'found') raw = keychain.item;
+    else if (keychain.status === 'unavailable') raw = await readFileKeychain(keychainFile);
+    else if (keychain.status === 'unreadable') throw new UsageError('Gemini CLI keeps its sign-in in the Windows Credential Manager, which cannot be read from here');
+  }
   if (raw && raw.trim()) {
     let item;
     try { item = JSON.parse(raw); } catch { throw new UsageError('Gemini CLI credentials could not be parsed'); }
@@ -295,7 +361,7 @@ export async function readGeminiCredentials({
   try {
     legacy = JSON.parse(await fs.promises.readFile(file, 'utf8'));
   } catch {
-    throw new UsageError(`Gemini CLI is not signed in on this machine (no "${GEMINI_KEYCHAIN_SERVICE}" keychain item or ${shortPath(file)})`);
+    throw notSignedIn(`Gemini CLI is not signed in on this machine (no "${GEMINI_KEYCHAIN_SERVICE}" keychain item or ${shortPath(file)})`);
   }
   if (typeof legacy?.access_token !== 'string' || !legacy.access_token) throw new UsageError('Gemini CLI credentials could not be parsed');
   const client = typeof legacy.client_id === 'string' && typeof legacy.client_secret === 'string'
@@ -471,28 +537,35 @@ export class UsageMonitor {
     this.gemini = new Map();
   }
 
-  /** Snapshots for every provider that has a usage source. */
+  /** Snapshots for every account of every provider that has a usage source. */
   all() {
-    return Promise.all(this.registry.providers.filter((p) => p.usage).map((p) => this.snapshot(p)));
+    const jobs = [];
+    for (const provider of this.registry.providers) {
+      if (!provider.usage) continue;
+      for (const account of this.registry.accountsFor(provider)) jobs.push(this.snapshot(provider, account));
+    }
+    return Promise.all(jobs);
   }
 
-  snapshot(provider) {
-    const entry = this.cache.get(provider.id);
+  snapshot(provider, account = this.registry.account(provider)) {
+    const key = `${provider.id}\0${account.id}`;
+    const entry = this.cache.get(key);
     const now = Date.now();
     if (entry?.inflight) return entry.inflight;
     if (entry && now - entry.at < entry.ttl) return Promise.resolve(entry.snapshot);
-    const inflight = this._fetch(provider).then((snapshot) => {
+    const inflight = this._fetch(provider, account, key).then((snapshot) => {
       const ttl = snapshot.rateLimited ? RATE_LIMITED_TTL_MS : this.ttlMs;
-      this.cache.set(provider.id, { snapshot, at: Date.now(), ttl });
+      this.cache.set(key, { snapshot, at: Date.now(), ttl });
       return snapshot;
     });
-    this.cache.set(provider.id, { ...entry, inflight });
+    this.cache.set(key, { ...entry, inflight });
     return inflight;
   }
 
-  async _fetch(provider) {
-    const base = { providerId: provider.id, plan: null, windows: [], credits: null, fetchedAt: new Date().toISOString(), error: null };
-    const env = { ...this.env, ...provider.env };
+  async _fetch(provider, account, key) {
+    const base = { providerId: provider.id, accountId: account.id, plan: null, windows: [], credits: null, signedIn: null, fetchedAt: new Date().toISOString(), error: null };
+    const env = { ...this.env, ...provider.env, ...account.env };
+    let signedIn = null;
     try {
       let result;
       if (provider.usage === 'claude') {
@@ -501,16 +574,24 @@ export class UsageMonitor {
           keychain: this.platform === 'darwin',
           service: claudeKeychainService(env),
         });
+        signedIn = true;
         result = await fetchClaudeUsage({ ...creds, version: this.registry.versions.get(provider.id)?.installed, fetchImpl: this.fetchImpl });
       } else if (provider.usage === 'codex') {
         const creds = await this.readers.codex({ file: codexAuthFile(env) });
+        signedIn = true;
         result = await fetchCodexUsage({ ...creds, fetchImpl: this.fetchImpl });
       } else if (provider.usage === 'gemini') {
-        const creds = await this.readers.gemini({ file: geminiCredentialsFile(env), platform: this.platform });
+        const creds = await this.readers.gemini({
+          file: geminiCredentialsFile(env),
+          keychainFile: geminiKeychainFile(env),
+          platform: this.platform,
+          ...geminiStorageMode(env),
+        });
+        signedIn = true;
         // The refreshed token, project and plan belong to one sign-in; a new
         // sign-in (another account, or the same one again) starts over.
         const signIn = creds.refreshToken || creds.accessToken;
-        const cached = this.gemini.get(provider.id);
+        const cached = this.gemini.get(key);
         const known = cached?.signIn === signIn ? cached : {};
         const fresh = known.token && known.token.expiresAt > Date.now() + 60000 ? known.token : null;
         const { plan, windows, project, token } = await fetchGeminiUsage({
@@ -521,15 +602,15 @@ export class UsageMonitor {
           version: this.registry.versions.get(provider.id)?.installed,
           fetchImpl: this.fetchImpl,
         });
-        this.gemini.set(provider.id, { signIn, project, token, plan: plan ?? known.plan ?? null });
+        this.gemini.set(key, { signIn, project, token, plan: plan ?? known.plan ?? null });
         result = { plan: plan ?? known.plan ?? null, windows };
       } else {
         result = await commandUsage(provider.usage, env, this.platform);
       }
-      return { ...base, ...result };
+      return { ...base, signedIn, ...result };
     } catch (err) {
       const message = err instanceof UsageError ? err.message : `usage check failed: ${err.name === 'TimeoutError' ? 'timed out' : err.message}`;
-      return { ...base, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
+      return { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
     }
   }
 }