can-you-assist/docs/cya-interactive-shell-session-design.md

# 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.