From f0ee0636c01b24ff3383831e513e2633386b9fd3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 01:39:11 +0200 Subject: [PATCH] docs(workplans): add CYA-WP-0007 shell session and CYA-WP-0008 llm-connect Define interactive cya shell mode with opt-in shell history, State Hub orientation, session learning, and weakness hints. Pair with llm-connect adapter integration for production multi-turn assistance. --- .../CYA-WP-0007-interactive-shell-session.md | 248 ++++++++++++++++++ ...WP-0008-llm-connect-adapter-integration.md | 161 ++++++++++++ 2 files changed, 409 insertions(+) create mode 100644 workplans/CYA-WP-0007-interactive-shell-session.md create mode 100644 workplans/CYA-WP-0008-llm-connect-adapter-integration.md diff --git a/workplans/CYA-WP-0007-interactive-shell-session.md b/workplans/CYA-WP-0007-interactive-shell-session.md new file mode 100644 index 0000000..c8f5072 --- /dev/null +++ b/workplans/CYA-WP-0007-interactive-shell-session.md @@ -0,0 +1,248 @@ +--- +id: CYA-WP-0007 +type: workplan +title: "Interactive Shell Session: REPL, History Context, and Hub-Aware Dev-Sec-Ops Helper" +domain: capabilities +repo: can-you-assist +status: ready +owner: grok +topic_slug: foerster-capabilities +created: "2026-06-22" +updated: "2026-06-22" +--- + +# CYA-WP-0007: Interactive Shell Session + +## Goal + +Add an interactive `cya shell` mode — a console session comparable to starting Grok or +Claude Code — that: + +- Maintains lightweight in-session state across turns +- Optionally incorporates **opt-in, capped, redacted** shell history for continuity +- Orients on **State Hub** workstreams and inbox at session start (read-only by default) +- Reuses the existing orchestrator, safety, and Profile 0/1 memory seams +- Supports end-of-session learning (retrospect, reflections, episodic export) +- Surfaces rule-based **weakness hints** (credential anti-patterns, repeated risk) for + knowledge transfer — never auto-executes or downgrades safety + +`cya` remains a helper **alongside** the shell, not a replacement for it. + +## Background & References + +- **INTENT.md:** interaction history under user control; recent command history when permitted. +- **SCOPE.md (current):** REPL and shell history explicitly deferred — this workplan + proposes a scoped update in T01. +- **CYA-WP-0006 (done):** Profile 1 reflections + `cya retrospect` — end-of-session learning. +- **wiki/CyaSpeechModeExtension.md:** prior session-mode thinking (voice bridge later). +- **Collector contract:** `src/cya/context/collector.py` — history excluded until opt-in. +- **State Hub:** non-runtime per `repo-boundary.md`; HTTP read at session start, write on + explicit operator action only. + +## Non-Goals (for this slice) + +- Autonomous or background command execution +- Full phase-memory graph / Profile 2 synthesis +- Voice / phone bridge (see wiki extension doc) +- Team-shared or hosted session state +- Deep semantic repo indexing or embeddings +- CI / PyPI automation +- Replacing State Hub MCP or custodian workflows + +## Dependencies + +- **CYA-WP-0008** (llm-connect adapter): required for *conversational quality* in the REPL; + CYA-WP-0007 MVP (T02–T05) can ship with `FakeLLMAdapter` for scaffolding and + history/hub/explain paths. +- **llm-connect** repo: stable client behind `LLMAdapter` Protocol. +- **State Hub API** at `http://127.0.0.1:8000` (or tunnel) for hub orientation tasks. + +## Task Breakdown + +### T01 — Design doc and SCOPE alignment + +```task +id: CYA-WP-0007-T01 +status: todo +priority: high +``` + +Produce `docs/cya-interactive-shell-session-design.md` covering: + +- REPL UX (`cya shell`), slash commands, session file layout +- Shell history opt-in model (config + flag), caps, redaction rules, provenance +- State Hub read/write boundaries and slash commands +- Episodic session log schema (`kind: session_turn` precursor) +- Weakness-hint rule catalog (v1, deterministic) +- SCOPE.md update: move REPL from out-of-scope to owned capability + +**Acceptance criteria:** +- Design doc reviewed against INTENT, SCOPE, MemoryVision, repo-boundary. +- Explicit checklist gates T02–T08. + +### T02 — REPL skeleton and session state + +```task +id: CYA-WP-0007-T02 +status: todo +priority: high +``` + +Implement `cya shell` Typer subcommand: + +- Readline or `prompt_toolkit` loop with prompt `cya> ` +- Session id + user-owned artifact at `~/.config/cya/sessions/.jsonl` +- In-session turn buffer (user + assistant text, timestamps) +- Slash commands: `/exit`, `/help`, `/explain` (last turn context) +- Graceful handling of EOF, Ctrl-C, non-TTY + +**Acceptance criteria:** +- `cya shell` starts, accepts input, persists turns to jsonl, exits cleanly. +- No LLM required for loop mechanics (may echo or use FakeLLMAdapter). + +### T03 — Opt-in shell history collector + +```task +id: CYA-WP-0007-T03 +status: todo +priority: high +``` + +Extend context collection (new module or `collector` extension): + +- Opt-in via `cya shell --with-history` and/or `[shell_history]` in config TOML +- Read last N lines from `$HISTFILE` or shell-appropriate fallback (`fc -l`) +- Hard cap (default 50 lines), redact secrets (API keys, tokens, passwords) +- Provenance per line in context envelope; visible via `/explain` +- Default **off** — no history without explicit enable + +**Acceptance criteria:** +- History appears in explain output when enabled; absent when disabled. +- Redaction tested with fixture lines containing fake secrets. +- Collector core invariants preserved for one-shot `cya "..."` (history off by default). + +### T04 — State Hub session orientation + +```task +id: CYA-WP-0007-T04 +status: todo +priority: medium +``` + +At session start, load orientation (graceful if hub offline): + +- `.custodian-brief.md` when present +- Active workstreams for topic `64418556-3206-457a-ba29-6884b5b12cf3` +- Unread inbox for `to_agent=can-you-assist` + +Slash commands: + +- `/hub` — show active workstreams + open tasks for current repo +- `/hub log "summary"` — POST progress event (operator confirms) +- `/inbox` — show unread messages (mark read only after explicit action) + +**Acceptance criteria:** +- Session banner shows brief summary when hub reachable. +- Hub offline degrades gracefully; shell still usable. +- No automatic hub writes without confirmation. + +### T05 — Wire REPL through orchestrator and safety + +```task +id: CYA-WP-0007-T05 +status: todo +priority: high +``` + +Connect each REPL turn to existing pipeline: + +- `collect()` + optional history + memory recall + `classify()` + adapter + render +- Mandatory confirmation for non-safe levels (same as one-shot) +- Memory surfacing (Profile 1 reflections) in multi-turn output +- `/explain` shows full envelope for last turn + +**Acceptance criteria:** +- Destructive intent in REPL still requires confirmation; memory cannot bypass. +- Turn output consistent with one-shot `cya "..."` for same input. + +### T06 — End-of-session learning and export + +```task +id: CYA-WP-0007-T06 +status: todo +priority: medium +``` + +On `/exit` or session end: + +- Offer inline Profile 1 lesson capture (reuse `memory/reflections.py` helpers) +- Optional `cya retrospect`-style mini-flow without leaving shell history +- `/export-session` — write redacted session summary JSON for knowledge transfer +- Store episodic turns with `kind: session_turn` (new constant) when user confirms + +**Acceptance criteria:** +- Session export is user-triggered and inspectable. +- Reflections from shell session appear in `cya memory reflections`. +- Skip path leaves no orphan records. + +### T07 — Weakness hints (rule-based v1) + +```task +id: CYA-WP-0007-T07 +status: todo +priority: medium +``` + +Deterministic post-turn or end-session hints: + +- Credential anti-patterns in discussed commands (paste keys, `warden route` bypass) +- Repeated destructive suggestions without confirmation +- State Hub alignment warnings (active work not matching stated goal) + +Surface as informational panels — not auto-fixes. Optional save as reflection. + +**Acceptance criteria:** +- At least three hint rules with tests. +- Hints never change risk level or skip confirmation. + +### T08 — Tests, docs, and operator guide + +```task +id: CYA-WP-0007-T08 +status: todo +priority: high +``` + +- `tests/test_shell_session.py` — REPL loop, history opt-in, hub degrade, safety +- README section: starting a shell session, history opt-in, hub commands +- AGENTS.md command reference update +- Example operator session in docs + +**Acceptance criteria:** +- `make test` passes. +- README documents `cya shell` with example transcript. + +### T09 — Register, sync, and handoff + +```task +id: CYA-WP-0007-T09 +status: todo +priority: low +``` + +Run `make fix-consistency REPO=can-you-assist`, log progress, move to `active` when +implementation begins. + +## Success Criteria + +When complete: + +- Operators can run `cya shell`, pick up recent shell context (opt-in), see hub work, + get multi-turn assistance with full safety, and export learnings for transfer. +- All artifacts remain user-controlled and explainable. +- SCOPE reflects interactive session as an owned capability. + +--- + +**Status note:** Promoted to `ready` on 2026-06-22 after operator approval of direction. +Pair with CYA-WP-0008 for production LLM quality in the REPL. \ No newline at end of file diff --git a/workplans/CYA-WP-0008-llm-connect-adapter-integration.md b/workplans/CYA-WP-0008-llm-connect-adapter-integration.md new file mode 100644 index 0000000..36db2b9 --- /dev/null +++ b/workplans/CYA-WP-0008-llm-connect-adapter-integration.md @@ -0,0 +1,161 @@ +--- +id: CYA-WP-0008 +type: workplan +title: "llm-connect Adapter Integration for Production Assistance" +domain: capabilities +repo: can-you-assist +status: ready +owner: grok +topic_slug: foerster-capabilities +created: "2026-06-22" +updated: "2026-06-22" +--- + +# 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: todo +priority: high +``` + +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`. + +### T02 — Implement `LLMConnectAdapter` + +```task +id: CYA-WP-0008-T02 +status: todo +priority: high +``` + +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`). + +### T03 — Configuration and developer ergonomics + +```task +id: CYA-WP-0008-T03 +status: todo +priority: medium +``` + +- `~/.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. + +### T04 — Orchestrator and shell integration + +```task +id: CYA-WP-0008-T04 +status: todo +priority: high +``` + +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). + +### T05 — Tests and offline CI strategy + +```task +id: CYA-WP-0008-T05 +status: todo +priority: high +``` + +- 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. + +### T06 — Documentation and SCOPE update + +```task +id: CYA-WP-0008-T06 +status: todo +priority: medium +``` + +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: todo +priority: low +``` + +`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:** `ready` on 2026-06-22. Can start T01–T03 in parallel with CYA-WP-0007 T02–T04. \ No newline at end of file