generated from coulomb/repo-seed
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.
This commit is contained in:
248
workplans/CYA-WP-0007-interactive-shell-session.md
Normal file
248
workplans/CYA-WP-0007-interactive-shell-session.md
Normal file
@@ -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/<id>.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.
|
||||||
161
workplans/CYA-WP-0008-llm-connect-adapter-integration.md
Normal file
161
workplans/CYA-WP-0008-llm-connect-adapter-integration.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user