Skip to content

Commit 674c173

Browse files
salman1993Leo
andauthored
feat(buzz-acp): give each channel thread its own agent session (#6732)
## What this does In a channel, people often run several unrelated conversations at once (separate threads). Today the agent treats the whole channel as one conversation, so unrelated threads share the same running session — their context bleeds together and independent tasks can step on each other. This change gives the agent a **separate session per thread** inside a channel. Direct messages stay as one conversation (unchanged). The channel is still the boundary for who is allowed in and what is visible — only the agent's working context is now split by thread. ## How it is turned on Off by default. Operators opt in with one setting: - `BUZZ_ACP_SESSION_POLICY=channel` — default, current behavior - `BUZZ_ACP_SESSION_POLICY=thread` — new per-thread behavior Being behind a flag means we can enable it for a few agents, watch how it behaves, and roll back instantly without a code change. ## Key design decisions - **Decide the thread once, up front.** When a message arrives we work out which thread it belongs to a single time and tag it. Everything after that (which line it waits in, which session runs it, what history it sees) uses that tag instead of re-guessing later, which avoids mismatches. - **Default stays identical to today.** Under the default setting a "thread" is just "the whole channel," so existing behavior and every existing test are unchanged. The new, riskier behavior is strictly opt-in. - **Give the agent only its thread's history.** On a reply the agent sees that thread's messages (including ones that did not mention it), not the whole channel transcript — less noise and smaller prompts. - **Don't let one channel use more memory than before.** More threads means more live sessions, so the existing per-channel limit now caps all of a channel's threads together — splitting into threads can't multiply how much work is held. ## Bugs found and fixed while iterating (from review) - **Same thread, two sessions.** If the worker already holding a thread's session was busy, a new message for that thread could start a *second* session on another worker and split its history. Now it waits for the right worker instead of forking. - **Interrupting the wrong thread.** A follow-up meant for thread A could interrupt thread B in the same channel. Interrupts now target the exact thread. - **Stuck thread after a crash.** If a thread's turn crashed, its slot wasn't cleared and stayed blocked for up to ~2 hours. It now clears right away and retries. - **Lost the original request.** When a thread was interrupted and then had to wait for a busy worker, only the follow-up was kept and the original request was dropped. The full request is now preserved on retry. - **Same thread seen as two.** Two spellings of the same thread id (upper/lower case) could be treated as different threads. Normalized so they count as one. ## Not in this PR - The desktop Settings toggle and rollout wiring for managed agents — #6909 - One pre-existing retry edge case (present today without this flag, unrelated to this change) — tracked separately so this PR stays focused. ## Testing The full `buzz-acp` test suite passes (830+ unit and integration tests), plus new focused tests for thread routing, session reuse, interrupt targeting, crash recovery, and request preservation. Behavior with the flag off is unchanged. --------- Signed-off-by: Salman Mohammed <[email protected]> Signed-off-by: Leo <5faf251baee50ee6bcde338aef6acdd70bb3e60115664c2cd490d94a55dfc488@buzz.block.builderlab.xyz> Co-authored-by: Leo <5faf251baee50ee6bcde338aef6acdd70bb3e60115664c2cd490d94a55dfc488@buzz.block.builderlab.xyz>
1 parent 4952f58 commit 674c173

10 files changed

Lines changed: 2855 additions & 685 deletions

File tree

‎.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,14 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
301301
# Set to true to process the agent's own messages (default: ignore self).
302302
# BUZZ_ACP_NO_IGNORE_SELF=false
303303

304+
# ── Session scoping ──────────────────────────────────────────────────────────
305+
# How ACP provider sessions are scoped in channels: "channel" (default) or
306+
# "thread". "channel" keeps one provider session per channel (legacy). "thread"
307+
# gives each canonical channel thread its own isolated provider session; direct
308+
# messages stay conversation-scoped either way. Ships as "channel" so thread
309+
# scoping can be canaried and rolled back without code changes.
310+
# BUZZ_ACP_SESSION_POLICY=channel
311+
304312
# ── Context ──────────────────────────────────────────────────────────────────
305313
# Max context messages fetched for thread replies and DMs (0–100). 0 = disabled.
306314
# BUZZ_ACP_CONTEXT_MESSAGE_LIMIT=12

‎crates/buzz-acp/README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -161,12 +161,17 @@ The gate applies to **all** inbound events — @mentions, DMs, thread replies, a
161161
| Command | Effect |
162162
|---------|--------|
163163
| `!shutdown` | Gracefully exits the harness. |
164-
| `!cancel` | Cancels the current in-flight turn for that channel, if any. |
165-
| `!rotate` | Rotates the ACP session for that channel. If a turn is in-flight, it is cancelled and the channel session is invalidated when the task returns; otherwise the cached idle session is invalidated immediately. The next queued/received event starts a fresh session. |
164+
| `!cancel` | Cancels the current in-flight turn for the command's resolved session scope, if any. |
165+
| `!rotate` | Rotates the ACP session for the command's resolved session scope. If a turn is in flight, it is cancelled and that scoped session is invalidated when the task returns; otherwise the cached scoped session is invalidated immediately. The next queued/received event in that scope starts a fresh session. |
166166

167-
Use `!cancel` to stop only the current turn; it is a no-op when the channel is idle. Use `!rotate` when you want the next turn in the channel to start from a fresh ACP session, even if the channel is currently idle.
167+
Under the default `channel` policy, a session scope is the whole channel, so these commands retain their channel-wide behavior. Under the `thread` policy, post the command as a reply in the target thread so `!cancel` or `!rotate` affects only that thread. DMs remain one conversation scope. `!cancel` is a no-op when its scope is idle.
168168

169-
Owner control commands must be kind:9 stream messages from the owner, must mention this agent with a `p` tag, and are consumed by the harness instead of being forwarded to the agent.
169+
Owner control commands must be kind:9 stream messages from the owner, must have body exactly `!cancel`, `!rotate`, or `!shutdown` after trimming, and must mention this agent with a separate `p` tag. They are consumed by the harness instead of being forwarded to the agent. An inline `@Name` changes the body and does not match. With the Buzz CLI, target a thread while preserving the exact command body by passing the mention separately:
170+
171+
```bash
172+
buzz messages send --channel <channel-id> --reply-to <thread-root-id> \
173+
--mention <agent-pubkey> --content '!cancel'
174+
```
170175

171176
> **Note:** The default mode is `owner-only`. Agents without a registered `agent_owner_pubkey` will not respond to any events until the owner is resolved. Set `--respond-to anyone` to disable the gate entirely.
172177

‎crates/buzz-acp/src/base_prompt.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,5 @@
11
You are operating inside the Buzz platform — a Nostr-based messaging platform for human-agent collaboration. The buzz-acp harness routes channel events to your session.
22

3-
## Session Model
4-
5-
You are one per-channel session of your agent identity — not the only copy. Each channel gets its own independent conversation context, and multiple sessions of the same agent may be active in different channels at the same time. Sessions share your core memory, your workspace on disk, and the relay. They do NOT share conversation context, in-progress reasoning, or in-context task state.
6-
7-
When a human references work "you" are doing in another channel, that work belongs to a different session of you. Unless the human asks you to take it over or coordinate it from this channel, leave execution with the owning session — answer from what you can verify (core memory, workspace files, relay messages) and assume the owning session has it handled.
8-
93
## Buzz CLI
104

115
The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ_PRIVATE_KEY`, `BUZZ_AUTH_TAG`. Exit codes: 0 ok, 1 user error, 2 network, 3 auth, 4 other. Output is structured JSON.

‎crates/buzz-acp/src/config.rs‎

Lines changed: 115 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,19 @@ pub struct CliArgs {
350350
#[arg(long, env = "BUZZ_ACP_DEDUP", default_value = "queue", value_enum)]
351351
pub dedup: DedupMode,
352352

353+
/// How ACP provider sessions are scoped in channels.
354+
/// channel (default): one provider session per channel (legacy behavior).
355+
/// thread: each canonical channel thread gets an isolated provider session;
356+
/// direct messages stay conversation-scoped either way. Ships as `channel`
357+
/// so thread scoping can be canaried and rolled back without code changes.
358+
#[arg(
359+
long,
360+
env = "BUZZ_ACP_SESSION_POLICY",
361+
default_value = "channel",
362+
value_enum
363+
)]
364+
pub session_policy: crate::scope::SessionPolicy,
365+
353366
/// How to handle new @mentions while a turn is already in-flight.
354367
/// steer (default): cancel+re-prompt, framing the new mention as a message
355368
/// that arrived mid-task — the agent keeps working and weaves it in.
@@ -536,6 +549,8 @@ pub struct Config {
536549
pub initial_message: Option<String>,
537550
pub subscribe_mode: SubscribeMode,
538551
pub dedup_mode: DedupMode,
552+
/// How ACP provider sessions are scoped in channels (channel vs thread).
553+
pub session_policy: crate::scope::SessionPolicy,
539554
pub multiple_event_handling: MultipleEventHandling,
540555
pub ignore_self: bool,
541556
pub kinds_override: Option<Vec<u32>>,
@@ -646,14 +661,43 @@ const SESSION_TITLE_SEPARATOR: &str = " · ";
646661
/// survives. Returns the bare agent name when there is no channel, the channel
647662
/// name is blank, or no room is left for it.
648663
pub(crate) fn compose_session_title(agent: &str, channel_name: Option<&str>) -> String {
664+
compose_session_title_with_limit(agent, channel_name, SESSION_TITLE_MAX_CHARS)
665+
}
666+
667+
/// Append the canonical thread root's first eight characters to a session title.
668+
/// Reserve suffix space before truncating names so thread identity always survives.
669+
/// Conversation and heartbeat sessions preserve their existing title behavior.
670+
pub(crate) fn compose_scoped_session_title(
671+
agent: &str,
672+
channel_name: Option<&str>,
673+
thread_root: Option<&str>,
674+
) -> String {
675+
let Some(root) = thread_root.filter(|root| !root.is_empty()) else {
676+
return compose_session_title(agent, channel_name);
677+
};
678+
let short_root: String = root.chars().take(8).collect();
679+
let suffix = format!("{SESSION_TITLE_SEPARATOR}{short_root}");
680+
let budget = SESSION_TITLE_MAX_CHARS.saturating_sub(suffix.chars().count());
681+
let agent: String = agent.chars().take(budget).collect();
682+
format!(
683+
"{}{suffix}",
684+
compose_session_title_with_limit(agent.trim_end(), channel_name, budget)
685+
)
686+
}
687+
688+
fn compose_session_title_with_limit(
689+
agent: &str,
690+
channel_name: Option<&str>,
691+
max_chars: usize,
692+
) -> String {
649693
let Some(channel) = channel_name.and_then(sanitize_session_title) else {
650694
return agent.to_string();
651695
};
652696
// Reserve the separator and the `#` sigil alongside the agent name.
653697
let reserved = agent.chars().count() + SESSION_TITLE_SEPARATOR.chars().count() + 1;
654698
let channel: String = channel
655699
.chars()
656-
.take(SESSION_TITLE_MAX_CHARS.saturating_sub(reserved))
700+
.take(max_chars.saturating_sub(reserved))
657701
.collect::<String>()
658702
.trim_end()
659703
.to_string();
@@ -1113,6 +1157,7 @@ impl Config {
11131157
initial_message: args.initial_message,
11141158
subscribe_mode: args.subscribe,
11151159
dedup_mode: args.dedup,
1160+
session_policy: args.session_policy,
11161161
multiple_event_handling: args.multiple_event_handling,
11171162
ignore_self: !args.no_ignore_self,
11181163
kinds_override: args.kinds,
@@ -1164,7 +1209,7 @@ impl Config {
11641209
format!(" allowed_respond_to=[{}]", modes.join(","))
11651210
};
11661211
format!(
1167-
"relay={} pubkey={} agent_cmd={} {} mcp_cmd={} idle_timeout={}s max_turn={}s agents={} heartbeat={}s subscribe={:?} dedup={:?} meh={:?} ignore_self={} context_limit={} max_turns_per_session={} presence={} typing={} memory={} model={} permission_mode={} {}{}",
1212+
"relay={} pubkey={} agent_cmd={} {} mcp_cmd={} idle_timeout={}s max_turn={}s agents={} heartbeat={}s subscribe={:?} dedup={:?} session_policy={} meh={:?} ignore_self={} context_limit={} max_turns_per_session={} presence={} typing={} memory={} model={} permission_mode={} {}{}",
11681213
self.relay_url,
11691214
self.keys.public_key().to_hex(),
11701215
self.agent_command,
@@ -1176,6 +1221,7 @@ impl Config {
11761221
self.heartbeat_interval_secs,
11771222
self.subscribe_mode,
11781223
self.dedup_mode,
1224+
self.session_policy,
11791225
self.multiple_event_handling,
11801226
self.ignore_self,
11811227
self.context_message_limit,
@@ -1489,6 +1535,7 @@ mod tests {
14891535
initial_message: None,
14901536
subscribe_mode: mode,
14911537
dedup_mode: DedupMode::Queue,
1538+
session_policy: crate::scope::SessionPolicy::Channel,
14921539
multiple_event_handling: MultipleEventHandling::Queue,
14931540
ignore_self: true,
14941541
kinds_override: None,
@@ -2618,6 +2665,42 @@ channels = "ALL"
26182665
assert!(result.is_empty());
26192666
}
26202667

2668+
// ── Session policy parsing + default ──────────────────────────────────────
2669+
2670+
#[test]
2671+
fn test_session_policy_default_is_channel() {
2672+
// Ships dark: the default must be `channel` so thread scoping is opt-in
2673+
// and can be rolled back without code changes.
2674+
let args = CliArgs::parse_from(["buzz-acp", "--private-key", &"0".repeat(64)]);
2675+
assert_eq!(args.session_policy, crate::scope::SessionPolicy::Channel);
2676+
}
2677+
2678+
#[test]
2679+
fn test_session_policy_thread_flag_parses() {
2680+
let args = CliArgs::parse_from([
2681+
"buzz-acp",
2682+
"--private-key",
2683+
&"0".repeat(64),
2684+
"--session-policy",
2685+
"thread",
2686+
]);
2687+
assert_eq!(args.session_policy, crate::scope::SessionPolicy::Thread);
2688+
}
2689+
2690+
#[test]
2691+
fn test_session_policy_env_var_parses() {
2692+
// The env fallback (`BUZZ_ACP_SESSION_POLICY`) must resolve to the same
2693+
// value as the flag; this is what the managed-agent runtime sets.
2694+
let args = CliArgs::parse_from([
2695+
"buzz-acp",
2696+
"--private-key",
2697+
&"0".repeat(64),
2698+
"--session-policy=thread",
2699+
]);
2700+
assert_eq!(args.session_policy, crate::scope::SessionPolicy::Thread);
2701+
assert_eq!(args.session_policy.to_string(), "thread");
2702+
}
2703+
26212704
// ── Multiple-event-handling validation + default ──────────────────────────
26222705

26232706
#[test]
@@ -2991,6 +3074,36 @@ channels = "ALL"
29913074
assert_eq!(compose_session_title(&agent, Some("buzz-dev")), agent);
29923075
}
29933076

3077+
#[test]
3078+
fn scoped_session_title_keeps_short_root_even_when_names_fill_the_cap() {
3079+
let root = "abcdef01".repeat(8);
3080+
assert_eq!(
3081+
compose_scoped_session_title("Fizz", Some("buzz-dev"), Some(&root)),
3082+
"Fizz · #buzz-dev · abcdef01"
3083+
);
3084+
assert_eq!(
3085+
compose_scoped_session_title("Fizz", None, Some(&root)),
3086+
"Fizz · abcdef01"
3087+
);
3088+
assert_eq!(
3089+
compose_scoped_session_title("Fizz", Some("buzz-dev"), Some("abc")),
3090+
"Fizz · #buzz-dev · abc"
3091+
);
3092+
for (agent, channel) in [
3093+
("🐝".repeat(80), "work".into()),
3094+
("Fizz".into(), "🐝".repeat(100)),
3095+
] {
3096+
let title = compose_scoped_session_title(&agent, Some(&channel), Some(&root));
3097+
assert_eq!(title.chars().count(), SESSION_TITLE_MAX_CHARS);
3098+
assert!(title.ends_with(" · abcdef01"));
3099+
}
3100+
assert_eq!(
3101+
compose_scoped_session_title("Fizz", Some("buzz-dev"), None),
3102+
"Fizz · #buzz-dev"
3103+
);
3104+
assert_eq!(compose_scoped_session_title("Fizz", None, None), "Fizz");
3105+
}
3106+
29943107
/// Every arg whose env var name contains KEY/SECRET/TOKEN/PASSWORD/CRED/AUTH
29953108
/// must set `hide_env_values = true` to prevent credential leakage in --help.
29963109
#[test]

0 commit comments

Comments
 (0)