coyote/docs/restful-api/testing/plans/09-repl-commands.md

Test Plan: REPL Commands

Feature description

The REPL processes dot-commands (.role, .session, .agent, etc.) and plain text (chat messages). Each command has state assertions (e.g., .info role requires an active role).

Behaviors to test

Command parsing

• Dot-commands parsed correctly (command + args)
• Multi-line input (:::) handled (regex)
• Plain text treated as chat message (parse_command returns None)
• Empty input ignored (parse_command returns None)

State assertions (REPL_COMMANDS array)

• Each command's assert_state enforced correctly
• Invalid state → command rejected (via is_valid)
• Commands with AssertState::pass() always available

Command handlers (each one)

• .help — prints help text
• .info [subcommand] — displays appropriate info
• .model — switches model
• .prompt — sets temp role
• .role [text] — enters role or one-shot
• .session [name] — starts/resumes session
• .agent [session] [key=value] — starts agent
• .rag [name] — initializes RAG
• .starter [n] — lists or executes conversation starter
• .set — updates setting
• .delete — deletes item
• .exit [type] — exits scope or REPL
• .save role/session [name] — saves to file
• .edit role/session/config/agent-config/rag-docs — opens editor
• .empty session — clears session
• .compress session — compresses session
• .rebuild rag — rebuilds RAG
• .sources rag — shows RAG sources
• .copy — copies last response
• .continue — continues response
• .regenerate — regenerates response
• .file [-- text] — includes files
• .macro [text] — runs/creates macro
• .authenticate — OAuth flow
• .vault [name] — vault operations
• .clear todo — clears agent todo

ask function (chat flow)

• Input constructed from text
• Embeddings applied if RAG active
• Waits for compression to complete
• before_chat_completion called
• Streaming vs non-streaming based on config
• Tool results loop (recursive ask with merged results)
• after_chat_completion called
• Auto-continuation for agents with todos

Additional behaviors tested (not in original plan)

• AssertState::pass() always returns true (all flag combos)
• AssertState::bare() only matches empty flags
• AssertState::True requires any matching flag present
• AssertState::True with multiple flags — any match suffices
• AssertState::False requires all specified flags absent
• AssertState::False with multiple flags
• AssertState::TrueFalse — true present AND false absent
• AssertState::Equal — exact flag match
• REPL_COMMANDS has exactly 39 entries
• All commands start with '.'
• All commands have non-empty descriptions
• .help, .exit always available (pass)
• .info role requires ROLE
• .session blocked when already in session
• .exit session requires session
• .exit agent requires agent
• .agent only when bare (no role/session/agent)
• .role blocked in session/agent
• .prompt blocked in session/agent
• .rag blocked in agent
• .starter requires agent
• .clear todo requires agent
• .edit role requires ROLE, blocked in SESSION
• .exit rag requires RAG, blocked in AGENT
• split_first_arg: None, single word, two words, extra spaces
• parse_command: plain text, empty, whitespace, dot only
• ReplCommand::is_valid with pass/True/False
• Multiline regex: captures content, rejects unclosed, rejects plain text

Old code reference

• src/repl/mod.rs — run_repl_command, ask, REPL_COMMANDS