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

The page manifest knows the docs, changelog, templates, sign-in, sign-up, status and agents pages, and says what an agent can do on each #13859

Merged opened this

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

Merged

scout/forge:scout/13849-the-page-manifest-knows-the-docs-changel → main 4 commits fork 3 threads · 3 unresolved

  • Merged. scout/13849-the-page-manifest-knows-the-docs-changel was merged into main as 0ab19fd.

Review

Sign in to review this change.
3 files changed +219 −10
src/actions/here.ts +139 −9
@@ -63,7 +63,7 @@ export interface Action {
6363
6464 export interface Manifest {
6565 readonly here:
66 | { readonly kind: "forge" | "explore" | "search" }
66 | { readonly kind: "forge" | "explore" | "search" | KeptPage }
6767 | { readonly kind: "person"; readonly username: string }
6868 | { readonly kind: "org"; readonly org: string }
6969 | {
@@ -96,6 +96,34 @@ export interface Manifest {
9696
9797 const SYSTEM = new Set(SYSTEM_NAMES);
9898
99 /** The pages the forge keeps that have their own kind and their own actions. */
100 const KEPT_PAGES = [
101 "docs",
102 "changelog",
103 "templates",
104 "signin",
105 "signup",
106 "status",
107 "agents",
108 ] as const;
109 type KeptPage = (typeof KEPT_PAGES)[number];
110
111 function keptPage(
112 owner: string | undefined,
113 name: string | undefined,
114 section: string | undefined,
115 ) {
116 const o = owner?.toLowerCase();
117 if (o === "changelog.atom") return "changelog" as const;
118 const found = KEPT_PAGES.find((k) => k === o);
119 // Only `/docs/x` and `/templates/x` have a page below them, one deep.
120 return found !== undefined &&
121 section === undefined &&
122 (name === undefined || found === "docs" || found === "templates")
123 ? found
124 : undefined;
125 }
126
99127 // `tell` and `plan` file issues too, but as directing the crew, a different
100128 // verb with a different check (`mayDirectCrew`).
101129 const NO_ISSUE_TOOL =
@@ -131,11 +159,13 @@ export function manifestFor(
131159 name === undefined && (owner === "explore" || owner === "search")
132160 ? owner
133161 : undefined;
162 const kept = page === undefined ? keptPage(owner, name, section) : undefined;
134163 // One segment, or `/:owner/-/…`, that is not a page the forge keeps for
135164 // itself names an account: a person, an organization, or nobody.
136165 if (
137166 owner !== undefined &&
138167 page === undefined &&
168 kept === undefined &&
139169 (name === undefined || name === "-") &&
140170 !SYSTEM.has(owner.toLowerCase())
141171 ) {
@@ -185,15 +215,9 @@ export function manifestFor(
185215 SYSTEM.has(owner.toLowerCase())
186216 )
187217 return ok({
outdated

keptActions is called twice per forge action here; bind it once and filter.

188 here: { kind: page ?? "forge" },
218 here: { kind: page ?? kept ?? "forge" },
189219 you: youFor(viewer, scope, undefined, app),
190 can:
191 page === undefined
192 ? forgeActions(app, viewer, scope)
193 : [
194 pageRead(page, path),
195 ...forgeActions(app, viewer, scope).filter((a) => a.mcp !== page),
196 ],
220 can: actionsFor(app, viewer, scope, path, page, kept),
197221 ...common,
198222 });
199223 const repo = getRepo(app.db, owner, name.replace(/\.git$/, ""));
@@ -292,6 +316,112 @@ function pageRead(page: "explore" | "search", path: string): Action {
292316 };
293317 }
294318
319 /** The page's own actions first, then the forge's, less any the page already names. */
320 function actionsFor(
321 app: App,
322 viewer: User | undefined,
323 scope: Parameters<typeof forgeActions>[2],
324 path: string,
325 page: "explore" | "search" | undefined,
326 kept: KeptPage | undefined,
327 ): Action[] {
328 const generic = forgeActions(app, viewer, scope);
329 if (kept !== undefined) {
330 const own = keptActions(app, kept, path, viewer);
331 return [...own, ...generic.filter((a) => !own.some((k) => k.http === a.http))];
332 }
333 if (page === undefined) return generic;
334 return [pageRead(page, path), ...generic.filter((a) => a.mcp !== page)];
335 }
336
337 /** What an agent does on a page the forge keeps, ahead of the generic list. */
338 function keptActions(
339 app: App,
340 kept: KeptPage,
341 path: string,
342 viewer: User | undefined,
343 ): Action[] {
344 const q = new URL(path, "http://forge.invalid").searchParams.get("q") ?? "";
345 switch (kept) {
346 case "docs":
347 return [
348 {
349 do: `search the guide${q === "" ? "" : `: ${q.slice(0, 200)}`}`,
350 http: `GET /docs?q=${encodeURIComponent(q.slice(0, 80))}`,
351 account: false,
352 },
353 {
354 do: "read a guide page, as HTML (/llms.txt lists them)",
355 http: "GET /docs/{name}",
356 noMcp: "no MCP tool reads the guide; fetch the page",
357 account: false,
358 },
359 ];
360 case "changelog":
outdated

The action says it reads the markdown source, but the route serves rendered HTML. Be honest or add the raw route.

361 return [
362 { do: "read what went live", http: "GET /api/v1/changelog", mcp: "releases" },
363 { do: "follow it as a feed", http: "GET /changelog.atom", account: false },
364 ];
365 case "templates":
366 return [
367 {
368 do: "list the templates",
369 http: "GET /api/v1/templates",
370 mcp: "templates",
371 account: false,
372 },
373 {
374 do: "start a forge from one",
375 http: "POST /api/v1/forges {template}",
376 mcp: "spawn",
377 mcpArgs: { template: "id" },
378 ...(viewer === undefined ? { account: true } : {}),
379 },
380 ];
381 case "signin":
382 case "signup":
383 return viewer !== undefined
384 ? []
385 : [
386 {
387 do: "make an account: {username, email, password}, as the signup setting allows",
388 http: "POST /api/v1/users",
389 noMcp: "an account comes before a token, so before the MCP",
390 account: false,
391 },
392 {
393 do: "a passkey needs a person at a browser; when signup is passkey-only, ask one to make the account",
394 http: "GET /signin",
395 noMcp: "a passkey is a person's",
396 account: false,
397 },
398 ];
399 case "status":
400 return [
401 {
402 do: "read the forge's state as JSON (Accept: application/json)",
403 http: "GET /status",
404 noMcp: "send the Accept header; the page is for people",
405 account: false,
406 },
407 ];
408 case "agents":
409 return [
410 ...(getAgentStart(app.db) === "off"
411 ? []
412 : [
413 {
414 do: "start building with no account",
415 http: "POST /api/v1/start",
416 mcp: "start",
417 ...tokenFree("start"),
418 },
419 ]),
420 { do: "read the machine-readable guide", http: "GET /llms.txt", account: false },
421 ];
422 }
423 }
424
295425 function forgeActions(
296426 app: App,
297427 viewer: User | undefined,
test/here-manifest.test.ts +71
@@ -12,6 +12,7 @@ import { newApp, updateAppSettings } from "../src/actions/apps.ts";
1212 import { addToCrew, createAgent } from "../src/actions/crew.ts";
1313 import { createApp, type App } from "../src/app.ts";
1414 import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts";
15 import { setAgentStart } from "../src/settings/agent_start.ts";
1516 import { createToken } from "../src/core/tokens.ts";
1617 import { createUser, type User } from "../src/core/users.ts";
1718 import { markVerified, resetVerification } from "../src/core/verify.ts";
@@ -556,4 +557,74 @@ describe("the manifest: what you can do here, as who you are", () => {
556557 expect(reads[0].http).toBe("GET /api/v1/explore?q=kind:app");
557558 expect(body.can.filter((a: any) => a.mcp === "search").length).toBe(1);
558559 });
560
561 test("the pages the forge keeps each have their own kind and actions", async () => {
562 const cases: [string, string, string][] = [
563 ["/docs?q=roles", "docs", "GET /docs?q=roles"],
564 ["/docs/CREW.md", "docs", "GET /docs/{name}"],
565 ["/changelog", "changelog", "GET /changelog.atom"],
566 ["/templates", "templates", "POST /api/v1/forges {template}"],
567 ["/signin", "signin", "POST /api/v1/users"],
568 ["/signup", "signup", "POST /api/v1/users"],
569 ["/status", "status", "GET /status"],
570 ["/agents", "agents", "GET /llms.txt"],
571 ];
572 for (const [path, kind, http] of cases) {
573 const { body } = await manifest(path);
574 expect(body.here).toEqual({ kind });
575 expect(body.can.map((a: any) => a.http)).toContain(http);
576 expect(body.can[0].http).not.toBe("GET /api/v1/explore?q=");
577 }
578 const log = (await manifest("/changelog")).body;
579 expect(log.can.some((a: any) => a.mcp === "releases")).toBe(true);
580 const t = (await manifest("/templates")).body;
581 expect(t.can.find((a: any) => a.mcp === "spawn").account).toBe(true);
582 const mine = (await manifest("/templates", "alice")).body;
583 expect(mine.can.find((a: any) => a.mcp === "spawn").account).toBeUndefined();
584 // Signed in, there is no account to make.
585 const si = (await manifest("/signin", "alice")).body;
586 expect(si.here.kind).toBe("signin");
587 expect(si.can.map((a: any) => a.http)).not.toContain("POST /api/v1/users");
588 });
589
590 test("/agents lists start only while the agent-start setting is not off", async () => {
591 const starts = async () =>
592 (await manifest("/agents")).body.can.map((a: any) => a.http);
593 setAgentStart(app.db, "off", usersByName["alice"]!.id);
594 expect(await starts()).not.toContain("POST /api/v1/start");
595 setAgentStart(app.db, "open", usersByName["alice"]!.id);
596 expect(await starts()).toContain("POST /api/v1/start");
597 });
598
599 test("/changelog.atom and /docs/x map to their kinds; deeper or extra segments stay forge", async () => {
600 expect((await manifest("/changelog.atom")).body.here.kind).toBe("changelog");
601 expect((await manifest("/docs/x")).body.here.kind).toBe("docs");
602 for (const p of ["/docs/a/b", "/status/x", "/agents/x", "/changelog/x"]) {
603 expect((await manifest(p)).body.here.kind).not.toBe(p.split("/")[1]);
604 }
605 });
606
607 test("a kept page differs between anonymous and signed in only in account flags and the users action", async () => {
608 const strip = (m: any) =>
609 m.can
610 .filter((a: any) => a.http !== "POST /api/v1/users")
611 .map((a: any) => a.http);
612 for (const p of ["/docs", "/changelog", "/templates", "/signin", "/status", "/agents"]) {
613 const anon = (await manifest(p)).body;
614 const me = (await manifest(p, "alice")).body;
615 expect(me.here).toEqual(anon.here);
616 const mineOnly = strip(me).filter((h: string) => !strip(anon).includes(h));
617 expect(mineOnly.every((h: string) => !h.startsWith("GET /docs") && !h.startsWith("GET /status"))).toBe(true);
618 }
619 const anon = (await manifest("/templates")).body.can.find((a: any) => a.mcp === "spawn");
620 expect(anon.account).toBe(true);
621 });
622
623 test("the docs search carries q capped and encoded", async () => {
624 const { body } = await manifest(`/docs?q=${encodeURIComponent("a&b=c#" + "x".repeat(300))}`);
625 const search = body.can[0];
626 expect(search.http.startsWith("GET /docs?q=a%26b%3Dc%23")).toBe(true);
627 expect(search.http.length).toBeLessThan(120);
628 expect(search.do.length).toBeLessThan(260);
629 });
559630 });
test/openapi.test.ts +9 −1
@@ -22,7 +22,15 @@ test("every http route the manifest names is described", () => {
2222 expect(named.length).toBeGreaterThan(5);
2323 const doc = openapi("https://f.test", "1", "admin") as any;
2424 // The sign-up and sign-in pages are HTML for a person, not part of the API.
25 const pages = new Set(["/signup", "/signin"]);
25 const pages = new Set([
outdated

Wrap this long line; one array per line is easier to diff.

26 "/signup",
27 "/signin",
28 "/docs",
29 "/docs/{name}",
30 "/changelog.atom",
31 "/status",
32 "/llms.txt",
33 ]);
2634 for (const [method, path] of named) {
2735 if (pages.has(path)) continue;
2836 const p = path.replace(/\{(\w+)\}/g, "{$1}");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs