@oddessentials/agent-guild 1.18.0 → 1.19.0

package/README.md

@@ -257,6 +257,7 @@ lets you try every skin.
 | `agent-guild stop` | Stop the manager and end every session. |
 | `agent-guild restart` | Restart the manager on the installed version and end every session. |
 | `agent-guild url` | Print the page link with the access token. |
+| `agent-guild fireworks` | Launch fireworks over every open Yard. A coding agent in any terminal can run it too. |
 | `agent-guild start` | Run the manager in the foreground. |
 | `agent-guild doctor` | Diagnose the health of the installation and related tooling. |
 | `agent-guild mcp` | Serve MCP on stdio, so a coding agent can see and steer the sessions. See [Agent Guild for agents](docs/mcp.md). |

package/bin/agent-guild.mjs

@@ -7,6 +7,7 @@
 //   agent-guild restart    stop the manager and start it again (ends all sessions)
 //   agent-guild status     show whether the manager is running
 //   agent-guild url        print the page URL (includes the access token)
+//   agent-guild fireworks  launch fireworks over every open Yard
 //   agent-guild mcp        serve the Model Context Protocol on stdio, for coding agents
 
 import fs from 'node:fs';
@@ -35,6 +36,7 @@ Commands:
   restart   Stop the session manager and start it again; ends every session
   status    Show whether the session manager is running
   url       Print the web page URL, including the access token
+  fireworks Launch fireworks over every open Yard
   doctor    Diagnose the health of the installation and related tooling
   mcp       Serve the Model Context Protocol on stdio, so a coding agent can
             see and steer the sessions (--allow-input lets it type into them)
@@ -287,6 +289,19 @@ async function cmdStatus() {
   }
 }
 
