@oddessentials/agent-guild 1.14.0 → 1.14.1

package/examples/claude-code-settings.json

@@ -67,6 +67,7 @@
     ],
     "PermissionRequest": [
       {
+        "matcher": "Bash|PowerShell|Monitor",
         "hooks": [
           {
             "type": "command",
@@ -78,6 +79,7 @@
     ],
     "PermissionDenied": [
       {
+        "matcher": "Bash|PowerShell|Monitor",
         "hooks": [
           {
             "type": "command",
@@ -89,6 +91,7 @@
     ],
     "PostToolUse": [
       {
+        "matcher": "Bash|PowerShell|Monitor|TaskStop",
         "hooks": [
           {
             "type": "command",
@@ -100,6 +103,7 @@
     ],
     "PostToolUseFailure": [
       {
+        "matcher": "Bash|PowerShell|Monitor",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "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.",
   "mcpName": "ai.oddessentials/agent-guild",
   "license": "AGPL-3.0-only",
@@ -30,7 +30,8 @@
     "web/",
     "!web/yard/assets/",
     "config/",
-    "examples/"
+    "examples/",
+    "docs/api.md"
   ],
   "scripts": {
     "start": "node bin/agent-guild.mjs open",

package/src/manager/server.mjs

@@ -26,6 +26,8 @@ const MAX_BODY = 64 * 1024;
 // A reply, and a Docker Agent stop that carries one, is a whole answer, which Claude Code does not clip.
 const REPLY_BODY_LIMIT = 1024 * 1024;
 const MAX_WS_PAYLOAD = 1024 * 1024;
+// The API explorer (web/api.html) reads the doc itself.
+const API_DOC = path.join(path.dirname(require.resolve('../../package.json')), 'docs', 'api.md');
 const SLOW_CLIENT_BYTES = 8 * 1024 * 1024;
 
 const MIME = {
@@ -33,6 +35,7 @@ const MIME = {
   '.js': 'text/javascript; charset=utf-8',
   '.mjs': 'text/javascript; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
   '.svg': 'image/svg+xml',
   '.png': 'image/png',
   '.avif': 'image/avif',
@@ -271,6 +274,7 @@ export function createManagerServer({
       throw new HttpError(405, 'method not allowed', 'method_not_allowed');
     }
     if (vendor[pathname]) return serveFile(req, res, vendor[pathname], { cache: true });
+    if (pathname === '/api.md') return serveFile(req, res, API_DOC);
     let rel;
     try {
       rel = pathname === '/' ? 'index.html' : decodeURIComponent(pathname).replace(/^\/+/, '');
@@ -302,7 +306,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|context|reporting|shells|docker|reply|permission|turn)$/);
+    const reportMatch = route.match(/^\/sessions\/([a-f0-9]+)\/(agents|model|tool-session|context|reporting|shells|docker|reply)$/);
     if (reportMatch && method === 'POST') {
       const [, id, kind] = reportMatch;
       const body = await readJsonBody(req, kind === 'reply' || kind === 'docker' ? REPLY_BODY_LIMIT : MAX_BODY);
@@ -323,8 +327,6 @@ export function createManagerServer({
         manager.reportShell(id, body, auth);
         return sendJson(res, 200, { ok: true });
       }
-      if (kind === 'permission') return sendJson(res, 200, { permission: manager.reportPermission(id, body, auth) });
-      if (kind === 'turn') return sendJson(res, 200, { turn: manager.reportTurn(id, body, auth) });
       return sendJson(res, 200, { toolSessionId: manager.reportToolSession(id, body, auth) });
     }
 

package/src/manager/session-hooks.mjs

@@ -16,12 +16,11 @@ const handler = (extra = {}) => ({ type: 'command', command: REPORT_COMMAND, ...
 
 const shellEvents = (events, matcher) => Object.fromEntries(events.map((event) => [event, { group: { matcher } }]));
 
-// Shell commands and monitors are the only tool calls whose start is reported. StopFailure (an API error) ends a turn
-// like Stop, and PermissionDenied (auto mode) ends a command that PreToolUse started, since no PostToolUse follows a
-// denial. A permission request for any tool is reported, and so is the end of any call, which answers it.
+// Shell commands and monitors are the only tool calls reported. StopFailure (an API error) ends a turn like Stop, and
+// PermissionDenied (auto mode) ends a command that PreToolUse started, since no PostToolUse follows a denial.
 const CLAUDE_SHELL_TOOLS = 'Bash|PowerShell|Monitor';
 const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'PostModelSwitch', 'PreToolUse', 'PermissionRequest', 'PermissionDenied', 'PostToolUse', 'PostToolUseFailure', 'Stop', 'StopFailure', 'PostCompact'];
-const CLAUDE_MATCHERS = { PreToolUse: CLAUDE_SHELL_TOOLS };
+const CLAUDE_MATCHERS = { PreToolUse: CLAUDE_SHELL_TOOLS, PermissionRequest: CLAUDE_SHELL_TOOLS, PermissionDenied: CLAUDE_SHELL_TOOLS, PostToolUse: `${CLAUDE_SHELL_TOOLS}|TaskStop`, PostToolUseFailure: CLAUDE_SHELL_TOOLS };
 const CLAUDE_BLOCKING = new Set(['SubagentStart', 'PreToolUse']);
 export const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'Stop', 'Interrupt', 'SessionEnd', 'PostCompact'];
 const CODEX_MATCHERS = { PermissionRequest: 'Bash', PostToolUse: 'Bash' };

package/src/manager/session-manager.mjs

@@ -811,14 +811,6 @@ export class SessionManager extends EventEmitter {
     return this._reportingSession(id, auth).reportShell(report);
   }
 
-  reportPermission(id, report, auth) {
-    return this._reportingSession(id, auth).reportPermission(report);
-  }
-
-  reportTurn(id, report, auth) {
-    return this._reportingSession(id, auth).reportTurn(report);
-  }
-
   /**
    * A Docker Agent hook event. A session that was not started as Docker Agent (a Shell card the user ran it in, with
    * its own hooks) becomes one at its first event; the first Docker session heard from is then its main one.

package/src/manager/session.mjs

@@ -29,12 +29,6 @@ const SHELL_EVENTS = new Set(['start', 'waiting', 'asked', 'background', 'end',
 const SHELL_KINDS = new Set(['shell', 'monitor']);
 const MAX_SHELLS = 256;
 const MAX_ENDED_TASKS = 256;
-const PERMISSION_EVENTS = new Set(['request', 'done']);
-const TURN_STATES = new Set(['working', 'ended']);
-// Claude Code's PermissionRequest means the user is asked; Codex CLI's may be answered by its Guardian reviewer.
-const PERMISSION_REPORTING = new Set(['claude']);
-const TURN_REPORTING = new Set(['claude', 'codex']);
-const MAX_PERMISSION_CLEARS = 256;
 // Keys and reports a terminal sends as escape sequences: X10 mouse reports (three raw bytes after ESC [ M), other CSI
 // and SS3 sequences, OSC and DCS strings (to their end, or the next ESC, so a large paste is scanned once), and ESC
 // with one character (Alt+key). Bracketed paste markers are CSI, so pasted text is kept.
@@ -126,16 +120,6 @@ export class Session extends EventEmitter {
     this.toolSessionId = null;
     this.reply = null;
     this._replies = 0;
-    this._reportingActiveAt = null;
-    // Agent Guild's own hooks, not ones the user added, which may not cover every tool.
-    this._hooksSupplied = this.reporting?.state === 'pending';
-    // Open permission requests, by agent ('' for the main one) and call, each at its latest request; and when each
-    // call and each agent's requests were last answered, so a request that arrives after its own end stays closed.
-    this._permissions = new Map();
-    this._permissionClears = new Map();
-    this._agentPermissionClears = new Map();
-    this._permissionChangedAt = null;
-    this.turn = null;
     this.context = { compactions: count(opts.context?.compactions), resets: count(opts.context?.resets) };
     this.compactionRepeatMs = opts.compactionRepeatMs ?? 2000;
     this._compactionKeys = [];
@@ -508,10 +492,7 @@ export class Session extends EventEmitter {
     }
     const now = new Date().toISOString();
     const existing = this.agents.get(id);
-    if (status === 'done') {
-      this._endForegroundShells(id);
-      this._clearAgentPermissions(id, reportTime(report.at));
-    }
+    if (status === 'done') this._endForegroundShells(id);
     // A first report that already says done would only flash an icon:
     // Claude Code's internal helpers (prompt suggestions, side questions)
     // stop without ever having started here.
@@ -801,75 +782,9 @@ export class Session extends EventEmitter {
     if (report.reply !== null && typeof report.reply !== 'string') throw badRequest('reply must be a string or null');
     this._reportingHeard();
     const text = report.reply?.trim() || null;
-    this.reply = text ? { id: ++this._replies, text, at: new Date(reportTime(report.at)).toISOString() } : null;
+    this.reply = text ? { id: ++this._replies, text } : null;
     this._changed();
-    return this.reply && { id: this.reply.id, at: this.reply.at };
-  }
-
-  /**
-   * Claude Code asked to use a tool (request), or a call it asked about ended (done). A done ends only the request
-   * it follows; an interactive denial reports nothing, and the main agent's next turn report ends the wait.
-   */
-  reportPermission(report) {
-    if (!report || typeof report !== 'object') throw badRequest('permission report must be an object');
-    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
-    if (!PERMISSION_EVENTS.has(report.permission)) throw badRequest(`permission must be one of ${[...PERMISSION_EVENTS].join(', ')}`);
-    if (typeof report.match !== 'string' || !/^[a-f0-9]{32}$/.test(report.match)) throw badRequest('match must be a call hash');
-    this._reportingHeard();
-    const agent = typeof report.agentId === 'string' ? report.agentId.slice(0, 128) : '';
-    const key = `${agent}\n${report.match}`;
-    const at = reportTime(report.at);
-    if (report.permission === 'done') {
-      remember(this._permissionClears, key, at);
-      if (this._permissions.get(key) <= at) this._dropPermissions([key], at);
-    } else {
-      const answered = Math.max(this._permissionClears.get(key) ?? -Infinity, this._agentPermissionClears.get(agent) ?? -Infinity);
-      if (at > answered && !(this._permissions.get(key) >= at)) {
-        this._permissions.set(key, at);
-        this._changed();
-      }
-    }
-    return this._permissionJSON();
-  }
-
-  /** The main agent's turn: a prompt was submitted (working), or the turn ended, with or without a reply (ended). */
-  reportTurn(report) {
-    if (!report || typeof report !== 'object') throw badRequest('turn report must be an object');
-    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
-    if (!TURN_STATES.has(report.turn)) throw badRequest(`turn must be one of ${[...TURN_STATES].join(', ')}`);
-    this._reportingHeard();
-    const at = reportTime(report.at);
-    this._clearAgentPermissions('', at);
-    if (!this.turn || this.turn.at <= at) {
-      this.turn = { state: report.turn, at };
-      this._changed();
-    }
-    return this._turnJSON();
-  }
-
-  /** An agent's turn or the agent itself ended: every request it made before then was answered. */
-  _clearAgentPermissions(agent, at) {
-    remember(this._agentPermissionClears, agent, at);
-    const prefix = `${agent}\n`;
-    this._dropPermissions([...this._permissions].filter(([key, since]) => key.startsWith(prefix) && since <= at).map(([key]) => key), at);
-  }
-
-  _dropPermissions(keys, at) {
-    if (!keys.length) return;
-    for (const key of keys) this._permissions.delete(key);
-    if (this._permissions.size === 0) this._permissionChangedAt = at;
-    this._changed();
-  }
-
-  _permissionJSON() {
-    if (!PERMISSION_REPORTING.has(this.provider.reporting) || !this._hooksSupplied || this.status !== 'running' || this.reporting?.state !== 'active') return null;
-    if (this._permissions.size) return { state: 'waiting', since: new Date(Math.min(...this._permissions.values())).toISOString() };
-    return { state: 'none', since: new Date(this._permissionChangedAt ?? this._reportingActiveAt ?? Date.parse(this.startedAt)).toISOString() };
-  }
-
-  _turnJSON() {
-    if (!TURN_REPORTING.has(this.provider.reporting) || this.status !== 'running' || this.reporting?.state !== 'active' || !this.turn) return null;
-    return { state: this.turn.state, at: new Date(this.turn.at).toISOString() };
+    return this.reply && { id: this.reply.id };
   }
 
   reportHello() {
@@ -882,7 +797,6 @@ export class Session extends EventEmitter {
     clearTimeout(this._reportingTimer);
     if (!this.reporting || this.reporting.state === 'active') return;
     this.reporting = { state: 'active', reason: null };
-    this._reportingActiveAt = Date.now();
     this._changed();
   }
 
@@ -950,9 +864,7 @@ export class Session extends EventEmitter {
       model: this.model,
       toolSessionId: this.toolSessionId,
       context: { ...this.context },
-      reply: this.reply && { id: this.reply.id, at: this.reply.at },
-      permission: this._permissionJSON(),
-      turn: this._turnJSON(),
+      reply: this.reply && { id: this.reply.id },
       reporting: this.reporting,
       agents: [...this.agents.values()],
       shells: [...this.shells.values()].filter((s) => s.visible).map((s) => ({ id: s.id, kind: s.kind })),
@@ -960,20 +872,6 @@ export class Session extends EventEmitter {
   }
 }
 
-/** A report's time: when its hook started, in milliseconds, or now for one that has none or names a later time. */
-function reportTime(at) {
-  const now = Date.now();
-  return Number.isFinite(at) && at > 0 && at < now ? at : now;
-}
-
-/** Record a time under a key, keeping the latest and only the most recent keys. */
-function remember(map, key, at) {
-  const last = map.get(key) ?? -Infinity;
-  map.delete(key);
-  map.set(key, Math.max(last, at));
-  if (map.size > MAX_PERMISSION_CLEARS) map.delete(map.keys().next().value);
-}
-
 function count(value) {
   return Number.isSafeInteger(value) && value > 0 ? value : 0;
 }

package/src/report/hooks.mjs

@@ -39,10 +39,6 @@ const TOOL_START_EVENTS = new Set(['PreToolUse']);
 const TOOL_END_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
 const TURN_BOUNDARY_EVENTS = new Set(['UserPromptSubmit', 'Stop', 'StopFailure', 'Interrupt']);
 const PERMISSION_EVENTS = new Set(['PermissionRequest', 'PermissionDenied']);
-// A call Claude Code asked permission for ends with one of these; an interactive denial fires none of them.
-const PERMISSION_ENDS = new Set(['PostToolUse', 'PostToolUseFailure', 'PermissionDenied']);
-// What the main agent's own events say about its turn.
-const TURN_EVENTS = new Map([['UserPromptSubmit', 'working'], ['Stop', 'ended'], ['StopFailure', 'ended'], ['Interrupt', 'ended']]);
 const MAX_DETAIL = 200;
 
 const FINISHED_TASKS = new Set(['completed', 'failed', 'killed']);
@@ -57,14 +53,6 @@ export function commandHash(command) {
   return crypto.createHash('sha256').update(command.replace(/\s+/g, ' ').trim()).digest('hex').slice(0, 32);
 }
 
-const sortedJson = (value) => JSON.stringify(value, (_key, v) => (v && typeof v === 'object' && !Array.isArray(v)
-  ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]])) : v));
-
-/** A tool call by its name and input: Claude Code's PermissionRequest carries no call id. */
-export function callHash(toolName, toolInput) {
-  return crypto.createHash('sha256').update(`${toolName}\n${sortedJson(toolInput ?? null)}`).digest('hex').slice(0, 32);
-}
-
 function shellReport(event, input, toolName, subagentId) {
   const toolInput = input.tool_input || input.toolInput || {};
   const id = text(input.tool_use_id, input.toolUseId);
@@ -193,7 +181,6 @@ export function hookToReports(input) {
       reports.push({ shell: 'end', task: taskId.slice(0, 128), ...(toolUseId ? { key: toolUseId.slice(0, 128) } : {}) });
       if (FINISHED_TASKS.has(status)) reports.push({ agentId: `hook-${taskId}`, status: 'done' });
     }
-    if (!subagentId && !text(input.subagent_type, input.subagentType) && !taskNotifications(input.prompt)) reports.push({ turn: 'working' });
     return reports;
   }
 
@@ -242,16 +229,6 @@ export function hookToReports(input) {
     }
   }
 
-  // Claude Code only (turn_id is Codex's): Codex CLI runs PermissionRequest before its Guardian reviewer as well, so
-  // there it does not mean the user is being asked.
-  if (toolName && !text(input.turn_id) && (event === 'PermissionRequest' || PERMISSION_ENDS.has(event))) {
-    reports.push({
-      permission: event === 'PermissionRequest' ? 'request' : 'done',
-      match: callHash(toolName, input.tool_input ?? input.toolInput),
-      ...(subagentId ? { agentId: `hook-${subagentId}` } : {}),
-    });
-  }
-
   // Codex CLI: SubagentStop ended the previous turn of this agent; a new
   // prompt inside it, or a tool call of a turn inside it (turn_id is Codex's
   // own field, so Claude Code's internal helpers stay out), means the agent
@@ -272,7 +249,6 @@ export function hookToReports(input) {
   const reply = event !== 'Stop' || insideSubagent ? undefined
     : 'last_assistant_message' in input ? input.last_assistant_message : input.lastAssistantMessage;
   if (reply !== undefined) reports.push({ reply: typeof reply === 'string' ? reply : null });
-  if (!insideSubagent && TURN_EVENTS.has(event)) reports.push({ turn: TURN_EVENTS.get(event) });
 
   const model = insideSubagent || toolEvent || PERMISSION_EVENTS.has(event) ? null : event === 'PostModelSwitch'
     ? text(input.to_model)

package/web/api-doc.js

@@ -0,0 +1,30 @@
+// The API explorer's only list of routes is docs/api.md itself: its HTTP endpoint table, read here row by row.
+
+// `| METHOD | `path` | body | result |`, where the body may be empty or hold an escaped `\|`.
+const ROW = /^\| (GET|POST|PUT|PATCH|DELETE) \| `([^`]+)` \|((?:\\.|[^|\\])*)\| (.*) \|$/;
+
+/** Every row of the HTTP endpoint table: `{ method, path, params, query, body, result }`, in the doc's order. */
+export function endpoints(markdown) {
+  return markdown.split(/\r?\n/).map((line) => line.match(ROW)).filter(Boolean).map(([, method, route, body, result]) => {
+    const [path, search = ''] = route.split('?');
+    return {
+      method,
+      path,
+      params: [...path.matchAll(/:([a-z]+)/gi)].map(([, name]) => name),
+      query: search ? search.split('&').map((pair) => pair.split('=')[0]).filter(Boolean) : [],
+      body: body.trim().replaceAll('\\|', '|'),
+      result: result.trim(),
+    };
+  });
+}
+
+// The GET routes the explorer sends. Each returns the manager's own state and starts no more work than opening
+// the page does. The others are shown, not sent: some GETs run a tool, read files, or ask an outside service.
+export const READS = new Set([
+  '/health', '/info', '/sign-in', '/remote-access', '/notes', '/providers', '/news', '/yard-art', '/changelog',
+  '/github', '/sessions', '/sessions/:id', '/sessions/:id/reply',
+]);
+
+// The sockets the explorer listens to. It sends nothing on them, and a terminal is opened without `page`,
+// so it can never claim or resize one.
+export const SOCKETS = new Set(['/events', '/sessions/:id/terminal']);

package/web/api-explorer.js

@@ -0,0 +1,164 @@
+// docs/api.md as a page, with its read-only routes and sockets live. Unlinked: a developer opens /api.html.
+// Everything the manager answers is shown as text, never as HTML, and the token is never shown.
+import markdownit from './vendor/markdown-it.mjs';
+import { endpoints, READS, SOCKETS } from './api-doc.js';
+
+const TOKEN_KEY = 'agentGuild.token';
+const MAX_MESSAGES = 200;
+const MAX_MESSAGE_CHARS = 2048;
+
+const $ = (id) => document.getElementById(id);
+const load = () => { try { return localStorage.getItem(TOKEN_KEY); } catch { return null; } };
+const save = (value) => { try { localStorage.setItem(TOKEN_KEY, value); } catch {} };
+
+// The page's own sign-in, kept by the main page; a #token= link also works, and leaves the address at once.
+let token = new URLSearchParams(location.hash.slice(1)).get('token');
+if (token) {
+  save(token);
+  history.replaceState(null, '', location.pathname + location.search);
+} else token = load();
+
+function el(tag, props = {}, ...children) {
+  const node = Object.assign(document.createElement(tag), props);
+  node.append(...children);
+  return node;
+}
+
+// GitHub's heading ids, so the doc's links between its sections work here too.
+const slug = (text) => text.toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').trim().replace(/\s/g, '-');
+// The manager serves only this doc: a link to another one goes to it in the repository.
+const DOCS = 'https://github.com/oddessentials/agent-guild/blob/main/docs/';
+
+function render(markdown) {
+  const md = markdownit({ html: false });
+  md.core.ruler.push('heading_ids', (state) => {
+    state.tokens.forEach((t, i) => { if (t.type === 'heading_open') t.attrSet('id', slug(state.tokens[i + 1].content)); });
+  });
+  md.core.ruler.push('doc_links', (state) => {
+    for (const link of state.tokens.flatMap((t) => t.children ?? []).filter((t) => t.type === 'link_open')) {
+      const href = link.attrGet('href');
+      if (!href.startsWith('#') && !/^[a-z][a-z\d+.-]*:/i.test(href)) link.attrSet('href', new URL(href, DOCS).href);
+    }
+  });
+  $('doc').innerHTML = md.render(markdown);
+}
+
+const fill = (path, values) => path.replace(/:([a-z]+)/gi, (_, name) => encodeURIComponent(values[name]));
+
+function fields(entry) {
+  const inputs = new Map();
+  for (const name of [...entry.params, ...entry.query]) {
+    const param = entry.params.includes(name);
+    const input = el('input', { name, required: param, placeholder: param ? `:${name}` : name, autocomplete: 'off', spellcheck: false });
+    if (name === 'id') input.setAttribute('list', 'session-ids');
+    inputs.set(name, input);
+  }
+  return inputs;
+}
+
+function prettyJson(text) {
+  try { return JSON.stringify(JSON.parse(text), null, 2); } catch { return text; }
+}
+
+function requestPanel(entry) {
+  const inputs = fields(entry);
+  const sent = el('p', { className: 'sent' });
+  const status = el('p', { className: 'status' });
+  const out = el('pre');
+  const form = el('form', {}, ...[...inputs].map(([name, input]) => el('label', {}, name, input)), el('button', { type: 'submit' }, `Send GET`));
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const values = Object.fromEntries([...inputs].map(([name, input]) => [name, input.value.trim()]));
+    const search = new URLSearchParams(entry.query.filter((name) => values[name]).map((name) => [name, values[name]]));
+    const url = `/api/v1${fill(entry.path, values)}${search.size ? `?${search}` : ''}`;
+    sent.textContent = `GET ${url}  ·  Authorization: Bearer •••`;
+    status.textContent = 'Waiting…';
+    out.textContent = '';
+    const started = performance.now();
+    try {
+      const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` }, cache: 'no-store' });
+      const text = await res.text();
+      status.textContent = `${res.status} ${res.statusText}  ·  ${Math.round(performance.now() - started)} ms`;
+      out.textContent = prettyJson(text);
+    } catch {
+      status.textContent = 'No answer: Agent Guild may have stopped.';
+    }
+  });
+  return el('div', { className: 'try' }, form, sent, status, out);
+}
+
+function socketPanel(path) {
+  const inputs = fields({ params: [...path.matchAll(/:([a-z]+)/gi)].map(([, name]) => name), query: [] });
+  const button = el('button', { type: 'submit' }, 'Connect');
+  const status = el('p', { className: 'status' });
+  const log = el('pre');
+  const lines = [];
+  let socket = null;
+  const add = (text) => {
+    lines.push(text.length > MAX_MESSAGE_CHARS ? `${text.slice(0, MAX_MESSAGE_CHARS)} … (${text.length} characters)` : text);
+    if (lines.length > MAX_MESSAGES) lines.shift();
+    log.textContent = lines.join('\n');
+  };
+  const form = el('form', {}, ...[...inputs].map(([name, input]) => el('label', {}, name, input)), button);
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    if (socket) return socket.close();
+    const values = Object.fromEntries([...inputs].map(([name, input]) => [name, input.value.trim()]));
+    const route = `/api/v1${fill(path, values)}`;
+    lines.length = 0;
+    log.textContent = '';
+    // Listening only: nothing is ever sent, and a terminal without `page` cannot claim or resize.
+    socket = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}${route}?token=${encodeURIComponent(token)}`);
+    status.textContent = `Connecting to ${route}…`;
+    button.textContent = 'Disconnect';
+    socket.onopen = () => { status.textContent = `Listening to ${route}`; };
+    socket.onmessage = ({ data }) => add(typeof data === 'string' ? data : '(binary message)');
+    socket.onclose = ({ code }) => {
+      status.textContent = `Closed (${code})`;
+      button.textContent = 'Connect';
+      socket = null;
+    };
+  });
+  return el('div', { className: 'try' }, form, status, log);
+}
+
+function addPanels(markdown) {
+  const documented = new Map(endpoints(markdown).map((entry) => [`${entry.method} ${entry.path}`, entry]));
+  for (const row of $('doc').querySelectorAll('tbody tr')) {
+    const [method, route] = [...row.cells].map((cell) => cell.textContent.trim());
+    const entry = documented.get(`${method} ${route?.split('?')[0]}`);
+    if (!entry || entry.method !== 'GET') continue;
+    if (!READS.has(entry.path)) {
+      row.cells[row.cells.length - 1].append(el('span', { className: 'not-sent' }, 'Not sent from here: it can do more than read.'));
+      continue;
+    }
+    const cell = el('td', { colSpan: row.cells.length }, requestPanel(entry));
+    row.after(el('tr', {}, cell));
+  }
+  for (const heading of $('doc').querySelectorAll('h3')) {
+    const path = heading.textContent.match(/^GET \/api\/v1(\/\S+)$/)?.[1];
+    if (SOCKETS.has(path)) heading.after(socketPanel(path));
+  }
+}
+
+async function listSessions() {
+  try {
+    const res = await fetch('/api/v1/sessions', { headers: { Authorization: `Bearer ${token}` }, cache: 'no-store' });
+    if (res.status === 401) $('note').textContent = 'Agent Guild refused the sign-in this browser keeps. Open Agent Guild again, then reload.';
+    if (!res.ok) return;
+    const { sessions = [] } = await res.json();
+    $('session-ids').replaceChildren(...sessions.map((s) => el('option', { value: s.id, label: `${s.name ?? ''} (${s.status})` })));
+  } catch { /* each request says so itself */ }
+}
+
+const res = await fetch('./api.md', { cache: 'no-cache' }).catch(() => null);
+if (!res?.ok) $('note').textContent = 'This Agent Guild does not serve its API doc.';
+else {
+  const markdown = await res.text();
+  render(markdown);
+  if (!token) $('note').textContent = 'Open Agent Guild in this browser once, then reload: the explorer uses its sign-in.';
+  else {
+    addPanels(markdown);
+    listSessions();
+  }
+}

package/web/api.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="The Agent Guild API, read from its doc, with its read-only routes and sockets live.">
+  <title>Agent Guild API</title>
+  <link rel="icon" href="/brand/favicon.png" type="image/png">
+  <style>
+    :root { color-scheme: light dark; --fg: #1c1c1e; --muted: #6b6b70; --bg: #fff; --panel: #f4f4f6; --line: #d9d9de; --accent: #0a5fd6; }
+    @media (prefers-color-scheme: dark) { :root { --fg: #e8e8ea; --muted: #9a9aa0; --bg: #141416; --panel: #1f1f23; --line: #34343a; --accent: #6aa6ff; } }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+    main { max-width: 1100px; margin: 0 auto; padding: 16px; }
+    #note { margin: 0 0 12px; padding: 10px 12px; border-left: 3px solid var(--accent); background: var(--panel); }
+    #note:empty { display: none; }
+    a { color: var(--accent); }
+    code, pre, input { font: 13px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace; }
+    table { display: block; overflow-x: auto; border-collapse: collapse; margin: 12px 0; }
+    th, td { border: 1px solid var(--line); padding: 6px 8px; text-align: left; vertical-align: top; }
+    .not-sent { display: block; margin-top: 4px; color: var(--muted); font-size: 13px; }
+    .try { margin: 6px 0 12px; padding: 10px; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+    .try form { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+    .try label { display: flex; gap: 6px; align-items: center; }
+    .try input { min-width: 14ch; padding: 4px 6px; border: 1px solid var(--line); border-radius: 4px; background: var(--bg); color: var(--fg); }
+    .try button { padding: 4px 12px; border: 1px solid var(--accent); border-radius: 4px; background: transparent; color: var(--accent); font: inherit; cursor: pointer; }
+    .try .sent, .try .status { margin: 6px 0 0; color: var(--muted); font-size: 13px; }
+    .try pre { max-height: 420px; margin: 6px 0 0; padding: 8px; overflow: auto; background: var(--bg); border: 1px solid var(--line); border-radius: 4px; white-space: pre-wrap; overflow-wrap: anywhere; }
+    .try pre:empty { display: none; }
+  </style>
+</head>
+<body>
+  <main>
+    <p id="note" role="status"></p>
+    <div id="doc"></div>
+    <datalist id="session-ids"></datalist>
+  </main>
+  <script type="module" src="./api-explorer.js"></script>
+</body>
+</html>