can-you-assist/workplans/CYA-WP-0007-interactive-shell-session.md

---
id: CYA-WP-0007
type: workplan
title: "Interactive Shell Session: REPL, History Context, and Hub-Aware Dev-Sec-Ops Helper"
domain: agents
repo: can-you-assist
status: finished
owner: grok
topic_slug: foerster-capabilities
created: "2026-06-22"
updated: "2026-06-23"
state_hub_workstream_id: "449b820c-6a7d-4b2f-93d8-f742aba45eab"
---

# 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: done
priority: high
state_hub_task_id: "b91c7b42-5ad9-4dcd-b237-63394a0f2f52"
```

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: done
priority: high
state_hub_task_id: "6f2361af-312b-4f30-bf2d-17c0ee387d29"
```

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: done
priority: high
state_hub_task_id: "0bce247e-d829-46eb-a8b0-63848bf9dfd5"
```

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: done
priority: medium
state_hub_task_id: "dc468c7e-92a8-48fb-bb10-06cd5da72e4d"
```

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: done
priority: high
state_hub_task_id: "5e2f2775-56b2-4f23-a2a9-66c6b26dde16"
```

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: done
priority: medium
state_hub_task_id: "7ad8ae85-5ba8-40e3-9c9a-facf918f2b16"
```

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: done
priority: medium
state_hub_task_id: "fbdd4f04-76ef-4a18-8c40-b41a134a743b"
```

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: done
priority: high
state_hub_task_id: "3bed6582-a11e-462a-843a-271c842b0103"
```

- `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: done
priority: low
state_hub_task_id: "3c932e69-ee0a-4135-be11-f890da09509d"
```

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.

## Completion Note - 2026-06-23

Implemented in this repo by Codex. Delivered `cya shell` with local JSONL
session artifacts, optional capped/redacted shell history, State Hub orientation
and explicit hub slash-command writes, `/explain`, `/export-session`, end-session
Profile 1 learning hooks, opt-in `session_turn` memory persistence, deterministic
weakness hints, docs, and tests.

Verification:

```bash
make test
python3 -m cya.cli.main --offline hello
python3 -m cya.cli.main shell --help
git diff --check
```

Operator follow-up: after this workplan file change, run from `~/state-hub`:

```bash
make fix-consistency REPO=can-you-assist
```