@oddessentials/agent-guild 0.10.0 → 0.11.0

package/README.md

@@ -140,20 +140,18 @@ The full reference, including every field and environment variable, is in
 
 ## Show agents and models
 
-Agents are reported by the coding tool, not guessed from its output. To see
-them, add the hooks from the matching file in [examples/](examples/) to
-Claude Code, Codex CLI, Gemini CLI or Grok Build. Each helper agent then
-appears on the card while it runs, and the card shows the model in use.
-Without hooks, the card still names the model when it is given with
-`--model` or shown on the tool's screen.
-
-The hooks call `agent-guild-report`, which the manager puts on the PATH of
-every session, so nothing else needs installing. Two tools need a one-time
-approval:
-
-* Codex CLI runs no hook until you trust it: choose "Trust all and continue"
-  when it starts, or run `/hooks`.
-* Claude Code runs none until you accept its workspace-trust prompt.
+Agents are reported by the coding tool's hooks, not guessed from its output.
+Each helper agent appears on the card while it runs. Agent Guild gives every
+Claude Code and Codex CLI session its reporting hooks for that session only,
+without changing the tool's own settings. Gemini CLI has no such option: turn
+on **Agent reporting** on its card once, which links an Agent Guild extension
+into Gemini. Grok Build cannot take hooks for one session yet; add the hooks
+from [examples/grok-hooks.json](examples/grok-hooks.json) to see its agents.
+When a tool's hooks do not run, because hooks are turned off, restricted by
+an administrator or not trusted for the folder, the card says so.
+
+The card also names the model, from the hooks, from `--model` or from the
+tool's screen.
 
 Any other tool or script can report agents and its model too. See
 [docs/agent-reporting.md](docs/agent-reporting.md).

package/bin/agent-guild-report.mjs

@@ -16,14 +16,28 @@
 //                      (reads Claude Code status line JSON on stdin; prints a
 //                       status line, or the JSON itself with --passthrough)
 
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import { hookToReports, claudeStatuslineToReport, formatStatusLine } from '../src/report/hooks.mjs';
 
+// Importing node:http as an ES module costs a hook about 50 ms more than requiring it.
+const http = createRequire(import.meta.url)('node:http');
 const env = process.env;
