Public: anyone can read this; the crew can change it.

The agent card lists what a stranger may call, not all 199 tools, and agrees with llms.txt #12411

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/12398-the-agent-card-lists-what-a-stranger-may → main 7 commits fork 2 threads · 2 unresolved

  • Merged. torque/12398-the-agent-card-lists-what-a-stranger-may was merged into main as a46f303.

Review

Sign in to review this change.
3 files changed +85 −10
src/core/mcp_card.ts +32 −4
@@ -157,10 +157,10 @@ export const toolsKey = (): string => cardTools.map((t) => t.name).join(",");
157157 /**
158158 * The agent card (A2A, protocol 0.3.0, the stable subset: name, description,
159159 * url, version, protocolVersion, capabilities, default modes, skills; the
160 * sign-in is named by `securitySchemes`). One skill per MCP tool, from the
161 * same list `mcpCard` names under `tools`.
160 * sign-in is named by `securitySchemes`). With a token, one skill per MCP tool,
161 * from the same list `mcpCard` names under `tools`; without, see `agentSkills`.
162162 */
163 export function agentCard(origin: string, now: Running = running()) {
163 export function agentCard(origin: string, now: Running = running(), signedIn = true) {
164164 const { url, oauth } = mcpPointers(origin);
165165 return {
166166 protocolVersion: "0.3.0",
@@ -176,10 +176,38 @@ export function agentCard(origin: string, now: Running = running()) {
176176 mcp: { endpoint: url, card: `${origin}${DISCOVERY.card}`, protectedResourceMetadata: oauth, tokenFreeTools: [...TOKEN_FREE_TOOLS] },
177177 defaultInputModes: ["application/json"],
178178 defaultOutputModes: ["application/json"],
179 skills: cardTools.map((t) => ({ id: t.name, name: t.name, description: t.description, tags: ["mcp"] })),
179 // Which list `skills` is: "full" is every tool;
180 // "open" is the token-free ones and a count of the rest.
181 skillsScope: signedIn ? "full" : "open",
182 skills: agentSkills(origin, signedIn),
180183 };
181184 }
182185
186 /**
187 * How many tools an account opens beyond the token-free ones:
188 * the number /llms.txt prints for a stranger.
189 */
190 export const moreAfterSignIn = (): number => cardTools.filter((t) => !TOKEN_FREE_TOOLS.includes(t.name)).length;
191
192 /**
193 * A reader with a token gets one skill per tool; a stranger gets the
194 * token-free tools and one entry counting the rest (the card is the first
195 * thing an agent reads, so it stays small).
196 */
outdated

The signed-in branch returns the bare tool list. Issue box 2 asks the card to say it is the full list: add a field (e.g. skillsScope: "full" vs "open", or a leading sentence in the card description) so an agent can tell which one it holds, and test it.

197 function agentSkills(origin: string, signedIn: boolean) {
198 const skill = (t: { name: string; description: string }) => ({ id: t.name, name: t.name, description: t.description, tags: ["mcp"] });
199 if (signedIn) return cardTools.map(skill);
200 return [
201 ...cardTools.filter((t) => TOKEN_FREE_TOOLS.includes(t.name)).map(skill),
202 {
203 id: "more-after-sign-in",
204 name: "more-after-sign-in",
205 description: `${moreAfterSignIn()} more tools with an account: call tools/list on ${origin}/mcp once signed in.`,
206 tags: ["mcp", "sign-in"],
207 },
208 ];
209 }
210
183211 /**
184212 * The server card. The format is still a draft, so only what we can keep
185213 * true is named: who answers, where, over what transport, how to sign in,
src/web/standards.ts +5 −3
@@ -126,7 +126,7 @@ const discoveryBodies = new Map<string, { inputs: string; body: string; etag: st
126126 * body reads (the plugin repo offered, the running build), so the body is
127127 * made once per origin until that changes. A matching If-None-Match is a 304.
128128 */
129 function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, type: string, cache: string, pretty = false): Response {
129 function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, type: string, cache: string, pretty = false, vary?: string): Response {
130130 const key = `${kind} ${ctx.url.origin}`;
131131 let kept = discoveryBodies.get(key);
132132 if (kept === undefined || kept.inputs !== inputs) {
@@ -139,7 +139,7 @@ function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown,
139139 if (discoveryBodies.size >= 48) discoveryBodies.delete(discoveryBodies.keys().next().value!);
140140 discoveryBodies.set(key, kept);
141141 }
142 const headers = { etag: kept.etag, "cache-control": cache, "access-control-allow-origin": "*" };
142 const headers = { etag: kept.etag, "cache-control": cache, "access-control-allow-origin": "*", ...(vary !== undefined ? { vary } : {}) };
143143 if (holds(ctx.request.headers.get("if-none-match"), kept.etag)) return new Response(null, { status: 304, headers });
144144 return new Response(kept.body, { headers: { ...headers, "content-type": type } });
145145 }
@@ -159,7 +159,9 @@ export async function mcpJson(ctx: Ctx): Promise<Response> {
159159 export async function agentCardJson(ctx: Ctx): Promise<Response> {
160160 await loadMcp();
161161 const now = running();
162 return discovery(ctx, "agent-card", JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now), "application/json", "public, max-age=3600", true);
162 // The same reader test /llms.txt uses, so the two agree on who sees the full list.
163 const signedIn = ctx.auth.user !== undefined;
164 return discovery(ctx, `agent-card ${signedIn}`, JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now, signedIn), "application/json", signedIn ? "private, max-age=3600" : "public, max-age=3600", true, "Cookie, Authorization");
outdated

public, max-age=3600 is also sent when signedIn. Pass private, max-age=3600 for the signed-in variant; Vary alone does not stop shared caches from keeping an account-gated body.

163165 }
164166
165167 /** GET /.well-known/api-catalog — RFC 9727: one linkset naming each API's description and docs. Anonymous. */
test/agent-card.test.ts +48 −3
@@ -3,19 +3,28 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
33 import { mkdtemp, rm } from "node:fs/promises";
44 import { tmpdir } from "node:os";
55 import { join } from "node:path";
6 import { moreAfterSignIn, TOKEN_FREE_TOOLS } from "../src/core/mcp_card.ts";
67 import { createApp } from "../src/app.ts";
78 import { TOOLS } from "../src/http/mcp/tools.ts";
89 import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts";
10 import { createUser } from "../src/core/users.ts";
11 import { createToken } from "../src/core/tokens.ts";
912 import { serve, type Servers } from "../src/http/server.ts";
1013
1114 describe("the agent card", () => {
1215 let dataDir: string;
1316 let servers: Servers;
1417 let base: string;
18 let app: ReturnType<typeof createApp>;
19 let bearer: string;
1520 beforeAll(async () => {
1621 dataDir = await mkdtemp(join(tmpdir(), "forge-agent-card-"));
17 servers = await serve(createApp({ dataDir, port: 0 }));
22 app = createApp({ dataDir, port: 0 });
23 servers = await serve(app);
1824 base = servers.url;
25 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "cardreader", email: "[email protected]", password: "correct horse battery 1", isAdmin: false });
26 if (!made.ok) throw new Error("user");
27 bearer = createToken(app.db, made.value.id, "t", "rw").token;
1928 });
2029 afterAll(async () => {
2130 await servers.stop();
@@ -41,8 +50,11 @@ describe("the agent card", () => {
4150 expect(card.mcp.endpoint).toBe(card.url);
4251 });
4352
44 test("its skills are exactly the tools mcp.json lists", async () => {
45 const agent = (await (await fetch(`${base}/.well-known/agent-card.json`)).json()) as any;
53 const auth = () => ({ headers: { authorization: `Bearer ${bearer}` } });
54
55 test("with a token its skills are exactly the tools mcp.json lists", async () => {
56 const res = await fetch(`${base}/.well-known/agent-card.json`, auth());
57 const agent = (await res.json()) as any;
4658 const mcp = (await (await fetch(`${base}/.well-known/mcp.json`)).json()) as any;
4759 expect(mcp.tools.length).toBeGreaterThan(10);
4860 expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...mcp.tools].sort());
@@ -50,5 +62,38 @@ describe("the agent card", () => {
5062 const served = [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL].map((t) => t.name);
5163 expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...new Set(served)].sort());
5264 for (const s of agent.skills) expect(s.description.length).toBeGreaterThan(0);
65 expect(res.headers.get("vary")).toContain("Authorization");
66 expect(agent.skillsScope).toBe("full");
67 expect(agent.skills.some((s: any) => s.id === "more-after-sign-in")).toBe(false);
68 // An account's view is never stored by a shared cache.
69 expect(res.headers.get("cache-control")).toBe("private, max-age=3600");
70 });
71
72 test("a stranger gets the open tools and one line for the rest, under 8 KB", async () => {
73 const res = await fetch(`${base}/.well-known/agent-card.json`);
74 const text = await res.text();
75 expect(text.length).toBeLessThan(8 * 1024);
76 expect(res.headers.get("vary")).toContain("Authorization");
77 const ids = JSON.parse(text).skills.map((s: any) => s.id);
78 expect(JSON.parse(text).skillsScope).toBe("open");
79 expect(res.headers.get("cache-control")).toBe("public, max-age=3600");
80 expect(ids.at(-1)).toBe("more-after-sign-in");
81 expect(ids.slice(0, -1).sort()).toEqual([...TOKEN_FREE_TOOLS].sort());
82 });
83
84 test("the ETag differs by reader and each is honoured", async () => {
85 const a = await fetch(`${base}/.well-known/agent-card.json`);
86 const b = await fetch(`${base}/.well-known/agent-card.json`, auth());
87 expect(a.headers.get("etag")).not.toBe(b.headers.get("etag"));
88 const again = await fetch(`${base}/.well-known/agent-card.json`, { headers: { "if-none-match": a.headers.get("etag")! } });
89 expect(again.status).toBe(304);
90 });
91
92 test("the count the card gives a stranger is the number /llms.txt prints", async () => {
93 const card = (await (await fetch(`${base}/.well-known/agent-card.json`)).json()) as any;
94 const more = card.skills.at(-1).description.match(/^(\d+) more tools/)[1];
95 const llms = await (await fetch(`${base}/llms.txt`)).text();
96 expect(llms).toContain(`- ${more} more tools with an account`);
97 expect(Number(more)).toBe(moreAfterSignIn());
5398 });
5499 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs