Agent-side wire: fetch the authorized vaulted LLM key → plant into Hermes

[hanwencheng]

Context

Today agentkeys wire plants the agent's LLM key from the operator's OPENROUTER_API_KEY env var (harness/phase1-wire-demo.sh:1072 writes it into ~/.hermes/.env + hermes config set model.*). That's a demo shortcut, not the design. The real guarantee is: the agent uses the key the master authorized it to fetch from the master's vault — never an ambient operator env var. This issue builds that path.

It's the agent-side complement to #214 (the master-side web pairing): #214 pairs + authorizes; this issue makes the agent actually fetch + use what it was authorized. Deferred from #207. Aligns with arch.md §10.2 + docs/plan/web-flow/onboarding-classifier-distribution.md §1.1 (cred:<service> authorizes "fetch/use the credential").

The agent-side sequence (this issue)

pairing (→ #214: master claims code, registers device, grants cred:<service> + memory:<ns> scopes)
   → cred-fetch    (agent fetches its AUTHORIZED LLM key from the master's vault via its cred:<service> cap — NO operator env)
   → wire hermes   (plant the fetched key into Hermes' model config + integrate the authorized memory/configs + enable Hermes + openviking)
   → the surprise  (the agent works, using the key + memory the master authorized — for the AI-toy case the toy backend is also a sandbox)

Scope

• Cred-fetch in the wire path — the agent fetches its authorized LLM key (cred:<service> scope → cap-mint → STS → cred worker → S3), via the shared agentkeys-backend-client path. No new broker/worker code (the cred-fetch cap + worker exist).
• Replace the env-key write — wire plants the vault-fetched key into Hermes (~/.hermes/.env + hermes config set model.*), instead of reading the operator's OPENROUTER_API_KEY. The operator env becomes a dev-only fallback, clearly labelled.
• Default-key selection (step 6).
  • Master-side default — at authorization (Wire web-app agent pairing to the real claim → register → scope flow #214) the master designates the agent's default LLM key. The no-UI AI-toy relies on this (no developer selection UI on the device).
  • Agent/CLI override — a developer can pick from the authorized list: --select 1 (default = first / the master-set default).
• Configs integration — wire also wires in the authorized memory namespaces (openviking memory + the injection hooks) so the agent reads the memory it was granted, same gesture.
• Demo + tests — update the wire demo to prove the agent uses a vault-fetched key (assert the agent's key == the master-authorized cred, NOT $OPENROUTER_API_KEY); revoking the cred:<service> scope cuts the agent off.

Acceptance

• The sandbox agent runs Hermes on an LLM key fetched from the master's vault via its granted cred:<service> scope — with no OPENROUTER_API_KEY in the operator env.
• The key + memory the agent uses are exactly what the master authorized at pairing; revoke the cred scope → the agent loses the key (next fetch denied).
• No-UI path: with no developer selection, the agent uses the master-designated default key.
• The wire demo asserts the above end-to-end (the real "surprise": the agent uses my authorized key, not the operator's env).

Out of scope

• Master-side pairing + authorization + default-key designation UX → Wire web-app agent pairing to the real claim → register → scope flow #214.
• QR delivery to a companion app for no-screen devices → deferred (arch §10.2 covers runtime QR on a screen; lifecycle/factory-reset is SidecarRegistry: agent/device-initiated on-chain self-revocation (device-key-signed revoke) #155/Agent-side device unbind / factory-reset + re-pair (method-A lifecycle) #156).

Effort

~L (agent-side wire integration: cred-fetch wiring + replace the env write + selection + configs integration + demo/tests). The cred-fetch cap, the cred worker, and the wire hooks already exist — this connects them.

References

• arch.md §10.2 (agent pairing) · onboarding-classifier-distribution.md §1.1 (cred = memory pattern; cred:<service> = fetch/use)
• harness/phase1-wire-demo.sh Phase 4.0 (the current operator-env shortcut to replace)
• Blocked by Wire web-app agent pairing to the real claim → register → scope flow #214 (master-side pairing + authorization) · deferred from Onboarding config bootstrap + classifier-driven auto-distribution (cred + memory, R1–R4) #207

[hanwencheng]

Scoping (from the #214 master-side build, 2026-06): the master side is now complete (PR #217 — claim → register → grant), so #216 is unblocked. Precise integration points found:

• No agent-side cred-fetch primitive exists yet. agentkeys-cli has only the master's broker-creds path (provision); there is no agentkeys cred fetch <service> for the agent to pull its authorized cred:<service> from the vault. This needs adding (cap-mint cred-fetch → STS → cred worker → S3, via the shared agentkeys-backend-client).
• wire.rs does NOT touch the LLM key. It only writes the IAM-guarantee pre_llm_call memory-injection hooks. The LLM key is configured outside wire — harness/phase1-wire-demo.sh Phase 4.0 writes OPENROUTER_API_KEY to ~/.hermes/.env + hermes config set model.* from the operator env. That Phase 4.0 is the swap point: fetch the authorized cred → plant it instead of the env key.
• Default-key (step 6): add a master-side default designation (small, master side) + the agent-side --select 1 / use-default consumption.

Verification posture: this is entirely agent-side + needs a live broker + cred worker + chain + a paired sandbox agent — it cannot be soundly verified locally. The sound path is a harness/sandbox e2e (the agent runs in the aiosandbox, fetches its vaulted key, and Hermes uses it — asserting the key == the master-authorized cred, NOT $OPENROUTER_API_KEY). Tracked as the live gate.

Sequencing: (1) cred fetch primitive → (2) swap Phase 4.0 to the vaulted key → (3) default-key select → (4) harness e2e assertion.