ADR-066: Packaging-Layer Abstraction (BYOC Plugin Per-Host Deployment)

Status: v0.2 (amended 2026-06-14) — Architect-authored; companion to PDR-005 v1.0 §Open question 7; gated by ADR-065 v0.1 ✅.

Date: 2026-06-06

Authors: Chief Architect (Arch)

Reviewers: PPM (PDR-005 owner), Lead Dev (implementation lane), CIO (methodology), CEO (xian)


Status

Context

What problem does this ADR solve?

PDR-005 v1.0 (Bring Your Own Chat, ratified 2026-06-05) commits Piper Morgan to plugin-based distribution (config + CLAUDE.md + skills + MCP server per PM’s 2026-06-01 clarification). ADR-065 (just filed) specifies the wire format for what flows between the plugin’s MCP server and connected hosts. This ADR specifies the packaging-layer abstraction that lets the same plugin deploy to multiple host surfaces with different capability profiles.

PDR-005 §Open question 7 routes the per-host capability map + deployment-layer concerns to this ADR.

The concrete need: the same Piper Morgan plugin, when deployed to Claude Desktop vs. ChatGPT vs. Slack vs. a bespoke UI vs. a sibling-project receiver (Klatch), must:

Why “packaging-layer abstraction”?

The “packaging layer” is the boundary between the plugin’s components and the host. It is:

Abstraction = the same plugin code path emits the right context packages and claims the right capabilities for whichever host it’s deployed to, via configuration + handshake + capability map. Not via #ifdef-style branching in the MCP server methods.

Format-decision space (inherits from ADR-065)

ADR-065 (companion ADR) settled:

This ADR organizes those primitives into a deployment-time abstraction. Sub-decisions:

Klatch alignment context

Same context as ADR-065: Klatch paused 2026-05-20; in-house drafting proceeds per Pattern-064 Evolution-section convention HOST lifted 2026-05-24. Klatch refinements fold to §Evolution when alignment resumes.

Prior art / cross-references


Decision

The packaging-layer abstraction is a config-declared per-host capability map + a surface.detect handshake + pure-function claim composition + three-tier degradation + SDK helpers + same-shape sibling integration. Sub-decisions D1-D6 inherit ADR-065 primitives (envelope+body+extensions; verb-enum+surface_type slot; error envelope; SemVer + Postel; spec-file source-of-truth) and organize them into a deployment-time abstraction the plugin runs at startup + per-request.

D1: Per-host capability map shape

Decision: The plugin’s config declares the per-host capability profile as a YAML map keyed on ADR-065 D3 surface_type values, mapping each verb to a claim + optional conditions set:

# plugin/config (excerpt)
capabilities:
  claude_desktop:
    "tool.call":
      claim: available
    "resource.read":
      claim: available
    "prompt.complete":
      claim: conditionally_available
      conditions:
        requires_user_consent: true
        max_tokens: 4096
    "audit.read":
      claim: available
    "surface.detect":
      claim: available
  chatgpt:
    "tool.call":
      claim: available
    "resource.read":
      claim: unavailable        # GPT actions don't expose generic resource read
    "prompt.complete":
      claim: unavailable
    # ...
  slack_thread:
    "tool.call":
      claim: conditionally_available
      conditions:
        requires_app_install: true
    # ...
  unknown:                        # surface-detect fallback
    "tool.call":
      claim: unavailable          # safe default: claim nothing until identified
    # all other verbs default to unavailable for unknown surface

Justification:

Pattern-072 8th application: this map IS a registry. Typed enum (verb × surface_type) + documented consumers (the MCP server’s claim-composer + the receiving hosts) + register-time validation (config-load-time schema check) + default policy (unknown verb-or-surface → unavailable). 8th application after task_type, safe_surface, probe registry, IndexDeclaration, PrivacyLevel, action VERB enum, ADR-065 D3 capability primitive. CIO catalog flag at Day-7 findings memo.

Alternatives considered:

D2: Surface-detection handshake

Decision: At plugin startup (MCP server initialization), the plugin emits a surface.detect capability claim package (ADR-065 D3 shape) with claim: unknown to the connected host. The host responds with an ADR-065 capability-claim package identifying its surface_type and any host-specific extensions. The plugin caches the detected identity for the session and uses it for all subsequent claim composition.

