Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
/**
* Generate the method-to-tool table in README.md and docs/arguments.md from
* src/coverage.ts, the table the drift test reads.
*
* npm run docs:generate rewrite both
* npm run docs:check fail when the committed copies are stale
*/
import { readFile, writeFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { camelCase, TOOL_COVERAGE } from "../src/coverage.js";
const root = new URL("../../", import.meta.url);
const readmePath = fileURLToPath(new URL("README.md", root));
const argumentsPath = fileURLToPath(new URL("docs/arguments.md", root));
const START = "<!-- generated:methods:start -->";
const END = "<!-- generated:methods:end -->";
/** Routes outside MCP: the read-only API and the admin entry point. */
const HTTP_ROWS: readonly [string, string][] = [
["identity", "`GET /identity`"],
["capabilities", "`initialize`, `tools/list`, `GET /identity`, `GET /api/v1/workspaces`"],
["api.workspaces", "`GET /api/v1/workspaces`"],
["api.projects", "`GET /api/v1/projects`"],
["api.pages", "`GET /api/v1/workspaces/{w}/projects/{p}/pages`"],
["api.page", "`GET /api/v1/workspaces/{w}/projects/{p}/pages/{path}`"],
["api.recent", "`GET /api/v1/workspaces/{w}/projects/{p}/recent?updated_since=`"],
["api.search", "`GET` or `POST /api/v1/search`"],
["api.briefing", "`GET /api/v1/workspaces/{w}/projects/{p}/briefing`"],
["api.handoffs", "`GET /api/v1/workspaces/{w}/projects/{p}/handoffs`"],
["api.sessions", "`GET /api/v1/workspaces/{w}/projects/{p}/sessions`"],
["api.observations", "`GET /api/v1/workspaces/{w}/projects/{p}/sessions/{id}/observations`"],
["AdminClient.checkpoints", "`GET /admin/checkpoints`"],
["AdminClient.restorePage", "`POST /admin/restore-page`"],
["AdminClient.purgeSession", "`POST /admin/purge-session`"],
["AdminClient.purgeProject", "`POST /admin/purge-project`"],
];
function methodTable(): string {
const lines = ["| SDK method | Server call |", "|---|---|"];
const rows: [string, string][] = [];
for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
if (entry.status !== "wrapped") continue;
for (const method of entry.methods) rows.push([method, `\`${tool}\``]);
}
const merged = new Map<string, string[]>();
for (const [method, call] of [...rows, ...HTTP_ROWS]) {
merged.set(method, [...(merged.get(method) ?? []), call]);
}
for (const [method, calls] of merged) lines.push(`| \`${method}\` | ${calls.join(", ")} |`);
lines.push("", "Not wrapped (call them with `callTool`):", "");
for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
if (entry.status === "not_exposed") lines.push(`- \`${tool}\`: ${entry.reason}`);
}
return lines.join("\n");
}
function argumentsDoc(): string {
const lines = [
"# Argument names",
"",
"<!-- Generated by `npm run docs:generate` from src/coverage.ts. Do not edit by hand. -->",
"",
"SDK arguments are the server's wire names in camelCase. `workspace` and",
"`project` travel inside `scope`; `messages.send` takes `to` and `from` scopes",
"for the `to_*` and `from_*` pairs.",
"",
];
for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
if (entry.status !== "wrapped") continue;
lines.push(`## \`${tool}\``, "", `Methods: ${entry.methods.map((m) => `\`${m}\``).join(", ")}`, "");
lines.push("| Wire name | SDK name |", "|---|---|");
for (const wire of entry.sends) lines.push(`| \`${wire}\` | \`${camelCase(wire)}\` |`);
lines.push("");
}
return lines.join("\n");
}
function withTable(readme: string): string {
const start = readme.indexOf(START);
const end = readme.indexOf(END);
if (start === -1 || end === -1 || end < start) {
throw new Error(`README.md lacks the ${START} / ${END} markers`);
}
return `${readme.slice(0, start + START.length)}\n${methodTable()}\n${readme.slice(end)}`;
}
const mode = process.argv[2];
const readme = await readFile(readmePath, "utf8");
const wantReadme = withTable(readme);
const wantArguments = argumentsDoc();
if (mode === "--write") {
await writeFile(readmePath, wantReadme);
await writeFile(argumentsPath, wantArguments);
console.log("wrote README.md method table and docs/arguments.md");
} else if (mode === "--check") {
const stale: string[] = [];
if (readme !== wantReadme) stale.push("README.md method table");
const current = await readFile(argumentsPath, "utf8").catch(() => "");
if (current !== wantArguments) stale.push("docs/arguments.md");
if (stale.length > 0) {
console.error(`stale generated docs: ${stale.join(", ")}; run \`npm run docs:generate\``);
process.exit(1);
}
console.log("generated docs are current");
} else {
console.error("usage: generate-docs.js --write|--check");
process.exit(2);
}