Skip to content

Commit f177f49

Browse files
authored
Use paired tags for standing & per-turn context (#6701)
## Why PR #6503 bundled a broader context compiler with several prompt-shape and telemetry changes, making it difficult to isolate whether paired XML-like top-level boundaries improve agent behavior. This keeps the follow-up experiment focused on framing only. ## What - Replace top-level standing and per-turn bracket headers with paired tags while preserving inner section content and event/message framing - Carry only metadata already present in dynamic headers as attributes, such as thread counts, truncation, event type, and batch count - Preserve every section body verbatim so the model executes the exact bytes reviewed in Desktop - Keep routing metadata, event content, batching, and delivery behavior unchanged - Teach Desktop diagnostics to parse the new framing while retaining compatibility with archived bracket-framed sessions; ambiguous paired boundaries render as the complete captured prompt ## Risk Assessment Medium — the change is limited to agent prompt framing and diagnostic parsing, but it affects both standing context and every dynamic agent turn. Bodies and delivery behavior remain unchanged, and compatibility parsing remains for prior sessions. ## References - Follow-up to #6503, scoped only to the paired-tag framing hypothesis ## Update — 2026-08-24 - Addressed review feedback by removing entity encoding/decoding from the execution and diagnostic paths. - Added regressions for literal closing tags, placeholders, entity-looking text, ampersands, and authored boundary whitespace. - Verified `cargo test -p buzz-acp` (805 unit + 9 integration), Desktop tests (5,412 before the main sync; 5,439 in the pre-push gate), Desktop typechecking, and Tauri clippy/tests. - Live local relay startup and message ingestion passed. The live ACP reply step is blocked locally because installed Goose 1.0.23 no longer provides the documented `goose acp` command and no alternate ACP adapter is installed. --- **Update Aug 25, 12:13 EDT:** Extended paired tags to per-turn top-level sections. - Converted context, conversation/thread context, event batches, and steer/interrupt boundaries without changing their inner bodies. - Preserved existing header metadata as attributes only; added no new prompt metadata. - Verified 806 Buzz ACP unit tests plus 9 integration tests, 5,441 Desktop tests, Desktop typechecking and formatting, and all differential pre-push lanes. --- **Update Aug 25, 13:58 EDT:** Addressed framing review feedback. - Updated operational base instructions to reference the emitted `<context>` section and added a regression guard against stale `[Context]` instructions. - Restored batched steer/interrupt cardinality in Desktop diagnostic titles with focused coverage for both paths. - Verified 807 Buzz ACP unit tests plus 9 integration tests, 5,442 Desktop tests, Desktop typechecking and formatting, and every differential pre-push lane including Tauri clippy/tests. --- **Update Aug 25, 15:37 EDT:** Hardened legacy transcript compatibility. - Semantic standing-context parsing now requires paired framing at the start and complete input consumption. - Historical bracket-framed personas keep literal balanced tag examples in their original section; malformed or mixed current framing displays as the complete captured prompt. - Added regressions for the reported legacy persona case and trailing unframed text; verified 60 focused parser tests, 5,444 full Desktop tests, formatting, and typechecking. --- **Update Aug 25, 16:31 EDT:** Preserved slash-command prompt block boundaries. - Desktop now sets aside a valid connector-facing slash-command block only when the following block begins recognized paired framing, parses the semantic blocks normally, and retains the command as visible Prompt metadata. - Added an end-to-end transcript regression using the production three-block ACP shape, including the user bubble, author pubkey, event ID, and grouped prompt context. - Verified 113 combined transcript tests, 5,445 full Desktop tests, formatting, typechecking, and all applicable pre-push lanes. Generated with Codex --------- Signed-off-by: Salman Mohammed <[email protected]>
1 parent 583af02 commit f177f49

11 files changed

Lines changed: 931 additions & 258 deletions

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ The `buzz` CLI is your primary interface. Auth env vars: `BUZZ_RELAY_URL`, `BUZZ
2929

3030
Run `buzz --help` or `buzz <group> --help` for full usage. For multiline message content, pass real newline bytes through stdin: `printf 'first\n\nsecond\n' | buzz messages send ... --content -`. Do not write `--content 'first\n\nsecond'`: single-quoted shell strings preserve `\n` literally, so recipients will see the backslash characters. `buzz agents draft-create` and `buzz agents draft-update` require `BUZZ_AUTH_TAG`; if it is missing, explain that this managed agent cannot open owner-reviewed agent drafts from chat.
3131

32-
When opening a pull request in response to channel work, always pass `--channel <current-channel-uuid>` using the UUID from `[Context]`. This preserves a link from the pull request back to its originating conversation.
32+
When opening a pull request in response to channel work, always pass `--channel <current-channel-uuid>` using the UUID from `<context>`. This preserves a link from the pull request back to its originating conversation.
3333

3434
`buzz pr open`, `buzz issues create`, `buzz repos create`, and `buzz projects create` return a `link` field (a `buzz://` deep link). When you announce that work in a channel message, include the `link` value verbatim — Buzz Desktop renders it as a rich preview card that opens the PR, issue, repo, or project in-app, the same way GitHub links render. Do not invent HTTPS web URLs for Buzz-hosted repos; the `link` field and the `clone` URL are the only shareable references.
3535

@@ -39,7 +39,7 @@ To assign an issue to someone, run `buzz issues assign --issue <event-id> --repo
3939

4040
When someone asks to create an agent, ask for at most two things: its name and what it should do day-to-day. Write the `--system-prompt` yourself. Do not ask about runtime, provider, model, credentials, environment variables, or access unless the request is genuinely ambiguous.
4141

42-
Open an owner-reviewed draft with `buzz agents draft-create --channel <current-channel-uuid> --display-name <name> --system-prompt <instructions>`, using the UUID from `[Context]`. Never claim the agent exists until the owner saves it. For explicit changes to an existing personal agent, use `buzz agents draft-update --help`.
42+
Open an owner-reviewed draft with `buzz agents draft-create --channel <current-channel-uuid> --display-name <name> --system-prompt <instructions>`, using the UUID from `<context>`. Never claim the agent exists until the owner saves it. For explicit changes to an existing personal agent, use `buzz agents draft-update --help`.
4343

4444
## Communication Patterns
4545

@@ -58,15 +58,15 @@ Open an owner-reviewed draft with `buzz agents draft-create --channel <current-c
5858

5959
### Threading
6060

61-
Use the reply destination supplied in the `[Context]` block for ordinary replies in this turn. Do not reuse a remembered thread id, an older event id from prior work, or a stale conversation root.
61+
Use the reply destination supplied in the `<context>` block for ordinary replies in this turn. Do not reuse a remembered thread id, an older event id from prior work, or a stale conversation root.
6262

6363
For human-facing work, keep the conversation flat and easy to read. The app/harness will choose the correct reply destination: the root of the triggering thread when the turn is already threaded, or the triggering top-level event when the human started a new thread.
6464

6565
For agent-to-agent coordination with no human in the loop, deeper nesting is allowed when it helps preserve task structure. Do not flatten agent-only subthreads just because they are inside a thread.
6666

67-
When in doubt, prefer the reply destination explicitly supplied in `[Context]`. If you intentionally choose a different destination, explain why briefly in the message.
67+
When in doubt, prefer the reply destination explicitly supplied in `<context>`. If you intentionally choose a different destination, explain why briefly in the message.
6868

69-
All replies and delegations — including task assignments to other agents — go to the **same channel where you were tagged** (use the channel UUID from `[Context]`). Never post responses or assignments to a different channel unless the user explicitly requests it.
69+
All replies and delegations — including task assignments to other agents — go to the **same channel where you were tagged** (use the channel UUID from `<context>`). Never post responses or assignments to a different channel unless the user explicitly requests it.
7070

7171
### General
7272

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -391,7 +391,7 @@ pub struct CliArgs {
391391
///
392392
/// Memory injection is on by default. When enabled, the harness
393393
/// fetches the agent's per-session core engram and renders it as an
394-
/// `[Agent Memory — core]` prompt section (or renders the onboarding nudge
394+
/// `<core-memory>` prompt section (or renders the onboarding nudge
395395
/// when the relay confirms no core engram exists). The `buzz mem` CLI
396396
/// and the relay's acceptance of kind:30174 engrams are unaffected — this
397397
/// flag controls prompt-time injection in the ACP harness only.
@@ -410,8 +410,8 @@ pub struct CliArgs {
410410
#[arg(long, env = "BUZZ_ACP_NO_MEMORY", conflicts_with = "memory")]
411411
pub no_memory: bool,
412412

413-
/// Disable the [Base] platform-context section prepended to every prompt.
414-
/// When set, agents receive only the persona `[Agent Instructions]` prompt with no Buzz orientation.
413+
/// Disable the `<base>` platform-context section prepended to every prompt.
414+
/// When set, agents receive only the persona `<system>` prompt with no Buzz orientation.
415415
#[arg(long, env = "BUZZ_ACP_NO_BASE_PROMPT")]
416416
pub no_base_prompt: bool,
417417

@@ -480,7 +480,7 @@ pub struct CliArgs {
480480
#[arg(long, env = "BUZZ_ACP_ALLOWED_RESPOND_TO", value_delimiter = ',')]
481481
pub allowed_respond_to: Option<Vec<String>>,
482482

483-
/// Team-owned instructions layered after `[Agent Instructions]` and before agent memory.
483+
/// Team-owned instructions layered after `<system>` and before agent memory.
484484
#[arg(long, env = "BUZZ_ACP_TEAM_INSTRUCTIONS")]
485485
pub team_instructions: Option<String>,
486486

@@ -549,7 +549,7 @@ pub struct Config {
549549
pub typing_enabled: bool,
550550
/// Whether NIP-AE agent core memory injection is enabled. When false,
551551
/// the harness skips the per-session core engram fetch and renders no
552-
/// `[Agent Memory — core]` section. On by default; disabled via the
552+
/// `<core-memory>` section. On by default; disabled via the
553553
/// `--no-memory` / `BUZZ_ACP_NO_MEMORY` opt-out.
554554
pub memory_enabled: bool,
555555
/// Desired LLM model ID. Applied after every `session_new_full()`.
@@ -593,7 +593,7 @@ pub struct Config {
593593
/// Agent owner pubkey (hex). Used for `--respond-to=owner-only` gate.
594594
/// Replaces the old REST-based owner lookup.
595595
pub agent_owner: Option<String>,
596-
/// Disable the [Base] platform-context section prepended to every prompt.
596+
/// Disable the `<base>` platform-context section prepended to every prompt.
597597
pub no_base_prompt: bool,
598598
/// Resolved content from `--base-prompt-file`, read and validated in
599599
/// `from_cli()`. `None` when using the compiled-in default or when

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

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
//!
44
//! Scope per Tyler's spec:
55
//! - Fire one synchronous query for the core head when a *new* session is born.
6-
//! - If a body is found, emit `[Agent Memory — core]\n<profile>`.
6+
//! - If a body is found, emit `<core-memory>…</core-memory>`.
77
//! - If no body is found, emit an onboarding nudge so the agent learns how
88
//! to set its own core.
99
//! - On any *error* (transport, parse), log and emit nothing. We must not
@@ -17,9 +17,6 @@ use nostr::{Event, Keys, PublicKey};
1717

1818
use crate::relay::RestClient;
1919

20-
/// Section header rendered into the prompt.
21-
const SECTION_LABEL: &str = "Agent Memory — core";
22-
2320
/// Onboarding nudge for new agents with no core yet.
2421
///
2522
/// Wording is from Tyler's brief: "No core memory found. Use `buzz mem`
@@ -42,8 +39,14 @@ pub async fn build_core_section(
4239
owner: &PublicKey,
4340
) -> Option<String> {
4441
match fetch_core_body(rest, agent_keys, owner).await {
45-
Ok(Some(profile)) => Some(format!("[{SECTION_LABEL}]\n{profile}")),
46-
Ok(None) => Some(format!("[{SECTION_LABEL}]\n{ONBOARDING_NUDGE}")),
42+
Ok(Some(profile)) => Some(crate::prompt_framing::semantic_section(
43+
"core-memory",
44+
&profile,
45+
)),
46+
Ok(None) => Some(crate::prompt_framing::semantic_section(
47+
"core-memory",
48+
ONBOARDING_NUDGE,
49+
)),
4750
Err(reason) => {
4851
tracing::warn!(
4952
target: "engram::core",

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

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ mod filter;
77
mod observer;
88
mod pool;
99
mod pool_lifecycle;
10+
mod prompt_framing;
1011
mod queue;
1112
mod relay;
1213
mod setup_mode;
@@ -3653,15 +3654,21 @@ fn try_native_steer(
36533654
// channel context and the actor's profile in the original prompt,
36543655
// duplicating it here would defeat the point of non-cancelling
36553656
// steering (which is to inject only what's new).
3656-
let (header, closing) = queue::native_steer_framing();
3657+
let (tag, closing) = queue::native_steer_framing();
36573658
let event_id_hex = event.id.to_hex();
36583659
let be = queue::BatchEvent {
36593660
event,
36603661
prompt_tag: prompt_tag.clone(),
36613662
received_at: std::time::Instant::now(),
36623663
};
36633664
let event_block = queue::format_event_block(channel_id, None, &be, None);
3664-
let body = format!("{header}\n\n[Buzz event: {prompt_tag}]\n{event_block}\n\n{closing}");
3665+
let new_message = prompt_framing::semantic_section(tag, "");
3666+
let event_section = prompt_framing::semantic_section_with_attributes(
3667+
"buzz-event",
3668+
&[("type", prompt_tag.as_str())],
3669+
&event_block,
3670+
);
3671+
let body = format!("{new_message}\n\n{event_section}\n\n{closing}");
36653672

36663673
let (ack_tx, ack_rx) = tokio::sync::oneshot::channel::<pool::SteerAck>();
36673674
let request = pool::SteerRequest {
@@ -4454,6 +4461,14 @@ mod agent_draft_prompt_tests {
44544461
assert!(prompt.contains("Do not ask about runtime, provider, model, credentials"));
44554462
}
44564463

4464+
#[test]
4465+
fn shared_base_prompt_names_current_context_framing() {
4466+
let prompt = include_str!("base_prompt.md");
4467+
assert!(prompt.contains("UUID from `<context>`"));
4468+
assert!(prompt.contains("reply destination supplied in the `<context>` block"));
4469+
assert!(!prompt.contains("`[Context]`"));
4470+
}
4471+
44574472
#[test]
44584473
fn shared_base_prompt_teaches_real_newlines_for_multiline_messages() {
44594474
let prompt = include_str!("base_prompt.md");
@@ -5092,8 +5107,8 @@ mod heartbeat_base_prompt_tests {
50925107
use super::*;
50935108

50945109
// Pins the heartbeat dispatch path (dispatch_heartbeat, ~line 2359): a
5095-
// legacy agent WITH a base_prompt must get [Base] prepended to the
5096-
// heartbeat user message, composed as `[Base]\n{bp}\n\n{prompt}`. This is
5110+
// legacy agent WITH a base_prompt must get <base> prepended to the
5111+
// heartbeat user message. This is
50975112
// the second half of the round-2 regression (the first being initial_message).
50985113

50995114
fn heartbeat_standing() -> queue::StandingContext<'static> {
@@ -5106,12 +5121,12 @@ mod heartbeat_base_prompt_tests {
51065121
#[test]
51075122
fn test_heartbeat_legacy_agent_gets_base_prepended() {
51085123
// protocol_version 1 + Some(base_prompt): heartbeat prompt is prefixed
5109-
// with the [Base] section exactly as the legacy session/new path would.
5124+
// with the <base> section exactly as the legacy session/new path would.
51105125
let prompt = "[System: Heartbeat]\nrun feed get";
51115126
let composed = pool::prepend_standing_for_legacy(1, &heartbeat_standing(), prompt);
51125127
assert_eq!(
51135128
composed,
5114-
"[Base]\nyou are a helpful agent\n\n[System: Heartbeat]\nrun feed get"
5129+
"<base>\nyou are a helpful agent\n</base>\n\n[System: Heartbeat]\nrun feed get"
51155130
);
51165131
}
51175132

0 commit comments

Comments
 (0)