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.
|
||||
Reference in New Issue
Block a user