@oddessentials/agent-guild 0.19.0 → 0.21.0

package/README.md

@@ -67,6 +67,17 @@ 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.
 
+**Work inside tmux or herdr.** When installed, the Shell card also offers
+tmux (3.2 or later, on macOS and Linux) and herdr. A tmux card runs a tmux
+session of its own, with your own configuration, and tools in it report to
+the card as they would in a shell. A herdr card opens your herdr session and
+shows the agents herdr sees in its panes, working, blocked or idle. Stopping
+or closing either card only detaches it, as closing a terminal window would:
+the session keeps running, **Reattach** on the card brings it back, and the
+card names the command that reattaches it from a terminal. Stopping or
+restarting the manager detaches them the same way, and the cards come back,
+closed and ready to reattach, when it starts again.
+
 <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
@@ -120,7 +131,23 @@ puts a crew of little robots in deep space; **Grove** is a calm moss garden
 of gentle nature spirits; **Gnomeland** is a lantern-lit village of gnome
 builders, engineers with a little magic. The page
 follows your system's light or dark setting until you pick one. See
-[docs/SKINS.md](docs/SKINS.md) to make another.
+[docs/SKINS.md](docs/SKINS.md) to make another. **Alert sounds**, off until
+you turn them on in the same menu, chime when the session manager confirms
+a stop or restart, remains unavailable after a brief recovery check, or a
+new version is discovered after the initial version check. Session activity
+and assistant responses have no sounds:
+the providers do not yet offer consistently reliable completion signals.
+
+Sounds play in one eligible tab per browser and origin after browser playback
+permission (usually a click or keypress). They require Web Locks and writable
+local storage. Opening or reconnecting a page does not replay old alerts,
+even when a different manager has taken over. Closing a browser does not
+stop the manager. After an unexpected disconnect, an already connected page
+checks the local health endpoint twice, two seconds apart, with a one-second
+timeout per request. If both fail, it shows “Manager unavailable” and alerts
+once; it cannot confirm whether the process exited or sessions ended.
+A successful health check, reconnection, or closing the page cancels the alert.
+There is no added polling while connected and no additional monitoring process.
 
 ## Commands
 
@@ -238,7 +265,9 @@ npm test
 
 ## Current limits
 
-* Sessions end when the manager stops or the computer restarts.
+* Sessions end when the manager stops or the computer restarts, except a
+  Shell session in tmux or herdr, which keeps running in it while the
+  manager is stopped.
 * Antigravity CLI and Grok Build have no usage meter.
 * Antigravity CLI has one account per computer user: it keeps its sign-in in
   the system keychain and has no setting for another home folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.19.0",
+  "version": "0.21.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/command-resolver.mjs

@@ -83,8 +83,9 @@ export function resolveAllCommands(command, env = process.env, platform = proces
   return hits;
 }
 
-export function killWindowsTree(pid, done = () => {}) {
-  execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, (err) => done(err));
+/** End a Windows process and, unless `tree` is false, every process it started. */
+export function killWindowsTree(pid, done = () => {}, { tree = true } = {}) {
+  execFile('taskkill', ['/PID', String(pid), ...(tree ? ['/T'] : []), '/F'], { windowsHide: true, timeout: 5000 }, (err) => done(err));
 }
 
 /** Quote one argument for a cmd.exe command line. */
@@ -121,10 +122,11 @@ export function buildSpawnSpec(resolvedPath, args = [], env = process.env, platf
 }
 
 /**
- * Run a spawn spec to completion without a terminal. Resolves with its
- * output; rejects with the error carrying stdout and stderr.
+ * Run a spawn spec to completion without a terminal, with `input` on its
+ * stdin. Resolves with its output; rejects with the error carrying stdout
+ * and stderr.
  */