-const inSession = env.AGENT_GUILD_URL && env.AGENT_GUILD_SESSION_ID && env.AGENT_GUILD_REPORT_TOKEN;
-// Gemini CLI's optional environment redaction removes every variable whose
-// name contains TOKEN before it runs a hook. Say so instead of staying silent.
-if (!inSession && env.AGENT_GUILD_SESSION_ID && !env.AGENT_GUILD_REPORT_TOKEN) {
-  console.error('agent-guild-report: AGENT_GUILD_REPORT_TOKEN is missing from the environment; the tool may be redacting variables named *TOKEN*');
+
+function reportToken() {
+  if (env.AGENT_GUILD_REPORT_TOKEN) return env.AGENT_GUILD_REPORT_TOKEN;
+  if (!env.AGENT_GUILD_REPORT_FILE) return null;
+  try {
+    return fs.readFileSync(env.AGENT_GUILD_REPORT_FILE, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+const token = env.AGENT_GUILD_URL && env.AGENT_GUILD_SESSION_ID ? reportToken() : null;
+const inSession = Boolean(token);
+if (!inSession && env.AGENT_GUILD_SESSION_ID) {
+  console.error('agent-guild-report: the session report token is missing; the tool may have removed AGENT_GUILD_REPORT_TOKEN and AGENT_GUILD_REPORT_FILE from the environment, or the session has ended');
 }
 
 const USAGE = `Usage: agent-guild-report <agent-id> [--name N] [--status working|waiting|idle|done] [--detail TEXT] [--kind KIND] [--remove]
@@ -61,23 +75,31 @@ function readStdin() {
   });
 }
 
-async function send(report) {
-  const kind = report.agentId !== undefined || report.finishForeground === true ? 'agents'
+function send(report) {
+  const kind = report.shell !== undefined ? 'shells'
+    : report.agentId !== undefined || report.finishForeground === true ? 'agents'
+    : report.hello === true ? 'reporting'
     : report.toolSessionId !== undefined ? 'tool-session' : 'model';
-  const url = `${env.AGENT_GUILD_URL}/api/v1/sessions/${env.AGENT_GUILD_SESSION_ID}/${kind}`;
-  const res = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'X-Agent-Guild-Report-Token': env.AGENT_GUILD_REPORT_TOKEN,
-    },
-    body: JSON.stringify(report),
-    signal: AbortSignal.timeout(3000),
+  const body = JSON.stringify(report);
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${env.AGENT_GUILD_URL}/api/v1/sessions/${env.AGENT_GUILD_SESSION_ID}/${kind}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'X-Agent-Guild-Report-Token': token,
+      },
+      timeout: 3000,
+    }, (res) => {
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { text += chunk; });
+      res.on('end', () => (res.statusCode >= 200 && res.statusCode < 300 ? resolve() : reject(new Error(`HTTP ${res.statusCode}: ${text}`))));
+    });
+    req.on('timeout', () => req.destroy(new Error('the manager did not answer in time')));
+    req.on('error', reject);
+    req.end(body);
   });
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`HTTP ${res.status}: ${body}`);
-  }
 }
 
 /** A hook must never break the coding tool, so report failures quietly. */

package/config/providers.default.json

@@ -9,6 +9,7 @@
       "versionArgs": ["--version"],
       "usage": "claude",
       "history": "claude",
+      "reporting": "claude",
       "homeVar": "CLAUDE_CONFIG_DIR",
       "accountEnv": { "CLAUDE_SECURESTORAGE_CONFIG_DIR": "{dir}" },
       "hooks": { "path": "settings.json", "example": "claude-code-settings.json" },
@@ -46,6 +47,7 @@
       "versionArgs": ["--version"],
       "usage": "codex",
       "history": "codex",
+      "reporting": "codex",
       "homeVar": "CODEX_HOME",
       "hooks": { "path": "hooks.json", "example": "codex-hooks.json" },
       "modelPattern": "\\bgpt-\\d[a-z0-9.-]*",
@@ -80,6 +82,7 @@
       "versionArgs": ["--version"],
       "usage": "gemini",
       "history": "gemini",
+      "reporting": "gemini",
       "homeVar": "GEMINI_CLI_HOME",
       "accountEnv": { "GEMINI_FORCE_FILE_STORAGE": "true" },
       "hooks": { "path": ".gemini/settings.json", "example": "gemini-settings.json" },
@@ -104,6 +107,7 @@
       "package": "@xai-official/grok",
       "versionArgs": ["--version"],
       "history": "grok",
+      "reporting": "grok",
       "homeVar": "GROK_HOME",
       "hooks": { "path": "hooks/agent-guild.json", "example": "grok-hooks.json" },
       "modelPattern": "\\bgrok-(?:build|\\d)[a-z0-9.-]*",

package/examples/grok-hooks.json

@@ -50,6 +50,49 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "run_terminal_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-guild-report --hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "run_terminal_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-guild-report --hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "run_terminal_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-guild-report --hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agent-guild-report --hook"
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.10.0",
+  "version": "0.11.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,6 +83,10 @@ 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));
+}
+
 /** Quote one argument for a cmd.exe command line. */
 export function quoteForCmd(arg) {
   const s = String(arg);
@@ -120,9 +124,9 @@ 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.
  */
-export function runSpec(spec, { env, timeoutMs = 15000 } = {}) {
+export function runSpec(spec, { env, timeoutMs = 15000, cwd } = {}) {
   return new Promise((resolve, reject) => {
-    const opts = { env, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 };
+    const opts = { env, cwd, timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 };
     let args = spec.args;
     if (typeof args === 'string') {
       opts.windowsVerbatimArguments = true;

package/src/manager/config.mjs

@@ -47,6 +47,8 @@ export const paths = {
   get log() { return path.join(dataDir(), 'manager.log'); },
   /** 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'); },
+  get reportTokens() { return path.join(dataDir(), 'report-tokens'); },
 };
 
 function writePrivate(file, contents) {

package/src/manager/main.mjs

@@ -16,6 +16,7 @@ import { createManagerServer } from './server.mjs';
 import { SelfUpdate } from './self-update.mjs';
 import { resolveBaseEnv, pathReader } from './shell-env.mjs';
 import { writeReportShims } from './report-shims.mjs';
+import { SessionHooks } from './session-hooks.mjs';
 import { launcherPath, spawnManager } from './launch.mjs';
 import {
   DEFAULT_HOST,
@@ -62,7 +63,12 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   let api;
   const selfUpdate = new SelfUpdate({ pkg: PACKAGE_NAME, version, packageFile, registry });
   const github = new GitHub({ dir: paths.github, registry, ...githubOptions });
-  const manager = new SessionManager({ registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github });
+  const sessionHooks = new SessionHooks({ registry, dir: paths.reporting, version, shimDir });
+  registry.reportingEnabled = (provider, account) => sessionHooks.enabled(provider, account);
+  sessionHooks.warm();
+  const manager = new SessionManager({
+    registry, baseEnv, getApiUrl: () => api.url, sessionDefaults, shimDir, selfUpdate, github, sessionHooks, reportTokenDir: paths.reportTokens,
+  });
   const usage = new UsageMonitor({ registry, env: baseEnv });
   const history = new SessionHistory({ registry, env: baseEnv });
   const modelStats = new ModelStats({ registry });
@@ -71,7 +77,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   let closing = null;
 
   const refreshVersions = () => {
-    registry.refreshVersions().catch(() => {});
+    registry.refreshVersions().then(() => sessionHooks.warm(), () => {});
     selfUpdate.refresh().catch(() => {});
   };
   const versionTimer = setInterval(refreshVersions, VERSION_REFRESH_MS);
@@ -141,6 +147,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     throw err;
   }
 
+  manager.sweepReportTokens();
   writeRuntimeFile({
     pid: process.pid,
     host,

package/src/manager/providers.mjs

@@ -19,6 +19,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 export const DEFAULTS_FILE = path.resolve(here, '../../config/providers.default.json');
 const ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
 const PLATFORM_KEYS = ['win32', 'darwin', 'linux'];
+const REPORTING_MODES = new Set(['claude', 'codex', 'gemini', 'grok']);
 const VERSION_TTL_MS = 60 * 60 * 1000;
 const FAILED_PROBE_TTL_MS = 5 * 60 * 1000;
 const PATH_REFRESH_MS = 60 * 1000;
@@ -163,6 +164,7 @@ function normalize(raw, platform, warnings) {
     versionArgs: Array.isArray(merged.versionArgs) && merged.versionArgs.length ? merged.versionArgs.map(String) : null,
     usage: normalizeUsage(merged.usage),
     history: normalizeHistory(merged.history),
+    reporting: REPORTING_MODES.has(merged.reporting) ? merged.reporting : null,
     modelPattern: merged.modelPattern ? String(merged.modelPattern) : null,
     args: Array.isArray(merged.args) ? merged.args.map(String) : [],
     resumeArgs: Array.isArray(merged.resumeArgs) ? merged.resumeArgs.map(String) : [],
@@ -251,6 +253,7 @@ export class ProviderRegistry extends EventEmitter {
     this.versions = new Map();
     this._refreshing = null;
     this._npmRegistry = null;
+    this.reportingEnabled = null;
     this.reload();
   }
 
@@ -623,7 +626,11 @@ export class ProviderRegistry extends EventEmitter {
       npmNote: provider.npmNote,
       usageSource: provider.usage === null ? null : typeof provider.usage === 'string' ? provider.usage : 'command',
       historySource: provider.history === null ? null : typeof provider.history === 'string' ? provider.history : 'command',
-      accounts: provider.accounts.map(({ id, label }) => ({ id, label })),
+      reporting: provider.reporting,
+      accounts: provider.accounts.map((account) => {
+        const reportingEnabled = this.reportingEnabled?.(provider, this.accountFor(provider, account)) ?? null;
+        return { id: account.id, label: account.label, ...(reportingEnabled === null ? {} : { reportingEnabled }) };
+      }),
       modelPattern: provider.modelPattern,
       color: provider.color,
       monogram: provider.monogram,
@@ -642,7 +649,7 @@ export class ProviderRegistry extends EventEmitter {
   }
 
   /** Spawn spec for node-pty, or throws with a user-facing message. */
-  spawnSpec(provider, extraArgs = [], resume = null) {
+  spawnSpec(provider, extraArgs = [], resume = null, leadArgs = []) {
     const resolved = this.resolve(provider);
     if (!resolved) {
       const hint = provider.install ? ` ${provider.install}` : '';
@@ -661,7 +668,7 @@ export class ProviderRegistry extends EventEmitter {
       }
       resumeArgs = provider.resumeArgs.map((arg) => arg.replaceAll('{id}', resume));
     }
-    return buildSpawnSpec(resolved, [...provider.args, ...resumeArgs, ...extraArgs], this.env, this.platform);
+    return buildSpawnSpec(resolved, [...leadArgs, ...provider.args, ...resumeArgs, ...extraArgs], this.env, this.platform);
   }
 
   async updateSpec(provider) {

package/src/manager/report-shims.mjs

@@ -48,6 +48,7 @@ export function shimContents({ execPath, script, platform = process.platform })
   const files = {
     [SHIM_NAME]: [
       '#!/bin/sh',
+      '[ "$1" = --hook ] && [ -z "$AGENT_GUILD_SESSION_ID" ] && exec cat >/dev/null',
       `n=${shQuote(forSh(execPath))}`,
       '[ -x "$n" ] || n=node',
       `exec "$n" ${shQuote(forSh(script))} "$@"`,
@@ -58,6 +59,7 @@ export function shimContents({ execPath, script, platform = process.platform })
     files[LOADER_NAME] = `import ${JSON.stringify(fileUrl(script, platform))};\n`;
     files[`${SHIM_NAME}.cmd`] = [
       '@ECHO OFF',
+      'IF "%~1"=="--hook" IF NOT DEFINED AGENT_GUILD_SESSION_ID EXIT /B 0',
       'IF EXIST "%AGENT_GUILD_NODE%" GOTO manager',
       `node "%~dp0${LOADER_NAME}" %*`,
       'EXIT /B %ERRORLEVEL%',

package/src/manager/server.mjs

@@ -207,7 +207,7 @@ export function createManagerServer({
     // Agent, model and tool-session reports may authenticate with the
     // per-session report token that the manager injects into each tool's
     // environment.
-    const reportMatch = route.match(/^\/sessions\/([a-f0-9]+)\/(agents|model|tool-session)$/);
+    const reportMatch = route.match(/^\/sessions\/([a-f0-9]+)\/(agents|model|tool-session|reporting|shells)$/);
     if (reportMatch && method === 'POST') {
       const [, id, kind] = reportMatch;
       const body = await readJsonBody(req);
@@ -217,6 +217,11 @@ export function createManagerServer({
       };
       if (kind === 'agents') return sendJson(res, 200, { agent: manager.reportAgent(id, body, auth) });
       if (kind === 'model') return sendJson(res, 200, { model: manager.reportModel(id, body, auth) });
+      if (kind === 'reporting') return sendJson(res, 200, { reporting: manager.reportHello(id, auth) });
+      if (kind === 'shells') {
+        manager.reportShell(id, body, auth);
+        return sendJson(res, 200, { ok: true });
+      }
       return sendJson(res, 200, { toolSessionId: manager.reportToolSession(id, body, auth) });
     }
 
@@ -269,6 +274,17 @@ export function createManagerServer({
       const account = registry.account(provider, url.searchParams.get('account'));
       return sendJson(res, 200, { history: await history.list(provider, account, { limit: url.searchParams.get('limit') }) });
     }
+    const reportingMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/reporting$/);
+    if (reportingMatch && method === 'POST' && manager.sessionHooks) {
+      const provider = registry.get(reportingMatch[1]);
+      if (!provider) throw new HttpError(404, `unknown provider "${reportingMatch[1]}"`, 'unknown_provider');
+      const body = await readJsonBody(req);
+      if (typeof body.enabled !== 'boolean') throw new HttpError(400, 'enabled must be true or false', 'bad_request');
+      const account = registry.account(provider, body.account ?? null);
+      await manager.sessionHooks.setEnabled(provider, account, body.enabled);
+      registry.emit('updated');
+      return sendJson(res, 200, { provider: registry.describe(provider) });
+    }
     const installMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/install$/);
     if (installMatch && method === 'POST') {
       const body = await readJsonBody(req);
@@ -280,7 +296,7 @@ export function createManagerServer({
     }
     if (route === '/sessions' && method === 'POST') {
       const body = await readJsonBody(req);
-      const session = manager.create(body);
+      const session = await manager.create(body);
       return sendJson(res, 201, { session: session.toJSON() });
     }
     if (route === '/shutdown' && method === 'POST') {
@@ -452,7 +468,7 @@ export function createManagerServer({
       if (isBinary) return;
       let msg;
       try { msg = JSON.parse(raw.toString('utf8')); } catch { return; }
-      if (msg.type === 'input' && typeof msg.data === 'string') session.write(msg.data);
+      if (msg.type === 'input' && typeof msg.data === 'string') session.input(msg.data);
       else if (msg.type === 'resize') session.resize(msg.cols, msg.rows);
     });
   }