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

MCP `tell` takes `from` (a page URL on this forge or one of its apps) and the tell records it as where it was said, as a tell from the toolbar does #5928

Parked opened this
Closed without merging

scout/forge:scout/5907-mcp-tell-takes-from-a-page-url-on-this-f → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
10 files changed +119 −17
docs/MCP.md +1 −1
@@ -164,7 +164,7 @@ enforces it); `dryRun` reads `false to apply` on every tool that takes it. The
164164 longer sentences:
165165
166166 - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token.
167 - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`. `tell.context`: where this was told from, for the builder.
167 - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`; or an https address of a page on this forge or one of its apps (`slug.<domain>`, a preview `slug--N.<domain>`), kept as where it was said, as a toolbar tell keeps its page (`page:` in the issue; with no `repo`, on the thought, which `thought` answers as `page`). Anything else, a foreign host, credentials, or a non-URL, is `invalid`. `tell.context`: where this was told from, for the builder.
168168 - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) or `take-updates`. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed.
169169 - `commits.ref`: branch, tag or commit; the default branch when absent. `report.page`: the http(s) address where the problem was seen. `plan.issues.pillar`: the pillar served, as `"P0"` or `"P0 Trust"`; `later: true` means no pillar and needs `why`.
170170 - `explore.query`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|use|fresh|name`.
src/actions/tell_context.ts +30
@@ -6,6 +6,8 @@
66 * the tell as a plain block the issue shows and the agent reads.
77 */
88
9 import { parseAppHost } from "../apps/proxy.ts";
10
911 export interface TellContext {
1012 readonly page?: string;
1113 readonly pull?: number;
@@ -70,3 +72,31 @@ export function contextNote(c: TellContext | undefined): string {
7072 ].filter((l) => l !== "");
7173 return lines.length === 0 ? "" : `\n\n---\nWhere this was told from:\n${lines.join("\n")}`;
7274 }
75
76 /** What a `from` URL is refused with, at the MCP door. */
77 export const FROM_URL_WORDS =
78 "from is an https address of a page on this forge or one of its apps, like https://forge.example/alice/notes/pulls/3";
79
80 /**
81 * A page address given as `from`: https, no credentials, and on the forge's
82 * own origin or one of its app hosts (`slug.<domain>`, `slug--N.<domain>`).
83 * What passes is stored the way the toolbar stores its page; null otherwise.
84 */
85 export function parsePageFrom(
86 raw: unknown,
87 forgeOrigin: string,
88 appDomain: string | undefined,
89 ): string | null {
90 if (typeof raw !== "string" || raw.length > 2000 || /[\s\x00-\x1f\x7f]/.test(raw))
91 return null;
92 const url = URL.parse(raw);
93 if (url === null || url.username !== "" || url.password !== "") return null;
94 const mine = url.origin === forgeOrigin;
95 // https always; the forge's own origin as it is, so a forge on plain http
96 // (local) can still point at its own pages.
97 if (url.protocol !== "https:" && !mine) return null;
98 if (!mine && (appDomain === undefined || parseAppHost(url.host, appDomain) === undefined))
99 return null;
100 const ok = parseContext({ page: raw });
101 return ok === null || ok === undefined ? null : (ok.page ?? null);
102 }
src/actions/thought.ts +3 −2
@@ -21,6 +21,7 @@ export function keepThought(
2121 actor: User | undefined,
2222 text: unknown,
2323 source: ThoughtSource,
24 page: string | null = null,
2425 ): Result<{ id: string; receivedAt: string }, ThoughtError> {
2526 if (!actor) return err("unauthorized");
2627 if (typeof text !== "string") return err("not_text");
@@ -30,9 +31,9 @@ export function keepThought(
3031 app.db.transaction(() => {
3132 app.db
3233 .query(
33 "INSERT INTO thought (id, author, text, source, received_at) VALUES (?1, ?2, ?3, ?4, ?5)",
34 "INSERT INTO thought (id, author, text, source, received_at, page) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
3435 )
35 .run(thoughtId, actor.id, text, source, receivedAt);
36 .run(thoughtId, actor.id, text, source, receivedAt, page);
3637 // The text stays out of the outbox: the event says one arrived.
3738 app.bus.append({
3839 kind: "thought.received",
src/core/migrations/20261025100000-thought-page.ts added +5
@@ -0,0 +1,5 @@
1 // The page a thought was said about, when an agent named one. Additive; the
2 // thought's text stays as typed.
3 export default `
4 ALTER TABLE thought ADD COLUMN page TEXT;
5 `;
src/core/placements.ts +5
@@ -107,3 +107,8 @@ export function authorsWithUnplaced(db: Database, since: string): string[] {
107107 export function thoughtAuthor(db: Database, thoughtId: string): string | undefined {
108108 return db.query<{ author: string }, [string]>("SELECT author FROM thought WHERE id = ?1").get(thoughtId)?.author;
109109 }
110
111 /** The page a thought was said about, when one was named. */
112 export function thoughtPage(db: Database, thoughtId: string): string | null {
113 return db.query<{ page: string | null }, [string]>("SELECT page FROM thought WHERE id = ?1").get(thoughtId)?.page ?? null;
114 }
src/core/thoughts.ts +8 −6
@@ -11,27 +11,29 @@ export interface Thought {
1111 text: string;
1212 source: string;
1313 receivedAt: string;
14 /** The page it was said about, when one was named. */
15 page: string | null;
1416 }
1517
1618 /** The author's newest thoughts received at or after `since` (ISO), newest first; the text exactly as kept. */
1719 export function recentThoughts(db: Database, authorId: string, limit: number, since = ""): Thought[] {
1820 return db
1921 .query<
20 { id: string; text: string; source: string; received_at: string },
22 { id: string; text: string; source: string; received_at: string; page: string | null },
2123 [string, string, number]
2224 >(
23 "SELECT id, text, source, received_at FROM thought WHERE author = ?1 AND received_at >= ?2 ORDER BY received_at DESC, id DESC LIMIT ?3",
25 "SELECT id, text, source, received_at, page FROM thought WHERE author = ?1 AND received_at >= ?2 ORDER BY received_at DESC, id DESC LIMIT ?3",
2426 )
2527 .all(authorId, since, limit)
26 .map((r) => ({ id: r.id, text: r.text, source: r.source, receivedAt: r.received_at }));
28 .map((r) => ({ id: r.id, text: r.text, source: r.source, receivedAt: r.received_at, page: r.page }));
2729 }
2830
2931 /** One of the author's thoughts by id, or nothing (a thought is its author's alone). */
3032 export function thoughtOf(db: Database, authorId: string, id: string): Thought | undefined {
3133 const r = db
32 .query<{ id: string; text: string; source: string; received_at: string }, [string, string]>(
33 "SELECT id, text, source, received_at FROM thought WHERE author = ?1 AND id = ?2",
34 .query<{ id: string; text: string; source: string; received_at: string; page: string | null }, [string, string]>(
35 "SELECT id, text, source, received_at, page FROM thought WHERE author = ?1 AND id = ?2",
3436 )
3537 .get(authorId, id);
36 return r ? { id: r.id, text: r.text, source: r.source, receivedAt: r.received_at } : undefined;
38 return r ? { id: r.id, text: r.text, source: r.source, receivedAt: r.received_at, page: r.page } : undefined;
3739 }
src/http/mcp/tools/tell.ts +15 −5
@@ -1,4 +1,5 @@
1 import { contextNote, parseContext } from "../../../actions/tell_context.ts";
1 import { appsRuntime } from "../../../apps/runtime.ts";
2 import { FROM_URL_WORDS, contextNote, parseContext, parsePageFrom } from "../../../actions/tell_context.ts";
23 import { keepThought } from "../../../actions/thought.ts";
34 import { FROM_WORDS, parseFrom, tell, toldWords, UNVERIFIED_WORDS } from "../../../actions/tell.ts";
45 import { DIRECTION_NOTE } from "../../../crew/direct.ts";
@@ -18,7 +19,7 @@ export const tool: Tool = {
1819 type: "string",
1920 maxLength: 512,
2021 description:
21 "Forge path to link, as /a/b/pulls/3.",
22 "Forge path to link, as /a/b/pulls/3; or an https page of this forge or one of its apps, kept as where it was said.",
2223 },
2324 context: {
2425 type: "object",
@@ -37,8 +38,16 @@ export const tool: Tool = {
3738 },
3839 writes: true,
3940 async run(ctx, user, args) {
41 // A page address is where it was said; a path is a link (`parseFrom`).
42 const fromPage = typeof args["from"] === "string" && /^https?:/i.test(args["from"]);
43 const page = fromPage
44 ? parsePageFrom(args["from"], ctx.url.origin, appsRuntime(ctx.app)?.options.domain)
45 : null;
46 if (fromPage && page === null) return bad("invalid", FROM_URL_WORDS);
4047 if (args["repo"] === undefined || args["repo"] === null) {
41 const kept = keepThought(ctx.app, user, args["text"], "mcp");
48 if (!fromPage && args["from"] !== undefined && parseFrom(args["from"]) === undefined)
49 return bad("invalid", FROM_WORDS);
50 const kept = keepThought(ctx.app, user, args["text"], "mcp", page);
4251 return kept.ok
4352 ? good({ thought: kept.value.id })
4453 : bad(
@@ -48,13 +57,14 @@ export const tool: Tool = {
4857 }
4958 const repo = repoArg(ctx, user, args);
5059 if (isAnswer(repo)) return repo;
51 const where = parseContext(args["context"]);
60 const given = parseContext(args["context"]);
61 const where = page === null || given === null ? given : { ...given, page };
5262 if (where === null)
5363 return bad(
5464 "invalid",
5565 "context is { page?: http(s) address, pull?: number, run?: id, commit?: hex, said?: words }",
5666 );
57 const from = parseFrom(args["from"]);
67 const from = fromPage ? null : parseFrom(args["from"]);
5868 if (from === undefined) return bad("invalid", FROM_WORDS);
5969 const told = await tell(
6070 ctx.app,
src/http/mcp/tools/thought.ts +3 −1
@@ -1,4 +1,4 @@
1 import { placementJson, placementOf, thoughtAuthor } from "../../../core/placements.ts";
1 import { placementJson, placementOf, thoughtAuthor, thoughtPage } from "../../../core/placements.ts";
22 import { linksFrom, linksTo } from "../../../core/thought_links.ts";
33 import { good, bad, type Tool } from "../shared.ts";
44
@@ -20,10 +20,12 @@ export const tool: Tool = {
2020 // Not yours and not there answer alike (a thought belongs to its author).
2121 if (thoughtAuthor(ctx.app.db, thoughtId) !== user.id)
2222 return bad("not_found", "no such thought");
23 const saidAt = thoughtPage(ctx.app.db, thoughtId);
2324 const links = linksFrom(ctx.app.db, thoughtId);
2425 const back = linksTo(ctx.app.db, thoughtId);
2526 return good({
2627 id: thoughtId,
28 ...(saidAt === null ? {} : { page: saidAt }),
2729 placement: placementJson(placementOf(ctx.app.db, thoughtId)),
2830 // The earlier thoughts this one repeats or takes back, and the later one that took it back.
2931 repeats: links.repeats,
test/mcp.test.ts +16
@@ -1355,6 +1355,22 @@ describe("the forge over MCP", () => {
13551355 }
13561356 });
13571357
1358 test("a tell's `from` page is kept as the page it was said on, and a foreign one is refused", async () => {
1359 const page = `${base}/alice/game/pulls/1`;
1360 const told = await tool(rw, "tell", { repo: "alice/game", text: "about this page", from: page });
1361 expect(told.error).toBeUndefined();
1362 const issue = listIssues(app.db, game.id, {}).find((i) => i.title === "about this page");
1363 expect(issue?.body).toContain(`page: ${page}`);
1364 const thought = await tool(rw, "tell", { text: "a thought about it", from: page });
1365 expect((await tool(rw, "thought", { id: thought.value.thought })).value.page).toBe(page);
1366 for (const from of ["https://evil.example/x", "javascript:alert(1)", "not a url", "https://u:[email protected]/"]) {
1367 const refused = await tool(rw, "tell", { repo: "alice/game", text: "nope", from });
1368 expect(refused.error).toContain("invalid");
1369 expect((await tool(rw, "tell", { text: "nope", from })).error).toContain("invalid");
1370 }
1371 expect(listIssues(app.db, game.id, {}).some((i) => i.title === "nope")).toBe(false);
1372 });
1373
13581374 test("GET /contract/openapi.json describes the public API", async () => {
13591375 const res = await fetch(`${base}/contract/openapi.json`);
13601376 expect(res.status).toBe(200);
test/tell-context.test.ts +33 −2
@@ -1,5 +1,5 @@
1 import { expect, test } from "bun:test";
2 import { contextNote, parseContext } from "../src/actions/tell_context.ts";
1 import { describe, expect, test } from "bun:test";
2 import { contextNote, parseContext, parsePageFrom } from "../src/actions/tell_context.ts";
33
44 test("a page told with a #fragment is told without it", () => {
55 const c = parseContext({ page: "https://app.example.test/a?b=1#access_token=secret" });
@@ -12,3 +12,34 @@ test("a page without a fragment is kept as it was", () => {
1212 page: "https://app.example.test/a",
1313 });
1414 });
15
16 describe("parsePageFrom", () => {
17 const forge = "https://forge.example";
18 const apps = "--forge.example";
19 test("a forge page and an app page pass; the fragment goes", () => {
20 expect(parsePageFrom("https://forge.example/alice/notes/pulls/3#t=x", forge, apps)).toBe(
21 "https://forge.example/alice/notes/pulls/3",
22 );
23 expect(parsePageFrom("https://notes--forge.example/play?l=2", forge, apps)).toBe(
24 "https://notes--forge.example/play?l=2",
25 );
26 expect(parsePageFrom("https://notes--4--forge.example/", forge, apps)).toBe(
27 "https://notes--4--forge.example/",
28 );
29 });
30 test("a foreign host, a lookalike, plain http, credentials and a non-URL are refused", () => {
31 for (const bad of [
32 "https://evil.example/x",
33 "https://forge.example.evil.example/x",
34 "https://a.b--forge.example/x",
35 "http://notes--forge.example/",
36 "https://u:[email protected]/",
37 "javascript:alert(1)",
38 "/alice/notes",
39 "not a url",
40 42,
41 ])
42 expect(parsePageFrom(bad, forge, apps)).toBeNull();
43 expect(parsePageFrom("https://notes--forge.example/", forge, undefined)).toBeNull();
44 });
45 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs