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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CYA-WP-0007	workplan	Interactive Shell Session: REPL, History Context, and Hub-Aware Dev-Sec-Ops Helper	capabilities	can-you-assist	ready	grok	foerster-capabilities	2026-06-22	2026-06-22	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

id: CYA-WP-0007-T01
status: todo
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

id: CYA-WP-0007-T02
status: todo
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

id: CYA-WP-0007-T03
status: todo
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

id: CYA-WP-0007-T04
status: todo
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

id: CYA-WP-0007-T05
status: todo
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

id: CYA-WP-0007-T06
status: todo
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)

id: CYA-WP-0007-T07
status: todo
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

id: CYA-WP-0007-T08
status: todo
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

id: CYA-WP-0007-T09
status: todo
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.