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:

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:

~/.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:

cya shell --with-history

or:

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