Plugin → Host:  {envelope: {package_type: "capability_claim", source: {agent: "piper-morgan", host_surface: "unknown", ...}},
                 body: {verb: "surface.detect", claim: "unknown"}}

Host → Plugin:  {envelope: {package_type: "capability_claim", source: {agent: "host-mcp-client", host_surface: "claude_desktop", host_surface_version: "1.4.2"}},
                 body: {verb: "surface.detect", claim: "available", surface_type: "claude_desktop"}}

Plugin caches: host_identity = "claude_desktop" (session-scoped)

Justification:

Alternatives considered:

D3: Capability-claim composition

Decision: Claim composition is a pure function of the detected host identity (D2 output) and the config’s per-host capability map (D1):

def compose_capability_claims(
    host_identity: SurfaceType,           # from D2 handshake cache
    capability_map: dict[SurfaceType, dict[Verb, ClaimSpec]],  # from D1 config
) -> list[CapabilityClaim]:
    """Pure function — same inputs always produce same output; no side effects."""
    host_profile = capability_map.get(host_identity) or capability_map["unknown"]
    return [
        CapabilityClaim(
            verb=verb,
            surface_type=host_identity,
            claim=spec.claim,
            conditions=spec.conditions or {},
        )
        for verb, spec in host_profile.items()
    ]

Justification:

Alternatives considered:

D4: Degradation policy — three tiers

Decision: When a capability claim’s runtime evaluation diverges from the static claim, the plugin surfaces one of three responses via the ADR-065 D4 error envelope:

Tier Claim state Runtime state Response
1: Static-unavailable unavailable (per D1 map) (not evaluated) Capability simply not advertised. Host receives no capability_claim package for that verb. No error surface.
2: Static-conditional, runtime-degraded conditionally_available + conditions (per D1 map) Predicate evaluation fails (e.g., requires_user_consent: true but consent absent) ADR-065 D4 error envelope: error_code: CAPABILITY_UNAVAILABLE, retry_hint: needs_user_action, human_message explains the missing precondition. User-visible.
3: Static-available, runtime-failed available (per D1 map) Tool invocation fails (transient, host limitation, etc.) ADR-065 D4 error envelope: error_code: TOOL_FAILED (or specific code), retry_hint: transient | permanent per failure mode. User-visible.

Justification:

Alternatives considered:

D5: SDK helper layer

Decision: Ship a per-language SDK helper library (initially Python + TypeScript) that receivers (MCP clients + sibling projects) consume to:

  1. Parse capability claims — deserialize ADR-065 D3 capability_claim packages into typed objects matching the receiver’s language idioms
  2. Evaluate conditions predicates — given a parsed claim with conditions, evaluate against the receiver’s runtime context (e.g., user consent state, app install state) and return bool + reason-if-false
  3. Generate well-formed error envelopes — given a tier-2 or tier-3 degradation, produce an ADR-065 D4-conformant error envelope without the receiver having to know the schema details
  4. Handle the surface.detect handshake — emit the response package + populate the surface_type field correctly
# Python SDK (sketch)
from piper_morgan_sdk import CapabilityClaim, ConditionEvaluator, ErrorEnvelope

claim = CapabilityClaim.from_package(received_package)  # (1) parse
evaluator = ConditionEvaluator(runtime_context={"user_consented": True, ...})
result = evaluator.evaluate(claim.conditions)            # (2) evaluate predicates
if not result.ok:
    error = ErrorEnvelope.capability_unavailable(       # (3) generate error envelope
        verb=claim.verb,
        human_message=f"Cannot {claim.verb}: {result.reason}",
        retry_hint="needs_user_action",
    )
    return error.to_package()
# ...proceed with capability invocation

Justification:

Alternatives considered:

D6: Sibling-project receiver shape

Decision: Sibling projects (Klatch primarily; future systems generically) consume Piper Morgan’s capability claims through the same SDK helper interface as MCP-client hosts — no separate “sibling-project integration mode.”

The sibling project:

Justification:

Alternatives considered:


D7: Configuration Ownership Convention — Server-Owned + Per-Request Host Augmentation (v0.2 addition)

Decision (v0.2): Configuration durability lives behind the MCP server, not on the host’s filesystem. The host augments per-request with ephemeral context; it does not package or persist configuration state. The plugin’s config artifact (D6 declaration sites) is consumed by the server’s startup, not the host’s. Configuration does not cross the host↔server boundary as durable state; only ephemeral per-request augmentation crosses.

