Skip to content

feat(engine): replace built-in bundle with vendored behavioral-anchor#59

Merged
manojp99 merged 2 commits into
mainfrom
feat/behavioral-anchor-bundle
Jun 17, 2026
Merged

feat(engine): replace built-in bundle with vendored behavioral-anchor#59
manojp99 merged 2 commits into
mainfrom
feat/behavioral-anchor-bundle

Conversation

@manojp99

Copy link
Copy Markdown
Collaborator

Summary

Replace the inbuilt amplifier-agent-builtin bundle with a vendored copy of the experimental behavioral-anchor bundle from amplifier-foundation@main:experiments/behavioral-anchor/behavioral-anchor.md.

This introduces a new agent set (explorer, architect, builder, debugger, git-ops, researcher) replacing the previous planner/coder/tester pattern. The new bundle uses a parent-level tool inheritance model via tool-delegate's context_inheritance feature, simplifying agent definitions and reducing duplication.

The Five Modifications

When vendoring behavioral-anchor, we diverged from upstream in these five specific places to preserve amplifier-agent architectural properties:

Upstream behavioral-anchor This vendored copy Why
no default_provider default_provider: anthropic Engine reads this directly from bundle frontmatter
behaviors/streaming-ui.yaml include omitted stdout reserved for JSON envelope (AGENTS.md invariant #5); engine handles streaming via bundle/hook_streaming.py
hooks-todo-display omitted same stdout contract — no progress bars on stdout
behaviors/logging.yaml include hook-context-intelligence instead Preserves workspace JSONL alignment with amplifier-app-cli per PR #57
hooks-approval omitted no wire-protocol approval round-trip yet; would deadlock on policy-driven rules
no tool-mcp added Preserves MCP for existing users; AAA doctor command checks for it

Architecture Impact

Agent set is flexible — Engine, protocol, runtime, both wrapper SDKs, and conformance fixtures have zero hardcoded agent names. No production code changes required beyond packaging and tests.

Tool inheritance model — The new bundle moves tools from per-agent frontmatter (old pattern) to parent-level declaration (new pattern). Agents inherit via tool-delegate.context_inheritance.enabled: true. Tests updated to validate agent definitions resolve correctly rather than checking for specific tool blocks.

Bundle cache key — Cache is keyed by sha256(bundle.md). The new manifest hash invalidates the warm pickle automatically; users see 30–90s of cold-start on first run after upgrade (foundation modules are cloned fresh).

How to Verify Locally

# Install from the current branch
uv tool install --force --reinstall --from . amplifier-agent

# Verify bundle preps cleanly and doctor passes
amplifier-agent doctor

# One full round-trip to confirm provider + streaming work
amplifier-agent run "say hi"

Test Status

Suite Result Notes
ruff check src/ tests/ ✓ clean no lint issues
ruff format --check ✓ clean formatting aligned
pyright src/ 1 pre-existing error JsonDisplaySystem | CliDisplaySystem in single_turn.py:702 — verified pre-existing on main
pytest tests/ -m "not integration" 703 passed, 6 failed 6 failures are pre-existing integration test failures (--provider CLI flag missing) — verified on main
TypeScript wrapper build/test not run verified agent-name-agnostic in prior audit; no changes needed
Conformance suite not run verified agent-name-agnostic in prior audit; no changes needed

Open Items

  • Design doc: Not yet written. The decisions are fully documented in this PR; can be promoted to a dated design doc (e.g. docs/designs/2026-06-15-behavioral-anchor-vendoring.md) if desired.
  • Runtime verification: Tool inheritance via tool-delegate.context_inheritance should be verified in a live session (architect or builder agent using bash/filesystem tools).
  • Extended thinking events: Behavioral-anchor enables extended_thinking: true on loop-streaming. Verify hook_streaming.py correctly forwards thinking blocks on the wire and that wrapper SDKs recognize them.

Architectural Reference

This change builds on the architectural predecessor: docs/designs/2026-05-19-baked-in-bundle-decision.md.

PR Status

Marked DRAFT — this is a test branch for runtime verification before merge.

Manoj Prabhakar Paidiparthy and others added 2 commits June 15, 2026 16:47
Replace the inbuilt amplifier-agent-builtin bundle with a vendored copy of the
experimental behavioral-anchor bundle from amplifier-foundation@main:
experiments/behavioral-anchor/behavioral-anchor.md.

This introduces a new agent set (explorer, architect, builder, debugger, git-ops,
researcher) replacing the previous planner/coder/tester pattern. The new bundle
uses a parent-level tool inheritance model via tool-delegate's context_inheritance
feature, simplifying agent definitions and reducing duplication.

Five modifications made to the upstream behavioral-anchor to align with
amplifier-agent architecture:

  1. Added default_provider: anthropic (engine reads from bundle frontmatter)
  2. Dropped behaviors/streaming-ui.yaml and hooks-todo-display (stdout reserved
     for JSON envelope; engine handles streaming via hook_streaming.py)
  3. Dropped behaviors/logging.yaml; kept hook-context-intelligence to preserve
     workspace JSONL alignment with amplifier-app-cli (PR #57)
  4. Dropped hooks-approval (no wire-protocol approval round-trip yet)
  5. Added tool-mcp (preserves MCP for existing users + doctor checks)

Cache implications: The warm-start prepared bundle is keyed by sha256(bundle.md),
which has changed. Users will see 30-90s of cold-start on first run after upgrade
(all foundation modules are cloned fresh and cache is repopulated).

Compliance: Tests updated for new agent set; protocol unchanged; wrapper SDKs
verified as name-agnostic and require no changes. Design doc TBD (can be promoted
from PR discussion if desired). Reference: 2026-05-19-baked-in-bundle-decision.md.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
When a module fails with 'No module named' or 'failed validation' errors
after a bundle.md change, the cause is usually a stale venv checkout, not
a missing dep. Document the diagnostic sequence (cache clear + --refresh
reinstall) and the finding that foundation's resolver does follow upstream
module transitive deps with fresh git clones.

This pitfall was discovered during PR #59 runtime testing where stale
module checkouts twice masked missing deps that disappeared with a fresh
install. Documented to prevent next contributor hitting the same issue.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
@manojp99 manojp99 marked this pull request as ready for review June 17, 2026 01:32
@manojp99 manojp99 merged commit e0aed1f into main Jun 17, 2026
2 of 3 checks passed
manojp99 added a commit that referenced this pull request Jun 17, 2026
Captures the behavioral-anchor built-in bundle replacement merged in #59 (e0aed1f). New sub-session agent set, expanded tool roster, bundle renamed. Wire protocol unchanged at 0.3.0; no wrapper bump required. See CHANGELOG.md for full details and migration notes.

Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-authored-by: Manoj Prabhakar Paidiparthy <mpaidiparthy@microsoft.com>
Co-authored-by: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
@manojp99 manojp99 deleted the feat/behavioral-anchor-bundle branch June 17, 2026 18:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant