@oddessentials/agent-guild 1.9.2 → 1.11.0

package/src/mcp/server.mjs

@@ -0,0 +1,400 @@
+// `agent-guild mcp`: a Model Context Protocol server on stdin and stdout, so a
+// coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor and others) can see
+// and steer the sessions of this computer's Agent Guild through its local API.
+//
+// It never returns the API token or the page link: either one gives full
+// control of every session, and anything a tool returns lands in the agent's
+// context. Typing into a session is off unless `--allow-input` turns it on.
+
+import readline from 'node:readline';
+import WebSocket from 'ws';
+import headless from '@xterm/headless';
+import { DEFAULT_HOST, VERSION, loadOrCreateToken, readRuntimeFile, resolvePort } from '../manager/config.mjs';
+import { cleanResumeId } from '../manager/resume-id.mjs';
+
+const { Terminal } = headless;
+
+/** Newest first; an older client gets its own version back when it is listed. */
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2024-11-05'];
+const REQUEST_TIMEOUT_MS = 10000;
+const START_TIMEOUT_MS = 50000;
+const SCREEN_TIMEOUT_MS = 5000;
+const SESSION_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const HIDDEN = '[token hidden]';
+// 64 bits of the known token; leave colors, short hashes and 12-digit session ids readable.
+const MIN_TOKEN_FRAGMENT = 16;
+
+const INSTRUCTIONS = `Agent Guild runs coding agents (Claude Code, Codex CLI, Antigravity CLI, Grok Build, Docker Agent) and shells in real terminals on this computer, and opens them on every other screen.
+Use guild_status first, list_sessions to see the sessions, read_reply for the answer that ended a session's last turn, and read_screen for what its terminal shows now.
+Ask the person before starting or stopping a session. Never ask for, print or store the Agent Guild page link or access token.`;
+
+const sessionId = { type: 'string', description: 'The session id from list_sessions.' };
+
+const TOOLS = [
+  {
+    name: 'guild_status',
+    title: 'Agent Guild status',
+    description: 'Whether Agent Guild is running on this computer, its version, and how many sessions it has.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'list_sessions',
+    title: 'List sessions',
+    description: 'Every session in Agent Guild: its id, tool, folder, status, whether it is working, its model, its sub-agents, and whether it has a reply to read.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'read_reply',
+    title: 'Read a reply',
+    description: "The whole text of the answer that ended a session's last turn, as Markdown. Only tools with reporting on (Claude Code, Codex CLI, Antigravity CLI, Grok Build, Docker Agent) have one.",
+    inputSchema: { type: 'object', properties: { session_id: sessionId }, required: ['session_id'], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'read_screen',
+    title: 'Read a terminal',
+    description: "The text a session's terminal shows right now, as plain lines. Use it to see a question the tool is waiting on.",
+    inputSchema: { type: 'object', properties: { session_id: sessionId }, required: ['session_id'], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'start_session',
+    title: 'Start a session',
+    description: 'Start a new session of a coding tool or shell in Agent Guild. Ask the person first. It opens on every screen connected to Agent Guild.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tool: { type: 'string', description: 'The tool: "claude", "codex", "antigravity", "grok", "docker" or "shell", or a provider id from guild_status.' },
+        cwd: { type: 'string', description: 'The folder to start in. Defaults to the home folder.' },
+        name: { type: 'string', description: "A name for the session's card." },
+        account: { type: 'string', description: 'The account id to run under. Defaults to "default".' },
+        resume: { type: 'string', description: "The id of one of the tool's own earlier sessions to resume." },
+      },
+      required: ['tool'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  },
+  {
+    name: 'stop_session',
+    title: 'Stop a session',
+    description: "End a session's process. Ask the person first. The session stays listed, with its final screen, until it is removed in Agent Guild.",
+    inputSchema: { type: 'object', properties: { session_id: sessionId }, required: ['session_id'], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  },
+];
+
+const INPUT_TOOL = {
+  name: 'send_input',
+  title: 'Type into a session',
+  description: "Type text into a session's terminal, as if the person typed it, and press Enter unless submit is false. Read the screen first, and send only what the person asked for.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      session_id: sessionId,
+      text: { type: 'string', description: 'The text to type.' },
+      submit: { type: 'boolean', description: 'Press Enter after the text. Defaults to true.' },
+    },
+    required: ['session_id', 'text'],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+};
+
+/** A refusal the agent should read, rather than a fault of the server. */
+class ToolError extends Error {}
+
+/** Where the running manager answers, as the launcher finds it. */
+export function managerUrl() {
+  const runtime = readRuntimeFile();
+  return runtime?.url || `http://${DEFAULT_HOST}:${resolvePort()}`;
+}
+
+export function createGuildClient({ url = managerUrl, token = loadOrCreateToken, startTimeoutMs = START_TIMEOUT_MS } = {}) {
+  const base = () => (typeof url === 'function' ? url() : url);
+  const secret = () => (typeof token === 'function' ? token() : token);
+  const auth = () => ({ Authorization: `Bearer ${secret()}` });
+  const notRunning = 'Agent Guild is not running on this computer. Ask the person to start it with `agent-guild` (or `agent-guild --no-browser`).';
+
+  async function health() {
+    try {
+      const res = await fetch(`${base()}/api/v1/health`, { signal: AbortSignal.timeout(2000) });
+      const body = res.ok ? await res.json() : null;
+      return body?.name === 'agent-guild' ? body : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const noSession = (id) => `No session has the id "${id}". Call list_sessions for the current ids.`;
+
+  async function api(path, { method = 'GET', body, session, timeoutMs = REQUEST_TIMEOUT_MS, late = 'Agent Guild did not answer in time. Try again.' } = {}) {
+    const request = {
+      method,
+      headers: { ...auth(), ...(body ? { 'Content-Type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+    let res;
+    try {
+      res = await fetch(`${base()}/api/v1${path}`, request);
+    } catch (err) {
+      throw new ToolError(err?.name === 'TimeoutError' ? late : notRunning);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (res.status === 401) throw new ToolError('Agent Guild refused the access token. Ask the person to restart Agent Guild with `agent-guild restart`.');
+    if (res.status === 404 && session) throw new ToolError(noSession(session));
+    if (!res.ok) throw new ToolError(data.error?.message || `Agent Guild answered HTTP ${res.status}.`);
+    return data;
+  }
+
+  /** Attach to a session's terminal until its first snapshot, then hand the socket and snapshot to `use`. */
+  function withTerminal(id, use) {
+    const ws = new WebSocket(`${base().replace(/^http/, 'ws')}/api/v1/sessions/${id}/terminal`, { headers: auth() });
+    return new Promise((resolve, reject) => {
+      const fail = (message) => { clearTimeout(timer); ws.terminate(); reject(new ToolError(message)); };
+      const timer = setTimeout(() => fail('Agent Guild did not send the terminal in time.'), SCREEN_TIMEOUT_MS);
+      ws.on('message', (raw) => {
+        let msg;
+        try { msg = JSON.parse(raw); } catch { return; }
+        if (msg.type === 'error') return fail(noSession(id));
+        if (msg.type !== 'snapshot') return undefined;
+        clearTimeout(timer);
+        Promise.resolve(use(ws, msg)).then(resolve, reject).finally(() => ws.close());
+        return undefined;
+      });
+      ws.on('unexpected-response', (_req, res) => fail(res.statusCode === 401 ? 'Agent Guild refused the access token.'
+        : res.statusCode === 404 ? noSession(id) : `Agent Guild answered HTTP ${res.statusCode}.`));
+      ws.on('error', () => fail(notRunning));
+      ws.on('close', (code) => { if (code === 4404) fail(noSession(id)); });
+    });
+  }
+
+  function redactor() {
+    let key = '';
+    try { key = secret(); } catch { /* no token to hide */ }
+    const gap = '(?:[\\s│┃|]|\\\\[nrt])*';
+    const spread = key && new RegExp(key.split('').join(gap), 'g');
+    const windows = [];
+    for (let i = 0; i + MIN_TOKEN_FRAGMENT <= key.length; i++) windows.push(key.slice(i, i + MIN_TOKEN_FRAGMENT).split('').join(gap));
+    const fragments = windows.length ? new RegExp(`(?=(${windows.join('|')}))`, 'g') : null;
+    const link = new RegExp(`#token=[0-9a-f](?:${gap}[0-9a-f]){0,63}(?![0-9A-Za-z])`, 'g');
+    const hide = (match) => match.replace(/[^\n]+/g, HIDDEN);
+    return (value) => {
+      value = (spread ? value.replace(spread, hide) : value).replace(link, (match) => `#token=${hide(match.slice(7))}`);
+      if (!fragments) return value;
+      // Merge overlapping known-token windows so a clipped span is hidden in full,
+      // including a final piece shorter than the minimum. Keep its original rows.
+      let result = '', start = 0, end = 0;
+      for (const match of value.matchAll(fragments)) {
+        if (match.index > end) {
+          result += hide(value.slice(start, end)) + value.slice(end, match.index);
+          start = match.index;
+        }
+        end = Math.max(end, match.index + match[1].length);
+      }
+      return result + hide(value.slice(start, end)) + value.slice(end);
+    };
+  }
+
+  return { health, api, withTerminal, redactor, notRunning, startTimeoutMs };
+}
+
+function checkId(id) {
+  if (typeof id !== 'string' || !SESSION_ID.test(id)) throw new ToolError('session_id must be a session id from list_sessions.');
+  return id;
+}
+
+function summarize(s) {
+  return {
+    id: s.id,
+    name: s.name,
+    tool: s.provider?.tool ?? s.provider?.vendor ?? null,
+    provider: s.provider?.id ?? null,
+    cwd: s.cwd,
+    status: s.status,
+    label: s.label,
+    working: s.status === 'running' && s.activity === 'active',
+    model: s.model ? s.model.displayName || s.model.name : null,
+    account: s.account?.id ?? null,
+    task: s.task,
+    agents: (s.agents ?? []).map((a) => ({ name: a.name, status: a.status, detail: a.detail ?? null })),
+    hasReply: s.reply != null,
+    startedAt: s.startedAt,
+    exitCode: s.exitCode,
+  };
+}
+
+/** The tool a person names, by id, command, tool name or vendor. */
+function findProvider(providers, wanted) {
+  const key = String(wanted ?? '').trim().toLowerCase();
+  if (!key) return null;
+  const names = (p) => [p.id, p.command, p.tool, p.vendor, p.command === '@shell' ? 'shell' : null]
+    .filter(Boolean).map((n) => String(n).toLowerCase());
+  return providers.find((p) => names(p).includes(key))
+    ?? providers.find((p) => names(p).some((n) => n.split(/[\s-]+/)[0] === key))
+    ?? null;
+}
+
+/** The visible screen of a snapshot, as text, from a headless terminal the same size. */
+function screenText({ data, cols, rows }, redact) {
+  const term = new Terminal({ cols, rows, scrollback: 1000, allowProposedApi: true });
+  return new Promise((resolve) => {
+    term.write(data, () => {
+      const buffer = term.buffer.active;
+      const all = [];
+      for (let y = 0; y < buffer.length; y++) all.push(buffer.getLine(y)?.translateToString(true) ?? '');
+      const lines = redact(all.join('\n')).split('\n').slice(buffer.viewportY, buffer.viewportY + term.rows);
+      term.dispose();
+      while (lines.length && !lines.at(-1).trim()) lines.pop();
+      resolve(lines.join('\n'));
+    });
+  });
+}
+
+const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+
+export function createToolHandlers(client, { allowInput = false } = {}) {
+  const handlers = {
+    async guild_status() {
+      const up = await client.health();
+      if (!up) return text({ running: false, message: client.notRunning, install: 'npm install -g @oddessentials/agent-guild' });
+      const [{ sessions = [] }, { providers = [] }] = await Promise.all([client.api('/sessions'), client.api('/providers')]);
+      return text({
+        running: true,
+        version: up.version,
+        sessions: sessions.length,
+        running_sessions: sessions.filter((s) => s.status === 'running').length,
+        working_sessions: sessions.filter((s) => s.status === 'running' && s.activity === 'active').length,
+        tools: providers.map((p) => ({ provider: p.id, tool: p.tool, installed: p.available === true })),
+      });
+    },
+    async list_sessions() {
+      const { sessions = [] } = await client.api('/sessions');
+      if (!sessions.length) return text('Agent Guild has no sessions.');
+      return text(sessions.map(summarize));
+    },
+    async read_reply({ session_id: id }) {
+      const { reply } = await client.api(`/sessions/${checkId(id)}/reply`, { session: id });
+      return text(reply?.text ?? 'This session has no finished reply yet. read_screen shows its terminal.');
+    },
+    async read_screen({ session_id: id }) {
+      return text(await client.withTerminal(checkId(id), (_ws, snapshot) => screenText(snapshot, client.redactor())) || '(The screen is blank.)');
+    },
+    async start_session({ tool, cwd, name, account, resume }) {
+      let resumeId = null;
+      try { resumeId = resume ? cleanResumeId(resume) : null; } catch (err) { throw new ToolError(err.message); }
+      const { providers = [] } = await client.api('/providers');
+      const provider = findProvider(providers, tool);
+      if (!provider) {
+        throw new ToolError(`Agent Guild has no tool called "${tool}". It has: ${providers.map((p) => `${p.id} (${p.tool})`).join(', ')}.`);
+      }
+      if (provider.available === false) {
+        throw new ToolError(`${provider.tool} is not installed. The person can install it from its card in Agent Guild${provider.install ? `, or with: ${provider.install}` : ''}.`);
+      }
+      // No `args`: launch flags such as --dangerously-skip-permissions are the person's to choose on the card.
+      const body = { providerId: provider.id };
+      for (const [key, value] of Object.entries({ cwd, name, account, resume: resumeId })) if (value) body[key] = String(value);
+      const { session } = await client.api('/sessions', {
+        method: 'POST',
+        body,
+        timeoutMs: client.startTimeoutMs,
+        late: 'Agent Guild did not finish starting the session in time, so whether it started is unknown: it may still appear. Call list_sessions before starting another.',
+      });
+      return text({ started: true, session: summarize(session) });
+    },
+    async stop_session({ session_id: id }) {
+      const { session } = await client.api(`/sessions/${checkId(id)}/stop`, { method: 'POST', session: id });
+      return text({ stopped: true, session: summarize(session) });
+    },
+  };
+  if (allowInput) {
+    handlers.send_input = async ({ session_id: id, text: typed, submit = true }) => {
+      if (typeof typed !== 'string') throw new ToolError('text must be a string.');
+      await client.withTerminal(checkId(id), (ws, snapshot) => new Promise((resolve, reject) => {
+        if (snapshot.session?.status !== 'running') throw new ToolError(`Session "${id}" has exited, so nothing was typed. start_session starts a new one.`);
+        ws.send(JSON.stringify({ type: 'input', data: typed + (submit ? '\r' : '') }), (err) => (err ? reject(new ToolError('The terminal closed before the text was sent.')) : resolve()));
+      }));
+      return text({ sent: true });
+    };
+  }
+  return handlers;
+}
+
+/**
+ * Serve MCP over newline-delimited JSON-RPC. Resolves when `input` ends.
+ * Only protocol messages go to `output`; nothing else may be written there.
+ */
+export function serveMcp({ input = process.stdin, output = process.stdout, allowInput = false, client = createGuildClient() } = {}) {
+  const tools = allowInput ? [...TOOLS, INPUT_TOOL] : TOOLS;
+  const handlers = createToolHandlers(client, { allowInput });
+  const hide = (value, redact) => {
+    if (typeof value === 'string') return redact(value);
+    if (Array.isArray(value)) return value.map((item) => hide(item, redact));
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, hide(item, redact)]));
+    return value;
+  };
+  const send = ({ id, ...body }) => output.write(`${JSON.stringify({ jsonrpc: '2.0', id, ...hide(body, client.redactor()) })}\n`);
+  const logError = (err) => console.error('[agent-guild mcp]', client.redactor()(String(err?.stack ?? err)));
+
+  async function call(name, args) {
+    const handler = Object.hasOwn(handlers, name) ? handlers[name] : null;
+    if (!handler) return { error: { code: -32602, message: `Unknown tool: ${name}` } };
+    try {
+      return { result: await handler(args ?? {}) };
+    } catch (err) {
+      if (err instanceof ToolError) return { result: { ...text(err.message), isError: true } };
+      logError(err);
+      return { result: { ...text('Agent Guild could not complete that request.'), isError: true } };
+    }
+  }
+
+  async function handle(msg) {
+    const { id, method, params } = msg;
+    const respond = id !== undefined && id !== null;
+    switch (method) {
+      case 'initialize': {
+        const asked = params?.protocolVersion;
+        return respond && send({ id, result: {
+          protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'agent-guild', title: 'Agent Guild', version: VERSION, websiteUrl: 'https://github.com/oddessentials/agent-guild/blob/main/docs/mcp.md' },
+          instructions: INSTRUCTIONS,
+        } });
+      }
+      case 'ping': return respond && send({ id, result: {} });
+      case 'tools/list': return respond && send({ id, result: { tools } });
+      case 'tools/call': {
+        const outcome = await call(params?.name, params?.arguments);
+        return respond && send({ id, ...outcome });
+      }
+      default:
+        // Notifications, such as notifications/initialized, need no answer.
+        return respond && send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+    }
+  }
+
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const pending = new Set();
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      send({ id: null, error: { code: -32700, message: 'Parse error' } });
+      return;
+    }
+    const isObject = msg !== null && typeof msg === 'object' && !Array.isArray(msg);
+    if (!isObject || typeof msg.method !== 'string') {
+      // Responses are ignored: this server sends no requests of its own.
+      if (!isObject || !('result' in msg || 'error' in msg)) send({ id: isObject ? msg.id ?? null : null, error: { code: -32600, message: 'Invalid Request' } });
+      return;
+    }
+    const job = handle(msg).catch(logError).finally(() => pending.delete(job));
+    pending.add(job);
+  });
+  return new Promise((resolve) => lines.once('close', () => Promise.allSettled([...pending]).then(() => resolve())));
+}

package/web/app.js

@@ -3414,10 +3414,10 @@ function closeNews() {
   if ($('news').open) $('news').close();
 }
 
-// Trailers and tutorials ship in web/videos.json, oldest first, and the page lists tutorials first. Nothing
+// Videos ship in web/videos.json, oldest first, and the page groups them like the channel's playlists. Nothing
 // reaches YouTube until the dialog opens, and a video plays only once YouTube's image server has answered for
 // its poster.
-const VIDEO_CATEGORIES = { tutorials: ['Tutorials', 'Tutorial'], trailers: ['Trailers', 'Trailer'] };
+const VIDEO_CATEGORIES = { tutorials: ['Tutorials', 'Tutorial'], trailers: ['Trailers', 'Trailer'], world: ['World', 'World'] };
 const VIDEO_ID = /^[\w-]{11}$/;
 const videosView = { list: [], filter: 'all', selected: null, play: false, poster: 0, opener: null };
 
@@ -3441,8 +3441,22 @@ function videoDate(video) {
   return Number.isNaN(date.getTime()) ? '' : date.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
 }
 
-function videoMeta(video) {
-  return [VIDEO_CATEGORIES[video.category][1], videoDate(video)].filter(Boolean).join(' · ');
+function videoLength(video) {
+  const seconds = video.duration;
+  if (!Number.isInteger(seconds) || seconds <= 0) return '';
+  const [h, m, s] = [Math.floor(seconds / 3600), Math.floor(seconds / 60) % 60, seconds % 60];
+  return [...(h ? [h, String(m).padStart(2, '0')] : [m]), String(s).padStart(2, '0')].join(':');
+}
+
+function videoLengthWords(video) {
+  const seconds = video.duration;
+  if (!videoLength(video) || !Intl.DurationFormat) return videoLength(video);
+  return new Intl.DurationFormat(undefined, { style: 'long' })
+    .format({ hours: Math.floor(seconds / 3600), minutes: Math.floor(seconds / 60) % 60, seconds: seconds % 60 });
+}
+
+function videoMeta(video, length = false) {
+  return [VIDEO_CATEGORIES[video.category][1], length && videoLength(video), videoDate(video)].filter(Boolean).join(' · ');
 }
 
 function shownVideos() {
@@ -3464,21 +3478,30 @@ function renderVideoFilters() {
   }));
 }
 
+function videoItem(video) {
+  const thumb = el('img', 'videos-thumb');
+  thumb.alt = '';
+  thumb.loading = 'lazy';
+  thumb.src = `https://i.ytimg.com/vi/${video.id}/mqdefault.jpg`;
+  thumb.addEventListener('error', () => { thumb.hidden = true; }, { once: true });
+  const length = videoLength(video) ? el('span', 'videos-length', videoLength(video)) : null;
+  length?.setAttribute('aria-hidden', 'true');
+  const item = el('button', 'videos-item', el('span', 'videos-frame', thumb, length),
+    el('span', 'videos-item-text', el('span', 'videos-item-title', video.title),
+      length && el('span', 'visually-hidden', `, ${videoLengthWords(video)}, `), el('span', 'news-meta', videoMeta(video))));
+  item.type = 'button';
+  item.dataset.id = video.id;
+  item.addEventListener('click', () => selectVideo(video, true));
+  if (video === videosView.selected) item.setAttribute('aria-current', 'true');
+  return el('li', null, item);
+}
+
 function renderVideoList() {
-  $('videos-list').replaceChildren(...shownVideos().map((video) => {
-    const thumb = el('img', 'videos-thumb');
-    thumb.alt = '';
-    thumb.loading = 'lazy';
-    thumb.src = `https://i.ytimg.com/vi/${video.id}/mqdefault.jpg`;
-    thumb.addEventListener('error', () => { thumb.hidden = true; }, { once: true });
-    const item = el('button', 'videos-item', el('span', 'videos-frame', thumb),
-      el('span', 'videos-item-text', el('span', 'videos-item-title', video.title), el('span', 'news-meta', videoMeta(video))));
-    item.type = 'button';
-    item.dataset.id = video.id;
-    item.addEventListener('click', () => selectVideo(video, true));
-    if (video === videosView.selected) item.setAttribute('aria-current', 'true');
-    return el('li', null, item);
-  }));
+  const shown = shownVideos();
+  const groups = Object.keys(VIDEO_CATEGORIES).map((id) => [id, shown.filter((video) => video.category === id)]).filter(([, videos]) => videos.length);
+  $('videos-list').replaceChildren(...groups.map(([id, videos]) => el('li', 'videos-group',
+    groups.length > 1 && el('h3', 'videos-group-title', VIDEO_CATEGORIES[id][0]),
+    el('ol', 'videos-group-list', ...videos.map(videoItem)))));
 }
 
 function stopVideo() {
@@ -3494,7 +3517,7 @@ function selectVideo(video, play) {
     else item.removeAttribute('aria-current');
   }
   $('videos-now').textContent = video.title;
-  $('videos-meta').textContent = videoMeta(video);
+  $('videos-meta').textContent = videoMeta(video, true);
   $('videos-youtube').href = `https://www.youtube.com/watch?v=${video.id}`;
   $('videos-play').setAttribute('aria-label', `Play ${video.title}`);
   const request = ++videosView.poster;

package/web/index.html

@@ -575,7 +575,7 @@
     <div class="models-bar">
       <div class="models-heading">
         <h2 id="videos-title">Videos</h2>
-        <p id="videos-sub" class="sub"></p>
+        <p class="sub"><span id="videos-sub"></span> · <a id="videos-channel" class="console-link" href="https://www.youtube.com/@Agent-Guild" target="_blank" rel="noopener noreferrer" aria-description="Opens in a new tab">@Agent-Guild on YouTube</a></p>
       </div>
       <button id="videos-close" class="btn" type="button">Close</button>
     </div>

package/web/styles.css

@@ -758,7 +758,7 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 .models-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 0 14px 14px; }
 .remote-access { width: min(560px, calc(100vw - 24px)); max-height: calc(100dvh - 24px); }
 .videos { width: min(1120px, calc(100vw - 32px)); }
-.videos-body { flex: 1 1 auto; min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) 320px; }
+.videos-body { flex: 1 1 auto; min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) min(320px, 45%); }
 .videos-stage { display: grid; align-content: start; gap: 12px; min-width: 0; padding: 16px; }
 /* The player keeps 16:9 and gives way to the bar and caption on short windows. */
 .videos-screen {
@@ -785,7 +785,9 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 .videos-caption h3 { margin: 0; font-size: 1rem; overflow-wrap: anywhere; }
 .videos-caption .news-meta { margin: 3px 0 0; }
 .videos-nav { display: flex; flex-direction: column; min-height: 0; overflow: auto; border-left: 1px solid var(--border); }
-.videos-list { list-style: none; margin: 0; padding: 8px; display: grid; gap: 2px; }
+.videos-list, .videos-group-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 2px; }
+.videos-list { padding: 8px; gap: 10px; }
+.videos-group-title { margin: 4px 6px; color: var(--muted); font-size: 0.72rem; font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
 .videos-item {
   display: grid; grid-template-columns: 128px minmax(0, 1fr); align-items: center; gap: 12px; width: 100%; padding: 6px;
   border: 0; border-radius: calc(var(--radius) - 2px); background: none; color: var(--text); font: inherit; text-align: left; cursor: pointer;
@@ -793,11 +795,15 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 .videos-item:hover, .videos-item[aria-current="true"] { background: var(--surface-2); }
 .videos-item[aria-current="true"] .videos-frame { outline: 2px solid var(--accent); outline-offset: 1px; }
 .videos-item:focus-visible { outline: 2px solid var(--focus); outline-offset: -2px; }
-.videos-frame { display: block; aspect-ratio: 16 / 9; overflow: hidden; border-radius: 4px; background: var(--surface-2); box-shadow: inset 0 0 0 1px var(--border); }
+.videos-frame { position: relative; display: block; aspect-ratio: 16 / 9; overflow: hidden; border-radius: 4px; background: var(--surface-2); box-shadow: inset 0 0 0 1px var(--border); }
 .videos-thumb { display: block; width: 100%; height: 100%; object-fit: cover; }
+.videos-length {
+  position: absolute; right: 4px; bottom: 4px; padding: 1px 4px; border-radius: 3px;
+  background: rgba(0, 0, 0, 0.78); color: #fff; font-size: 0.68rem; font-weight: 600; line-height: 1.3; font-variant-numeric: tabular-nums;
+}
 .videos-item-title { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; font-size: 0.85rem; font-weight: 600; line-height: 1.3; }
 .videos-item .news-meta { display: block; margin-top: 3px; white-space: normal; }
-@media (max-width: 900px) {
+@media (max-width: 900px) and (orientation: portrait) {
   .videos-body { display: flex; flex-direction: column; }
   .videos-stage { flex: none; }
   .videos-nav { flex: 1 1 auto; border-left: 0; border-top: 1px solid var(--border); }

package/web/videos.json

@@ -1,10 +1,16 @@
 {
   "videos": [
-    { "id": "ziT62WtXQ1M", "title": "Agent Guild Trailer", "category": "trailers", "published": "2026-10-01" },
-    { "id": "Zttp-vs_6z0", "title": "Agent Guild - The Yard Update v0.38.0", "category": "trailers", "published": "2026-10-07" },
-    { "id": "mEEI3cuOGzU", "title": "Docker-Agent Joins Agent Guild v0.47.0", "category": "trailers", "published": "2026-10-09" },
-    { "id": "XPSRCpiHokk", "title": "01 - Installation (Windows)", "category": "tutorials", "published": "2026-10-11" },
-    { "id": "5DRFbKgGoUk", "title": "01 - Installation (Linux Headless)", "category": "tutorials", "published": "2026-10-11" },
-    { "id": "QXIH4pv8CDk", "title": "02 - Claude and Codex Install", "category": "tutorials", "published": "2026-10-11" }
+    { "id": "xQ0cBp1wqhA", "title": "Run Them All: Launch Trailer (v0.1.0)", "category": "trailers", "published": "2026-10-01", "duration": 90 },
+    { "id": "5Pg85-_TvRI", "title": "The Yard Update (v0.38.0)", "category": "trailers", "published": "2026-10-07", "duration": 29 },
+    { "id": "C4aAHThCOeo", "title": "Docker Agent Joins the Guild (v0.47.0)", "category": "trailers", "published": "2026-10-09", "duration": 27 },
+    { "id": "unHsaXn4VL4", "title": "Install Agent Guild on Windows (Tutorial 1)", "category": "tutorials", "published": "2026-10-11", "duration": 153 },
+    { "id": "yPnUo7-cpHo", "title": "Add Claude Code and Codex (Tutorial 2)", "category": "tutorials", "published": "2026-10-11", "duration": 125 },
+    { "id": "OJ1n184WVc4", "title": "Run Agent Guild on a Headless Linux Server", "category": "tutorials", "published": "2026-10-11", "duration": 172 },
+    { "id": "n4uXFv6Xgcw", "title": "Agent Guild: World Official Trailer", "category": "world", "published": "2026-10-18", "duration": 62 },
+    { "id": "_vQuW0v-uMY", "title": "Built for Builders: Official Trailer", "category": "trailers", "published": "2026-10-23", "duration": 75 },
+    { "id": "qykaJBmkcM8", "title": "Quests and Glory: The Guild Board and Achievements", "category": "world", "published": "2026-10-23", "duration": 39 },
+    { "id": "tsrkFwj5cgQ", "title": "Use Agent Guild From Your Phone or Anywhere", "category": "tutorials", "published": "2026-10-23", "duration": 263 },
+    { "id": "nwAssNU0OVM", "title": "Happy Thanksgiving! New Workshop Pieces", "category": "world", "published": "2026-10-24", "duration": 43 },
+    { "id": "buiktzLc5yU", "title": "Everywhere: Official Trailer", "category": "trailers", "published": "2026-10-25", "duration": 92 }
   ]
 }