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