can-you-assist/README.md

# cya — console-native assistant for local work

`cya` lets you express intent in natural language from your terminal and receive
safe, explainable, context-aware help.

It is the CLI surface for the capabilities domain. It owns orchestration,
the user experience, and the safety layer. It talks to `llm-connect` only
through a stable adapter boundary and keeps all memory under explicit
user-controlled ports (implemented by `phase-memory`).

## Status

This is the first narrow MVP slice (CYA-WP-0001). The tool is already
usable after `pip install -e .`:

- `cya "your request in plain English"`
- `cya --explain-context "..."` — shows exactly what local context would be sent
- Automatic rule-based risk classification with mandatory confirmation for anything destructive, privileged, mass-edit, or network-affecting
- All LLM interaction flows through a documented `LLMAdapter` seam (`FakeLLMAdapter` by default; real `llm-connect` when configured)

## Installation

### 1. Install from Development Head (Recommended for Daily Use)

Stay on the absolute latest code with one command:

```bash
git clone https://github.com/worsch/can-you-assist.git
cd can-you-assist
make dev-install
```

Or the direct git method (no permanent clone needed):

```bash
pip install "git+https://github.com/worsch/can-you-assist.git@main#egg=can-you-assist[dev]"
```

After installing, `cya --version` will show a development version (e.g. `0.2.0.dev48+gf500a35...`).

### 2. Install a Released Version (Future)

Once we publish official releases:

```bash
pip install can-you-assist
# or a specific version
pip install "can-you-assist>=0.3.0"
```

See `docs/release-process.md` for how releases are cut.

### Updating

```bash
cd can-you-assist
git pull
make dev-install
```

## LLM backend (configured vs offline)

By default `cya` uses a deterministic **offline** adapter (no API keys, no network).
For real inference, configure llm-connect:

```bash
# 1. Install llm-connect (sibling checkout)
pip install -e ~/llm-connect

# 2. Route credentials — do not commit keys
warden route find "OpenRouter API key" --json

# 3. Export key and configure cya
export OPENROUTER_API_KEY="..."   # from OpenBao / operator path
mkdir -p ~/.config/cya
cat > ~/.config/cya/config.toml <<'EOF'
[llm]
adapter = "connect"
backend = "openrouter"
model = "anthropic/claude-sonnet-4"
EOF

cya "show me the recent git history for this repo"
```

Force offline mode anytime (tests, CI, air-gapped):

```bash
cya --offline "your request"
# or: CYA_LLM_ADAPTER=fake cya "..."
```

See `docs/llm-connect-integration.md` for the full mapping, session context budget,
and optional `.cya.toml` project overrides.

## Usage examples

```bash
# Normal request (safe path)
cya "show me the recent git history for this repo"

# Risky request — will show classification + require explicit confirmation
cya "delete every log file older than 30 days in this tree"

# See exactly what context would be collected and sent
cya --explain-context "explain the changes in the last commit"
```

The output includes a structured suggestion, rationale, and (when relevant) a
clear preview + confirmation prompt. Nothing executes without your explicit yes.

## Interactive Shell Sessions

Start a stateful console session when you want continuity across turns:

```bash
cya shell
cya shell --offline --no-hub          # local smoke / air-gapped mode
cya shell --with-history              # opt in to capped, redacted shell history
```

Each session writes a user-owned JSONL artifact under:

```text
~/.config/cya/sessions/<session-id>.jsonl
```

Useful slash commands:

```text
/help                         show shell commands
/explain                      show last turn context, risk, history, hub, hints
/hub                          show State Hub workplans and inbox orientation
/hub log "summary"            post a progress note after confirmation
/inbox                        show unread State Hub messages
/export-session               write a redacted JSON session summary
/learn                        capture Profile 1 reflections now
/exit                         close the session
```

Shell history is off by default. `--with-history` or `[shell_history]` config
includes at most 50 recent lines from `$HISTFILE` or common shell history files,
redacts secret-like values, and exposes provenance in `/explain`. One-shot
`cya "..."` requests remain history-free by default.

Example transcript:

```text
$ cya shell --offline --no-hub
cya> summarize recent git changes
... standard orchestrator response ...
cya> /explain
... context envelope, memory, shell history status, hub summary, and hints ...
cya> /export-session
Exported session summary: ~/.config/cya/sessions/cya-...-summary.json
cya> /exit
Session saved: ~/.config/cya/sessions/cya-...jsonl
```

State Hub writes never happen automatically. `/hub log` and `/inbox read` are
explicit operator actions; `/hub log` also asks for confirmation.

See `docs/cya-interactive-shell-session-design.md` and
`docs/cya-shell-operator-session.md` for the full design and operator example.

## Safety (core product behavior)

