You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 848924d
Browse filesBrowse the repository at this point in the historyBrowse files
feat(plugins): let a plugin wake an agent at a channel's top level (#3299)
## Why
A plugin can only wake an agent inside an existing thread or a Solo
chat, so it cannot have an agent start a new thread in a channel.
## What
- Add optional `topLevel: true` to `ctx.agents.wake`. The wake lands at
the channel's top level, the same conversation a whole-channel watch
already uses.
- Reject a wake that sets both `topLevel` and `root`.
- Document the option in the plugin contract, the authoring guide and
the agents guide.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <[email protected]>
Copy file name to clipboardExpand all lines: docs/plugin-architecture.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1046,10 +1046,11 @@ plugin's folder can replace that plugin's code, though not its host access,
1046
1046
without a new review. Plugin code is trusted and unsandboxed, so only load folders
1047
1047
that the agents you run may change.
1048
1048
1049
-
`ctx.agents.wake(pubkey, { channel, root?, text })` wakes an agent this copy of
1049
+
`ctx.agents.wake(pubkey, { channel, root?, topLevel?, text })` wakes an agent this copy of
1050
1050
the app runs in one of its conversations, as a mention there would, with no
1051
1051
message. `root` is the thread's root event id (64 hex); leave it out for a Solo
1052
-
chat. The agent is told
1052
+
chat. `topLevel: true`, without `root`, wakes it at the top level of a channel
1053
+
that is not a Solo chat, for example to start a new thread there. The agent is told
1053
1054
the text comes from the plugin, not its owner, and is data, so quote what others
1054
1055
wrote (comments, check output) rather than phrasing it as instructions. It
1055
1056
throws when this copy does not run the agent or its queue is full. Claude, Codex and Goose accept plugin wakes; Pi ignores them. Attention delivery uses a separate internal `attention` trigger in the Interest lane, accepted by all four harnesses. Its Interest instructions retain their instruction framing, while observed messages remain data. A channel-only Attention address supplies a default posting destination and allows explicit thread replies outside Solo chats.
Copy file name to clipboardExpand all lines: docs/plugin-authoring-guide.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,7 +62,7 @@ export function apply(ctx) {
62
62
|`settingsCards`| A Settings destination |`ctx.settingsCards.register({ id, title, component, group?, personal?, identityRow? })`. `component` receives `{ active(), community?, navigation? }`; `navigation.target.route` can carry bounded, versioned presentation data for the card. Opening a route must never submit an operation. Optional `identityRow` receives `{ active() }` and contributes a compact account-status link inside Identity. Reuse the plugin’s existing session; check `active()` before navigation or an action. The row retires with its owning registration. Omit `icon` (it is a host icon component). The host supplies navigation and the content column, not a heading. |
63
63
|`sidebarSections` (optional) | A section in the Team sidebar |`ctx.reflect.get("sidebarSections")?.register({ version: 1, id, title, icon, rows: { snapshot, subscribe }, select, actions? })`. `snapshot()` returns a stable array of `{ id, label, icon?, badge?, count?, status? }` until data changes, then notify subscribers. `select(row)` returns an open target such as `{ version: 1, kind: "home" }`. Actions: `{ id, label, icon: ReactElement, onSelect }`. |
64
64
|`conversation`| Composer/message UI |`registerAccessory({ id, title, component, order?, placement? })` (read-only UI above the composer; props `{ session, scope, channelId, threadRootId?, canOpen, open }`; `placement`: `"composer"`, `"message"`, `"response"`). `registerMessage({ id, title, matches(message), component })`, `registerMessageAction({ id, title, matches(message, session), component })`, `registerIdentityMark({ id, title, component })` (presentation after a person's name in @mention suggestions; props `{ pubkey, profiles }`, where `profiles.snapshot().get(pubkey)?.verified` carries community verification), `registerLink({ id, title, matches(url), component })`, `registerLinkPreview({ id, title, matches(url), order?, component })` (a card below the message for one of its HTTPS links; props `{ url, messageId, open }`; lowest `order` wins, so claim your URLs below the default web card's `100`), `registerTool({ id, title, component })`. |
65
-
| `agents` | Tools and hooks for agents | `ctx.agents.addTool({ name, description, inputSchema, call })`. `name` matches `/^[a-z][a-z0-9_]{0,63}$/`, is unique across plugins and not a Buzz tool name (prefix it with your plugin: `notes_get`). `inputSchema` is a JSON-serializable object with `type: "object"`. `async call(client, context, args)` resolves to a string (or `{ data, type, text? }`) and runs as the agent; a throw is shown to the agent as a tool error. Changing a tool's name, description or schema restarts some agent sessions, so edit deliberately. `ctx.agents.addInstructions({ id, text, when? })` gives every turn of the agents this copy runs, or those `when(agent)` accepts, a `<plugin-instructions>` section with `text` (at most 4096 UTF-8 bytes after trimming); it is sent with every turn, so keep it short. `ctx.agents.registerHook({ id, harness, event, run })` needs `host.agentHooks`. `ctx.agents.wake(agentKey, { channel, root?, text })` wakes a local agent (`root` is a 64-hex event id). With `host.files`, `ctx.agents.assignConversationFolder(agentKey, { channelId, root? }, path)` gives one conversation of a local Claude or Codex agent its own working folder before its first turn; see [Agents](agents.md). |
65
+
| `agents` | Tools and hooks for agents | `ctx.agents.addTool({ name, description, inputSchema, call })`. `name` matches `/^[a-z][a-z0-9_]{0,63}$/`, is unique across plugins and not a Buzz tool name (prefix it with your plugin: `notes_get`). `inputSchema` is a JSON-serializable object with `type: "object"`. `async call(client, context, args)` resolves to a string (or `{ data, type, text? }`) and runs as the agent; a throw is shown to the agent as a tool error. Changing a tool's name, description or schema restarts some agent sessions, so edit deliberately. `ctx.agents.addInstructions({ id, text, when? })` gives every turn of the agents this copy runs, or those `when(agent)` accepts, a `<plugin-instructions>` section with `text` (at most 4096 UTF-8 bytes after trimming); it is sent with every turn, so keep it short. `ctx.agents.registerHook({ id, harness, event, run })` needs `host.agentHooks`. `ctx.agents.wake(agentKey, { channel, root?, topLevel?, text })` wakes a local agent (`root` is a 64-hex event id; `topLevel: true` instead wakes it at a channel's top level). With `host.files`, `ctx.agents.assignConversationFolder(agentKey, { channelId, root? }, path)` gives one conversation of a local Claude or Codex agent its own working folder before its first turn; see [Agents](agents.md). |
66
66
|`shortcuts`| In-app key bindings |`ctx.shortcuts.register({ id, title, binding, run, when?, order?, allowInEditable?, allowInModal?, repeat? })`. `binding` is `{ key, mod?, shift?, alt?, ctrl? }` or an array; `mod` is Command on macOS, Control elsewhere. `key` is the logical key, case-insensitive (Space is `" "`). Skipped in text fields and modals unless opted in. |
|`communityJoin` (optional) | Join a community the person chose in your UI |`ctx.reflect.get("communityJoin")?.open(address)` with a `wss://` or `https://` community address, for example one your plugin just created. It opens the app's join dialog, which connects at once; the person still completes admission and the profile step there, and nothing is saved before they do. An address already saved just selects that community. It returns `false` when the address is not a community origin (for example it has a path or credentials) or no identity is ready to join with (hand the address off another way), otherwise `true`; it reports no completion. Call it only from a live, user-initiated action. |
0 commit comments