generated from coulomb/repo-seed
feat(shell): add interactive cya shell session (CYA-WP-0007)
Implement the full interactive shell REPL with session persistence, opt-in capped/redacted shell history, State Hub orientation and explicit slash-command writes, orchestrator/safety wiring, end-session learning hooks, weakness hints, docs, and tests.
This commit is contained in:
172
docs/cya-interactive-shell-session-design.md
Normal file
172
docs/cya-interactive-shell-session-design.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# cya Interactive Shell Session Design
|
||||
|
||||
Status: implemented for CYA-WP-0007
|
||||
Date: 2026-06-23
|
||||
|
||||
## Scope Alignment
|
||||
|
||||
This design moves `cya shell` from the old deferred REPL note in SCOPE.md into
|
||||
owned product scope. It preserves the core INTENT principle: `cya` helps from
|
||||
inside the console while the user keeps control of context, history, memory,
|
||||
backend choice, and safety decisions.
|
||||
|
||||
Reviewed against:
|
||||
|
||||
- INTENT.md: console-native, user-controlled, explainable assistance.
|
||||
- SCOPE.md: `cya` owns UX, orchestration, safety, context, and documentation;
|
||||
State Hub remains non-runtime coordination.
|
||||
- MemoryVision.md: session turns are an episodic precursor with explicit
|
||||
`kind: session_turn`, user-triggered export, and opt-in persistence to memory.
|
||||
- AGENTS.md / State Hub boundary: hub reads are allowed for orientation;
|
||||
hub writes require explicit operator confirmation.
|
||||
|
||||
## REPL UX
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
cya shell
|
||||
cya shell --offline --no-hub
|
||||
cya shell --with-history
|
||||
```
|
||||
|
||||
Prompt: `cya> `
|
||||
|
||||
The shell is intentionally still a helper alongside the user's shell. It never
|
||||
auto-executes commands. Natural-language turns are passed through the existing
|
||||
orchestrator path: context collection, memory recall, risk classification,
|
||||
mandatory confirmation for non-safe levels, adapter call, and rendering.
|
||||
|
||||
Slash commands:
|
||||
|
||||
- `/help` - show the shell command list.
|
||||
- `/exit` or `/quit` - close the shell session.
|
||||
- `/explain` - show the last turn's risk, context envelope, shell history
|
||||
provenance, hub summary, and weakness hints.
|
||||
- `/hub` - show loaded active workstreams, open tasks, inbox, and hub errors.
|
||||
- `/hub log "summary"` - post a State Hub progress note only after interactive
|
||||
confirmation.
|
||||
- `/inbox` - show unread messages.
|
||||
- `/inbox read <id>` - explicitly mark a message read.
|
||||
- `/export-session` - write a redacted JSON session summary.
|
||||
- `/learn` - capture Profile 1 reflections immediately.
|
||||
|
||||
EOF exits cleanly. Ctrl-C interrupts the current prompt and keeps the session
|
||||
alive. Non-TTY input is accepted for smoke/scripted use; end-session learning
|
||||
prompts are skipped unless the session is interactive.
|
||||
|
||||
## Session File Layout
|
||||
|
||||
Session artifacts are user-owned and local:
|
||||
|
||||
```text
|
||||
~/.config/cya/sessions/<session-id>.jsonl
|
||||
~/.config/cya/sessions/<session-id>-summary.json
|
||||
```
|
||||
|
||||
Session ids use `cya-YYYYMMDD-HHMMSS-<random>`.
|
||||
|
||||
JSONL event kinds:
|
||||
|
||||
- `session_start`: session metadata, cwd, loaded history context, compact hub
|
||||
orientation.
|
||||
- `session_turn`: one redacted turn with user text, assistant text, risk,
|
||||
cancellation/dry-run flags, weakness hints, and redaction count.
|
||||
- `session_export`: emitted when `/export-session` writes a summary file.
|
||||
- `session_end`: final turn count and timestamp.
|
||||
|
||||
`session_turn` is also registered as a memory kind. End-of-session memory writes
|
||||
are opt-in and store only redacted turn summaries through the existing memory
|
||||
port, not a new private store.
|
||||
|
||||
## Shell History Model
|
||||
|
||||
History is off by default.
|
||||
|
||||
Opt-in paths:
|
||||
|
||||
```bash
|
||||
cya shell --with-history
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```toml
|
||||
[shell_history]
|
||||
enabled = true
|
||||
limit = 50
|
||||
histfile = "~/.bash_history"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Default hard cap: 50 lines.
|
||||
- Source: `$HISTFILE`, then `.bash_history`, `.zsh_history`, or fish history.
|
||||
- Per-line provenance: source path, line number, and `shell_history.histfile`.
|
||||
- Redaction before session context or persistence: API keys, tokens, passwords,
|
||||
common provider key forms, and secret-like env assignments.
|
||||
- `/explain` shows whether history was enabled, how many lines were included,
|
||||
redaction count, and provenance.
|
||||
- One-shot `cya "..."` remains history-free by default; no collector invariant
|
||||
changes are required for one-shot mode.
|
||||
|
||||
## State Hub Boundary
|
||||
|
||||
Session start reads:
|
||||
|
||||
- `.custodian-brief.md` if present.
|
||||
- `GET /workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active`.
|
||||
- `GET /messages/?to_agent=can-you-assist&unread_only=true`.
|
||||
|
||||
Remote hub failures are non-fatal and are recorded in the session context.
|
||||
|
||||
Writes are explicit slash commands only:
|
||||
|
||||
- `/hub log "summary"` posts a progress note after confirmation.
|
||||
- `/inbox read <id>` marks one message read by explicit command.
|
||||
|
||||
No automatic State Hub writes occur on shell start, normal turns, export, or
|
||||
session close.
|
||||
|
||||
## Weakness Hints v1
|
||||
|
||||
Hints are deterministic informational panels. They never change the risk level,
|
||||
never skip confirmation, and never execute fixes.
|
||||
|
||||
Rules:
|
||||
|
||||
- `credential-routing`: secret-like topics without `warden route` guidance.
|
||||
- `ops-warden-secret-anti-pattern`: requests that imply ops-warden should vend
|
||||
API keys or passwords.
|
||||
- `remote-exec-review`: `curl`/`wget` piped to interpreters.
|
||||
- `repeated-destructive-intent`: repeated destructive or mass-edit turns.
|
||||
- `state-hub-alignment`: requested workplan id not visible in loaded hub
|
||||
summary, reminding the user that local workplan files are source of truth.
|
||||
|
||||
## End-of-Session Learning
|
||||
|
||||
On interactive close, the shell offers:
|
||||
|
||||
1. Profile 1 lesson capture using the same reflection helpers as
|
||||
`cya retrospect`.
|
||||
2. Optional redacted `session_turn` memory persistence.
|
||||
|
||||
Skipping either path writes no reflection or session-turn memory records.
|
||||
`/export-session` remains separate and always writes only a redacted JSON
|
||||
summary under the sessions directory.
|
||||
|
||||
## Gate Checklist
|
||||
|
||||
- T02 REPL skeleton: `cya shell` command, prompt loop, JSONL session file,
|
||||
`/help`, `/exit`, `/explain`, EOF/Ctrl-C handling.
|
||||
- T03 history: off by default, `--with-history`, config support, caps,
|
||||
redaction, provenance, tests.
|
||||
- T04 hub: brief + active workstreams + inbox, graceful offline behavior,
|
||||
`/hub`, `/hub log`, `/inbox`, explicit mark-read.
|
||||
- T05 orchestrator/safety: every turn uses `handle_request`; non-safe levels
|
||||
still require confirmation; `/explain` shows the full session context.
|
||||
- T06 learning/export: Profile 1 capture, `/export-session`, opt-in
|
||||
`session_turn` memory persistence.
|
||||
- T07 hints: at least three deterministic rules with tests; advisory only.
|
||||
- T08 docs/tests: README, AGENTS command reference, operator example, and
|
||||
pytest coverage.
|
||||
Reference in New Issue
Block a user