Skip to content

Commit 79e9f8f

Browse files
baxenmbotclaude
committed
Let agent_create propose instructions
agent_create takes an optional instructions argument, as agent_update does. The request keeps it, and the owner's Create agent review starts from the type's defaults with those instructions adopted. A type with no instructions to adopt refuses the request up front. Co-authored-by: mbot <3754f8729004d95654c46dbab3129e4ab9ef05cc2534e2a3fbfc155983bd637b@buzz.block.builderlab.xyz> Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Bradley Axen <[email protected]>
1 parent f51ecb1 commit 79e9f8f

9 files changed

Lines changed: 134 additions & 16 deletions

File tree

‎docs/agents.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,9 @@ and reported as migration errors.
3636

3737
The shared tools offer `agent_types` to list installed local runtimes and
3838
`agent_create` to submit an unsaved creation draft using a listed type key and a display name,
39-
optionally with a picture. It returns a request ID and `saved: false`; no identity exists yet. The owner reviews
40-
the usual Create agent form, may edit the name, runtime and settings, and creates
39+
optionally with instructions for types that take them and a picture. It returns a request ID and `saved: false`; no identity exists yet. The owner reviews
40+
the usual Create agent form, filled in with any requested instructions and picture, may edit
41+
the name, runtime and settings, and creates
4142
only by submitting it. Closing the form discards the request. Requests are local,
4243
bounded to 16 and do not survive reload or a change of signed-in owner.
4344
Approval binds the identity to the requesting agent's owner and community, even

