Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions docs/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -1203,19 +1203,36 @@ Regression source: `features/agents/choices.test.ts`, plus the chooser, composer
and Solo chat admission tests. They exercise shared selection and Solo chat admission,
not native execution.

## Creating a Solo chat in a personal workspace

Only locally hosted agent runs can call `solo_workspace_list` for the host-bound
owner's personal workspace IDs and names in that community. Pass an exact ID as
`workspace` to `channel_create` with `solo: true`, and name the owner explicitly
in `members`. This files only that new confirmed Solo chat. It does not enroll
members implicitly, copy default agents/Canvas, or change agent authorship.
Unknown targets and missing owner membership fail before creation. A target
removed later or a failed preference write leaves the created chat intact; the
result preserves its ID. A known refusal before assignment says “created, not
filed”; after assignment starts, failure says placement is unconfirmed and may
have completed. Inspect or refresh the chat before using **Move to**; never
create a duplicate. Omit `workspace` for unchanged creation.
## Filing conversations in the owner's workspaces

Only locally hosted agent runs can call `workspace_list` for the host-bound
owner's sidebar workspace IDs and names in that community: every unified
workspace. Pass an exact ID as `workspace` to `channel_create` for any type.
The owner must be able to see the result: a Solo chat names the owner in
`members`, and a stream or forum is `open` (a private one would leave the owner
out, so it is refused before creation). Filing checks the relay's confirmed
metadata and roster: the agent created it, it is in no plugin region, its named
members joined, and the owner is a member or it is open.

Without `template`, creation applies the workspace's defaults through the same
`loadChatSetup` read as the Solo **New chat** flow: a Solo chat's default agents
join in the create and its Canvas starts with the full workspace block; a team
channel's Canvas gets only `shareableInstructions`, as **New channel** shares by
default, and its default agents are added after. A chosen `template` replaces
the defaults, as in the dialog. Defaults that cannot load fail before creation.

Unknown targets and missing owner visibility fail before creation. A target
removed later or a failed preference write leaves the created conversation
intact; the result preserves its ID. A known refusal before assignment says
“created, not filed”; after assignment starts, failure says placement is
unconfirmed and may have completed. Check the sidebar before `channel_move`;
never create a duplicate. Omit `workspace` for unchanged creation.

`channel_move` files an existing conversation of any type, DMs included, in a
workspace, or unfiles it with an empty `workspace`. It reads the conversation's
relay metadata and roster as the owner and moves only what the owner can see
(member, or open), and refuses chats a plugin region manages, as **Move to**
does. It writes the same sidebar assignment as **Move to**.

## Exact channel-member mentions

