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

The Crew teams page and the `teams` MCP tool say each team's effective share of builder slots #13275

Merged opened this

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

Merged

scout/forge:scout/13255-the-crew-teams-page-and-the-teams-mcp-to → main 5 commits fork 3 threads · 3 unresolved

  • Merged. scout/13255-the-crew-teams-page-and-the-teams-mcp-to was merged into main as 3c69915.

Review

Sign in to review this change.
8 files changed +166 −5
docs/OPERATING.md +1 −1

Diff not shown — a line 5,045 characters wide (limit 2,000). +1 −1

View file
docs/features/README.md +1
@@ -375,6 +375,7 @@ Read with the guide page [Agents: MCP, git, or the terminal](../guide-agents.md)
375375 - [Offering a patch with no account](offer.md)
376376 - [The report form for outsiders](report-form.md)
377377 - [The receipt an outsider is handed for a report](report-receipt.md)
378 - [A team's effective share of builder slots](team-effective-share.md)
378379 - [Which harness holds a token](tokens-harness.md)
379380
380381 ### Backups and moving
docs/features/team-effective-share.md added +16
@@ -0,0 +1,16 @@
1 # A team's effective share of builder slots
2
3 A team's share is its dial, as it stands: dials are percentages that may not pass 100 together, and nothing is
outdated

Wrong: the code (effectiveShare) returns the dial itself when above zero, so two teams at 50 read 50% each, but 30 beside 10 reads 30% and 10%, not 75% and 25%. There is no normalising, and OPERATING.md says dials may not pass 100. Rewrite to match: the share is the dial; a zero-dial team shows the rest the dials leave, as unlabelled.

4 normalised, so 30 beside 10 reads 30% and 10%. A team at zero owns nothing extra: its issues are unlabelled work, and it
5 reads `dial 0% · shares the 50% left, unlabelled`, the rest the dials leave, shared among all unlabelled work (so several
6 zero-dial teams are not each 50%). The dial is said once per row.
7
8 - **Web:** `/settings/teams` shows each team's dial and its share (`shareSays`).
9 - **Terminal:** the Teams screen lists each team with its dial and share in the secondary column.
10 - **MCP:** the `teams` tool lists each team with the share fields and `shareSays` beside its dial.
11
12 All three read the same `effectiveShare` and `shareSays` in `src/core/teams.ts`.
13
14 Try it: open `/settings/teams` as the owner and change a dial; the shares of every team move.
15
16 Pinned by `test/team-effective-share.test.ts`.
src/core/teams.ts +25
@@ -98,3 +98,28 @@ export function saveTeam(
9898 if (failed) return err(failed);
9999 return ok(getTeam(db, slug)!);
100100 }
101
102 /**
103 * The share of builder starts a team actually gets: its dial when above zero.
104 * A zero-dial team owns nothing extra, so its issues are unlabelled work and
105 * take the rest the dials leave (`labelled: false`).
106 */
107 export function effectiveShare(
108 teams: readonly Team[],
109 slug: string,
110 ): { readonly share: number; readonly labelled: boolean } {
111 const used = teams.reduce((n, t) => n + Math.max(0, t.dial), 0);
112 const t = teams.find((x) => x.slug === slug);
113 if (t && t.dial > 0) return { share: t.dial, labelled: true };
114 return { share: Math.max(0, DIAL_MAX - used), labelled: false };
115 }

With several zero-dial teams each row says the full rest (e.g. three teams each 50% of starts, unlabelled), which reads as 150%. Say the rest is shared among unlabelled work, e.g. shares the 50% left, so the figure is not read per team.

116
117 /**
118 * The one sentence of a team's share, said alike by the page, terminal and tool.
119 * The dial is said once: a labelled team's share is its dial; a zero-dial team
120 * shares what the dials leave with all unlabelled work, so the figure is not per team.
121 */
122 export function shareSays(teams: readonly Team[], slug: string): string {
123 const { share, labelled } = effectiveShare(teams, slug);
124 return labelled ? `${share}% of starts` : `dial 0% · shares the ${share}% left, unlabelled`;
125 }
src/http/mcp/tools/teams.ts +9 −1
@@ -1,4 +1,5 @@
11 import { changeTeam, planTeam, readTeams, TEAM_SAYS } from "../../../actions/teams.ts";
2 import { effectiveShare, shareSays } from "../../../core/teams.ts";
23 import { scopeAllows } from "../../../core/tokens.ts";
34 import { good, bad, type Tool } from "../shared.ts";
45
@@ -23,7 +24,14 @@ export const tool: Tool = {
2324 const read = readTeams(ctx.app, user);
2425 if (!read.ok) return bad("not_found", "no such tool here");
2526 const slug = args["slug"];
26 if (slug === undefined) return good({ teams: read.value.teams });
27 if (slug === undefined)
28 return good({
29 teams: read.value.teams.map((t) => ({
30 ...t,
31 ...effectiveShare(read.value.teams, t.slug),
32 shareSays: shareSays(read.value.teams, t.slug),
33 })),
34 });
2735 const team = typeof slug === "string" ? read.value.teams.find((t) => t.slug === slug) : undefined;
2836 if (!team) return bad("not_found", `no team ${String(slug)}`);
2937 const { charter, dial, members } = args;
src/tui/screens/teams.ts +2 −1
@@ -7,6 +7,7 @@
77 * nothing and sets nothing.
88 */
99
10 import { shareSays } from "../../core/teams.ts";
1011 import { changeTeam, readTeamQueue, readTeams, teamChanges, TEAM_SAYS } from "../../actions/teams.ts";
1112 import type { Ctx, Screen } from "../app/app.ts";
1213 import { binding } from "../app/keys.ts";
@@ -69,7 +70,7 @@ export function teamsScreen(f: Session, ctx: Ctx): Screen {
6970 const names = new Map(r.value.agents.map((a) => [a.user.id, a.user.username]));
7071 return r.value.teams.map((t) => ({
7172 title: t.name,
72 secondary: `${t.dial}%`,
73 secondary: shareSays(r.value.teams, t.slug),
7374 meta: t.members.map((id) => names.get(id) ?? id).join(", ") || "no members",
7475 }));
7576 };
src/web/pages/teams.ts +2 −2
@@ -7,7 +7,7 @@
77
88 import { changeTeam, readTeamQueue, readTeams, teamChanges, TEAM_SAYS } from "../../actions/teams.ts";
99 import type { Agent } from "../../core/agents.ts";
10 import { CHARTER_MAX, DIAL_MAX, type Team } from "../../core/teams.ts";
10 import { CHARTER_MAX, DIAL_MAX, shareSays, type Team } from "../../core/teams.ts";
1111 import type { QueuedPull } from "../../core/team_queue.ts";
1212 import { timeAgo } from "../ui.ts";
1313 import type { Ctx } from "../../http/context.ts";
@@ -45,7 +45,7 @@ function regions(ctx: Ctx, timed = false): Record<string, string> | undefined {
4545 href: `/settings/teams/${t.slug}`,
4646 lead: icon("bot"),
4747 title: t.name,
48 meta: html`${String(t.dial)}% · ${String(t.members.length)} ${t.members.length === 1 ? "member" : "members"} · ${String(waiting)} waiting`,
48 meta: html`${shareSays(teams, t.slug)} · ${String(t.members.length)} ${t.members.length === 1 ? "member" : "members"} · ${String(waiting)} waiting`,
outdated

Principle 1 (nothing explains itself twice): dial 30% · 30% of starts prints the same number twice for every team with a dial. Show the dial once; for a labelled team the share sentence is enough, and add the dial only where it differs (a zero-dial team: dial 0% · 50% of starts, unlabelled). Same in src/tui/screens/teams.ts.

4949 });
5050 });
5151 const out: Record<string, Html> = {
test/team-effective-share.test.ts added +110
@@ -0,0 +1,110 @@
1 /**
2 * One figure: the Crew teams page, the terminal screen and the `teams` tool say the same effective
3 * share.
4 */
5 import { afterAll, beforeAll, 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 { effectiveShare, saveTeam, shareSays, type Team } from "../src/core/teams.ts";
11 import { createSession } from "../src/core/sessions.ts";
12 import { createToken } from "../src/core/tokens.ts";
13 import { createUser, getUserByName } from "../src/core/users.ts";
14 import { sharesOf, REST } from "../src/crew/team_share.ts";
15 import { serve, type Servers } from "../src/http/server.ts";
16 import { createForgeApp } from "../src/tui/forge.ts";
17 import { headlessTerminal } from "../src/tui/term/terminal.ts";
18 import { quietLogs } from "./helpers/globals.ts";
19 import { settleApp } from "./helpers/tui.ts";
20
21 type TeamRow = { slug: string; shareSays: string };
22
23 quietLogs();
24
25 let dir: string;
26 let app: App;
27 let servers: Servers;
28 let aliceId: string;
29
30 beforeAll(async () => {
31 dir = await mkdtemp(join(tmpdir(), "forge-share-"));
32 app = createApp({ dataDir: dir, port: 0 });
33 servers = await serve(app);
34 const made = await createUser(app.db, {
35 origin: "seed",
36 trusted: true,
37 username: "alice",
38 email: "[email protected]",
39 password: "a-good-passphrase",
40 adminIfFirst: true,
41 });
42 if (!made.ok) throw new Error(made.error);
43 aliceId = made.value.id;
44 saveTeam(app.db, "design", { charter: "x", dial: 30, members: [] });
45 saveTeam(app.db, "platform", { charter: "x", dial: 20, members: [] });
46 });
47 afterAll(async () => {
48 servers.stop();
49 app.close();
50 await rm(dir, { recursive: true, force: true });
51 });
52
53 const t = (slug: string, dial: number): Team => ({ slug, name: slug, charter: "", dial, members: [] });
54
55 test("dispatch's shares and the effective share agree; a zero dial is unlabelled", () => {
56 const teams = [t("a", 30), t("b", 0), t("c", 20)];
57 expect(effectiveShare(teams, "a")).toEqual({ share: 30, labelled: true });
58 expect(effectiveShare(teams, "b")).toEqual({ share: 50, labelled: false });
59 expect(sharesOf(teams).get(REST)).toBe(50);
60 });
61
62 test("page, terminal and tool print the same share for every team", async () => {
63 const says = (slug: string) =>
64 shareSays(
65 [t("design", 30), t("data-science", 0), t("security", 0), t("platform", 20)],
66 slug,
67 );
68 expect(says("design")).toBe("30% of starts");
69 expect(says("security")).toBe("dial 0% · shares the 50% left, unlabelled");
70
71 const page = await (
72 await fetch(`${servers.url}/settings/teams`, {
73 headers: { cookie: `forge_session=${createSession(app.db, aliceId).token}` },
74 })
75 ).text();
76
77 const res = await fetch(`${servers.url}/mcp`, {
78 method: "POST",
79 headers: {
80 "content-type": "application/json",
81 accept: "application/json, text/event-stream",
82 authorization: `Bearer ${createToken(app.db, aliceId, "admin", "admin").token}`,
83 },
84 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "teams", arguments: {} } }),
85 });
86 const listed = JSON.parse(((await res.json()) as { result: { content: { text: string }[] } }).result.content[0]!.text).teams as TeamRow[];
87
88 const terminal = headlessTerminal(160, 32);
89 const { app: tui } = createForgeApp(
90 app,
91 { sshUsername: "t", remoteAddress: "127.0.0.1", user: getUserByName(app.db, "alice")! },
92 { terminal, exitHooks: false },
93 );
94 tui.start();
95 const press = (key: string, ctrl = false) => tui.dispatch({ type: "key", key, ctrl, alt: false, shift: false });
96 press("k", true);
97 for (const ch of "Crew teams") press(ch);
98 press("enter");
99 await settleApp(tui);
100 const screen = tui.screen.toText();
101 tui.stop();
102
103 expect(listed.length).toBe(4);
104 for (const team of listed) {
105 const sentence = says(team.slug);
106 expect(team.shareSays).toBe(sentence);
107 expect(page).toContain(sentence);
108 expect(screen).toContain(sentence);
109 }
110 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs