@oddessentials/agent-guild 1.18.0 → 1.20.0

package/README.md

@@ -7,6 +7,8 @@
   <img src="https://img.shields.io/node/v/@oddessentials/agent-guild?color=4cc38a" alt="Node.js version">
 </p>
 
+<p align="center"><strong>English</strong> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.zh-TW.md">繁體中文</a></p>
+
 **Run Claude Code, Codex CLI, Antigravity CLI, Grok Build, Docker Agent and
 your own shells side by side in real terminals. Pick the same live sessions up
 from your phone, VS Code or any browser. Free, on Windows, macOS and Linux.**
@@ -58,11 +60,15 @@ then connects over [MCP](docs/mcp.md) to see and steer your sessions.
   Codex CLI.
 * **The same session on every screen.** Any browser, a phone over
   [Tailscale](#remote-access-with-tailscale) with touch keys, VS Code, and
-  apps for [Apple Vision Pro](https://apps.apple.com/us/app/agent-guild-remote/id6825451331),
-  iPhone and iPad (beta) and
-  [Android](https://github.com/oddessentials/agent-guild-android/releases/latest).
+  the Agent Guild app: iPhone, iPad and Apple Vision Pro on the
+  [App Store](https://apps.apple.com/us/app/agent-guild-remote/id6825451331);
+  Android, Android TV, Google TV and Android XR on
+  [Google Play](https://play.google.com/store/apps/details?id=com.oddessentials.agentguild)
+  or [GitHub](https://github.com/oddessentials/agent-guild-android/releases/latest);
+  Fire tablets and Fire TV on the [Amazon Appstore](https://www.amazon.com/dp/B0HPLBDYPR);
+  and Meta Quest on the [Meta Horizon Store](https://www.meta.com/experiences/1325496170657270/).
   Apple Watch and Meta Ray-Ban Display list your sessions and read a
-  session's last answer aloud.
+  session's last answer aloud. See [what each screen needs](https://agentguild.oddessentials.ai/requirements/).
 * **Native on Windows.** No WSL. Also macOS, Linux, and headless Linux
   servers over SSH.
 * **Nothing in between.** No account and no relay server: the manager
@@ -257,6 +263,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/README.zh-CN.md

@@ -0,0 +1,67 @@
+<h1 align="center">Agent Guild</h1>
+
+<p align="center"><a href="README.md">English</a> · <strong>简体中文</strong> · <a href="README.zh-TW.md">繁體中文</a></p>
+
+**在你自己的电脑上，用真正的终端并排运行 Claude Code、Codex CLI、Antigravity CLI、
+Grok Build、Docker Agent 和你自己的 shell。在手机、VS Code 或任何浏览器上接着用同一批
+正在运行的会话。免费，支持 Windows、macOS 和 Linux。**
+
+Agent Guild 是一个运行在你电脑上的小管理器，提供一个本地网页。网页随时可以关掉，会话照常运行。
+
+<a href="https://oddessentials.github.io/agent-guild/?view=yard&skin=guild&theme=dark"><picture>
+  <source media="(prefers-reduced-motion: reduce)" srcset="docs/images/yard-still.webp">
+  <img src="docs/images/yard-clip.webp" alt="七个编程智能体会话化身为 Guild Yard 里的角色：它们离开广场前往各自工具的大厅开始工作；双击其中一个，就会打开 Claude Code 的真实终端" width="100%">
+</picture></a>
+
+**[试玩演示](https://oddessentials.github.io/agent-guild/?view=yard&skin=guild&theme=dark)**：
+在浏览器里逛一逛 Yard。模拟数据，免费，无需账号，什么都不用安装。
+
+## 快速开始
+
+需要 Node.js 22 或更新版本：
+
+```sh
+npm install -g @oddessentials/agent-guild
+agent-guild
+```
+
+网页会自动在浏览器中打开。在某个工具的卡片上按 **New** 即可启动会话。
+每个工具在第一个会话里照常登录，和在任何终端里一样。
+
+**或者交给你的智能体。** 让它读取
+[安装技能](https://github.com/oddessentials/agent-guild/blob/main/plugins/agent-guild/skills/setup-agent-guild/SKILL.md)，
+它会安装并检查 Agent Guild，然后通过 [MCP](docs/mcp.md) 连接，查看并操控你的会话。
+
+## 为什么选 Agent Guild
+
+* **原版 CLI，原封不动。** 每个会话都是工具本身，跑在真实终端里，而不是聊天界面的复制品。
+  工具支持的登录方式都能用：订阅、API key、Amazon Bedrock 或你自己的网关。
+* **所有智能体，一处管理。** Claude Code、Codex CLI、Antigravity CLI、Grok Build、
+  Docker Agent、任意 shell，以及 tmux 或 herdr 会话。Claude Code、Codex CLI 和
+  Grok Build 可以同时登录多个账号；Claude Code 和 Codex 账号的用量上限实时可见。
+* **同一个会话，每块屏幕。** 任何浏览器；通过 Tailscale 在手机上使用，带触屏按键；
+  VS Code；以及 Agent Guild 应用：iPhone、iPad 和 Apple Vision Pro（[App Store](https://apps.apple.com/us/app/agent-guild-remote/id6825451331)），
+  Android、Android TV、Google TV 和 Android XR（[Google Play](https://play.google.com/store/apps/details?id=com.oddessentials.agentguild)），Fire 平板和 Fire TV
+  （[Amazon Appstore](https://www.amazon.com/dp/B0HPLBDYPR)），[Meta Horizon Store](https://www.meta.com/experiences/1325496170657270/)。Apple Watch 和 Meta Ray-Ban Display
+  会列出你的会话，并朗读某个会话的最后一条回答。
+* **Yard：看着它们干活。** 每个会话都是 3D 世界里的一个角色。等你回复的会被标出来；
+  CI 通过时 Yard 会放烟花。双击任何一个角色，就能打开它的真实终端直接输入。
+* **原生支持 Windows。** 无需 WSL。也支持 macOS、Linux，以及通过 SSH 使用的无头 Linux 服务器。
+* **中间没有任何东西。** 不需要账号，没有中转服务器。其他设备通过你自己的 Tailscale
+  网络或反向代理访问。开启远程访问后，拿到二维码或链接的人都能使用你的终端。
+
+尚未支持：推送通知。
+
+完整的功能、设置和命令说明见 [英文 README](README.md)。
+
+## 链接
+
+* 网站：https://agentguild.oddessentials.ai
+* 各设备的要求：https://agentguild.oddessentials.ai/requirements/
+* App：[App Store](https://apps.apple.com/us/app/agent-guild-remote/id6825451331) · [Google Play](https://play.google.com/store/apps/details?id=com.oddessentials.agentguild) · [Amazon Appstore](https://www.amazon.com/dp/B0HPLBDYPR) · [Meta Horizon Store](https://www.meta.com/experiences/1325496170657270/) · [GitHub 上的 Android 版](https://github.com/oddessentials/agent-guild-android/releases/latest)
+* VS Code：[Marketplace](https://marketplace.visualstudio.com/items?itemName=OddEssentials.agent-guild) · [Open VSX](https://open-vsx.org/extension/OddEssentials/agent-guild)（Cursor、Windsurf 等编辑器）
+* [Agent Guild: World](https://store.steampowered.com/app/5462970/Agent_Guild_World/)：Steam 上的 3D 世界
+* YouTube：https://www.youtube.com/@Agent-Guild
+* X：https://x.com/agentguild_3d
+
+以 [GNU AGPL 3.0](LICENSE) 开源。

package/README.zh-TW.md

@@ -0,0 +1,67 @@
+<h1 align="center">Agent Guild</h1>
+
+<p align="center"><a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <strong>繁體中文</strong></p>
+
+**在你自己的電腦上，用真正的終端機並排執行 Claude Code、Codex CLI、Antigravity CLI、
+Grok Build、Docker Agent 和你自己的 shell。在手機、VS Code 或任何瀏覽器上接著使用同一批
+正在執行的工作階段。免費，支援 Windows、macOS 和 Linux。**
+
+Agent Guild 是一個在你電腦上執行的小型管理程式，提供一個本機網頁。網頁隨時可以關掉，工作階段照常執行。
+
+<a href="https://oddessentials.github.io/agent-guild/?view=yard&skin=guild&theme=dark"><picture>
+  <source media="(prefers-reduced-motion: reduce)" srcset="docs/images/yard-still.webp">
+  <img src="docs/images/yard-clip.webp" alt="七個程式設計代理的工作階段化身為 Guild Yard 裡的角色：它們離開廣場前往各自工具的大廳開始工作；雙擊其中一個，就會開啟 Claude Code 的真實終端機" width="100%">
+</picture></a>
+
+**[試玩展示](https://oddessentials.github.io/agent-guild/?view=yard&skin=guild&theme=dark)**：
+在瀏覽器裡逛逛 Yard。模擬資料，免費，不需要帳號，什麼都不用安裝。
+
+## 快速開始
+
+需要 Node.js 22 或更新版本：
+
+```sh
+npm install -g @oddessentials/agent-guild
+agent-guild
+```
+
+網頁會自動在瀏覽器中開啟。在某個工具的卡片上按 **New** 就能啟動工作階段。
+每個工具在第一個工作階段裡照常登入，和在任何終端機裡一樣。
+
+**或者交給你的代理。** 讓它讀取
+[安裝技能](https://github.com/oddessentials/agent-guild/blob/main/plugins/agent-guild/skills/setup-agent-guild/SKILL.md)，
+它會安裝並檢查 Agent Guild，然後透過 [MCP](docs/mcp.md) 連線，查看並操控你的工作階段。
+
+## 為什麼選 Agent Guild
+
+* **原版 CLI，原封不動。** 每個工作階段都是工具本身，跑在真實的終端機裡，而不是聊天介面的複製品。
+  工具支援的登入方式都能用：訂閱、API 金鑰、Amazon Bedrock 或你自己的閘道。
+* **所有代理，一處管理。** Claude Code、Codex CLI、Antigravity CLI、Grok Build、
+  Docker Agent、任何 shell，以及 tmux 或 herdr 工作階段。Claude Code、Codex CLI 和
+  Grok Build 可以同時登入多個帳號；Claude Code 和 Codex 帳號的用量上限即時可見。
+* **同一個工作階段，每個螢幕。** 任何瀏覽器；透過 Tailscale 在手機上使用，附觸控按鍵；
+  VS Code；以及 Agent Guild App：iPhone、iPad 和 Apple Vision Pro（[App Store](https://apps.apple.com/us/app/agent-guild-remote/id6825451331)），
+  Android、Android TV、Google TV 和 Android XR（[Google Play](https://play.google.com/store/apps/details?id=com.oddessentials.agentguild)），Fire 平板和 Fire TV
+  （[Amazon Appstore](https://www.amazon.com/dp/B0HPLBDYPR)），[Meta Horizon Store](https://www.meta.com/experiences/1325496170657270/)。Apple Watch 和 Meta Ray-Ban Display
+  會列出你的工作階段，並朗讀某個工作階段的最後一則回答。
+* **Yard：看著它們工作。** 每個工作階段都是 3D 世界裡的一個角色。等你回覆的會被標示出來；
+  CI 通過時 Yard 會放煙火。雙擊任何一個角色，就能開啟它的真實終端機直接輸入。
+* **原生支援 Windows。** 不需要 WSL。也支援 macOS、Linux，以及透過 SSH 使用的無頭 Linux 伺服器。
+* **中間沒有任何東西。** 不需要帳號，沒有中繼伺服器。其他裝置透過你自己的 Tailscale
+  網路或反向代理連線。開啟遠端存取後，拿到 QR code 或連結的人都能使用你的終端機。
+
+尚未支援：推播通知。
+
+完整的功能、設定和指令說明請見 [英文 README](README.md)。
+
+## 連結
+
+* 網站：https://agentguild.oddessentials.ai
+* 各裝置的需求：https://agentguild.oddessentials.ai/requirements/
+* App：[App Store](https://apps.apple.com/us/app/agent-guild-remote/id6825451331) · [Google Play](https://play.google.com/store/apps/details?id=com.oddessentials.agentguild) · [Amazon Appstore](https://www.amazon.com/dp/B0HPLBDYPR) · [Meta Horizon Store](https://www.meta.com/experiences/1325496170657270/) · [GitHub 上的 Android 版](https://github.com/oddessentials/agent-guild-android/releases/latest)
+* VS Code：[Marketplace](https://marketplace.visualstudio.com/items?itemName=OddEssentials.agent-guild) · [Open VSX](https://open-vsx.org/extension/OddEssentials/agent-guild)（Cursor、Windsurf 等編輯器）
+* [Agent Guild: World](https://store.steampowered.com/app/5462970/Agent_Guild_World/)：Steam 上的 3D 世界
+* YouTube：https://www.youtube.com/@Agent-Guild
+* X：https://x.com/agentguild_3d
+
+以 [GNU AGPL 3.0](LICENSE) 開源。

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.20.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'); },