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

An MCP tool 'steer' takes one sentence and files it as a tell, with the same words as the feed composer's result #13699

Merged opened this

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

Merged

scout/forge:scout/13663-an-mcp-tool-steer-takes-one-sentence-and → main 7 commits fork 2 threads · 2 unresolved

  • Merged. scout/13663-an-mcp-tool-steer-takes-one-sentence-and was merged into main as 4765d9f.

Review

Sign in to review this change.
8 files changed +182 −48
docs/mcp/tools/tell.md added +39
@@ -0,0 +1,39 @@
1 # `tell`
2
3 Tell an app's crew what to change. One sentence becomes an issue (the first
4 line is the title), a builder is picked, and a run starts on the crew's next
5 tick: the same `tell()` as the feed composer, the forge pill and the terminal.
6
7 ## Arguments
8
9 `{ repo?, text, from?, context? }`
10
11 - `repo`: `owner/name`. Without it, a person with no app but the forge's own
12 copy makes a new app; anyone else has the sentence kept as a thought
13 (`thought` reads it back).
14 - `text`: the sentence, at most 8000 characters.
15 - `from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`.
16 - `context`: where this was told from, `{ page?, pull?, run?, commit?, said? }`.
17
18 ## Result
19
20 `{ says, issue, page }`: `says` is the same sentence the composer shows (who
21 is on it, or that nobody is on the crew yet), `issue` the number opened, and
22 `page` its address.
23
24 ## Refusals
25
26 A refused tell is an error answer whose text is `refusalWords(error)` in
27 `src/actions/tell_answer.ts`, the one function the composer, the terminal and
28 this tool all use:
29
30 | error | words |
31 | --- | --- |
32 | `empty` | Say something first. |
33 | `body_too_long` | That is too long to tell in one go. |
34 | `unverified` | Verify your email first. |
35 | `forbidden` | the crew's direction note |
36 | anything else | That could not be told. |
37
38 `test/mcp-tell.test.ts` asserts the composer's and this tool's text are equal
39 for the empty, over-long and unverified cases.
src/actions/tell_answer.ts +17 −12
@@ -4,21 +4,26 @@
44 */
55
66 import { toldWords, TOO_LONG_WORDS, UNVERIFIED_WORDS, type Told, type TellError } from "./tell.ts";
7 import { NOT_TOLD_WORDS } from "./tell_words.ts";
7 import { NOT_TOLD_WORDS, SAY_SOMETHING_WORDS } from "./tell_words.ts";
88 import { DIRECTION_NOTE } from "../crew/direct.ts";
99 import type { Result } from "../kernel/result.ts";
1010
11 const SENTENCE_UNVERIFIED = `${UNVERIFIED_WORDS[0]!.toUpperCase()}${UNVERIFIED_WORDS.slice(1)}.`;
12
13 /** The words for a refused tell: one sentence at the feed composer, the terminal and the MCP. */
14 export function refusalWords(error: TellError): string {
15 return error === "forbidden"
16 ? DIRECTION_NOTE
17 : error === "unverified"
18 ? SENTENCE_UNVERIFIED
19 : error === "body_too_long"
20 ? TOO_LONG_WORDS
21 : error === "empty"
22 ? SAY_SOMETHING_WORDS
23 : NOT_TOLD_WORDS;
24 }
25
1126 export function tellAnswer(told: Result<Told, TellError>): { text: string; tone: "success" | "danger" } {
1227 if (told.ok) return { tone: told.value.routed === undefined || told.value.assigned ? "success" : "danger", text: toldWords(told.value) };
13 return {
14 tone: "danger",
15 text:
16 told.error === "forbidden"
17 ? DIRECTION_NOTE
18 : told.error === "unverified"
19 ? UNVERIFIED_WORDS
20 : told.error === "body_too_long"
21 ? TOO_LONG_WORDS
22 : NOT_TOLD_WORDS,
23 };
28 return { tone: "danger", text: refusalWords(told.error) };
2429 }
src/http/mcp/tools/tell.ts +3 −13
@@ -3,8 +3,8 @@ import { asksMakeANewApp, firstAsk } from "../../../actions/first_ask.ts";
33 import { crewCanRun } from "../../../web/studio/crew_key.ts";
44 import { keepThought } from "../../../actions/thought.ts";
55 import { parseFrom } from "../../../actions/tell_from.ts";
6 import { FROM_WORDS, tell, toldWords, UNVERIFIED_WORDS } from "../../../actions/tell.ts";
7 import { DIRECTION_NOTE } from "../../../crew/direct.ts";
6 import { FROM_WORDS, tell, toldWords } from "../../../actions/tell.ts";
7 import { refusalWords } from "../../../actions/tell_answer.ts";
88 import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
99
1010 export const tool: Tool = {
@@ -79,17 +79,7 @@ export const tool: Tool = {
7979 1,
8080 from,
8181 );
82 if (!told.ok)
83 return bad(
84 told.error,
85 told.error === "empty"
86 ? "say something first"
87 : told.error === "forbidden"
88 ? DIRECTION_NOTE
89 : told.error === "unverified"
90 ? UNVERIFIED_WORDS
91 : "that could not be told here",
92 );
82 if (!told.ok) return bad(told.error, refusalWords(told.error));

Box 1: add docs/mcp/tools/tell.md, since the issue asks for a file there. It should cover the arguments, the result (says, issue, page) and the refusal wording.

9383 return good({
9484 says: toldWords(told.value),
9585 issue: told.value.issue.number,
src/web/studio/actions.ts +4 −16
@@ -16,9 +16,9 @@ import { addComment } from "../../actions/issues.ts";
1616 import { parseFrom } from "../../actions/tell_from.ts";
1717 import { SENT_WORDS, tell, toldWords, TOO_LONG_WORDS } from "../../actions/tell.ts";
1818 import { contextNote, parseContext } from "../../actions/tell_context.ts";
19 import { NOT_TOLD_FROM_WORDS, NOT_TOLD_WORDS, SAY_SOMETHING_WORDS } from "../../actions/tell_words.ts";
19 import { refusalWords } from "../../actions/tell_answer.ts";
20 import { NOT_TOLD_FROM_WORDS, SAY_SOMETHING_WORDS } from "../../actions/tell_words.ts";
2021 import { keepThought } from "../../actions/thought.ts";
21 import { DIRECTION_NOTE } from "../../crew/direct.ts";
2222 import { mergePull } from "../../actions/pulls.ts";
2323 import { revertPull } from "../../actions/revert.ts";
2424 import { takeBackWords } from "../../actions/revert_words.ts";
@@ -99,12 +99,7 @@ function toldAnswer(
9999 if (!told.ok)
100100 return flashOrJson(ctx, back, {
101101 tone: "danger",
102 message:
103 told.error === "forbidden"
104 ? DIRECTION_NOTE
105 : told.error === "unverified"
106 ? "Verify your email first."
107 : NOT_TOLD_WORDS,
102 message: refusalWords(told.error),
108103 });
109104 onTold();
110105 const { routed } = told.value;
@@ -192,14 +187,7 @@ async function tellFromPage(ctx: Ctx, repo: Repo, form: Form): Promise<Response>
192187 if (!told.ok)
193188 return flashTo(ctx, back, {
194189 tone: "danger",
195 message:
196 told.error === "forbidden"
197 ? DIRECTION_NOTE
198 : told.error === "unverified"
199 ? "Verify your email first."
200 : told.error === "body_too_long"
201 ? TOO_LONG_WORDS
202 : NOT_TOLD_WORDS,
190 message: refusalWords(told.error),
203191 });
204192 const issue = `${repoBase(repo)}/issues/${told.value.issue.number}`;
205193 return page({
test/mcp-tell.test.ts added +110
@@ -0,0 +1,110 @@
1 /**
2 * `tell` refuses in the feed composer's words: one function (`refusalWords`)
3 * speaks for the page, the terminal and the MCP.
4 */
5 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { newApp } from "../src/actions/apps.ts";
11 import { refusalWords, tellAnswer } from "../src/actions/tell_answer.ts";
12 import { SAY_SOMETHING_WORDS } from "../src/actions/tell_words.ts";
13 import { getUserByName } from "../src/core/users.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { seedAdmin } from "./helpers/admin.ts";
16 import { tokenFor } from "./helpers/tokens.ts";
17 import { proveAll } from "./helpers/verified.ts";
18
19 describe("MCP tell refusals", () => {
20 let dataDir: string;
21 let app: App;
22 let servers: Servers;
23 let rw: string;
24
25 const call = async (args: unknown) => {
26 const res = await fetch(`${servers.url}/mcp`, {
27 method: "POST",
28 headers: {
29 "content-type": "application/json",
30 accept: "application/json, text/event-stream",
31 authorization: `Bearer ${rw}`,
32 },
33 body: JSON.stringify({
34 jsonrpc: "2.0",
35 id: 1,
36 method: "tools/call",
37 params: { name: "tell", arguments: args },
38 }),
39 });
40 const body = (await res.json()) as { result: { isError?: boolean; content: { text: string }[] } };
41 return { error: body.result.isError === true, text: body.result.content[0]!.text };
42 };
43
44 beforeAll(async () => {
45 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-tell-"));
46 app = createApp({ dataDir, port: 0 });
47 servers = await serve(app);
48 await seedAdmin(app, { username: "alice", email: "[email protected]", password: "a-good-passphrase" });
49 const made = await newApp(app, getUserByName(app.db, "alice")!, { name: "notes", description: "Notes" });
50 if (!made.ok) throw new Error(String(made.error));
51 rw = tokenFor(app, "alice", "rw");
52 }, 30_000);
53 afterAll(async () => {
54 servers.stop();
55 app.close();
56 await rm(dataDir, { recursive: true, force: true });
57 });
58
59 test("an empty tell is refused in the composer's words", async () => {
60 const r = await call({ repo: "alice/notes", text: " " });
61 expect(r.text).toContain(SAY_SOMETHING_WORDS);
62 });
63
64 test("an over-long tell is refused in the words the terminal and the page say", async () => {
65 const r = await call({ repo: "alice/notes", text: "x".repeat(7999) + "\n".repeat(3) + "y".repeat(60_000) });
66 expect(r.error).toBe(true);
67 expect(r.text).toContain(tellAnswer({ ok: false, error: "body_too_long" }).text);
outdated

Box 3: this is the only comparison, and it checks the function against itself. Add a test that drives the web composer's action and asserts its message equals the MCP tool's text for the same input.

68 });
69
70 /** The feed composer's own action (the studio's POST /:owner/:name/tell), asked for JSON. */
71 const composer = async (text: string): Promise<string> => {
72 const res = await fetch(`${servers.url}/alice/notes/tell`, {
73 method: "POST",
74 headers: { authorization: `Bearer ${rw}`, origin: servers.url, accept: "application/json" },
75 body: new URLSearchParams({ text }),
76 redirect: "manual",
77 });
78 expect(res.status).toBe(422);
79 return ((await res.json()) as { error: string }).error;
80 };
81
82 test("the composer and the MCP refuse the same input in the same words", async () => {
83 const long = "x".repeat(7999) + "\n".repeat(3) + "y".repeat(60_000);
84 for (const [text, said] of [
85 [" ", refusalWords("empty")],
86 [long, refusalWords("body_too_long")],
87 ] as const) {
88 const web = await composer(text);
89 expect(web).toBe(said);
90 expect((await call({ repo: "alice/notes", text })).text).toContain(web);
91 }
92 app.db.query("UPDATE email_check SET verified_at = NULL").run();
93 try {
94 const web = await composer("hello");
95 expect(web).toBe(refusalWords("unverified"));
96 const mcp = await call({ repo: "alice/notes", text: "hello" });
97 expect(mcp.error).toBe(true);
98 expect(mcp.text).toContain(web);
99 } finally {
100 proveAll(app);
101 }
102 });
103
104 test("every refusal the composer words is worded by the shared function", () => {
105 expect(refusalWords("empty")).toBe(SAY_SOMETHING_WORDS);
106 expect(refusalWords("unverified")).toBe("Verify your email first."); // the one place the sentence is spelled out
107 expect(refusalWords("body_too_long")).toBe("That is too long to tell in one go.");
108 expect(refusalWords("not_found")).toBe("That could not be told.");
109 });
110 });
test/ssh-tell.test.ts +3 −2
@@ -10,7 +10,8 @@ import { createApp, type App } from "../src/app.ts";
1010 import { createRepo } from "../src/actions/repos.ts";
1111 import { SAY_SOMETHING_WORDS } from "../src/actions/tell_words.ts";
1212 import { MAX_BODY } from "../src/core/issues.ts";
13 import { TOO_LONG_WORDS, UNVERIFIED_WORDS } from "../src/actions/tell.ts";
13 import { TOO_LONG_WORDS } from "../src/actions/tell.ts";
14 import { refusalWords } from "../src/actions/tell_answer.ts";
1415 import { addKey, fingerprint, parseAuthorizedKey } from "../src/core/keys.ts";
1516 import { getRepo } from "../src/core/repos.ts";
1617 import { AppsRuntime } from "../src/apps/runtime.ts";
@@ -139,7 +140,7 @@ describe("ssh forge tell", () => {
139140 expect([r.code, r.err]).toEqual([1, `forge: ${CONTROL_WORDS}\r\n`]);
140141 }
141142 const unverified = await exec(KEY_B, "tell hello");
142 expect([unverified.code, unverified.err]).toEqual([1, `forge: ${UNVERIFIED_WORDS}\r\n`]);
143 expect([unverified.code, unverified.err]).toEqual([1, `forge: ${refusalWords("unverified")}\r\n`]);
143144 expect(issues().length).toBe(1);
144145 });
145146
test/tui-answers-tell.test.ts +3 −2
@@ -9,7 +9,8 @@ import { tmpdir } from "node:os";
99 import { join } from "node:path";
1010 import { enableApp } from "../src/actions/apps.ts";
1111 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
12 import { tell, UNVERIFIED_WORDS } from "../src/actions/tell.ts";
12 import { tell } from "../src/actions/tell.ts";
13 import { refusalWords } from "../src/actions/tell_answer.ts";
1314 import { createApp, type App } from "../src/app.ts";
1415 import { listIssues } from "../src/core/issues.ts";
1516 import type { Repo } from "../src/core/repos.ts";
@@ -117,7 +118,7 @@ describe("t on the answers screen", () => {
117118 app.db.query("UPDATE email_check SET verified_at = NULL").run();
118119 try {
119120 const seen = await drive(alice, ["t", ..."Unseen.", "\r"]);
120 expect(seen.text).toContain(UNVERIFIED_WORDS.slice(0, 30));
121 expect(seen.text).toContain(refusalWords("unverified"));
121122 } finally {
122123 proveAll(app);
123124 }
test/tui-tell.test.ts +3 −3
@@ -11,8 +11,8 @@ import { createRepo } from "../src/actions/repos.ts";
1111 import { createApp, type App } from "../src/app.ts";
1212 import { listIssues, MAX_BODY } from "../src/core/issues.ts";
1313 import { createUser, type User } from "../src/core/users.ts";
14 import { tellAnswer } from "../src/actions/tell_answer.ts";
15 import { tell, toldWords, TOO_LONG_WORDS, UNVERIFIED_WORDS, type Told } from "../src/actions/tell.ts";
14 import { refusalWords, tellAnswer } from "../src/actions/tell_answer.ts";
15 import { tell, toldWords, TOO_LONG_WORDS, type Told } from "../src/actions/tell.ts";
1616 import { createForgeApp } from "../src/tui/forge.ts";
1717 import { repoScreen } from "../src/tui/screens/repo.ts";
1818 import { local } from "../src/tui/screens/where.ts";
@@ -125,7 +125,7 @@ describe("tell the crew in the terminal", () => {
125125 });
126126
127127 test("an unverified address gets the shared words", () => {
128 expect(tellAnswer({ ok: false, error: "unverified" }).text).toBe(UNVERIFIED_WORDS);
128 expect(tellAnswer({ ok: false, error: "unverified" }).text).toBe(refusalWords("unverified"));
129129 });
130130
131131 test("an over-long line gets the page's words", async () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs