@oddessentials/agent-guild 1.13.0 → 1.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.13.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(/^\/+/, '');

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>