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 #7403

Parked opened this
Closed without merging

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

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
11 files changed +120 −17
docs/MCP.md +1 −1
@@ -231,8 +231,8 @@ enforces it); `dryRun` reads `false to apply` on every tool that takes it. The
231231 longer sentences:
232232
233233 - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token.
234 - `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.
234235 - `signup`: the terminal's Invite links screen does the same: `s` picks a mode, shows the plan (from → to) and changes it after a confirm, for a forge admin who is a person.
235 - `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.
236236 - `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) tells the owner in their inbox when this forge's code moves; `take-updates` opens a pull with the new code, and a person merges it. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed.
237237 - `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`.
238238 - `explore.query`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|use|fresh|name`, `updated:1d|7d|30d` (only what moved in that window) and `archived:yes`.
src/actions/tell_context.ts +30
@@ -6,6 +6,9 @@
66 * the tell as a plain block the issue shows and the agent reads.
77 */
88
9 import { FROM_WORDS } from "./tell.ts";
10 import { parseAppHost } from "../apps/proxy.ts";
11
912 export interface TellContext {
1013 readonly page?: string;
1114 readonly pull?: number;
@@ -70,3 +73,30 @@ export function contextNote(c: TellContext | undefined): string {
7073 ].filter((l) => l !== "");
7174 return lines.length === 0 ? "" : `\n\n---\nWhere this was told from:\n${lines.join("\n")}`;
7275 }
76
77 /** What a `from` URL is refused with, at the MCP door. */
78 export const FROM_URL_WORDS = `${FROM_WORDS}; or an https address of a page on this forge or one of its apps`;
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/migration-pins/20261025100000-thought-page.pin added +1
@@ -0,0 +1,1 @@
1 ae86e1ec34a602ea297a677dd5e091d6597634e4bbef59242d6b10260427c20f
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
@@ -117,3 +117,8 @@ export function authorsWithUnplaced(db: Database, since: string): string[] {
117117 export function thoughtAuthor(db: Database, thoughtId: string): string | undefined {
118118 return db.query<{ author: string }, [string]>("SELECT author FROM thought WHERE id = ?1").get(thoughtId)?.author;
119119 }
120
121 /** The page a thought was said about, when one was named. */
122 export function thoughtPage(db: Database, thoughtId: string): string | null {
123 return db.query<{ page: string | null }, [string]>("SELECT page FROM thought WHERE id = ?1").get(thoughtId)?.page ?? null;
124 }
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",
@@ -35,8 +36,16 @@ export const tool: Tool = {
3536 },
3637 writes: true,
3738 async run(ctx, user, args) {
39 // A page address is where it was said; a path is a link (`parseFrom`).
40 const fromPage = typeof args["from"] === "string" && /^https?:/i.test(args["from"]);
41 const page = fromPage
42 ? parsePageFrom(args["from"], ctx.url.origin, appsRuntime(ctx.app)?.options.domain)
43 : null;
44 if (fromPage && page === null) return bad("invalid", FROM_URL_WORDS);
3845 if (args["repo"] === undefined || args["repo"] === null) {
39 const kept = keepThought(ctx.app, user, args["text"], "mcp");
46 if (!fromPage && args["from"] !== undefined && parseFrom(args["from"]) === undefined)
47 return bad("invalid", FROM_WORDS);
48 const kept = keepThought(ctx.app, user, args["text"], "mcp", page);
4049 return kept.ok
4150 ? good({ thought: kept.value.id })
4251 : bad(
@@ -46,13 +55,14 @@ export const tool: Tool = {
4655 }
4756 const repo = repoArg(ctx, user, args);
4857 if (isAnswer(repo)) return repo;
49 const where = parseContext(args["context"]);
58 const given = parseContext(args["context"]);
59 const where = page === null || given === null ? given : { ...given, page };
5060 if (where === null)
5161 return bad(
5262 "invalid",
5363 "context is { page?: http(s) address, pull?: number, run?: id, commit?: hex, said?: words }",
5464 );
55 const from = parseFrom(args["from"]);
65 const from = fromPage ? null : parseFrom(args["from"]);
5666 if (from === undefined) return bad("invalid", FROM_WORDS);
5767 const told = await tell(
5868 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
@@ -1498,6 +1498,22 @@ describe("the forge over MCP", () => {
14981498 }
14991499 });
15001500
1501 test("a tell's `from` page is kept as the page it was said on, and a foreign one is refused", async () => {
1502 const page = `${base}/alice/game/pulls/1`;
1503 const told = await tool(rw, "tell", { repo: "alice/game", text: "about this page", from: page });
1504 expect(told.error).toBeUndefined();
1505 const issue = listIssues(app.db, game.id, {}).find((i) => i.title === "about this page");
1506 expect(issue?.body).toContain(`page: ${page}`);
1507 const thought = await tool(rw, "tell", { text: "a thought about it", from: page });
1508 expect((await tool(rw, "thought", { id: thought.value.thought })).value.page).toBe(page);
1509 for (const from of ["https://evil.example/x", "javascript:alert(1)", "not a url", "https://u:[email protected]/"]) {
1510 const refused = await tool(rw, "tell", { repo: "alice/game", text: "nope", from });
1511 expect(refused.error).toContain("invalid");
1512 expect((await tool(rw, "tell", { text: "nope", from })).error).toContain("invalid");
1513 }
1514 expect(listIssues(app.db, game.id, {}).some((i) => i.title === "nope")).toBe(false);
1515 });
1516
15011517 test("GET /contract/openapi.json describes the public API", async () => {
15021518 const res = await fetch(`${base}/contract/openapi.json`);
15031519 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