Skip to content

Commit 859c995

Browse files
loganjLarryclaude
authored
feat(buzz-mcp): let agents make announce channels with join_role (#1996)
Signed-off-by: Logan Johnson <[email protected]> Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz> Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent e56124c commit 859c995

2 files changed

Lines changed: 236 additions & 8 deletions

File tree

‎src/buzz-mcp/tools.test.ts‎

Lines changed: 175 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1006,7 +1006,15 @@ function relay(refused: Readonly<Record<string, string>> = {}) {
10061006
}
10071007
if (kind === 9000 || kind === 9021) {
10081008
const key = kind === 9021 ? me : target;
1009-
const role = template.tags.find((t) => t[0] === "role")?.[1] ?? "member";
1009+
// Like the relay, with no role asked for a member keeps theirs and a
1010+
// new one gets the channel's join_role.
1011+
const tags = (kind: number) =>
1012+
state.find((e) => e.kind === kind && e.tags[0]?.[1] === id)?.tags ?? [];
1013+
const role =
1014+
template.tags.find((t) => t[0] === "role")?.[1] ??
1015+
tags(39002).find((t) => t[0] === "p" && t[1] === key)?.[3] ??
1016+
tags(39000).find((t) => t[0] === "join_role")?.[1] ??
1017+
"member";
10101018
put(39002, id, (tags) => [...without(tags, key), ["p", key, "", role]]);
10111019
}
10121020
if (kind === 9001 || kind === 9022)
@@ -1720,9 +1728,29 @@ it("refuses channel arguments that do not fit, before publishing", async () => {
17201728
await expect(
17211729
channel("channel_create", { name: "x", visibility: "open", ttl: 1.5 }),
17221730
).rejects.toThrow("ttl must be a whole number of seconds.");
1731+
await expect(
1732+
channel("channel_create", {
1733+
name: "x",
1734+
visibility: "open",
1735+
join_role: "admin",
1736+
}),
1737+
).rejects.toThrow("join_role must be member or guest.");
1738+
await expect(
1739+
channel("channel_create", {
1740+
name: "x",
1741+
visibility: "private",
1742+
join_role: "guest",
1743+
}),
1744+
).rejects.toThrow("join_role guest is for open channels.");
1745+
await expect(
1746+
channel("channel_update", { visibility: "private", join_role: "guest" }),
1747+
).rejects.toThrow("join_role guest is for open channels.");
17231748
await expect(channel("channel_update", {})).rejects.toThrow(
1724-
"Give name, about, visibility, ttl, topic or purpose.",
1749+
"Give name, about, visibility, ttl, join_role, topic or purpose.",
17251750
);
1751+
await expect(
1752+
channel("channel_update", { join_role: "owner" }),
1753+
).rejects.toThrow("join_role must be member or guest.");
17261754
await expect(
17271755
callTool(client, { channel: "chan" }, "channel_leave", {}),
17281756
).rejects.toThrow("Invalid channel ID");
@@ -1760,6 +1788,151 @@ it("shows a channel's details and changes them as the channel shows", async () =
17601788
);
17611789
});
17621790

1791+
it("makes a channel an announce channel and back", async () => {
1792+
const { client, published } = relay();
1793+
const context = { channel: room };
1794+
await expect(
1795+
callTool(client, context, "channel_update", { join_role: "guest" }),
1796+
).resolves.toBe(`updated ${room}`);
1797+
await expect(callTool(client, context, "channel_get", {})).resolves.toBe(
1798+
`${room} plans (stream, open, join as guest)\nabout: roadmap\nyou: owner`,
1799+
);
1800+
await expect(
1801+
callTool(client, context, "channel_update", { join_role: "member" }),
1802+
).resolves.toBe(`updated ${room}`);
1803+
expect(published.map((template) => template.tags)).toEqual([
1804+
[
1805+
["h", room],
1806+
["join_role", "guest"],
1807+
],
1808+
[
1809+
["h", room],
1810+
["join_role", "member"],
1811+
],
1812+
]);
1813+
});
1814+
1815+
it("creates an announce channel after adding its template's agents", async () => {
1816+
const { client, published, state } = relay();
1817+
client.templates = vi.fn(async () => [
1818+
{ name: "Team", canvas: "", agents: [alice] },
1819+
]);
1820+
const answer = await callTool(client, {}, "channel_create", {
1821+
name: "team",
1822+
visibility: "open",
1823+
join_role: "guest",
1824+
template: "Team",
1825+
});
1826+
const id = published[0]?.tags[0]?.[1] as string;
1827+
// Set last: an agent added with no role would otherwise join as a guest.
1828+
expect(published.map((template) => [template.kind, template.tags])).toEqual([
1829+
[
1830+
9007,
1831+
[
1832+
["h", id],
1833+
["name", "team"],
1834+
["visibility", "open"],
1835+
["channel_type", "stream"],
1836+
],
1837+
],
1838+
[
1839+
9000,
1840+
[
1841+
["h", id],
1842+
["p", alice],
1843+
],
1844+
],
1845+
[
1846+
9002,
1847+
[
1848+
["h", id],
1849+
["join_role", "guest"],
1850+
],
1851+
],
1852+
]);
1853+
expect(answer).toBe(
1854+
[
1855+
`created ${id}`,
1856+
`added ${alice} Alice Smith`,
1857+
"new people join as guests",
1858+
].join("\n"),
1859+
);
1860+
await expect(
1861+
callTool(client, { channel: id }, "channel_get", {}),
1862+
).resolves.toBe(`${id} team (stream, open, join as guest)\nyou: owner`);
1863+
const roster = () =>
1864+
state.find((e) => e.kind === 39002 && e.tags[0]?.[1] === id)?.tags;
1865+
expect(roster()).toContainEqual(["p", alice, "", "member"]);
1866+
// Now anyone added with no role is a guest, and the answer says so.
1867+
await expect(
1868+
callTool(client, { channel: id }, "members", { add: [bob] }),
1869+
).resolves.toBe(`added ${bob} as guest`);
1870+
expect(roster()).toContainEqual(["p", bob, "", "guest"]);
1871+
});
1872+
1873+
it("sets join_role when the template's Canvas is refused, and says when it cannot", async () => {
1874+
const { client, published } = relay();
1875+
const publish = client.publish;
1876+
client.publish = vi.fn(async (template: Template) => {
1877+
if (template.kind === 40100) throw new Error("canvas refused");
1878+
return publish(template);
1879+
});
1880+
client.templates = vi.fn(async () => [
1881+
{ name: "Team", canvas: "# Plan", agents: [alice] },
1882+
]);
1883+
const create = () =>
1884+
callTool(client, {}, "channel_create", {
1885+
name: "team",
1886+
visibility: "open",
1887+
join_role: "guest",
1888+
template: "Team",
1889+
});
1890+
let answer = await create();
1891+
let id = published[0]?.tags[0]?.[1] as string;
1892+
expect(published.map((template) => template.kind)).toEqual([9007, 9002]);
1893+
expect(answer).toBe(
1894+
`created ${id}\nCanvas not started, so no agents were added: canvas refused\nnew people join as guests`,
1895+
);
1896+
const query = client.query;
1897+
client.query = vi.fn(async (filters: readonly Filter[]) => {
1898+
if (filters.some((f) => (f.kinds as number[]).includes(39000)))
1899+
throw new Error("kind 39000 unavailable");
1900+
return query(filters);
1901+
});
1902+
answer = await create();
1903+
id = published.at(-1)?.tags[0]?.[1] as string;
1904+
expect(published.at(-1)?.kind).toBe(9007);
1905+
expect(answer).toBe(
1906+
`The community accepted channel ${id} but its state could not be read back: kind 39000 unavailable; the template was not applied; join_role was not set.`,
1907+
);
1908+
});
1909+
1910+
it("reports a new channel whose join_role was refused", async () => {
1911+
const { client, published } = relay();
1912+
const publish = client.publish;
1913+
client.publish = vi.fn(async (template: Template) => {
1914+
if (template.kind === 9002) throw new Error("restricted: admins only");
1915+
return publish(template);
1916+
});
1917+
const answer = await callTool(client, {}, "channel_create", {
1918+
name: "news",
1919+
visibility: "open",
1920+
join_role: "guest",
1921+
});
1922+
const id = published[0]?.tags[0]?.[1] as string;
1923+
expect(published.map((template) => template.kind)).toEqual([9007]);
1924+
expect(answer).toBe(
1925+
`created ${id}\njoin_role not set: restricted: admins only`,
1926+
);
1927+
// member is the default, so it needs no second event.
1928+
await callTool(client, {}, "channel_create", {
1929+
name: "chat",
1930+
visibility: "open",
1931+
join_role: "member",
1932+
});
1933+
expect(published.map((template) => template.kind)).toEqual([9007, 9007]);
1934+
});
1935+
17631936
it("leaves, joins, archives, unarchives and deletes a channel", async () => {
17641937
const { client, published } = relay();
17651938
const context = { channel: room };

‎src/buzz-mcp/tools.ts‎

Lines changed: 61 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import { attestedOwner } from "../features/agents/owner-attestation";
2525
import type {
2626
BuzzClient,
2727
BuzzEvent,
28+
ChannelTemplate,
2829
Context,
2930
Filter,
3031
Memory,
@@ -51,6 +52,12 @@ const ttl = {
5152
type: "integer",
5253
description: "Seconds without a message before it archives; 0: never.",
5354
} as const;
55+
const joinRole = {
56+
type: "string",
57+
enum: ["member", "guest"],
58+
description:
59+
"Role for people who join or are added without one. guest on an open channel: anyone reads, only members post.",
60+
} as const;
5461
const tool = (
5562
name: string,
5663
description: string,
@@ -185,6 +192,7 @@ export const TOOLS: readonly Tool[] = [
185192
"system: left out of ordinary channel lists; anyone can still list an open one.",
186193
},
187194
ttl,
195+
join_role: joinRole,
188196
template: str,
189197
},
190198
["name", "visibility"],
@@ -195,6 +203,7 @@ export const TOOLS: readonly Tool[] = [
195203
about: str,
196204
visibility: { type: "string", enum: ["open", "private"] },
197205
ttl,
206+
join_role: joinRole,
198207
topic: str,
199208
purpose: str,
200209
}),
@@ -1356,6 +1365,7 @@ class Tools {
13561365
tag(metadata, "ttl")
13571366
? `archives after ${tag(metadata, "ttl")}s idle`
13581367
: "",
1368+
tag(metadata, "join_role") === "guest" ? "join as guest" : "",
13591369
].filter(Boolean);
13601370
return [
13611371
`${channel} ${tag(metadata, "name") ?? ""} (${flags.join(", ")})`,
@@ -1376,6 +1386,9 @@ class Tools {
13761386
const type = args.type ?? "stream";
13771387
if (type !== "stream" && type !== "forum" && type !== "system")
13781388
throw new Error("type must be stream, forum or system.");
1389+
const role = joinRoleArg(args);
1390+
if (role === "guest" && args.visibility === "private")
1391+
throw new Error("join_role guest is for open channels.");
13791392
// Found first, so a wrong name creates nothing.
13801393
const template =
13811394
args.template === undefined
@@ -1396,9 +1409,25 @@ class Tools {
13961409
});
13971410
const shown = await until(() => this.metadata(id), Boolean).catch(unread);
13981411
if (!shown || shown instanceof Error)
1399-
return `The community accepted channel ${id} but ${shown ? shown.message : "does not show it yet"}${template ? "; the template was not applied" : ""}.`;
1412+
return `The community accepted channel ${id} but ${shown ? shown.message : "does not show it yet"}${template ? "; the template was not applied" : ""}${role === "guest" ? "; join_role was not set" : ""}.`;
14001413
const lines = [`created ${id}`];
1401-
if (!template) return lines.join("\n");
1414+
if (template) lines.push(...(await this.apply(id, template)));
1415+
// Last, so the template's agents join as members, not guests.
1416+
if (role === "guest")
1417+
try {
1418+
const answer = await this.update(id, { join_role: role });
1419+
lines.push(
1420+
answer === `updated ${id}` ? "new people join as guests" : answer,
1421+
);
1422+
} catch (error) {
1423+
lines.push(`join_role not set: ${reason(error)}`);
1424+
}
1425+
return lines.join("\n");
1426+
}
1427+
1428+
/** Starts a new channel's Canvas and adds its agents from `template`. */
1429+
async apply(id: string, template: ChannelTemplate) {
1430+
const lines: string[] = [];
14021431
// The template's own agents, as Buzz adds them; each is tried.
14031432
const agents = template.agents.filter((key) => key !== this.client.pubkey);
14041433
if (template.canvas.trim())
@@ -1417,10 +1446,10 @@ class Tools {
14171446
lines.push(
14181447
`Canvas not started${agents.length ? ", so no agents were added" : ""}: ${reason(error)}`,
14191448
);
1420-
return lines.join("\n");
1449+
return lines;
14211450
}
14221451
if (agents.length) lines.push(...(await this.change(id, agents, [])).lines);
1423-
return lines.join("\n");
1452+
return lines;
14241453
}
14251454

14261455
/** The owner's template named `name`, as one, without guessing. */
@@ -1461,8 +1490,18 @@ class Tools {
14611490
}
14621491
if (args.ttl !== undefined)
14631492
wanted.push(["ttl", String(seconds(args.ttl) ?? "")]);
1493+
const role = joinRoleArg(args);
1494+
if (
1495+
role === "guest" &&
1496+
(args.visibility ?? (has(metadata, "private") ? "private" : "open")) ===
1497+
"private"
1498+
)
1499+
throw new Error("join_role guest is for open channels.");
1500+
if (role) wanted.push(["join_role", role]);
14641501
if (!wanted.length)
1465-
throw new Error("Give name, about, visibility, ttl, topic or purpose.");
1502+
throw new Error(
1503+
"Give name, about, visibility, ttl, join_role, topic or purpose.",
1504+
);
14661505
const value = (key: string) => wanted.find((t) => t[0] === key)?.[1];
14671506
checkDetails(
14681507
value("name"),
@@ -1531,13 +1570,20 @@ class Tools {
15311570
);
15321571
const who = (key: string) =>
15331572
names.has(key) ? `${key} ${names.get(key)}` : key;
1573+
// With no role asked for, the relay gives a new member the channel's
1574+
// join_role, which is guest on an announce channel.
1575+
const shown = (key: string) =>
1576+
role ??
1577+
(roster instanceof Error
1578+
? undefined
1579+
: roster.find((m) => m.pubkey === key)?.role);
15341580
const report = (key: string, verb: string, done?: typeof added) =>
15351581
refused.has(key)
15361582
? `not ${verb} ${who(key)}: ${refused.get(key)}`
15371583
: roster instanceof Error
15381584
? `${who(key)}: the community accepted it but ${roster.message}`
15391585
: done?.(roster, key)
1540-
? `${verb} ${who(key)}${verb === "added" && role ? ` as ${role}` : ""}`
1586+
? `${verb} ${who(key)}${verb === "added" && (role || shown(key) !== "member") ? ` as ${shown(key)}` : ""}`
15411587
: `${who(key)}: the community accepted it but does not show it yet`;
15421588
return {
15431589
changed: refused.size < add.length + remove.length,
@@ -2118,6 +2164,15 @@ function seconds(value: unknown) {
21182164
return value;
21192165
}
21202166

2167+
/** A `join_role` argument: undefined when absent. */
2168+
function joinRoleArg(args: Args) {
2169+
const value = args.join_role;
2170+
if (value === undefined) return undefined;
2171+
if (value !== "member" && value !== "guest")
2172+
throw new Error("join_role must be member or guest.");
2173+
return value;
2174+
}
2175+
21212176
/** A `since` or `before` argument: a Unix time in seconds, inclusive. */
21222177
function unixTime(args: Args, key: string) {
21232178
const value = args[key];

0 commit comments

Comments
 (0)