glas-harness/docs/adr/ADR-002-credential-brokering-and-composable-reins.md

ADR-002: Credential brokering for rein-openweights; composable reins deferred

• Status: accepted (part 1), open (part 2)
• Date: 2026-07-26
• Deciders: Bernd Worsch

Context

GLAS-WP-0001-T06 asked who acquires the OpenRouter credential rein-openweights needs: glas-harness (mirroring how it brokers sand-boxer sandbox handles) or the rein itself (mirroring how rein-aharness already holds its own OpenBao AppRole lane for IMAP/mail credentials).

Discussion surfaced a prior question: should rein-openweights talk to OpenRouter through llm-connect, or through a leaner, independent wrapper that both llm-connect and rein-openweights depend on — keeping llm-connect's monitoring/evaluation/optimization features optional rather than bundled in?

Checking llm-connect directly resolved that half cleanly:

• Its own ARCHITECTURE-LAYERS.md already separates Core (frozen adapter ABC + models) from Functional (independently shippable per-provider adapters, diagnostics, replay, budget tracking — all explicitly optional: "Keeps base install lightweight... optional dep, not runtime dep") from Configuration (TOML resolution, key lookup).
• resolve_api_key() (llm_connect/config.py) only reads an already-materialized key — explicit argument → env var → file. It never talks to OpenBao/ops-warden. llm-connect/INTENT.md states this as an explicit boundary: "not intended to... manage secrets, credentials, or organizational access policies."

So llm-connect was never a credential broker regardless of which adapter path rein-openweights uses — the earlier concern that "using llm-connect" imports a credential model doesn't hold. rein-openweights can depend on just Core + the OpenRouterAdapter Functional module and skip diagnostics/replay/budget, the same way any other consumer can today.

Decision (part 1 — resolved)

Option B: rein-openweights acquires its OpenRouter credential directly (OpenBao/ops-warden), the same way rein-aharness already does for its own credentials. glas-harness does not broker LLM-provider credentials.

Rationale, in order of weight:

1. Consistency with the existing family precedent. rein-aharness's own INTENT.md states "the harness is the only credential holder and only policy enforcement point." Having glas-harness broker for one rein but not the other bakes an inconsistency into the family from its second member.
2. Scope discipline. glas-harness has zero live end-to-end proof yet (GLAS-WP-0001-T04 is a unit-tested wiring, not a live run) — growing it into a secrets broker ahead of validated need repeats the premature-generalization mistake ADR-001 was written to avoid on the sandbox side.
3. Credential lifecycle doesn't map cleanly onto sand-boxer's create/destroy session lifecycle the way a sandbox handle does — the analogy that made Option A attractive was weaker than it first looked.

Accepted cost: rein-openweights duplicates OpenBao wiring rather than inheriting it from glas-harness. Revisit centralizing it if a third rein repeats the same need — decide from evidence, not in advance.

Consequences (part 1)

• rein-openweights (REIN-OW-WP-0001-T04) implements its own credential acquisition; it does not wait on or call into glas-harness for this.
• rein-openweights depends on llm-connect's Core + OpenRouterAdapter only — not the full package surface — confirmed against the actual layer boundaries above, not assumed.
• GLAS-WP-0001-T06 is done. GLAS-WP-0001-T05 (bootstrap rein-openweights) is unblocked.

Part 2 — resolved in ADR-004: composable reins stay deferred

See docs/adr/ADR-004-composable-reins-stay-deferred.md — the deferral below held even after two more observability additions landed; both turned out simpler as direct implementations, not middleware.

Part 2 (original framing, for context)

Separately, the idea surfaced that monitoring/evaluation/optimization (capabilities llm-connect already stages as optional Functional modules) could eventually become their own composable reins — cross-cutting capabilities that wrap or observe another rein's dispatch_tool calls, rather than each being a complete alternative harness backend the way rein-aharness/rein-openweights are.

This is a real extension to docs/harness-contract.md: the current Rein ABC assumes one rein is the whole session, with no wrapping/composition concept (no middleware chain, no way for a "monitoring rein" to sit between glas-harness and the base rein's calls).

Left open deliberately — it does not block rein-openweights bootstrap and there is only one candidate capability (llm-connect's existing optional modules) to generalize from, not evidence of a recurring pattern. Revisit if/when a second capability (evaluation, or a distinct optimization concern) wants the same treatment. If pursued, it would need:

• A Middleware/ReinWrapper concept distinct from Rein in contract.py, with an explicit chain-of-responsibility around dispatch_tool.
• A decision on whether llm-connect itself gets decomposed into reins/middleware, or stays a shared library that both base reins and middleware reins happen to depend on (the leaner option, and the one consistent with llm-connect's own INTENT.md boundary against owning application-level workflow).