K. Hodges
a4769580b0
Added /keys and /help keys through src/keybindings.rs, wired into src/app.rs and src/repl.rs. It documents key actions and explicit slash-command fallbacks for copy, explain, discard, context, and stance without adding a premature TUI dependency.
5.9 KiB
Phase 2 Interaction Model
Phase 2 makes Exoshell behave more like an operational overlay than a generic terminal chat client.
The shell remains primary. Exoshell suggests commands, explains tradeoffs, preserves explicit context, and records transcript events. It does not execute commands.
Core Objects
User input is the operator's prompt in the REPL or a multi-line prompt collected with /multi.
Attached context is explicit, session-scoped material selected by the operator. Context comes from the Phase 1.5 context engine: notes, files, pasted command output, piped stdin, and directory summaries. Disabled context remains visible in the session but is not sent to the model.
Stance is a compact behavior fragment added to the system prompt. Supported stances are operator, audit, teach, and quiet.
Model response is provider output recorded as assistant transcript text. Exoshell may parse fenced shell blocks from the response as command suggestions.
Command suggestion is a shell fenced code block such as powershell, pwsh, sh, bash, zsh, or posix. Suggestions receive per-response IDs such as cmd-001. Exoshell can print, explain, or discard a suggestion by ID. These actions do not execute the command.
Transcript entry is a markdown record of user prompts, assistant responses, context events, budget warnings, stance changes, command suggestions, and command actions.
Model route is an optional provider decision made before a request is answered. When model routing is enabled, a fast router model chooses one configured role. The selected role, target model, and reason are recorded in the transcript.
Prompt Assembly
Prompt assembly is deterministic:
- Phase 2 system prompt with the selected shell family and stance.
- Conversation history before the current user prompt.
- Attached context rendered by the Phase 1.5 prompt context renderer.
- Current user prompt.
Context rendering preserves context IDs, types, titles, provenance, priority, and truncation metadata when present.
The context budget check uses the Phase 1.5 context budget settings. /context stats and /panel also show an approximate full prompt estimate covering the system prompt, conversation history, and attached context.
Stances
operator favors concise next steps, commands, and operational diagnosis.
audit prioritizes security, correctness, reliability, and failure modes. It asks the model to separate evidence from inference.
teach explains commands and concepts more fully while staying usable in a terminal.
quiet minimizes prose and focuses on direct output. It does not suppress safety warnings.
Configure the default stance:
[interaction]
stance = "audit"
Override it from the CLI:
cargo run -- --stance teach
Switch it during a session:
/stance audit
Command Suggestions
The model is instructed to put suggested commands in shell fenced code blocks. Exoshell parses those blocks and displays action IDs.
Example response fragment:
Inspect tracked changes first:
```sh
git status --short
```
Available actions:
/copy cmd-001
/explain cmd-001
/discard cmd-001
/copy prints the command when clipboard support is unavailable. It does not run the command.
/explain describes the shell family, original command text, model note when available, and detected risk warning.
/discard marks the suggestion as discarded in session state and records the action in the transcript.
Risk Detection
Phase 2 includes a simple non-blocking detector for obvious risky commands. The detector is policy-driven: Exoshell ships with conservative defaults, and users can add or replace rules at runtime through config.
Default rules flag patterns such as recursive forced deletion, disk formatting, recursive permission changes, downloaded content piped to an interpreter, credential exposure, and package removal.
Example custom rule:
[commands.risk]
include_defaults = true
[[commands.risk.rules]]
match_all = ["kubectl delete", "--all"]
reason = "cluster-wide deletion"
shell = "posix"
False positives are acceptable. A warning means "review this carefully," not "this command is definitely harmful." Lack of a warning does not mean a command is safe.
Session Controls
Useful commands:
/panel
/keys
/context
/context stats
/help
/help keys
/help context
/help stance
/help commands
/panel renders stance, shell family, provider/model, transcript state, context entries, and prompt estimates without requiring a TUI.
/keys documents the current line-REPL key actions and slash-command fallbacks. Advanced terminal key handling is not active yet; copy, explain, discard, context, and stance controls degrade to explicit slash commands.
Non-Goals
Phase 2 does not make Exoshell an autonomous executor.
Phase 2 does not add hidden memory. Context remains explicit and session-scoped.
Phase 2 does not perform full repository indexing. Project awareness belongs to Phase 3.
Phase 2 does not claim command suggestions are safe. It provides review language and simple detection only.
Known Limitations
Clipboard integration is not implemented. /copy prints the command.
Command parsing is intentionally simple and based on fenced blocks.
Risk detection is heuristic and incomplete.
Advanced full-screen TUI keybindings and config profiles remain planned work.
Model Routing
The configurable model router lets a fast model inspect the prompt payload and choose the model role that should answer.
Default roles:
instant qwen2.5-coder:7b
coding coder-g4-26b
heavy coder-g4-26b
conversational qwen2.5-coder:7b
Enable routing:
[router]
enabled = true
model = "qwen2.5-coder:7b"
fallback_role = "coding"
The router asks for compact JSON:
{"role":"coding","reason":"source code change request"}
If the router fails or returns an unknown role, Exoshell uses the configured fallback role and records that reason in the transcript.