+async function cmdFireworks() {
+  const url = baseUrl();
+  if (!(await health(url))) {
+    console.log('Session manager is not running.');
+    process.exitCode = 3;
+    return;
+  }
+  const res = await fetch(`${url}/api/v1/yard/fireworks`, { method: 'POST', headers: { Authorization: `Bearer ${loadOrCreateToken()}` } });
+  if (!res.ok) throw new Error(`the session manager answered ${res.status}.`);
+  const { pages } = await res.json();
+  console.log(pages ? `Fireworks sent to ${pages} open page(s); every Yard on show lights up.` : 'No page is open to see the fireworks.');
+}
+
 const MIN_NODE_MAJOR = 22;
 
 async function main() {
@@ -335,6 +350,7 @@ async function main() {
       process.exitCode = ok ? 0 : 1;
       return undefined;
     }
+    case 'fireworks': return cmdFireworks();
     case 'url': {
       console.log(pageUrl(baseUrl(), loadOrCreateToken()));
       return undefined;

package/docs/api.md

@@ -132,7 +132,8 @@ listed them once.
 null when `GET /usage`, `GET /providers/:id/history`,
 `GET /providers/:id/memory` or `GET /providers/:id/instructions` cannot report
 the tool. `historyDetails` is true when `GET /providers/:id/history/detail`
-can read saved messages. `accounts` lists the sign-ins the tool can run
+can read saved messages: for every built-in history source, not for a
+`command`. `accounts` lists the sign-ins the tool can run
 under: `default` is the tool's own, and each further one has its own home
 folder, so it keeps its own sign-in and usage. `POST /sessions` takes an
 account id. `accountsEditable` is true when accounts can be added, renamed
@@ -260,7 +261,7 @@ account, true when one was read, and null when that is unknown.
   "providerId": "anthropic",
   "accountId": "default",
   "sessions": [
-    { "id": "581893e5-a93d-5e49-968b-1c1c277d3255", "title": "Fix the login bug", "cwd": "/Users/me/src/app", "startedAt": "2026-10-01T13:26:53.713Z", "updatedAt": "2026-10-01T13:49:28.000Z" }
+    { "id": "581893e5-a93d-5e49-968b-1c1c277d3255", "name": "Login bug", "title": "Fix the login bug", "cwd": "/Users/me/src/app", "startedAt": "2026-10-01T13:26:53.713Z", "updatedAt": "2026-10-01T13:49:28.000Z" }
   ],
   "total": 42,
   "fetchedAt": "2026-10-01T14:00:00.000Z",
@@ -269,16 +270,19 @@ account, true when one was read, and null when that is unknown.
 ```
 
 The tool's own earlier sessions, newest first. `id` is what the tool resumes
-by (`POST /sessions` with `resume`); `title` is the session's name or first
-prompt, or null; `cwd` is the folder the session ran in, or null. Claude Code
+by (`POST /sessions` with `resume`); `name` is the name a card holding
+that session was given, or null; `title` is the name the tool gave the
+session, else its first prompt, or null; `cwd` is the folder the session ran
+in, or null. Claude Code
 finds a session only from its own folder, so resume with that `cwd`.
 `sessions` holds at most `limit` entries of the `total` found. `error` says
 why nothing could be listed; a tool that has never run lists no sessions and
 no error. Antigravity CLI entries add `workspaces`, and its history may add a
 `note`.
 
-The optional `cwd` and `q` parameters filter by folder and by text (title, id
-or folder) **before** applying `limit`; `total` counts matching entries.
+The optional `cwd` and `q` parameters filter by folder and by text (name,
+title, id or folder) **before** applying `limit`; `total` counts matching
+entries. Filtering uses the listing only and never reads a conversation.
 
 #### Saved messages
 
@@ -291,16 +295,26 @@ or folder) **before** applying `limit`; `total` counts matching entries.
     "messages": [{ "role": "user", "text": "Fix the login bug" }],
     "nextCursor": null,
     "incomplete": false,
-    "omitted": false
+    "omitted": false,
+    "truncated": false
   }
 }
 ```
 
-Only the user's requests and the visible answers are included, as plain text.
-Follow `nextCursor` until it is null, even when a page has no visible
-messages. `omitted` says records were left out; `incomplete` says the last one
-was partial, and a later read may complete it. 409 `history_changed` means the
-transcript changed: start again without a cursor.
+Only the user's requests and the visible answers are included, as plain text:
+no thinking, tool calls or results, text the tool inserted, or turns it
+rewound or rolled back. The first page holds the newest messages; each
+`nextCursor` reads the page before it, and messages within a page are oldest
+first. Every message is whole. Follow `nextCursor` until it is null, even when
+a page has no visible messages. `omitted` says records were left out, such as
+an unreadable one the tool itself skips; `truncated` says the history ends
+early, at a record too large to read or one that cannot be read safely, and
+nothing before it is shown; `incomplete` says the newest record was still being
+written, and a later read may complete it. Messages added after the first page
+appear when it is read again without a cursor. 409 `history_changed` means
+the part a cursor depends on was rewritten, truncated or replaced: start again
+without a cursor. 413 `history_too_large` means a compressed Codex rollout
+decodes to more than 64 MiB.
 
 ### Memory
 
@@ -618,6 +632,7 @@ All paths are under `/api/v1`.
 | GET | `/yard-art` | | `{ yardArt }`: the Yard's art. `state` is `ready`, `missing`, `downloading` (with `received` bytes), `installing`, `failed` or `unavailable` (each with `error`), or `cancelled`; `size` is the pack's size in bytes. A checkout serves `web/yard/assets` and is always `ready`. `/yard/assets/` answers 404 until the art is `ready`. |
 | POST | `/yard-art/download` | | `202 { yardArt }`: starts the one download of the art pack named by the package, unless it is running or installed. Progress and the outcome arrive as `yard-art.updated`. |
 | POST | `/yard-art/cancel` | | `{ yardArt }`: stops the download for every client; the state becomes `cancelled`. |
+| POST | `/yard/fireworks` | | `{ ok, pages }`: fireworks over the Yard of every open page, sent as `yard.fireworks`. `pages` is how many pages were listening. |
 | GET | `/changelog` | | `{ refreshing, okAt, error, releases }`: Agent Guild's own releases, newest first, each `{ version, url, publishedAt, sections: [{ title, changes }] }`, where `title` may be null and a change is a list of text runs. A `changelog.updated` event follows a refresh. |
 | GET | `/providers/:id/history?account=&limit=&cwd=&q=` | | `{ history }`: a History object for one account (default `default`). |
 | GET | `/providers/:id/history/detail?account=&id=&cursor=` | | `{ detail }`; see [Saved messages](#saved-messages). |
@@ -664,7 +679,11 @@ All paths are under `/api/v1`.
 `cwd` defaults to the user's home folder, and a leading `~` is expanded.
 `args` are appended to the provider's configured arguments. `resume` is an
 id or name of one of the tool's own sessions; one that starts with `-` is
-refused with 400 `bad_resume`. `account` defaults to `default`.
+refused with 400 `bad_resume`. `account` defaults to `default`. A session
+resumed without a `name` gets back the name a card holding it was given.
+A name given to a session, by `name` or a rename, is kept for every tool
+session the card holds; renaming the card to its default name drops it for
+the tool session it holds then.
 
 The `POST /sessions/:id/…` report routes (`agents`, `model`, `tool-session`,
 `context`, `reply`, `reporting`, `docker` and `shells`) also accept the per-session
@@ -695,6 +714,7 @@ but `{ type: "ping" }`, which the manager answers with `{ type: "pong" }`.
 | `{ type: "environment.updated", environment }` | An environment check started or finished. |
 | `{ type: "news.updated" }` | Fetch `/news` again. |
 | `{ type: "yard-art.updated", yardArt }` | The Yard's art changed state or made download progress, as in `/yard-art`. |
+| `{ type: "yard.fireworks" }` | Fireworks over the Yard, when it is on show. |
 | `{ type: "changelog.updated" }` | Fetch `/changelog` again. |
 | `{ type: "github.updated" }` | Fetch `/github` again. |
 | `{ type: "remote-access.updated" }` | Fetch `/remote-access` again. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "1.18.0",
+  "version": "1.19.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.",
   "mcpName": "ai.oddessentials/agent-guild",
   "license": "AGPL-3.0-only",

package/src/manager/antigravity-transcript.mjs

@@ -2,11 +2,9 @@
 // or the binary conversation/implicit stores as conversation text.
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
 import { antigravityUserConversation } from '../report/hooks.mjs';
 
 export const ANTIGRAVITY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-export const TRANSCRIPT_PAGE_BYTES = 256 * 1024;
 
 export function historyError(status, code, message) {
   return Object.assign(new Error(message), { status, code });
@@ -15,14 +13,13 @@ export function historyError(status, code, message) {
 /** Reject links below the provider home, including a linked conversation or logs folder. */
 export async function transcriptFile(dir, id) {
   if (!ANTIGRAVITY_ID.test(id)) throw historyError(400, 'bad_history_id', 'Invalid conversation id.');
-  let file = await fs.promises.realpath(dir);
+  const unavailable = () => historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
+  let file = await fs.promises.realpath(dir).catch(() => { throw unavailable(); });
   const parts = ['brain', id, '.system_generated', 'logs', 'transcript.jsonl'];
   for (const [i, part] of parts.entries()) {
     file = path.join(file, part);
-    const stat = await fs.promises.lstat(file);
-    if (stat.isSymbolicLink() || (i === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())) {
-      throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
-    }
+    const stat = await fs.promises.lstat(file).catch(() => { throw unavailable(); });
+    if (stat.isSymbolicLink() || (i === parts.length - 1 ? !stat.isFile() : !stat.isDirectory())) throw unavailable();
   }
   return file;
 }
@@ -39,66 +36,3 @@ export function transcriptMessage(record) {
   }
   return text?.trim() ? { role, text: text.trim() } : null;
 }
-
-/** One bounded byte page. A cursor pins the file revision; partial final lines wait for Refresh. */
-export async function readAntigravityTranscript(dir, id, cursor = null) {
-  let handle;
-  try {
-    handle = await fs.promises.open(await transcriptFile(dir, id), 'r');
-    const stat = await handle.stat();
-    const revision = createHash('sha256').update(`${id}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`).digest('hex').slice(0, 24);
-    let offset = 0, skipping = false;
-    if (cursor) {
-      if (typeof cursor !== 'string' || cursor.length > 256) {
-        throw historyError(400, 'bad_history_cursor', 'Invalid conversation page.');
-      }
-      let value;
-      try { value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); } catch { /* invalid below */ }
-      if (!value || !Number.isSafeInteger(value.offset)
-        || value.offset < 0 || typeof value.skipping !== 'boolean' || typeof value.revision !== 'string') {
-        throw historyError(400, 'bad_history_cursor', 'Invalid conversation page.');
-      }
-      if (value.revision !== revision) throw historyError(409, 'history_changed', 'The conversation changed. Refresh to read it again.');
-      if (value.offset > stat.size) throw historyError(400, 'bad_history_cursor', 'Invalid conversation page.');
-      ({ offset, skipping } = value);
-    }
-    // Check the first record on every request, including requests using a supplied cursor.
-    const head = Buffer.alloc(Math.min(stat.size, TRANSCRIPT_PAGE_BYTES));
-    const firstRead = await handle.read(head, 0, head.length, 0);
-    const headEnd = head.subarray(0, firstRead.bytesRead).indexOf(10);
-    let first;
-    try { first = JSON.parse(head.subarray(0, headEnd < 0 ? firstRead.bytesRead : headEnd).toString('utf8')); } catch { /* unavailable */ }
-    if (!antigravityUserConversation(first)) throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
-    const buffer = offset === 0 ? head : Buffer.alloc(Math.min(stat.size - offset, TRANSCRIPT_PAGE_BYTES));
-    const bytesRead = offset === 0 ? firstRead.bytesRead : (await handle.read(buffer, 0, buffer.length, offset)).bytesRead;
-    const data = buffer.subarray(0, bytesRead);
-    const messages = [];
-    let start = 0, omitted = false;
-    for (let end; (end = data.indexOf(10, start)) >= 0;) {
-      if (skipping) { skipping = false; omitted = true; }
-      else if (end > start) {
-        try {
-          const message = transcriptMessage(JSON.parse(data.subarray(start, end).toString('utf8')));
-          if (message) messages.push(message);
-        } catch { omitted = true; }
-      }
-      start = end + 1;
-    }
-    const atEnd = offset + bytesRead >= stat.size;
-    const incomplete = atEnd && start < bytesRead;
-    // Leave a split record for the next page. An oversized record is skipped in bounded pieces.
-    if (!atEnd && start === 0) { start = bytesRead; skipping = true; omitted = true; }
-    const nextCursor = !atEnd && bytesRead > 0
-      ? Buffer.from(JSON.stringify({ offset: offset + start, skipping, revision })).toString('base64url') : null;
-    const after = await handle.stat();
-    if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) {
-      throw historyError(409, 'history_changed', 'The conversation changed. Refresh to read it again.');
-    }
-    return { id, messages, nextCursor, incomplete, omitted };
-  } catch (err) {
-    if (err.status) throw err;
-    throw historyError(404, 'history_unavailable', 'This conversation transcript is unavailable.');
-  } finally {
-    await handle?.close();
-  }
-}

package/src/manager/card-names.mjs

@@ -0,0 +1,110 @@
+// Names given to cards, by provider, account and the tool's own session id.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const CARD_NAMES_LIMIT = 5000;
+const FILE_LIMIT = 4 * 1024 * 1024;
+
+const key = (providerId, accountId, toolSessionId) => `${providerId}\0${accountId}\0${toolSessionId}`;
+
+function readNames(file) {
+  let stat;
+  try { stat = fs.statSync(file); } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  if (!stat.isFile() || stat.size > FILE_LIMIT) throw new Error('not a names file');
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (value?.version !== 1 || !Array.isArray(value.names)) throw new Error('not a names file');
+  return value.names.filter((n) => n && typeof n.provider === 'string' && typeof n.account === 'string' && typeof n.id === 'string'
+    && typeof n.name === 'string' && n.name && typeof n.at === 'string');
+}
+
+function writeNames(file, names) {
+  const contents = `${JSON.stringify({ version: 1, names }, null, 2)}\n`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const next = `${file}.${randomUUID()}.tmp`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(next, 'wx', 0o600);
+    fs.writeFileSync(descriptor, contents);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(next, file);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    try { fs.unlinkSync(next); } catch { /* renamed, or never created */ }
+  }
+  try { fs.chmodSync(file, 0o600); } catch { /* not supported on Windows */ }
+}
+
+/**
+ * @param {string} [file] omit for an in-memory store (tests). The real manager passes its names file.
+ * @param {{ limit?: number, warn?: (message: string) => void, now?: () => string }} [options]
+ */
+export function createCardNames(file, { limit = CARD_NAMES_LIMIT, warn = (message) => console.warn(message), now = () => new Date().toISOString() } = {}) {
+  let names = null;
+  let warned = false;
+
+  /** An unreadable file is read again next time and never overwritten, so fixing or removing it needs no restart. */
+  function load() {
+    if (names) return names;
+    if (!file) return (names = new Map());
+    try {
+      names = new Map(readNames(file).map((n) => [key(n.provider, n.account, n.id), n]));
+      warned = false;
+    } catch {
+      if (!warned) warn(`[names] ${file} cannot be read, so card names are not kept until it is fixed or removed.`);
+      warned = true;
+      return null;
+    }
+    return names;
+  }
+
+  function save(current) {
+    if (!file) return true;
+    try {
+      writeNames(file, [...current.values()]);
+      return true;
+    } catch (err) {
+      warn(`[names] could not save card names: ${err.message}`);
+      return false;
+    }
+  }
+
+  return {
+    get(providerId, accountId, toolSessionId) {
+      return load()?.get(key(providerId, accountId, toolSessionId))?.name ?? null;
+    },
+    /** True once the name is stored. The cache changes only with the file, so a failed save is retried by the next call. */
+    set(providerId, accountId, toolSessionId, name) {
+      const current = load();
+      if (!current) return false;
+      const k = key(providerId, accountId, toolSessionId);
+      if (current.get(k)?.name === name) return true;
+      const next = new Map(current);
+      // Newest last, so the oldest are dropped first.
+      next.delete(k);
+      next.set(k, { provider: providerId, account: accountId, id: toolSessionId, name, at: now() });
+      while (next.size > limit) next.delete(next.keys().next().value);
+      if (!save(next)) return false;
+      names = next;
+      return true;
+    },
+    /** True once no name is stored. */
+    delete(providerId, accountId, toolSessionId) {
+      const current = load();
+      if (!current) return false;
+      const k = key(providerId, accountId, toolSessionId);
+      if (!current.has(k)) return true;
+      const next = new Map(current);
+      next.delete(k);
+      if (!save(next)) return false;
+      names = next;
+      return true;
+    },
+  };
+}

package/src/manager/config.mjs

@@ -47,6 +47,7 @@ export const paths = {
   get remoteAccess() { return path.join(dataDir(), 'remote-access.json'); },
   /** The shared notepad. A missing file means it was never stored. */
   get notes() { return path.join(dataDir(), 'notes.json'); },
+  get cardNames() { return path.join(dataDir(), 'card-names.json'); },
   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'); },