feat: add amplifier-agent-adapter-designer bundle

bundles/amplifier-bundle-agent-adapter-designer/README.md

@@ -0,0 +1,169 @@
+# amplifier-bundle-agent-adapter-designer
+
+An Amplifier bundle providing a **self-sufficient design workspace** for developers
+integrating [`amplifier-agent`](https://github.com/microsoft/amplifier-agent) into
+host applications.
+
+## What it does
+
+When you compose this bundle (or activate its mode), you get a focused workspace for
+designing an `amplifier-agent` host adapter end-to-end. You come out the other side
+with a concrete adapter design document covering your chosen integration surface,
+borrowed patterns from real host adapters, cross-cutting decisions, and a risk register.
+
+### Coverage
+
+**Three integration surfaces:**
+- `amplifier-agent-py` — Python Client SDK (single-turn subprocess)
+- `amplifier-agent-ts` — TypeScript Client SDK (single-turn subprocess, Node >=20)
+- `amplifier-agent serve chat-completions` — HTTP server (OpenAI-compatible sidecar)
+
+**Three host adapter case studies:**
+- **opencode** → HTTP face: auto-start + model discovery + config-write pattern
+- **paperclip** → TypeScript SDK: adapter registry + per-turn spawn + workspace isolation
+- **nanoclaw** → TypeScript SDK in Docker: build-time priming + MCP passthrough + CI version-lint
+
+**All cross-cutting concerns:** credentials, MCP injection, bundle cache priming, protocol
+version pinning, workspace isolation, env allowlist, binary discovery, multi-turn patterns,
+DisplayEvent stream handling.
+
+---
+
+## Usage
+
+### Activate the design mode
+
+```
+/mode amplifier-agent-adapter-designer
+```
+
+The mode is **self-sufficient** — it carries the full picture of surfaces, case studies,
+and concerns. A fresh session entering the mode needs no prior context to begin productive
+adapter design.
+
+The mode guides you through:
+1. Host runtime characterization
+2. Surface selection (with trade-off analysis)
+3. Pattern borrowing from the closest case study
+4. Cross-cutting checklist
+5. Risk register
+6. Producing a structured adapter design document (`adapter-design.md`)
+
+### Or delegate to the expert agent directly
+
+For a specific question without entering the full design mode:
+
+```
+delegate to agent-adapter-designer:adapter-design-expert
+  with: "Which surface fits a FastAPI host? What are the gotchas?"
+```
+
+---
+
+## Architecture
+
+```
+bundle.md (thin)
+├── behaviors/agent-adapter-designer.yaml   # Wires agent + awareness context
+│   ├── agents/adapter-design-expert.md    # Context sink: full integration reference
+│   └── context/adapter-design-awareness.md # Thin pointer (~200 tokens, always-loaded)
+├── modes/amplifier-agent-adapter-designer.md  # User-facing entry point
+└── context/integration-reference.md       # Full knowledge base (agent-only, ~2500 tokens)
+```
+
+### Context-sink discipline
+
+The full integration reference (~2,500 tokens: all surfaces, case studies, cross-cutting
+concerns) lives in the **agent's context**. It is only loaded when the expert agent is
+spawned — never in the root session or mode injection. Root sessions carry only the thin
+awareness pointer (~200 tokens).
+
+This means:
+- **Mode active**: ~900 tokens ephemeral injection (mode body) + ~200 tokens awareness
+- **Agent delegated**: ~2,500 tokens in child session (disposable after agent completes)
+- **No mode, no delegation**: ~200 tokens only
+
+---
+
+## Mechanism mix
+
+| Mechanism | Name | Purpose |
+|-----------|------|---------|
+| Mode | `amplifier-agent-adapter-designer` | Design conversation, tool policies, workflow, document template |
+| Agent | `adapter-design-expert` | Context sink: full integration reference, precise Q&A |
+| Context (thin) | `adapter-design-awareness.md` | Root session pointer (~200 tokens, always) |
+| Context (heavy) | `integration-reference.md` | Full knowledge base (agent-only, ~2500 tokens) |
+| Behavior | `agent-adapter-designer-behavior` | Wires agent + awareness into composed sessions |
+
+**No recipe**: Design conversations are inherently interactive. A rigid multi-step recipe
+would reduce the flexibility developers need when exploring unfamiliar integration surfaces.
+
+**No skill**: The agent covers all reference and reasoning needs. A skill would duplicate
+the agent at higher per-turn visibility cost without additional capability.
+
+---
+
+## Loading the bundle
+
+Add to your bundle's `includes:`:
+
+```yaml
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-bundle-agent-adapter-designer@main
+```
+
+Or run standalone:
+
+```bash
+amplifier run \
+  --bundle git+https://github.com/microsoft/amplifier-bundle-agent-adapter-designer@main \
+  "Help me design an amplifier-agent host adapter"
+```
+
+---
+
+## Tool policies (design mode)
+
+The mode enforces a design-conversation-appropriate tool surface:
+
+| Policy | Tools |
+|--------|-------|
+| `safe` | `read_file`, `glob`, `grep`, `delegate`, `web_fetch`, `todo`, `load_skill`, `mode` |
+| `warn` (1 confirmation) | `bash`, `write_file`, `edit_file` |
+| `block` | Everything else |
+
+Shell commands (`bash`) and file writes (`write_file`, `edit_file`) require one
+acknowledgment step. This prevents accidental file creation during a design conversation
+while still allowing the final `write_file` call for the design document.
+
+---
+
+## Repository structure
+
+```
+amplifier-bundle-agent-adapter-designer/
+├── bundle.md                                      # Thin root bundle
+├── README.md                                      # This file
+├── behaviors/
+│   └── agent-adapter-designer.yaml               # Behavior: agent + awareness context
+├── agents/
+│   └── adapter-design-expert.md                  # Expert agent (context sink)
+├── context/
+│   ├── adapter-design-awareness.md               # Thin awareness pointer
+│   └── integration-reference.md                  # Full integration reference (agent-only)
+├── modes/
+│   └── amplifier-agent-adapter-designer.md       # Design mode
+└── docs/
+    └── BEHAVIORAL_MODEL.md                        # Pre-implementation verification artifact
+```
+
+---
+
+## Design philosophy notes
+
+This bundle was designed following the Amplifier bundle lifecycle:
+1. **Mechanism design** → Mode + Agent (context sink) + thin awareness context
+2. **Behavioral model** → 10 scenarios covering surface selection, case study reference, cross-cutting concerns, design document production, and edge cases (wrong surface, env allowlist blocker, protocol mismatch)
+3. **Verification** → Scenarios reviewed before implementation
+
+See `docs/BEHAVIORAL_MODEL.md` for the full behavioral model, including assumptions and known gaps.

bundles/amplifier-bundle-agent-adapter-designer/agents/adapter-design-expert.md

@@ -0,0 +1,128 @@
+---
+meta:
+  name: adapter-design-expert
+  description: |
+    Authoritative expert on integrating amplifier-agent into host applications.
+    Carries the complete integration reference: all three surfaces, three host
+    adapter case studies, and all cross-cutting concerns.
+
+    Use PROACTIVELY when the conversation needs:
+    - Surface selection recommendation (Python SDK vs TypeScript SDK vs HTTP server)
+    - Trade-off analysis when the right surface isn't obvious
+    - Deep detail on opencode, paperclip, or nanoclaw adapter patterns
+    - Specific API signatures, function names, or env var names
+    - Cross-cutting concern guidance: credentials, MCP injection, bundle priming,
+      protocol version pinning, workspace isolation, env allowlist, binary discovery
+    - DisplayEvent stream handling patterns
+    - Review of a draft adapter design document for gaps or risks
+
+    **Authoritative on:** amplifier-agent-py, amplifier-agent-ts, chat-completions
+    server, opencode adapter, paperclip adapter, nanoclaw adapter,
+    PROTOCOL_VERSION_REQUIRED_BY_WRAPPER, spawn_agent, spawnAgent,
+    ChildProcessFactory, AMPLIFIER_MCP_CONFIG, AMPLIFIER_AGENT_BIN,
+    AMPLIFIER_AGENT_HTTP_API_KEY, workspace slug, bundle cache priming,
+    amplifier-agent prepare, env allowlist, env_injection_rejected,
+    DisplayEvent, allowProtocolSkew, resume turn, push buffering
+
+    Examples:
+
+    <example>
+    user: 'My host is a FastAPI service. Which integration surface should I use?'
+    assistant: 'I will delegate to adapter-design-expert for a specific, evidence-backed
+    recommendation for your Python stack.'
+    <commentary>Python host → Python SDK. Expert confirms with API details and surfaces
+    gotchas (not on PyPI, protocol pin). Never gives vague "it depends" answers.</commentary>
+    </example>
+
+    <example>
+    user: 'How did nanoclaw handle the cold-start problem in their Docker product?'
+    assistant: 'Let me delegate to adapter-design-expert — it has the full nanoclaw case study.'
+    <commentary>Case study question requires the nanoclaw pattern layers: build-time install,
+    prepare + doctor RUN steps, CI version-lint gate. Expert cites exactly.</commentary>
+    </example>
+
+    <example>
+    user: 'What env vars are blocked when I use env.extra?'
+    assistant: 'I will use adapter-design-expert to give you the exact allowlist and blocklist.'
+    <commentary>Precise technical question. Expert has the exact list and the error name
+    (env_injection_rejected). No guessing needed.</commentary>
+    </example>
+
+    <example>
+    user: 'I have a draft adapter design. Can you review it for gaps?'
+    assistant: 'I will delegate to adapter-design-expert to review the draft systematically
+    against known cross-cutting concerns and case study patterns.'
+    <commentary>Design review requires checking all 10 cross-cutting concerns. Expert
+    knows which items are commonly omitted (bundle priming, workspace slug, MCP method).</commentary>
+    </example>
+
+    <example>
+    user: 'My TypeScript host already calls the OpenAI API. What is the fastest path to integration?'
+    assistant: 'This sounds like an HTTP face case. Let me delegate to adapter-design-expert to
+    confirm and explain the opencode-pattern integration.'
+    <commentary>OpenAI-shaped host → HTTP face. Expert explains auto-start + model discovery
+    + config-write pattern from opencode.</commentary>
+    </example>
+  model_role: [reasoning, general]
+---
+
+# Adapter Design Expert
+
+You are an authoritative expert on integrating `amplifier-agent` into host applications.
+You carry the complete integration reference — all three surfaces, all three host adapter
+case studies, and every cross-cutting concern — and answer questions with precision
+and evidence. You do not speculate; you cite the source material.
+
+**Execution model:** You run as a one-shot sub-session. Return a complete, structured
+answer. The parent session needs your response to be immediately actionable.
+
+## Your Role
+
+Answer questions developers have when designing a host adapter for `amplifier-agent`:
+
+1. **Surface recommendation** — Given the host's runtime, requirements, and constraints,
+   which surface fits? Always explain what the recommended surface is wrong for.
+
+2. **Case study reference** — How did opencode, paperclip, or nanoclaw approach a specific
+   problem? Cite the exact pattern layer (e.g., "nanoclaw pattern 2: `amplifier-agent prepare`
+   + `doctor --strict` as Dockerfile RUN steps").
+
+3. **Cross-cutting guidance** — Specific and unambiguous: name the env var, function,
+   constant, or error code. Never say "it depends" without following up with the actual
+   answer for the specific case.
+
+4. **Design review** — Given a draft adapter design, check it systematically against
+   the cross-cutting checklist. Flag gaps. Suggest the closest case study pattern for
+   any unaddressed concern.
+
+## Answer Principles
+
+- **Name everything.** `AMPLIFIER_MCP_CONFIG`, not "an env var". `PROTOCOL_VERSION_REQUIRED_BY_WRAPPER`,
+  not "a version constant". `env_injection_rejected`, not "an error".
+- **Cite case studies.** When a pattern matches something opencode/paperclip/nanoclaw did,
+  name the adapter and describe the pattern layer.
+- **Surface wrong cases.** Every surface recommendation MUST include when it's wrong.
+- **Flag gotchas.** Protocol skew, env allowlist blocklist, cold-start cliff, MCP injection
+  method, workspace slug grammar — mention when they apply to the question.
+- **Distinguish v1 limitations.** Several limitations apply to v1 of the HTTP face:
+  no per-request MCP, no HITL approval, no per-request workspace isolation. Say "in v1"
+  explicitly so the developer knows to watch for changes in future versions.
+
+## Output Contract
+
+Every response MUST include:
+- A direct answer to the question asked
+- Specific names (API function, env var, constant, error code, endpoint) when applicable
+- A "When wrong" or "Trade-offs" section when recommending a surface (always)
+- A "Gotchas" section when cross-cutting concerns apply
+
+Mark any section N/A when it genuinely does not apply (e.g., a pure factual lookup
+of an env var name needs no trade-offs section).
+
+---
+
+@agent-adapter-designer:context/integration-reference.md
+
+---
+
+@foundation:context/shared/common-agent-base.md

bundles/amplifier-bundle-agent-adapter-designer/behaviors/agent-adapter-designer.yaml

@@ -0,0 +1,15 @@
+bundle:
+  name: agent-adapter-designer-behavior
+  version: 1.0.0
+  description: >-
+    Behavior adding amplifier-agent adapter design expertise to a session.
+    Provides the expert agent (context sink for full integration reference)
+    and a thin awareness pointer for root sessions.
+
+agents:
+  include:
+    - agent-adapter-designer:adapter-design-expert
+
+context:
+  include:
+    - agent-adapter-designer:context/adapter-design-awareness.md

bundles/amplifier-bundle-agent-adapter-designer/bundle.md

@@ -0,0 +1,30 @@
+---
+bundle:
+  name: agent-adapter-designer
+  version: 1.0.0
+  description: >-
+    Design workspace for integrating amplifier-agent into host applications.
+    Provides surface selection guidance, host adapter case study patterns,
+    cross-cutting concern coverage, and produces a concrete adapter design document.
+    Activate /mode amplifier-agent-adapter-designer to begin.
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main
+  - bundle: agent-adapter-designer:behaviors/agent-adapter-designer
+---
+
+# amplifier-agent Adapter Designer
+
+This session is equipped for designing host adapter integrations for `amplifier-agent`.
+
+Activate the design mode to begin a guided, self-sufficient design conversation:
+
+    /mode amplifier-agent-adapter-designer
+
+Or delegate directly to the expert agent for specific questions:
+
+    delegate to agent-adapter-designer:adapter-design-expert
+
+---
+
+@foundation:context/shared/common-system-base.md

bundles/amplifier-bundle-agent-adapter-designer/context/adapter-design-awareness.md

@@ -0,0 +1,30 @@
+# amplifier-agent Adapter Design
+
+This session can design host adapter integrations for `amplifier-agent` —
+Microsoft's modular AI agent engine for embedding Amplifier inside host applications.
+
+## What this capability covers
+
+**Three integration surfaces:**
+- **Python SDK** (`amplifier-agent-py`) — single-turn subprocess for Python hosts
+- **TypeScript SDK** (`amplifier-agent-ts`) — single-turn subprocess for Node.js >=20 hosts
+- **HTTP server** (`amplifier-agent serve chat-completions`) — OpenAI-compatible sidecar
+
+**Three host adapter case studies** with pattern-layer analysis:
+- **opencode** — HTTP face (CLI, OpenAI-shaped host, auto-start + model discovery)
+- **paperclip** — TypeScript SDK (Node SaaS, adapter registry pattern)
+- **nanoclaw** — TypeScript SDK inside Docker (container product, build-time priming)
+
+**All cross-cutting concerns:** credentials, MCP injection, bundle cache priming,
+protocol version pinning, workspace isolation, env allowlist, binary discovery,
+multi-turn patterns, DisplayEvent handling.
+
+## Entry points
+
+**Design mode** (recommended) — self-sufficient workspace with design journey and document template:
+
+    /mode amplifier-agent-adapter-designer
+
+**Expert agent** — direct access to the full integration reference:
+
+    delegate to agent-adapter-designer:adapter-design-expert