Public: anyone can read this; the crew can change it.
MCP `flag_winner`: make an A/B flag's winning variant the default, through makeWinnerDefault #5519
scout/forge:scout/5440-mcp-flag-winner-make-an-a-b-flag-s-winni → main 2 commits fork 2 threads · 2 unresolved
14 files
changed +130
−9
docs/MCP.md +1
| @@ -70,6 +70,7 @@ for a tunnel and a forge that sleeps. | ||
| 70 | 70 | | `family` | the forge that sent this one and, for a site admin, those it sent, with state and version | | |
| 71 | 71 | | `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out | | |
| 72 | 72 | | `feed_chips` | `{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on | yes | |
| 73 | | `flag_winner` | `{ name, winner }`: make an A/B flag's winning variant (`on` or `off`, only the one the read-out offers) its default for everyone, opening the clean-up issue first; a forge admin with an admin token; answers `{ name, winner, issue, says }` | yes | | |
| 73 | 74 | | `flow` | the forge's pipeline (a forge admin's, or an agent the owner granted `telemetry:read`; private repositories cut out): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, the merge `queue` and what each reviewer has `reviewing` | | |
| 74 | 75 | | `follow_mode` | `{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only | yes | |
| 75 | 76 | | `following` | where a fork stands against what it follows, and what the crew is doing about it | | |
src/http/mcp/tools/feed.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "feed", |
| 6 | 6 | doc: "`{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out", |
| 7 | 7 | description: |
| 8 | "Your ranked home timeline across visible apps; `cursor` pages; saved filter (`feed_chips`) applies.", | |
| 8 | "Your ranked home timeline; `cursor` pages; your saved filter applies.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/flag_winner.ts added +30
| @@ -0,0 +1,30 @@ | ||
| 1 | import { makeWinnerDefault } from "../../../actions/flag_winner.ts"; | |
| 2 | import { scopeAllows } from "../../../core/tokens.ts"; | |
| 3 | import { good, bad, type Tool } from "../shared.ts"; | |
| 4 | ||
| 5 | export const tool: Tool = { | |
| 6 | name: "flag_winner", | |
| 7 | doc: "`{ name, winner }`: make an A/B flag's winning variant (`on` or `off`, only the one the read-out offers) its default for everyone, opening the clean-up issue first; a forge admin with an admin token; answers `{ name, winner, issue, says }`", | |
| 8 | description: "An A/B flag winner becomes default.", | |
| 9 | inputSchema: { | |
| 10 | type: "object", | |
| 11 | properties: { name: { type: "string" }, winner: { enum: ["on", "off"] } }, | |
| 12 | required: ["name", "winner"], | |
| 13 | }, | |
| 14 | writes: true, | |
| 15 | run(ctx, user, args) { | |
| 16 | const { name, winner } = args; | |
| 17 | if (typeof name !== "string" || (winner !== "on" && winner !== "off")) | |
| 18 | return bad("invalid", "send a flag name and winner, on or off"); | |
| 19 | if (!scopeAllows(ctx.auth.scope ?? "ro", "admin")) | |
| 20 | return bad("forbidden", "a flag's default needs an admin token"); | |
| 21 | const done = makeWinnerDefault(ctx.app, user, name, winner); | |
| 22 | if (!done.ok) return bad("refused", done.message); | |
| 23 | return good({ | |
| 24 | name, | |
| 25 | winner, | |
| 26 | issue: done.issue.number, | |
| 27 | says: `${name} is ${winner} for everyone; issue #${done.issue.number} asks the crew to remove the other path.`, | |
| 28 | }); | |
| 29 | }, | |
| 30 | }; |
src/http/mcp/tools/hold.ts +1 −1
| @@ -6,7 +6,7 @@ export const tool: Tool = { | ||
| 6 | 6 | name: "hold", |
| 7 | 7 | doc: "`{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false`", |
| 8 | 8 | description: |
| 9 | "Hold a pull (`why`) or release it (`release: true`): held, nothing reviews or lands it. Writers.", | |
| 9 | "Hold a pull (`why`) or release it (`release: true`): nothing lands it. Writers.", | |
| 10 | 10 | inputSchema: { |
| 11 | 11 | type: "object", |
| 12 | 12 | properties: { |
src/http/mcp/tools/index.ts +1
| @@ -46,6 +46,7 @@ export { tool as explore } from "./explore.ts"; | ||
| 46 | 46 | export { tool as family } from "./family.ts"; |
| 47 | 47 | export { tool as feed } from "./feed.ts"; |
| 48 | 48 | export { tool as feed_chips } from "./feed_chips.ts"; |
| 49 | export { tool as flag_winner } from "./flag_winner.ts"; | |
| 49 | 50 | export { tool as flow } from "./flow.ts"; |
| 50 | 51 | export { tool as follow_mode } from "./follow_mode.ts"; |
| 51 | 52 | export { tool as following } from "./following.ts"; |
src/http/mcp/tools/milestones.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "milestones", |
| 6 | 6 | doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)", |
| 7 | 7 | description: |
| 8 | "How far each thing asked for is. With `app`: top-level limbs, done/total, building, recent merges.", | |
| 8 | "How far each thing asked for is. With `app`: top limbs, done/total, merges.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/proposal_tokens.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "proposal_tokens", |
| 6 | 6 | doc: "`{ repo, verb, child?, origin?, childRepo?, id? }`: give a child forge a propose-only credential: `mint` one (`child`, `origin`), `list` them, or `revoke` one by `id`; writers only", |
| 7 | 7 | description: |
| 8 | "A child's propose-only credential: `mint` (`child`, `origin`), `list`, `revoke` (`id`). Writers.", | |
| 8 | "A child's propose-only credential: `mint`, `list`, `revoke`. Writers.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/pull.ts +1 −1
| @@ -12,7 +12,7 @@ export const tool: Tool = { | ||
| 12 | 12 | name: "pull", |
| 13 | 13 | doc: "`{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment", |
| 14 | 14 | description: |
| 15 | "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.", | |
| 15 | "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `check`.", | |
This drops |
||
| 16 | 16 | inputSchema: { |
| 17 | 17 | type: "object", |
| 18 | 18 | properties: { |
src/http/mcp/tools/repo_settings.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "repo_settings", |
| 6 | 6 | doc: "`{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`", |
| 7 | 7 | description: |
| 8 | "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name (admin token).", | |
| 8 | "Change a repo's description or visibility (admin).", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/say.ts +1 −1
| @@ -7,7 +7,7 @@ export const tool: Tool = { | ||
| 7 | 7 | name: "say", |
| 8 | 8 | doc: "speak on an issue or a pull; a working builder hears it as its next step", |
| 9 | 9 | description: |
| 10 | "Say something on an issue or pull. A working builder hears it next; otherwise the next run does.", | |
| 10 | "Comment on an issue or pull; a builder hears it.", | |
| 11 | 11 | inputSchema: { |
| 12 | 12 | type: "object", |
| 13 | 13 | properties: { |
src/http/mcp/tools/sever.ts +1 −1
| @@ -6,7 +6,7 @@ export const tool: Tool = { | ||
| 6 | 6 | name: "sever", |
| 7 | 7 | doc: "`{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing", |
| 8 | 8 | description: |
| 9 | "Cut a spawned forge's link to its parent (its `forge` repository's owner only). Deletes nothing.", | |
| 9 | "Cut a spawned forge's link to its parent (owner only). Deletes nothing.", | |
| 10 | 10 | inputSchema: { |
| 11 | 11 | type: "object", |
| 12 | 12 | properties: { repo: REPO_ARG }, |
src/http/mcp/tools/variant.ts +1 −1
| @@ -8,7 +8,7 @@ export const tool: Tool = { | ||
| 8 | 8 | name: "variant", |
| 9 | 9 | doc: "`{ repo, number, answer, reason? }`: like or dislike one pull among its variants (`answer` like or dislike); a later vote replaces the earlier; a dislike closes the pull with `reason`", |
| 10 | 10 | description: |
| 11 | "Like or dislike a pull among its variants; a later vote replaces it; dislike closes it (`reason`).", | |
| 11 | "Like or dislike a pull among its variants; a later vote replaces; dislike closes.", | |
| 12 | 12 | inputSchema: { |
| 13 | 13 | type: "object", |
| 14 | 14 | properties: { |
test/mcp-flag-winner.test.ts added +88
| @@ -0,0 +1,88 @@ | ||
| 1 | /** MCP `flag_winner`: the page's make-the-winner-default, from a harness. */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { makeFlags, useFlagRegistry } from "../src/core/flags.ts"; | |
| 9 | import { createRepo } from "../src/core/repos.ts"; | |
| 10 | import { createToken } from "../src/core/tokens.ts"; | |
| 11 | import { createUser, getUserByName } from "../src/core/users.ts"; | |
| 12 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | ||
| 15 | quietLogs(); | |
| 16 | ||
| 17 | const PASS = "a-long-flag-passphrase"; | |
| 18 | const reg = makeFlags({ gamma: { why: "tries the new board", default: true, issue: 5440 } }); | |
| 19 | ||
| 20 | describe("MCP flag_winner", () => { | |
| 21 | let dataDir = ""; | |
| 22 | let app: App; | |
| 23 | let servers: Servers; | |
| 24 | ||
| 25 | const id = (name: string) => getUserByName(app.db, name)!.id; | |
| 26 | const winner = async (token: string, flagName: string, win: string) => { | |
| 27 | const res = await fetch(`${servers.url}/mcp`, { | |
| 28 | method: "POST", | |
| 29 | headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` }, | |
| 30 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "flag_winner", arguments: { name: flagName, winner: win } } }), | |
| 31 | }); | |
| 32 | const body = (await res.json()) as any; | |
| 33 | return { error: body.result.isError === true, text: body.result.content[0].text as string }; | |
| 34 | }; | |
| 35 | ||
| 36 | beforeAll(async () => { | |
| 37 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-flagwin-")); | |
| 38 | app = createApp({ dataDir, port: 0, forgeRepo: "alice/forge" }); | |
| 39 | servers = await serve(app); | |
| 40 | for (const [username, isAdmin] of [["alice", true], ["bob", false]] as const) { | |
| 41 | const made = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@x.test`, password: PASS, isAdmin }); | |
| 42 | if (!made.ok) throw new Error(username); | |
| 43 | } | |
| 44 | const repo = await createRepo(app.db, app.reposRoot, { ownerId: id("alice"), name: "forge", visibility: "public" }); | |
| 45 | if (!repo.ok) throw new Error(String(repo.error)); | |
| 46 | useFlagRegistry(reg); | |
| 47 | for (let i = 0; i < 60; i++) reg.flag("gamma"); // on x60 | |
| 48 | reg.set(app.db, "gamma", { users: ["u1"] }, "x"); | |
| 49 | }, 30_000); | |
| 50 | ||
| 51 | afterAll(async () => { | |
| 52 | useFlagRegistry(undefined); | |
| 53 | servers.stop(); | |
| 54 | app.close(); | |
| 55 | await rm(dataDir, { recursive: true, force: true }); | |
| 56 | }); | |
| 57 | ||
| 58 | test("a non-admin is refused and nothing changes", async () => { | |
| 59 | const bob = createToken(app.db, id("bob"), "t", "admin").token; | |
| 60 | const r = await winner(bob, "gamma", "on"); | |
| 61 | expect(r.error).toBe(true); | |
| 62 | expect(r.text).toContain("Flags are set by a forge admin."); | |
| 63 | expect(reg.value("gamma")).toEqual({ users: ["u1"] }); | |
| 64 | expect(app.db.query("SELECT 1 FROM issue").all()).toEqual([]); | |
| 65 | }); | |
| 66 | ||
| 67 | test("a winner the read-out does not offer is refused and the flag is unchanged", async () => { | |
| 68 | const admin = createToken(app.db, id("alice"), "t", "admin").token; | |
| 69 | const r = await winner(admin, "gamma", "off"); | |
| 70 | expect(r.error).toBe(true); | |
| 71 | expect(r.text).toContain("That variant is not the winner yet."); | |
| 72 | expect(reg.value("gamma")).toEqual({ users: ["u1"] }); | |
| 73 | expect(app.db.query("SELECT 1 FROM issue").all()).toEqual([]); | |
| 74 | }); | |
| 75 | ||
| 76 | test("the offered winner becomes the default and the issue exists", async () => { | |
| 77 | const admin = createToken(app.db, id("alice"), "t", "admin").token; | |
| 78 | const r = await winner(admin, "gamma", "on"); | |
| 79 | expect(r.error).toBe(false); | |
| 80 | const out = JSON.parse(r.text); | |
| 81 | expect(out.name).toBe("gamma"); | |
| 82 | expect(out.winner).toBe("on"); | |
| 83 | expect(typeof out.says).toBe("string"); | |
| 84 | expect(reg.value("gamma")).toEqual({ forge: true }); | |
| 85 | const row = app.db.query<{ title: string }, [number]>("SELECT title FROM issue WHERE number = ?1").get(out.issue); | |
| 86 | expect(row?.title).toContain("Remove flag gamma"); | |
| 87 | }); | |
| 88 | }); |
test/mcp.test.ts +1
| @@ -217,6 +217,7 @@ describe("the forge over MCP", () => { | ||
| 217 | 217 | "invites", |
| 218 | 218 | "account_role", |
| 219 | 219 | "account_suspend", |
| 220 | "flag_winner", | |
| 220 | 221 | "restore_drill", |
| 221 | 222 | "model_ceiling", |
| 222 | 223 | "account_verify", |
new above
offline
The tool itself is fine. Validation, the admin-scope check and the delegation to
makeWinnerDefault(which checksmayManageFlags) are right. It is new feature work under a FLOW ONLY direction, so it should wait until #5930's alarms are clear.