‎src/bundled/agents/AgentCreateDialog.test.tsx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import { AgentInstructions } from "../../features/agents/AgentInstructions";
1818
import { agentAvatars } from "../../features/agents/avatar-packs";
1919
import type {
2020
Agent,
21+
AgentCreationRequest,
2122
Agents,
2223
NewAgent,
2324
RegisteredAgentType,
@@ -162,6 +163,7 @@ function setup(
162163
types: readonly RegisteredAgentType[],
163164
create: (input: NewAgent) => Promise<Agent> = async () => made,
164165
community?: string,
166+
request?: AgentCreationRequest,
165167
) {
166168
const agents = { create: vi.fn(create) } as unknown as Agents & {
167169
create: ReturnType<typeof vi.fn>;
@@ -175,6 +177,7 @@ function setup(
175177
community={community}
176178
onCreated={onCreated}
177179
onClose={onClose}
180+
{...(request && { request })}
178181
/>,
179182
);
180183
const dialog = screen.getByRole("dialog", { name: "Create agent" });
@@ -850,6 +853,52 @@ it("keeps typed instructions when choosing a harness or model", async () => {
850853
);
851854
});
852855

856+
it("keeps requested instructions the owner cleared when choosing a harness", async () => {
857+
// Both carry instructions as the bundled harnesses do, omitting blank ones.
858+
const carrying = (key: string, title: string): RegisteredAgentType => ({
859+
...notes,
860+
key,
861+
title,
862+
defaults: () => ({ config: { notes: "start", instructions: "" } }),
863+
carry: (config) => {
864+
const { instructions } = config as Notes;
865+
return instructions.trim() ? { instructions } : {};
866+
},
867+
adopt: (carry, config) => ({
868+
...(config as Notes),
869+
instructions: carry.instructions ?? (config as Notes).instructions,
870+
}),
871+
});
872+
const { agents, dialog, user } = setup(
873+
[carrying("test/notes", "Notes"), carrying("test/other", "Other")],
874+
undefined,
875+
undefined,
876+
{
877+
id: "draft",
878+
requester: "a".repeat(64),
879+
requesterName: "Parent",
880+
owner: "b".repeat(64),
881+
community: "https://relay.example",
882+
type: "test/notes",
883+
name: "Nova",
884+
instructions: "Review PRs.",
885+
},
886+
);
887+
const instructions = within(dialog).getByLabelText("Instructions");
888+
expect(instructions).toHaveValue("Review PRs.");
889+
await user.clear(instructions);
890+
await user.click(within(dialog).getByRole("combobox", { name: "Harness" }));
891+
await user.click(await screen.findByRole("option", { name: "Other" }));
892+
expect(within(dialog).getByLabelText("Instructions")).toHaveValue("");
893+
await user.click(createButton());
894+
expect(agents.create).toHaveBeenCalledWith(
895+
expect.objectContaining({
896+
type: "test/other",
897+
config: { notes: "start", instructions: "" },
898+
}),
899+
);
900+
});
901+
853902
it("submits custom creation instructions and disables editing while saving", async () => {
854903
let finish: (agent: Agent) => void = () => {};
855904
const creationType: RegisteredAgentType = {

‎src/bundled/agents/AgentCreateDialog.tsx‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -108,16 +108,19 @@ export function AgentCreateDialog({
108108
return undefined;
109109
}
110110
};
111-
/** The agent's settings in `item`, with the requested instructions. */
111+
/** The agent's settings in `item`, or a new agent's defaults, with the
112+
* requested instructions. */
112113
const seed = (item: RegisteredAgentType | undefined) => {
113-
if (!update) return startingConfig(item);
114-
const { agent, request } = update;
115-
const config =
116-
item?.key === agent.type
117-
? agent.config
114+
const instructions = update
115+
? update.request.instructions
116+
: request?.instructions;
117+
const config = !update
118+
? startingConfig(item)
119+
: item?.key === update.agent.type
120+
? update.agent.config
118121
: (migration(item)?.config ?? startingConfig(item));
119-
return request.instructions !== undefined && item?.adopt
120-
? item.adopt({ instructions: request.instructions }, config)
122+
return instructions !== undefined && item?.adopt
123+
? item.adopt({ instructions }, config)
121124
: config;
122125
};
123126
const [config, setConfig] = useState(() => seed(type));
@@ -144,7 +147,9 @@ export function AgentCreateDialog({
144147
const choose = (key: string) => {
145148
const item = types.find((candidate) => candidate.key === key);
146149
if (!item || key === type?.key) return;
147-
const next = seed(item);
150+
// A new agent's request seeds only the first harness; from then on its
151+
// instructions are what the owner left, cleared ones included.
152+
const next = update ? seed(item) : startingConfig(item);
148153
// Typed instructions follow a new agent to its new harness.
149154
const instructions = update
150155
? undefined

‎src/bundled/agents/CreationReview.test.tsx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@ function fixture(change: Partial<AgentCreationRequest> = {}) {
3636
key: "test/echo",
3737
title: "Echo",
3838
defaults: () => ({ config: { reply: "default" } }),
39+
adopt: (carry: { instructions?: string }, saved: { reply: string }) => ({
40+
reply: carry.instructions ?? saved.reply,
41+
}),
3942
},
4043
] as unknown as readonly RegisteredAgentType[];
4144
const agents = {
@@ -93,6 +96,19 @@ it("starts from a requested picture and creates the agent with it", async () =>
9396
);
9497
});
9598

99+
it("starts the review from the requested instructions", async () => {
100+
const user = userEvent.setup();
101+
const agents = fixture({ instructions: "Review PRs." });
102+
await screen.findByDisplayValue("Child");
103+
await user.click(screen.getByRole("button", { name: /^Create agent$/ }));
104+
await waitFor(() =>
105+
expect(agents.approveCreation).toHaveBeenCalledWith(
106+
"draft",
107+
expect.objectContaining({ config: { reply: "Review PRs." } }),
108+
),
109+
);
110+
});
111+
96112
it("dismisses an unsaved request when the owner closes its review", async () => {
97113
const user = userEvent.setup();
98114
const agents = fixture();

‎src/buzz-mcp/client.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ export interface BuzzClient {
9191
input: Readonly<{
9292
type: string;
9393
name: string;
94+
instructions?: string;
9495
/** Uploads the picture once the request is valid: its URL. */
9596
picture?: () => Promise<string>;
9697
}>,

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3851,6 +3851,21 @@ it("validates creation inputs and reports hosts without agent creation", async (
38513851
"required",
38523852
);
38533853
expect(client.createAgent).not.toHaveBeenCalled();
3854+
await callTool(client, {}, "agent_create", { type: "x", name: "Child" });
3855+
await callTool(client, {}, "agent_create", {
3856+
type: "x",
3857+
name: "Child",
3858+
instructions: "Review PRs.",
3859+
});
3860+
expect(client.createAgent).toHaveBeenNthCalledWith(1, {
3861+
type: "x",
3862+
name: "Child",
3863+
});
3864+
expect(client.createAgent).toHaveBeenNthCalledWith(2, {
3865+
type: "x",
3866+
name: "Child",
3867+
instructions: "Review PRs.",
3868+
});
38543869
});
38553870

38563871
it("hands off to the agent in another of its conversations it can see", async () => {

‎src/buzz-mcp/tools.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,8 +138,8 @@ export const TOOLS: readonly Tool[] = [
138138
),
139139
tool(
140140
"agent_create",
141-
"Submit an unsaved agent-creation draft for your owner to review. Nothing is created until they save it. Use a type key from agent_types; picture is a local image file for its avatar.",
142-
{ type: str, name: str, picture: str },
141+
"Submit an unsaved agent-creation draft for your owner to review. Nothing is created until they save it. Use a type key from agent_types; instructions are optional; picture is a local image file for its avatar.",
142+
{ type: str, name: str, instructions: str, picture: str },
143143
["type", "name"],
144144
),
145145
tool(
@@ -463,9 +463,15 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
463463
const type = text(args.type)?.trim();
464464
const name = text(args.name)?.trim();
465465
if (!type || !name) throw new Error("type and name are required");
466+
const instructions = text(args.instructions);
466467
const picture = proposedPicture(client, args.picture);
467468
return JSON.stringify(
468-
await client.createAgent({ type, name, ...(picture && { picture }) }),
469+
await client.createAgent({
470+
type,
471+
name,
472+
...(instructions && { instructions }),
473+
...(picture && { picture }),
474+
}),
469475
);
470476
},
471477
async self_handoff(tools, args) {

‎src/features/agents/service.test.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11538,6 +11538,7 @@ it("submits an unsaved creation draft and creates only after owner review", asyn
1153811538
(await callTool(client, {}, "agent_create", {
1153911539
type: "example/echo",
1154011540
name: " Child ",
11541+
instructions: "Review PRs.",
1154111542
})) as string,
1154211543
);
1154311544
expect(result).toEqual({ requestId: expect.any(String), saved: false });
@@ -11547,6 +11548,7 @@ it("submits an unsaved creation draft and creates only after owner review", asyn
1154711548
id: result.requestId,
1154811549
type: "example/echo",
1154911550
name: "Child",
11551+
instructions: "Review PRs.",
1155011552
requester: bot,
1155111553
community: "https://relay.example.test",
1155211554
});
@@ -11588,7 +11590,15 @@ it("dismisses a creation draft without creating an identity", async () => {
1158811590
});
1158911591

1159011592
it("refuses agent creation through a stale handle or an unavailable type", async () => {
11591-
const { service, native, plugin, connect } = await setup();
11593+
const { service, native, plugin, connect, ctx } = await setup();
11594+
ctx
11595+
.extend({ pluginOwner: Object.freeze({ id: "other", revision: "one" }) })
11596+
.agents.register({
11597+
id: "plain",
11598+
title: "Plain",
11599+
defaults: () => ({ config: {} }),
11600+
run: vi.fn(),
11601+
});
1159211602
await service.create({ type: "example/echo", name: "Parent" });
1159311603
await vi.waitFor(() => expect(plugin.agents.handle(bot)).toBeDefined());
1159411604
const handle = plugin.agents.handle(bot);
@@ -11599,6 +11609,14 @@ it("refuses agent creation through a stale handle or an unavailable type", async
1159911609
await expect(
1160011610
handle.createAgent?.({ type: "example/echo", name: " " }),
1160111611
).rejects.toThrow("Name the agent");
11612+
await expect(
11613+
handle.createAgent?.({
11614+
type: "other/plain",
11615+
name: "Child",
11616+
instructions: "Triage.",
11617+
}),
11618+
).rejects.toThrow("Plain agents have no instructions to set");
11619+
expect(service.creationRequests()).toEqual([]);
1160211620
connect(false);
1160311621
await expect(
1160411622
handle.createAgent?.({ type: "example/echo", name: "Child" }),

‎src/features/agents/service.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -906,7 +906,11 @@ export type RetypePreview = Readonly<{
906906
/** A proposal's picture: uploads it once the proposal is valid, giving its
907907
* HTTPS image URL. */
908908
export type ProposedPicture = () => Promise<string>;
909-
type AgentCreation = Readonly<{ type: string; name: string }>;
909+
type AgentCreation = Readonly<{
910+
type: string;
911+
name: string;
912+
instructions?: string;
913+
}>;
910914
/** A requested agent. */
911915
export type AgentCreationInput = AgentCreation &
912916
Readonly<{ picture?: ProposedPicture }>;
@@ -1860,6 +1864,8 @@ export class AgentsService extends Service implements Agents {
18601864
if (!kind) throw new Error("That agent type is not available");
18611865
if (kind.remote)
18621866
throw new Error("A hosted agent's key stays with its provider");
1867+
if (input.instructions && !kind.adopt)
1868+
throw new Error(`${kind.title} agents have no instructions to set`);
18631869
if (this.requests.length + this.updates.length >= 16)
18641870
throw new Error("Review the pending agent requests first");
18651871
return {
@@ -1870,6 +1876,7 @@ export class AgentsService extends Service implements Agents {
18701876
community: binding.origin,
18711877
type: input.type,
18721878
name: input.name.trim(),
1879+
...(input.instructions && { instructions: input.instructions }),
18731880
...(picture && { picture }),
18741881
};
18751882
};

0 commit comments

Comments
 (0)