This is a v0.2 amendment to v0.1’s implicit model (“host packages config → server consumes”), driven by the Cowork 2026-06-05 sandbox-runtime finding: meet-piper’s config-write to ~/.claude/ failed in Cowork because the sandboxed runtime ≠ host filesystem. The constraint forced a refinement: if config doesn’t live on the host’s filesystem, the host can be any runtime — Code, Cowork, Desktop, future ChatGPT plugin, future hosted-on-marketplace listing. The filesystem dependency that broke Cowork goes away by construction.

The two roles, explicitly:

Surface Owns Examples
Server (MCP server) Configuration durability — config artifact, user preferences, per-tenant settings, credential references The schema spec file (ADR-066 D6) lives in plugin package; the materialized config at runtime lives in server-side storage (DB, server filesystem, KMS)
Host Per-request ephemeral augmentation only Current user-session context; transient operational state; nothing the server needs to recover after a session ends

Why this is a refinement, not a withdrawal of v0.1:

v0.1 D1 (per-host capability map) + D6 (plugin packaging declaration sites) remain unchanged. What changes is the operational boundary: the config file at deployment time describes the capability profile (a spec); the runtime config-state (user preferences, deployed credentials, learned associations) lives behind the server. The plugin packaging at D6 specifies the schema; D7 specifies who owns the materialized state at runtime.

The “run anywhere” property — natural rather than aspirational:

PDR-005’s BYOC commitment implies plugin portability across hosts. v0.1 imagined this as the host packaging config and the server consuming whatever the host could provide — which makes “run anywhere” an aspirational property contingent on every host runtime supporting filesystem write to a conventional location. D7’s inversion makes “run anywhere” a structural property by construction: the host never has to write configuration durably, so no host-runtime-specific filesystem assumption can block plugin deployment. Cowork → server-owned-config converted a constraint into a cleaner architecture; the cleaner architecture composes with arbitrary host runtimes.

Composition with v0.1 sub-decisions:

Composition with companion ADRs:

Cross-link to methodologies + patterns:

Counter-arguments considered:

Open question (D7-specific):


Implementation sequencing (suggested)

Not gating decisions — sequencing notes for Lead Dev / implementation reviewers:

  1. D1 (capability map schema) ships first — additive declaration; no runtime behavior change
  2. D2 (handshake) + D3 (compose function) ship together — handshake produces input, compose produces output; testable as a pair
  3. D4 (degradation policy) ships with the first tier-2-conditioned capability — until any verb has conditions, tier 1 + tier 3 are the only live paths
  4. D5 (SDK helpers) ships in waves — Python first (Piper Morgan’s own ecosystem); TypeScript when first non-Python receiver lands; one-language-at-a-time keeps the surface manageable
  5. D6 (sibling integration) activates when first sibling project (likely Klatch) integrates — same SDK; just add their surface_type to D1’s map
  6. D7 (configuration ownership) ships with the first hosted-Piper deployment (Skunkworks BYOC Phase 2a) — the server-owned-config convention is validated when meet-piper-style host-filesystem-write is provably absent. v0.2 amendment landed 2026-06-14; first operational instance scheduled with Phase 2a build.

Consequences

Positive

Negative / Tradeoffs

Non-consequences


Evolution


Open questions (v0.1)

  1. Per-host capability map source-of-truth location — config declares per host (D1); is there a separate canonical “supported hosts + capability profiles” registry, or is config the registry? Initial lean: config is per-plugin-deploy declaration; a separate cohort-level registry of “what hosts are supported, with what default capability profile” lives elsewhere (likely docs/).
  2. Surface-detection handshake protocol (D2) — what’s the message shape? Initial lean: a surface.detect capability claim package with claim: unknown triggers the host to respond with its identity. Lead Dev consultation at Fire 4+.
  3. SDK helper distribution (D5) — published as plugin’s skills or as separate language packages? Initial lean: published as separate language packages (PyPI, npm) so non-plugin consumers can integrate too. Lead Dev consultation.
  4. Sibling-project integration depth (D6) — does Klatch consume capability claims the same way an MCP client does, or does it consume a higher-level abstraction? Pending Klatch resumption + Daedalus feedback.
  5. Pattern-072 application count — confirmed as 8th application if the per-host capability map becomes a typed registry. CIO catalog awareness flag at next cron-shape findings memo.

What this ADR is NOT