-export function runSpec(spec, { env, timeoutMs = 15000, cwd } = {}) {
+export function runSpec(spec, { env, timeoutMs = 15000, cwd, input } = {}) {
   return new Promise((resolve, reject) => {
     const opts = { env, cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 };
     let args = spec.args;
@@ -133,10 +135,11 @@ export function runSpec(spec, { env, timeoutMs = 15000, cwd } = {}) {
       args = [args];
     }
     try {
-      execFile(spec.file, args, opts, (err, stdout, stderr) => {
+      const child = execFile(spec.file, args, opts, (err, stdout, stderr) => {
         if (err) reject(Object.assign(err, { stdout, stderr }));
         else resolve({ stdout, stderr });
       });
+      if (input !== undefined) child.stdin.end(input);
     } catch (err) {
       reject(err);
     }

package/src/manager/config.mjs

@@ -48,6 +48,8 @@ export const paths = {
   /** Launchers for agent-guild-report, put first on every session's PATH. */
   get shims() { return path.join(dataDir(), 'bin'); },
   get reporting() { return path.join(dataDir(), 'reporting'); },
+  /** The tmux and herdr cards a restarted manager brings back, report tokens included. */
+  get multiplexers() { return path.join(dataDir(), 'multiplexers.json'); },
 };
 
 function writePrivate(file, contents) {
@@ -72,6 +74,25 @@ export function loadOrCreateToken() {
   return token;
 }
 
+/** Where the manager keeps its tmux and herdr cards, readable only by the user since they hold report tokens. */
+export const multiplexerStore = {
+  load() {
+    try {
+      const { cards } = JSON.parse(fs.readFileSync(paths.multiplexers, 'utf8'));
+      return Array.isArray(cards) ? cards : [];
+    } catch {
+      return [];
+    }
+  },
+  save(cards) {
+    ensureDataDir();
+    // Written aside and renamed, so a crash never leaves half a file.
+    const next = `${paths.multiplexers}.${process.pid}.tmp`;
+    writePrivate(next, JSON.stringify({ cards }, null, 2) + '\n');
+    fs.renameSync(next, paths.multiplexers);
+  },
+};
+
 export function writeRuntimeFile(info) {
   ensureDataDir();
   writePrivate(paths.runtime, JSON.stringify(info, null, 2) + '\n');

package/src/manager/herdr.mjs

@@ -0,0 +1,156 @@
+// The agents herdr sees in its panes, for a herdr card. herdr tracks every
+// coding agent in its panes and whether it is working, blocked or idle, with
+// no hooks of ours. Its socket API pushes an event when an agent appears or
+// leaves and, for a pane named in the subscription, when its agent changes
+// state; each event triggers a fresh agent.list, as herdr's documentation
+// advises, since events and reads share no sequence.
+
+import net from 'node:net';
+import { buildSpawnSpec, runSpec } from './command-resolver.mjs';
+
+const ANY_PANE = ['pane.agent_detected', 'pane.closed', 'pane.exited'];
+const STATUS = { working: 'working', blocked: 'waiting' };
+const REQUEST_TIMEOUT_MS = 10000;
+
+/** Card agent reports for herdr's agent list. Idle, done and unknown agents show as idle. */
+export function herdrAgentReports(agents) {
+  return (Array.isArray(agents) ? agents : [])
+    .filter((agent) => typeof agent?.pane_id === 'string' && typeof agent.agent === 'string')
+    .map((agent) => ({
+      agentId: `herdr:${agent.pane_id}`,
+      name: agent.agent,
+      kind: 'agent',
+      status: STATUS[agent.agent_status] ?? 'idle',
+      detail: typeof agent.cwd === 'string' ? agent.cwd : '',
+    }));
+}
+
+/**
+ * Where to reach the herdr session that a client started with `env` uses:
+ * the one HERDR_SESSION names, else the default. herdr names its Windows
+ * pipe after the socket path.
+ */
+export function herdrSocket(listing, env, platform = process.platform) {
+  const sessions = Array.isArray(listing?.sessions) ? listing.sessions : [];
+  const session = sessions.find((s) => (env.HERDR_SESSION ? s.name === env.HERDR_SESSION : s.default === true));
+  if (!session?.running || typeof session.socket_path !== 'string') return null;
+  return platform === 'win32' ? `\\\\.\\pipe\\${session.socket_path}` : session.socket_path;
+}
+
+/** Call `onLine` with each JSON line read from `socket`. */
+function readLines(socket, onLine) {
+  let buffer = '';
+  socket.setEncoding('utf8');
+  socket.on('data', (chunk) => {
+    buffer += chunk;
+    for (let end = buffer.indexOf('\n'); end !== -1; end = buffer.indexOf('\n')) {
+      const line = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (!line) continue;
+      try { onLine(JSON.parse(line)); } catch { /* not JSON */ }
+    }
+  });
+}
+
+/** One request on its own connection: resolves with its result. */
+function request(socketPath, method, params = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(socketPath);
+    socket.setTimeout(REQUEST_TIMEOUT_MS, () => socket.destroy(new Error(`herdr did not answer ${method}`)));
+    socket.on('connect', () => socket.write(`${JSON.stringify({ id: 'agent-guild', method, params })}\n`));
+    readLines(socket, (msg) => {
+      socket.end();
+      if (msg.error) reject(new Error(msg.error.message || msg.error.code));
+      else resolve(msg.result);
+    });
+    socket.on('error', reject);
+    socket.on('close', () => reject(new Error(`herdr closed the connection before answering ${method}`)));
+  });
+}
+
+export class HerdrAgents {
+  /**
+   * @param {object} opts
+   * @param {string} opts.herdr   the herdr executable
+   * @param {object} opts.env     the environment the card's herdr client runs with
+   * @param {(agents: object[]) => void} opts.onAgents  called with herdr's agent list after each change
+   */
+  constructor({ herdr, env, platform = process.platform, onAgents }) {
+    Object.assign(this, { herdr, env, platform, onAgents });
+    this.socketPath = null;
+    this.subscription = null;
+    this.panes = null;
+    this.connecting = false;
+    this.reading = false;
+    this.readAgain = false;
+    this.stopped = false;
+  }
+
+  /** Connect unless connected. A server that was still starting is found on a later call. */
+  poke() {
+    if (this.stopped || this.subscription || this.connecting) return;
+    this.connecting = true;
+    this._connect().finally(() => { this.connecting = false; });
+  }
+
+  stop() {
+    this.stopped = true;
+    this.subscription?.destroy();
+    this.subscription = null;
+  }
+
+  async _connect() {
+    try {
+      const spec = buildSpawnSpec(this.herdr, ['session', 'list', '--json'], this.env, this.platform);
+      const { stdout } = await runSpec(spec, { env: this.env, timeoutMs: REQUEST_TIMEOUT_MS });
+      this.socketPath = herdrSocket(JSON.parse(stdout), this.env, this.platform);
+    } catch {
+      return;
+    }
+    if (this.socketPath && !this.stopped) this._subscribe([]);
+  }
+
+  /** Replace the subscription: any pane's agent arriving or leaving, and each of `panes` changing state. */
+  _subscribe(panes) {
+    this.subscription?.destroy();
+    this.panes = panes;
+    const socket = net.connect(this.socketPath);
+    this.subscription = socket;
+    const subscriptions = [...ANY_PANE.map((type) => ({ type })), ...panes.map((pane) => ({ type: 'pane.agent_status_changed', pane_id: pane }))];
+    socket.on('connect', () => socket.write(`${JSON.stringify({ id: 'agent-guild', method: 'events.subscribe', params: { subscriptions } })}\n`));
+    readLines(socket, (msg) => {
+      if (this.subscription !== socket) return;
+      // herdr refuses a subscription naming a pane that has closed, and ends one that fell behind;
+      // start over from no panes. Anything else, the acknowledgement included, is a reason to read.
+      if (msg.error) return panes.length ? this._subscribe([]) : socket.destroy();
+      this._read();
+    });
+    socket.on('error', () => {});
+    socket.on('close', () => {
+      if (this.subscription === socket) this.subscription = null;
+    });
+  }
+
+  /** Read herdr's agent list, once more if an event arrives meanwhile, and follow the panes it names. */
+  async _read() {
+    if (this.reading) {
+      this.readAgain = true;
+      return;
+    }
+    this.reading = true;
+    try {
+      do {
+        this.readAgain = false;
+        const { agents = [] } = (await request(this.socketPath, 'agent.list')) ?? {};
+        if (this.stopped) return;
+        this.onAgents(agents);
+        const panes = agents.map((agent) => agent?.pane_id).filter((pane) => typeof pane === 'string').sort();
+        if (this.subscription && panes.join('\n') !== this.panes.join('\n')) this._subscribe(panes);
+      } while (this.readAgain && !this.stopped);
+    } catch {
+      // herdr went away or did not answer; the next event or poke tries again.
+    } finally {
+      this.reading = false;
+    }
+  }
+}

package/src/manager/main.mjs

@@ -25,6 +25,7 @@ import {
   VERSION,
   ensureDataDir,
   loadOrCreateToken,
+  multiplexerStore,
   paths,
   removeRuntimeFile,
   resolvePort,
@@ -67,7 +68,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   registry.reportingEnabled = (provider) => sessionHooks.enabled(provider);
   sessionHooks.warm();
   const manager = new SessionManager({
-    registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks,
+    registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks, store: multiplexerStore,
   });
   const usage = new UsageMonitor({ registry, env: baseEnv });
   const history = new SessionHistory({ registry, env: baseEnv });
@@ -146,6 +147,10 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     }
     throw err;
   }
+  // tmux and herdr cards come back closed, ready to reattach, before the
+  // runtime file announces this manager; after listening, since a card's
+  // environment names the API's URL.
+  await manager.restore();
 
   writeRuntimeFile({
     pid: process.pid,

package/src/manager/providers.mjs

@@ -669,7 +669,7 @@ 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,
+      shells: shells?.shells.map((shell) => ({ id: shell.id, label: shell.label, path: shell.path, multiplexer: Boolean(shell.multiplexer) })) ?? null,
       defaultShell: shells?.defaultId ?? null,
       modelPattern: provider.modelPattern,
       color: provider.color,

package/src/manager/server.mjs

@@ -25,6 +25,7 @@ const MIME = {
   '.webp': 'image/webp',
   '.woff2': 'font/woff2',
   '.ico': 'image/x-icon',
+  '.wav': 'audio/wav',
   '.json': 'application/json; charset=utf-8',
 };
 
@@ -305,8 +306,9 @@ export function createManagerServer({
       return sendJson(res, 201, { session: session.toJSON() });
     }
     if (route === '/shutdown' && method === 'POST') {
-      // Stopping the manager ends every session, so a client must say
-      // `force` while any is running. The same guard serves every front end.
+      // Stopping the manager ends every session but the tmux and herdr ones,
+      // so a client must say `force` while any of those is running. The same
+      // guard serves every front end.
       const body = await readJsonBody(req);
       const running = manager.runningCount();
       if (running > 0 && body.force !== true) {
@@ -327,7 +329,7 @@ export function createManagerServer({
       return undefined;
     }
 
-    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop)?$/);
+    const sessionMatch = route.match(/^\/sessions\/([a-f0-9]+)(\/stop|\/reattach)?$/);
     if (sessionMatch) {
       const [, id, action] = sessionMatch;
       if (!action && method === 'GET') return sendJson(res, 200, { session: manager.get(id).toJSON() });
@@ -347,6 +349,9 @@ export function createManagerServer({
       if (action === '/stop' && method === 'POST') {
         return sendJson(res, 200, { session: manager.stop(id).toJSON() });
       }
+      if (action === '/reattach' && method === 'POST') {
+        return sendJson(res, 200, { session: (await manager.reattach(id)).toJSON() });
+      }
     }
     throw new HttpError(404, `no route for ${method} ${url.pathname}`, 'not_found');
   }
@@ -450,7 +455,7 @@ export function createManagerServer({
 
   function handleEvents(ws) {
     eventClients.add(ws);
-    safeSend(ws, { type: 'hello', version, pid: process.pid, launcher, upgrade: upgradeInfo(), sessions: manager.list() });
+    safeSend(ws, { type: 'hello', version, pid: process.pid, startedAt, launcher, upgrade: upgradeInfo(), sessions: manager.list() });
     ws.on('close', () => eventClients.delete(ws));
     ws.on('message', () => { /* events socket is server -> client only */ });
   }