@oddessentials/agent-guild 0.16.0 → 0.17.0

package/README.md

@@ -58,6 +58,13 @@ terminal: type instructions, answer prompts, watch output. Run as many as you
 like. A local session manager owns them, so you can close or reload the page
 and come back to the same screens.
 
+**Pick your shell.** The Shell card offers the shells installed on your
+computer and remembers your choice in this browser. On Windows it defaults
+to PowerShell 7 when installed, then Windows PowerShell; Git Bash and Command
+Prompt are also offered when found. On macOS and Linux it follows your login
+shell. Pick the default chip to clear a saved choice and follow the default
+again. The choice applies to new sessions.
+
 <img src="docs/images/terminal.webp" alt="An open Claude Code session with its helper agents shown in the header">
 
 **Agents and models at work.** Helper agents that a tool starts appear on its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/src/manager/providers.mjs

@@ -13,6 +13,7 @@ import { resolveCommand, resolveAllCommands, pathKey, buildSpawnSpec, runSpec }
 import { compareVersions, probeVersion, fetchManifest, latestVersion, DEFAULT_NPM_REGISTRY } from './versions.mjs';
 import { CHANNEL_LABELS, classifyInstall, expandHome, formatCommand, homeRelative, knownLaunchers, listInstallations, platformDependency, updateHelpAccepted } from './install-channels.mjs';
 import { weavePaths } from './shell-env.mjs';
+import { detectShells, fallbackShell } from './shells.mjs';
 import { RUNNER, encodePlan } from './uninstall.mjs';
 import { paths } from './config.mjs';
 
@@ -34,11 +35,6 @@ function refusal(status, code, message) {
   return Object.assign(new Error(message), { status, code });
 }
 
-export function defaultShell(env = process.env, platform = process.platform) {
-  if (platform === 'win32') return 'powershell.exe';
-  return env.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/bash');
-}
-
 function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