- Genuine rule-based assessment is the primary mechanism.
- Results are available to the model.
- Anything above "safe" produces a preview and blocks until you confirm in the
  launching terminal.
- No autonomous execution in this slice.

See the risk classifier tests and workplan T03 for the exact rules and invariants.

## Memory (T02 + T03 + T04 + 0003)

`cya` has real, user-controlled, context-aware memory that improves over time.

### Automatic Directory/Project-Bound Activation (T03)

Memory scoped to a directory or project is automatically activated when you work there.

```bash
# In your project directory, teach cya your preferences once
cya "remember that I always want the short git status with branch info"

# Later, in the same directory (or any subdirectory), cya will use it automatically
cya "show me the recent changes"

# No need to restate your preference — it is activated based on the working directory
```

See exactly what memory influenced a response:
```bash
cya --explain-context "show me the recent changes"
```

### Structured Retrospection & Continuous Improvement (T04)

Run a guided reflection session to review how memory was used and explicitly set goals for future interactions.

```bash
cya retrospect
```

During the session `cya` will:
- Show recent memory items that were activated.
- Help you reflect on what worked or didn't.
- Let you record new **interaction goals** (e.g. "be more concise", "always show one safe alternative for destructive commands").
- Optionally capture **1–3 verbal lessons** (Profile 1) with guided prompts, preview, and confirmation.

Example Profile 1 flow at the end of `cya retrospect`:

```
Capture 1–3 verbal lessons from this session? (y/n) y
What went well that you want to remember? (or 'skip') Safety warnings were clear
What should cya remember for next time? (or 'skip') Always suggest git status first
What should cya avoid in this scope? (or 'skip') skip

Preview — verbal lessons to save
1. [went well] Safety warnings were clear
2. [remember] Always suggest git status first

Save these lessons? (y/n) y
Saved 2 verbal reflection(s) (Profile 1).
```

These goals and lessons are stored as first-class memory and will influence future activations and responses.

### Inspecting and Controlling Memory

All memory is stored in plain, user-editable JSON:
```bash
~/.config/cya/memory/<scope>.json
```

Useful commands:
```bash
cya --explain-context "..."     # See exactly what memory was activated and why
cya memory reflections            # List verbal reflections for the current scope
cya memory reflections --json     # Export reflections as JSON
# (You can also use the memory ports directly in Python if you want to script it.)
```

Memory also feeds the safety layer: a "never auto-run" preference you set during retrospection will still force mandatory confirmation.

### Architecture Notes
- Memory lives behind explicit ports in `src/cya/memory/__init__.py`.
- Activation is automatic based on cwd + git root (with full provenance).
- Retrospection outcomes are stored with special kinds (`retrospection`, `interaction_goal`) and get preferential treatment in future context building.
- Everything is designed to be replaced/enriched by a full `phase-memory` implementation later (see MemoryVision.md).
- **Profile 0** (post-0003 local JSON + activation + retrospection loop) is the stable foundation.
- **Profile 1** (verbal reflections) is production-ready as of CYA-WP-0006: guided capture in `cya retrospect`, `cya memory reflections`, compaction, and surfacing in responses / `--explain-context`.
- Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap items — see MemoryVision.md.

See:
- `docs/cya-memory-activation-and-retrospection-concept.md` (the T01 design)
- `workplans/CYA-WP-0003-...md`
- `src/cya/memory/__init__.py`
- `MemoryVision.md` for the long-term phase-memory vision

All memory usage is visible, explainable, and under your control. Nothing is hidden or opaque.

## Architecture & boundaries (important)

- `can-you-assist` (this repo): CLI, context collection, safety, orchestration.
- `llm-connect`: Provider access, config, token counting, structured responses.
  All interaction goes through `cya/llm/adapter.py` (`LLMAdapter` Protocol).
- `phase-memory`: Durable, user-controlled memory. Real (persisting) implementation
  lives behind the explicit ports in `cya/memory/__init__.py` (T02). Signals also flow
  into the rule-based risk layer (T04).

See `workplans/CYA-WP-0001-console-native-mvp.md` for the full task breakdown,
decisions, and integration guide.

## Development

```bash
# Recommended one-liner (see Installation section above)
make dev-install
pip install -e ~/llm-connect   # optional, for live inference

pytest tests/ -q               # offline mocks only; no API keys
pytest -m llm_live             # manual live check (requires OPENROUTER_API_KEY)
cya --offline "..."            # manual verification without network
make version   # show current dev version
```

## License

MIT (see LICENSE).

## Workplan & coordination

- Workplan: `workplans/CYA-WP-0001-console-native-mvp.md`
- State Hub workplan: `repo-integration-can-you-assist`
- Operator reminder after changes: `cd ~/state-hub && make fix-consistency REPO=can-you-assist`