---
id: CYA-WP-0008
type: workplan
title: "llm-connect Adapter Integration for Production Assistance"
domain: agents
repo: can-you-assist
status: finished
owner: grok
topic_slug: foerster-capabilities
created: "2026-06-22"
updated: "2026-06-22"
state_hub_workstream_id: "f713db12-5b90-4453-8fbb-a0e50f61699b"
---

# CYA-WP-0008: llm-connect Adapter Integration

## Goal

Replace `FakeLLMAdapter` on production code paths with a real **llm-connect** client
behind the existing `LLMAdapter` Protocol, so one-shot `cya "..."` and `cya shell`
(CYA-WP-0007) can deliver genuinely useful multi-turn assistance.

Preserve the seam: `cya` never hard-codes a vendor; all provider config lives in
llm-connect. Credential routing via `warden route` before requesting secrets.

## Background & References

- **Seam:** `src/cya/llm/adapter.py` — `LLMAdapter` Protocol + `FakeLLMAdapter`
- **INTENT.md:** `cya` asks; `llm-connect` reaches infrastructure
- **SCOPE.md:** real client listed as explicit out-of-scope / future work
- **CYA-WP-0007:** REPL usable with fake adapter for scaffolding; quality needs this slice
- **Credential routing:** `AGENTS.md` / `warden route find` — no secrets in repo

## Non-Goals

- Provider-specific UI inside `cya` (model picker beyond minimal config)
- Token billing dashboards or cost analytics
- Embedding / RAG pipelines
- Bypassing `LLMAdapter` Protocol for any production path

## Dependencies

- **llm-connect** package/API stability (coordinate with that repo owner)
- Operator-provided credentials via OpenBao paths surfaced by `warden route`
- CYA-WP-0007 T05 can proceed in parallel using `FakeLLMAdapter`

## Task Breakdown

### T01 — Adapter contract review and llm-connect API survey

```task
id: CYA-WP-0008-T01
status: done
priority: high
state_hub_task_id: "483d13bb-aabe-48ad-96c2-8df83de5f442"
```

Document mapping from `AssistanceRequest` / `AssistanceResponse` to llm-connect calls.
Identify config surface (TOML keys, env vars). Note gaps requiring llm-connect changes.

**Acceptance criteria:**
- Short integration note in `docs/` or workplan appendix.
- Credential route catalog id(s) documented via `warden route find`.

**Delivered:** `docs/llm-connect-integration.md`

### T02 — Implement `LLMConnectAdapter`

```task
id: CYA-WP-0008-T02
status: done
priority: high
state_hub_task_id: "0fc17ad5-d90b-4ad1-b060-a1a2f9c25ea8"
```

New class in `src/cya/llm/` implementing `LLMAdapter`:

- Delegates to llm-connect client
- Graceful degrade message when llm-connect unavailable / misconfigured
- `FakeLLMAdapter` remains for tests and `--offline` mode

**Acceptance criteria:**
- Protocol-compliant; swap via config or env (`CYA_LLM_ADAPTER=connect|fake`).

**Delivered:** `src/cya/llm/connect_adapter.py`, `src/cya/llm/factory.py`

### T03 — Configuration and developer ergonomics

```task
id: CYA-WP-0008-T03
status: done
priority: medium
state_hub_task_id: "e8470a37-ecec-42f1-920b-ccd8b98b5512"
```

- `~/.config/cya/config.toml` `[llm]` section (backend, model hints)
- Document `warden route` steps in README
- `make dev-install` optional extra `[llm]` dependency group if needed

**Acceptance criteria:**
- Operator can configure adapter without editing source.
- No secrets committed; example config uses placeholders.

**Delivered:** `src/cya/config.py`, `docs/cya-config.example.toml`, README section

### T04 — Orchestrator and shell integration

```task
id: CYA-WP-0008-T04
status: done
priority: high
state_hub_task_id: "f2781963-fecf-4576-96de-bd745df271a0"
```

Wire `handle_request()` and CYA-WP-0007 shell turns to adapter selection:

- Default fake when unconfigured (current behavior)
- Real adapter when config present
- Multi-turn context: pass recent session turns in `AssistanceRequest.context`

**Acceptance criteria:**
- One-shot and shell paths use same adapter factory.
- Session context bounded (token/line budget documented).

**Delivered:** `get_adapter()` wired in orchestrator; `session_turns` + `bound_session_turns()` ready for CYA-WP-0007 shell

### T05 — Tests and offline CI strategy

```task
id: CYA-WP-0008-T05
status: done
priority: high
state_hub_task_id: "32de980b-1a24-4159-9550-7c516570cae3"
```

- Mock llm-connect for unit tests (no live API in default `make test`)
- Optional integration test marker `@pytest.mark.llm_live` for manual runs
- Fake adapter remains default in CI

**Acceptance criteria:**
- `make test` passes without network or API keys.
- Live test documented for operator manual verification.

**Delivered:** `tests/test_llm_factory.py`, `tests/test_llm_connect_adapter.py`, `tests/test_llm_prompt.py`

### T06 — Documentation and SCOPE update

```task
id: CYA-WP-0008-T06
status: done
priority: medium
state_hub_task_id: "2d152d4b-e4b2-4a94-8f85-d8f033e55d5f"
```

Update README, SCOPE.md (remove "only FakeLLMAdapter" where accurate), AGENTS.md.

**Acceptance criteria:**
- Clear "configured vs offline" operator paths documented.

### T07 — Register, sync, and handoff

```task
id: CYA-WP-0008-T07
status: done
priority: low
state_hub_task_id: "2fb42517-b2df-43d3-8195-f02d310107dc"
```

`make fix-consistency`, progress event, coordinate with llm-connect repo if API gaps found.

## Success Criteria

- Configured `cya` uses llm-connect for real inference.
- Unconfigured / test environments behave exactly as today (fake adapter).
- CYA-WP-0007 shell session becomes practically useful once both workplans complete.

---

**Status note:** `finished` on 2026-06-22. Integration doc: `docs/llm-connect-integration.md`.