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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13663-an-mcp-tool-steer-takes-one-sentence-and → main 7 commits fork 2 threads · 2 unresolved
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 @@ | ||
| 4 | 4 | */ |
| 5 | 5 | |
| 6 | 6 | 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"; | |
| 8 | 8 | import { DIRECTION_NOTE } from "../crew/direct.ts"; |
| 9 | 9 | import type { Result } from "../kernel/result.ts"; |
| 10 | 10 | |
| 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 | ||
| 11 | 26 | export function tellAnswer(told: Result<Told, TellError>): { text: string; tone: "success" | "danger" } { |
| 12 | 27 | 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) }; | |
| 24 | 29 | } |
src/http/mcp/tools/tell.ts +3 −13
| @@ -3,8 +3,8 @@ import { asksMakeANewApp, firstAsk } from "../../../actions/first_ask.ts"; | ||
| 3 | 3 | import { crewCanRun } from "../../../web/studio/crew_key.ts"; |
| 4 | 4 | import { keepThought } from "../../../actions/thought.ts"; |
| 5 | 5 | 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"; | |
| 8 | 8 | import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 9 | 9 | |
| 10 | 10 | export const tool: Tool = { |
| @@ -79,17 +79,7 @@ export const tool: Tool = { | ||
| 79 | 79 | 1, |
| 80 | 80 | from, |
| 81 | 81 | ); |
| 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)); | |
| 93 | 83 | return good({ |
| 94 | 84 | says: toldWords(told.value), |
| 95 | 85 | issue: told.value.issue.number, |
src/web/studio/actions.ts +4 −16
| @@ -16,9 +16,9 @@ import { addComment } from "../../actions/issues.ts"; | ||
| 16 | 16 | import { parseFrom } from "../../actions/tell_from.ts"; |
| 17 | 17 | import { SENT_WORDS, tell, toldWords, TOO_LONG_WORDS } from "../../actions/tell.ts"; |
| 18 | 18 | 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"; | |
| 20 | 21 | import { keepThought } from "../../actions/thought.ts"; |
| 21 | import { DIRECTION_NOTE } from "../../crew/direct.ts"; | |
| 22 | 22 | import { mergePull } from "../../actions/pulls.ts"; |
| 23 | 23 | import { revertPull } from "../../actions/revert.ts"; |
| 24 | 24 | import { takeBackWords } from "../../actions/revert_words.ts"; |
| @@ -99,12 +99,7 @@ function toldAnswer( | ||
| 99 | 99 | if (!told.ok) |
| 100 | 100 | return flashOrJson(ctx, back, { |
| 101 | 101 | 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), | |
| 108 | 103 | }); |
| 109 | 104 | onTold(); |
| 110 | 105 | const { routed } = told.value; |
| @@ -192,14 +187,7 @@ async function tellFromPage(ctx: Ctx, repo: Repo, form: Form): Promise<Response> | ||
| 192 | 187 | if (!told.ok) |
| 193 | 188 | return flashTo(ctx, back, { |
| 194 | 189 | 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), | |
| 203 | 191 | }); |
| 204 | 192 | const issue = `${repoBase(repo)}/issues/${told.value.issue.number}`; |
| 205 | 193 | 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"; | ||
| 10 | 10 | import { createRepo } from "../src/actions/repos.ts"; |
| 11 | 11 | import { SAY_SOMETHING_WORDS } from "../src/actions/tell_words.ts"; |
| 12 | 12 | 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"; | |
| 14 | 15 | import { addKey, fingerprint, parseAuthorizedKey } from "../src/core/keys.ts"; |
| 15 | 16 | import { getRepo } from "../src/core/repos.ts"; |
| 16 | 17 | import { AppsRuntime } from "../src/apps/runtime.ts"; |
| @@ -139,7 +140,7 @@ describe("ssh forge tell", () => { | ||
| 139 | 140 | expect([r.code, r.err]).toEqual([1, `forge: ${CONTROL_WORDS}\r\n`]); |
| 140 | 141 | } |
| 141 | 142 | 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`]); | |
| 143 | 144 | expect(issues().length).toBe(1); |
| 144 | 145 | }); |
| 145 | 146 |
test/tui-answers-tell.test.ts +3 −2
| @@ -9,7 +9,8 @@ import { tmpdir } from "node:os"; | ||
| 9 | 9 | import { join } from "node:path"; |
| 10 | 10 | import { enableApp } from "../src/actions/apps.ts"; |
| 11 | 11 | 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"; | |
| 13 | 14 | import { createApp, type App } from "../src/app.ts"; |
| 14 | 15 | import { listIssues } from "../src/core/issues.ts"; |
| 15 | 16 | import type { Repo } from "../src/core/repos.ts"; |
| @@ -117,7 +118,7 @@ describe("t on the answers screen", () => { | ||
| 117 | 118 | app.db.query("UPDATE email_check SET verified_at = NULL").run(); |
| 118 | 119 | try { |
| 119 | 120 | 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")); | |
| 121 | 122 | } finally { |
| 122 | 123 | proveAll(app); |
| 123 | 124 | } |
test/tui-tell.test.ts +3 −3
| @@ -11,8 +11,8 @@ import { createRepo } from "../src/actions/repos.ts"; | ||
| 11 | 11 | import { createApp, type App } from "../src/app.ts"; |
| 12 | 12 | import { listIssues, MAX_BODY } from "../src/core/issues.ts"; |
| 13 | 13 | 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"; | |
| 16 | 16 | import { createForgeApp } from "../src/tui/forge.ts"; |
| 17 | 17 | import { repoScreen } from "../src/tui/screens/repo.ts"; |
| 18 | 18 | import { local } from "../src/tui/screens/where.ts"; |
| @@ -125,7 +125,7 @@ describe("tell the crew in the terminal", () => { | ||
| 125 | 125 | }); |
| 126 | 126 | |
| 127 | 127 | 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")); | |
| 129 | 129 | }); |
| 130 | 130 | |
| 131 | 131 | test("an over-long line gets the page's words", async () => { |
new above
offline
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.