Expand Down
19 changes: 12 additions & 7 deletions docs/buzz-help.md
Original file line number Diff line number Diff line change
Expand Up @@ -551,13 +551,18 @@ Quitting Buzz also turns it off.
that represents it.
Plugins can keep separate unsent drafts in the same workspace. Where supported,
each draft keeps its text, files, settings, model, and effort when you return.
A locally hosted agent can list your personal workspace IDs with
`solo_workspace_list` and explicitly choose one when creating a Solo chat,
provided it includes you in the chat’s members. This only files the new chat;
it does not copy workspace defaults or Canvas. A known pre-write refusal
reports “created, not filed.” A write that cannot be
confirmed reports that placement may have completed: inspect or refresh the
reported chat before **Move to**, and never create it again.
A locally hosted agent can list your sidebar workspaces with `workspace_list`
and choose one when it creates a chat, channel or forum, if you can see the
result: a Solo chat must include you in its members, and a channel or forum
in a workspace must be open. Unless the agent picks a template, the
workspace’s defaults apply as from its **New chat** or **New channel**: its
default agents and Canvas. A team channel gets only the Canvas instructions,
not the folders or worktree settings. A known pre-write refusal reports
“created, not filed.” A write that cannot be confirmed reports that placement
may have completed: check the sidebar before moving it, and never create it
again. The agent can also move any conversation you can see, including a DM,
to a workspace with `channel_move`, or unfile it with an empty workspace, as
**Move to** does. Chats a plugin manages stay where the plugin puts them.
Solo chats can also be shared with other people; do not describe every Solo
chat as visible only to its creator. In a Solo chat, including its first
message, **@** can name anyone in the community. A tagged agent of yours joins
Expand Down
14 changes: 8 additions & 6 deletions docs/solo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,14 +100,16 @@ behavior on the label, so a rename touches copy only.
label and any `members` it names. The caller is the creator, so an agent's
key makes a chat its human members see as shared, not their own. It sends no
message, so no agent turn starts. Only locally hosted agent runs may use
`solo_workspace_list` for their host-bound owner's personal workspace IDs and
pass an exact `workspace` to `channel_create` with `solo: true`. Include the
owner explicitly in `members`; filing never adds members, copies workspace
defaults or Canvas, or changes the creator.
`workspace_list` for their host-bound owner's workspace IDs and pass an exact
`workspace` to `channel_create`. With `solo: true`, include the owner
explicitly in `members`. The workspace's default agents join in the create
and its Canvas starts the chat, as in **New chat**; filing never changes the
creator. See [agents](../agents.md#filing-conversations-in-the-owners-workspaces)
for other types and `channel_move`.
Creation and filing are not atomic. A known refusal before assignment reports
the created ID and “created, not filed.” After assignment starts, failure reports
placement unconfirmed: it may already be durable or pending delivery. Inspect
or refresh that chat before **Move to**, never create another. Omitting
placement unconfirmed: it may already be durable or pending delivery. Check
the sidebar before `channel_move`, never create another. Omitting
`workspace` preserves creation without filing.
It cannot check NIP-CL support first, so on a relay that drops the
label it reports an ordinary private channel instead.
Expand Down
38 changes: 29 additions & 9 deletions src/buzz-mcp/app-client.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -568,13 +568,17 @@ it("offers the handle's settings, checking the turn before each call", () => {
expect(settings.get).not.toHaveBeenCalled();
});

it("forwards workspace discovery and one-use filing only while the app client is live", async () => {
it("forwards workspace discovery, defaults, filing and moves only while the app client is live", async () => {
let live = true;
const file = vi.fn(async () => {});
const list = vi.fn(async () => [{ id: "work", name: "Work" }]);
const prepare = vi.fn(async () => file);
const defaults = vi.fn(async () => ({ canvas: "# Rules", agents: [] }));
const move = vi.fn(async () => ({ status: "filed" as const }));
const client = appClient(
{ soloWorkspaces: { list, prepare } } as unknown as AgentHandle,
{
workspaces: { list, prepare, defaults, move },
} as unknown as AgentHandle,
{
read: async () => new Uint8Array(),
memories: async () => ({ entries: [], partial: false }),
Expand All @@ -583,20 +587,32 @@ it("forwards workspace discovery and one-use filing only while the app client is
},
},
);
expect(await client.soloWorkspaces?.list()).toEqual([
expect(await client.workspaces?.list()).toEqual([
{ id: "work", name: "Work" },
]);
const place = await client.soloWorkspaces?.prepare("work", ["owner"], "chat");
expect(await client.workspaces?.defaults("work", true)).toEqual({
canvas: "# Rules",
agents: [],
});
expect(defaults).toHaveBeenCalledExactlyOnceWith("work", true, undefined);
const audience = { members: ["owner"], open: false };
const place = await client.workspaces?.prepare("work", audience, "chat");
expect(prepare).toHaveBeenCalledExactlyOnceWith(
"work",
["owner"],
audience,
"chat",
undefined,
);
expect(await client.workspaces?.move("chat")).toEqual({ status: "filed" });
expect(move).toHaveBeenCalledExactlyOnceWith("chat", undefined, undefined);
live = false;
await expect(place?.("chat")).rejects.toThrow("retired");
expect(file).not.toHaveBeenCalled();
await expect(client.soloWorkspaces?.list()).rejects.toThrow("retired");
await expect(client.workspaces?.list()).rejects.toThrow("retired");
await expect(client.workspaces?.move("chat", "work")).rejects.toThrow(
"retired",
);
expect(move).toHaveBeenCalledOnce();
});

it("rejects app retirement after a completed placement without undoing it", async () => {
Expand All @@ -612,7 +628,7 @@ it("rejects app retirement after a completed placement without undoing it", asyn
});
const client = appClient(
{
soloWorkspaces: { list: async () => [], prepare: async () => file },
workspaces: { list: async () => [], prepare: async () => file },
} as unknown as AgentHandle,
{
read: async () => new Uint8Array(),
Expand All @@ -622,7 +638,11 @@ it("rejects app retirement after a completed placement without undoing it", asyn
},
},
);
const place = await client.soloWorkspaces?.prepare("work", ["owner"], "chat");
const place = await client.workspaces?.prepare(
"work",
{ members: ["owner"], open: false },
"chat",
);
const pending = place?.("chat");
const refused = expect(pending).rejects.toThrow("retired");
try {
Expand All @@ -642,7 +662,7 @@ it("does not expose workspace capability on unsupported handles", () => {
appClient({} as AgentHandle, {
read: async () => new Uint8Array(),
memories: async () => ({ entries: [], partial: false }),
}).soloWorkspaces,
}).workspaces,
).toBeUndefined();
});

Expand Down
36 changes: 28 additions & 8 deletions src/buzz-mcp/app-client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ import type { BuzzClient, Memories } from "./client";
import { nativeToolClient } from "../features/agents/tool-operation";
import { prepareAttachment } from "../features/messages/prepare-attachment";
import { imageType } from "../features/relay/attachment-limits";
import type { AgentHandle, AgentHandoff } from "../features/agents/service";
import type {
AgentHandle,
AgentHandoff,
WorkspaceAudience,
} from "../features/agents/service";
import type {
HostProcess,
HostProcessOptions,
Expand Down Expand Up @@ -78,7 +82,7 @@ export function appClient(
const threadsApart = agent.threadsApart;
const isTaskThread = agent.isTaskThread;
const plugins = agent.plugins;
const { settings, soloWorkspaces } = agent;
const { settings, workspaces } = agent;
const signal = options.callSignal ?? options.signal;
const client: BuzzClient = {
...(signal ? { signal } : {}),
Expand Down Expand Up @@ -135,23 +139,33 @@ export function appClient(
...(options.nativeToolGate ? { nativeToolGate: true as const } : {}),
}
: {}),
...(soloWorkspaces && {
soloWorkspaces: {
...(workspaces && {
workspaces: {
list: async () => {
check();
const result = await soloWorkspaces.list(options.signal);
const result = await workspaces.list(options.signal);
check();
return result;
},
defaults: async (workspace: string, shared: boolean) => {
check();
const result = await workspaces.defaults(
workspace,
shared,
options.signal,
);
check();
return result;
},
prepare: async (
workspace: string,
members: readonly string[],
audience: WorkspaceAudience,
channelId: string,
) => {
check();
const file = await soloWorkspaces.prepare(
const file = await workspaces.prepare(
workspace,
members,
audience,
channelId,
options.signal,
);
Expand All @@ -163,6 +177,12 @@ export function appClient(
return result;
};
},
move: async (id: string, workspace?: string) => {
check();
const result = await workspaces.move(id, workspace, options.signal);
check();
return result;
},
},
}),
pubkey: agent.pubkey,
Expand Down
16 changes: 11 additions & 5 deletions src/buzz-mcp/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ import type { ProtectionAction } from "../features/agent-protection/service";
import type { GitAuth } from "../features/agents/native";
import type {
AgentAttention,
SoloPlacement,
WorkspaceAudience,
WorkspaceDefaults,
WorkspacePlacement,
AgentReadout,
AgentUpdateInput,
TeamReadout,
Expand Down Expand Up @@ -193,14 +195,18 @@ export interface BuzzClient {
/** Writes entry `slug`, newer than the one it replaces (`after`, or 0);
* a `null` body deletes it. */
remember(slug: string, body: string | null, after: number): Promise<void>;
/** Local run-only discovery and one-use placement of a newly published Solo. */
soloWorkspaces?: Readonly<{
/** The owner's sidebar workspaces, in a local run: their list, defaults,
* one-use placement of a newly published conversation, and moves. */
workspaces?: Readonly<{
list(): Promise<readonly Readonly<{ id: string; name: string }>[]>;
defaults(workspace: string, shared: boolean): Promise<WorkspaceDefaults>;
prepare(
workspace: string,
members: readonly string[],
audience: WorkspaceAudience,
channelId: string,
): Promise<(id: string) => Promise<SoloPlacement>>;
): Promise<(id: string) => Promise<WorkspacePlacement>>;
/** Files conversation `id` in `workspace`, or unfiles it without one. */
move(id: string, workspace?: string): Promise<WorkspacePlacement>;
}>;
/** The owner's channel templates, where the host has them. */
templates?(): Promise<readonly ChannelTemplate[]>;
Expand Down
Loading
Loading