@@ -259,6 +255,7 @@ export class ProviderRegistry extends EventEmitter {
     this._pathReadAt = 0;
     this._pathPending = null;
     this._installs = new Map();
+    this._shells = new Map();
     this.versions = new Map();
     this._refreshing = null;
     this._npmRegistry = null;
@@ -272,6 +269,7 @@ export class ProviderRegistry extends EventEmitter {
     this.warnings = warnings;
     this._npmRegistry = null;
     this._installs.clear();
+    this._shells.clear();
     for (const w of warnings) console.warn(`[providers] ${w}`);
     this.emit('updated');
   }
@@ -335,6 +333,7 @@ export class ProviderRegistry extends EventEmitter {
     if (next === (this.env[key] || '')) return false;
     this.env[key] = next;
     this._installs.clear();
+    this._shells.clear();
     return true;
   }
 
@@ -568,8 +567,32 @@ export class ProviderRegistry extends EventEmitter {
     return this.accountFor(provider, found);
   }
 
+  /** The shells the provider can start, or null when it is not the `@shell` provider. */
+  shellsFor(provider) {
+    if (provider.command !== '@shell') return null;
+    const cached = this._shells.get(provider.id);
+    if (cached && Date.now() - cached.at < INSTALLS_TTL_MS) return cached.found;
+    const found = detectShells({ ...this.env, ...provider.env }, this.platform);
+    this._shells.set(provider.id, { found, at: Date.now() });
+    return found;
+  }
+
+  /** The shell a session of the provider runs: the one named by `id`, else the default. Null for other providers. */
+  shellFor(provider, id = null) {
+    const found = this.shellsFor(provider);
+    if (!found) {
+      if (id == null) return null;
+      throw refusal(400, 'bad_shell', `${provider.tool} does not start a shell`);
+    }
+    const wanted = id ?? found.defaultId;
+    const shell = found.shells.find((s) => s.id === wanted) ?? null;
+    if (!shell && wanted !== null) throw refusal(409, 'shell_unavailable', `The shell "${wanted}" was not found on this computer`);
+    return shell;
+  }
+
   commandFor(provider) {
-    return provider.command === '@shell' ? defaultShell(this.env, this.platform) : provider.command;
+    if (provider.command !== '@shell') return provider.command;
+    return this.shellFor(provider)?.path ?? fallbackShell(this.env, this.platform);
   }
 
   resolve(provider) {
@@ -597,6 +620,7 @@ export class ProviderRegistry extends EventEmitter {
     const channel = this.channelFor(provider, resolvedPath);
     const update = this.updateFor(provider, channel);
     const shown = (file) => homeRelative(file, { ...this.env, ...provider.env }, this.platform);
+    const shells = this.shellsFor(provider);
     const installs = this.installsFor(provider, resolvedPath).map((install) => {
       const active = install.resolvedPath === resolvedPath;
       const copy = active ? { version: installed, status: versions?.versionStatus ?? null } : versions?.copies?.[install.resolvedPath];
@@ -645,6 +669,8 @@ export class ProviderRegistry extends EventEmitter {
       reporting: provider.reporting,
       reportingEnabled: this.reportingEnabled?.(provider) ?? null,
       accounts: provider.accounts.map((account) => ({ id: account.id, label: account.label })),
+      shells: shells?.shells.map((shell) => ({ id: shell.id, label: shell.label, path: shell.path })) ?? null,
+      defaultShell: shells?.defaultId ?? null,
       modelPattern: provider.modelPattern,
       color: provider.color,
       monogram: provider.monogram,
@@ -664,8 +690,8 @@ export class ProviderRegistry extends EventEmitter {
   }
 
   /** Spawn spec for node-pty, or throws with a user-facing message. */
-  spawnSpec(provider, extraArgs = [], resume = null, leadArgs = []) {
-    const resolved = this.resolve(provider);
+  spawnSpec(provider, extraArgs = [], resume = null, leadArgs = [], shell = null) {
+    const resolved = shell ? shell.path : this.resolve(provider);
     if (!resolved) {
       const hint = provider.install ? ` ${provider.install}` : '';
       const err = new Error(`${provider.tool} ("${this.commandFor(provider)}") was not found on PATH.${hint}`);
@@ -683,7 +709,9 @@ export class ProviderRegistry extends EventEmitter {
       }
       resumeArgs = provider.resumeArgs.map((arg) => arg.replaceAll('{id}', resume));
     }
-    return buildSpawnSpec(resolved, [...leadArgs, ...provider.args, ...resumeArgs, ...extraArgs], this.env, this.platform);
+    // The provider's own args were written for its default shell, not for one picked instead.
+    const args = shell && shell.id !== this.shellsFor(provider).defaultId ? [] : provider.args;
+    return buildSpawnSpec(resolved, [...(shell?.args ?? []), ...leadArgs, ...args, ...resumeArgs, ...extraArgs], this.env, this.platform);
   }
 
   async updateSpec(provider) {

package/src/manager/session-manager.mjs

@@ -93,25 +93,31 @@ export class SessionManager extends EventEmitter {
     return dir;
   }
 
-  async create({ providerId, cwd, cols, rows, name, args, resume, account } = {}) {
+  async create({ providerId, cwd, cols, rows, name, args, resume, account, shell } = {}) {
     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');
+    if (shell !== undefined && shell !== null && typeof shell !== 'string') throw httpError(400, 'shell must be a string', 'bad_shell');
     const resumeId = cleanResumeId(resume);
     const workDir = this.resolveCwd(cwd);
     const signIn = this.registry.account(provider, account);
+    const runShell = this.registry.shellFor(provider, shell);
     const hooks = this.sessionHooks ? await this.sessionHooks.launch(provider) : { args: [], reporting: null };
     // Checked after the await, so an install that started meanwhile is seen.
     if (this.installing.has(provider.id) || this.installsRunningFor(provider.id) > 0) {
       throw httpError(409, `${provider.tool} is being installed, updated or removed; start it once that finishes`, 'install_in_progress');
     }
-    const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args);
+    const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId, hooks.args, runShell);
     this.prepareAccount(provider, signIn, { hooksSupplied: hooks.args.length > 0 });
-    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, reporting: hooks.reporting });
+    const sessionName = cleanName(name)
+      || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null)
+      || (runShell && this.registry.shellsFor(provider).shells.length > 1 ? `${provider.tool} · ${runShell.label}` : null);
+    const session = this._spawn({
+      provider, spawnSpec, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn, reporting: hooks.reporting, extraEnv: runShell?.env,
+    });
     const model = modelFromArgs([...provider.args, ...(args || [])]);
     if (model) session.setModel({ name: model }, 'args');
     return session;

package/src/manager/shells.mjs

@@ -0,0 +1,82 @@
+// The shells the Shell card can start: the ones installed on this computer,
+// and which of them is the default.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveCommand } from './command-resolver.mjs';
+
+const UNIX_SHELLS = [
+  { id: 'bash', label: 'bash' },
+  { id: 'zsh', label: 'zsh' },
+  { id: 'fish', label: 'fish' },
+  { id: 'pwsh', label: 'PowerShell' },
+];
+
+function isFile(file) {
+  try { return fs.statSync(file).isFile(); } catch { return false; }
+}
+
+function envValue(env, name) {
+  const key = Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
+  return key ? env[key] : undefined;
+}
+
+// Git for Windows keeps bash.exe in <root>\bin, and git.exe in <root>\cmd,
+// <root>\bin or <root>\mingw64\bin.
+function findGitBash(env, resolve, exists) {
+  const p = path.win32;
+  const roots = [];
+  const git = resolve('git');
+  if (git) for (let dir = p.dirname(git), i = 0; i < 3; i++, dir = p.dirname(dir)) roots.push(dir);
+  for (const [name, sub] of [['ProgramFiles', 'Git'], ['ProgramW6432', 'Git'], ['ProgramFiles(x86)', 'Git'], ['LOCALAPPDATA', 'Programs\\Git'], ['USERPROFILE', 'scoop\\apps\\git\\current']]) {
+    const base = envValue(env, name);
+    if (base) roots.push(p.join(base, sub));
+  }
+  for (const root of roots) {
+    const bash = p.join(root, 'bin', 'bash.exe');
+    if (exists(bash) && exists(p.join(root, 'cmd', 'git.exe'))) return bash;
+  }
+  return null;
+}
+
+/** The shell to name when none is installed. */
+export function fallbackShell(env, platform) {
+  if (platform === 'win32') return 'powershell.exe';
+  return env.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/bash');
+}
+
+function windowsShells(env, resolve, exists) {
+  const installed = ['ProgramFiles', 'ProgramW6432'].map((name) => envValue(env, name)).filter(Boolean).map((base) => path.win32.join(base, 'PowerShell', '7', 'pwsh.exe'));
+  const pwsh = resolve('pwsh') || installed.find(exists) || null;
+  const gitBash = findGitBash(env, resolve, exists);
+  const shells = [
+    pwsh && { id: 'pwsh', label: 'PowerShell', path: pwsh, args: [], env: {} },
+    { id: 'powershell', label: 'Windows PowerShell', path: resolve('powershell.exe'), args: [], env: {} },
+    { id: 'cmd', label: 'Command Prompt', path: resolve('cmd.exe'), args: [], env: {} },
+    // CHERE_INVOKING keeps a login bash in the session's folder instead of moving to HOME.
+    gitBash && { id: 'git-bash', label: 'Git Bash', path: gitBash, args: ['--login', '-i'], env: { CHERE_INVOKING: '1' } },
+  ].filter((shell) => shell?.path);
+  return { shells, defaultId: shells[0]?.id ?? null };
+}
+
+function unixShells(env, platform, resolve) {
+  const name = (file) => path.posix.basename(file);
+  const own = resolve(env.SHELL || '') || resolve(fallbackShell({}, platform));
+  const shells = [];
+  for (const { id, label } of UNIX_SHELLS) {
+    const found = own && name(own) === id ? own : resolve(id);
+    if (found) shells.push({ id, label, path: found, args: [], env: {} });
+  }
+  let defaultId = own ? name(own) : null;
+  if (own && !shells.some((shell) => shell.id === defaultId)) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/.test(defaultId)) defaultId = 'login';
+    shells.unshift({ id: defaultId, label: name(own), path: own, args: [], env: {} });
+  }
+  return { shells, defaultId: defaultId ?? shells[0]?.id ?? null };
+}
+
+/** The installed shells, as { id, label, path, args, env }, and the id of the default one. */
+export function detectShells(env = process.env, platform = process.platform, { exists = isFile, resolve: resolveWith = resolveCommand } = {}) {
+  const resolve = (command) => resolveWith(command, env, platform);
+  return platform === 'win32' ? windowsShells(env, resolve, exists) : unixShells(env, platform, resolve);
+}

package/web/app.js

@@ -4,6 +4,7 @@
 const TOKEN_KEY = 'agentGuild.token';
 const CWD_KEY = 'agentGuild.cwd';
 const ACCOUNTS_KEY = 'agentGuild.accounts';
+const SHELLS_KEY = 'agentGuild.shells';
 const THEME_KEY = 'agentGuild.theme';
 const SKIN_KEY = 'agentGuild.skin';
 const NEWS_SEEN_KEY = 'agentGuild.newsSeen';
@@ -23,6 +24,7 @@ const state = {
   providers: [],
   usage: new Map(),
   accounts: {},
+  shellPicks: {},
   stats: null,
   statsFor: new Map(),
   news: null,
@@ -456,6 +458,51 @@ function selectAccount(provider, id) {
   save(ACCOUNTS_KEY, JSON.stringify(state.accounts));
 }
 
+/** The shell the user picked for the provider, or null to start its default. */
+function pickedShell(provider) {
+  return provider.shells?.find((s) => s.id === state.shellPicks[provider.id] && s.id !== provider.defaultShell) ?? null;
+}
+
+function selectedShell(provider) {
+  return pickedShell(provider) ?? provider.shells?.find((s) => s.id === provider.defaultShell) ?? null;
+}
+
+function selectShell(provider, id) {
+  if (id === provider.defaultShell) delete state.shellPicks[provider.id];
+  else state.shellPicks[provider.id] = id;
+  save(SHELLS_KEY, JSON.stringify(state.shellPicks));
+}
+
+function renderShells(card, provider) {
+  const host = card.querySelector('.shells');
+  const shells = provider.shells || [];
+  host.hidden = !provider.available || shells.length < 2;
+  if (host.hidden) return host.replaceChildren();
+  const selected = selectedShell(provider)?.id;
+  const same = host.children.length === shells.length && shells.every((s, i) => host.children[i].dataset.shell === s.id);
+  if (!same) {
+    host.replaceChildren(...shells.map((shell) => {
+      const chip = document.createElement('button');
+      chip.type = 'button';
+      chip.className = 'account-chip';
+      chip.setAttribute('role', 'tab');
+      chip.dataset.shell = shell.id;
+      chip.addEventListener('click', () => {
+        selectShell(provider, shell.id);
+        renderShells(card, provider);
+        renderUsage(card, provider);
+      });
+      return chip;
+    }));
+  }
+  shells.forEach((shell, i) => {
+    const chip = host.children[i];
+    chip.setAttribute('aria-selected', String(shell.id === selected));
+    chip.textContent = shell.label;
+    chip.title = `Start new sessions in ${shell.label}${shell.id === provider.defaultShell ? ', used unless you pick another' : ''}\n${shell.path}`;
+  });
+}
+
 function usageFor(provider, account = selectedAccount(provider)) {
   return state.usage.get(`${provider.id}/${account.id}`);
 }
@@ -559,6 +606,7 @@ function renderProviders() {
     renderCopies(node.querySelector('.copies'), provider, node);
     renderVendorLinks(node, provider);
     renderAccounts(node, provider);
+    renderShells(node, provider);
     renderUsage(node, provider);
     renderReportingSetup(node, provider);
     renderModelStats(node, provider);
@@ -685,7 +733,7 @@ function renderUsage(card, provider) {
   start.textContent = unsigned ? 'Sign in' : 'New';
   start.title = unsigned
     ? `Start a ${provider.tool} session and sign in as the ${account.label} account`
-    : `Start a new ${provider.tool} session${provider.accounts?.length > 1 ? ` as the ${account.label} account` : ''}`;
+    : `Start a new ${provider.tool} session${provider.accounts?.length > 1 ? ` as the ${account.label} account` : ''}${provider.shells?.length > 1 ? ` in ${selectedShell(provider)?.label}` : ''}`;
   if (!provider.available || !provider.usageSource || !usage) return host.replaceChildren();
   if (usage.error || usage.windows.length === 0) {
     const note = document.createElement('div');
@@ -1728,7 +1776,7 @@ async function startSession(provider, card, { resume, cwd, account = selectedAcc
   save(CWD_KEY, working);
   card?.classList.add('busy');
   try {
-    const body = { providerId: provider.id, account, cwd: cwd || working || undefined, cols: 120, rows: 32, resume };
+    const body = { providerId: provider.id, account, shell: pickedShell(provider)?.id, cwd: cwd || working || undefined, cols: 120, rows: 32, resume };
     let session;
     try {
       ({ session } = await api('POST', '/sessions', body));
@@ -3403,8 +3451,10 @@ $('panel-stop').addEventListener('click', () => {
 });
 $('cwd').value = load(CWD_KEY) || '';
 try { state.accounts = JSON.parse(load(ACCOUNTS_KEY)) || {}; } catch { state.accounts = {}; }
+try { state.shellPicks = JSON.parse(load(SHELLS_KEY)) || {}; } catch { state.shellPicks = {}; }
 githubView.accountId = Number(load(GITHUB_ACCOUNT_KEY)) || null;
 if (typeof state.accounts !== 'object' || Array.isArray(state.accounts)) state.accounts = {};
+if (typeof state.shellPicks !== 'object' || Array.isArray(state.shellPicks)) state.shellPicks = {};
 setInterval(renderSessions, 30000);
 setInterval(tickNews, 30000);
 setInterval(() => { if ($('github').open && state.github) renderGitHub(); }, 30000);

package/web/index.html

@@ -262,6 +262,7 @@
         <a class="cloud-link" target="_blank" rel="noopener noreferrer" hidden></a>
       </div>
       <div class="accounts" role="tablist" aria-label="Accounts" hidden></div>
+      <div class="shells" role="tablist" aria-label="Shells" hidden></div>
       <div class="usage"></div>
       <div class="model-stats"></div>
       <div class="reporting-row" hidden>

package/web/styles.css

@@ -109,7 +109,7 @@ main { max-width: 1200px; margin: 0 auto; padding: 26px 16px 56px; display: grid
 .provider .state.update-available { color: var(--warn); }
 .provider.unavailable .state { color: var(--muted); }
 .provider .update { color: var(--warn); border-color: var(--warn); }
-.provider .accounts { display: flex; flex-wrap: wrap; gap: 6px; }
+.provider .accounts, .provider .shells { display: flex; flex-wrap: wrap; gap: 6px; }
 .account-chip {
   font: inherit; font-size: 0.75rem; font-weight: 600; padding: 2px 10px; border-radius: 999px; cursor: pointer;
   border: 1px solid var(--border); background: var(--surface-2); color: var(--muted); max-width: 100%;