//! Context system — system prompt composition. //! //! Assembles what the model actually sees, layer by layer: //! 1. Base harness prompt (the persona, then the always-on charters: honesty, communication, //! engineering standards, memory, working discipline) //! 2. Environment (cwd, OS, shell, git status) //! 3. Tool guidance (what a per-tool schema can't say — not an index) //! 4. AGENTS.md (global + project, nearest-wins order) //! 5. Skills index (when skills are discovered) //! //! Durable project documents are NOT injected — they are pointed at. `AGENTS.md` is the one file //! that rides in every request; a plan or a spec is something the agent opens when the work calls //! for it (repo-as-memory). //! //! The prompt is the same in every mode. A mode changes what the session may do, held at dispatch //! and told to the model in the transcript (`luxe_core::mode`), so switching never moves the prefix. use serde::{Deserialize, Serialize}; use std::path::PathBuf; /// Tools the always-on charters name by name. /// /// A prompt that tells the model to reach for a tool the request does not carry is worse than /// silent: it spends the instruction *and* buys a failed call. Every name in the harness therefore /// has to be either always shipped or emitted conditionally, and this list is what the test holds /// the two sides to. #[cfg(test)] const HARNESS_TOOLS: &[&str] = &["question", "todo"]; /// Where questions about Luxe itself are answered: its own guide, built into the binary and run /// through `bash`. Static text, so the prompt stays byte-identical between turns; without it, a /// model asked how to configure Luxe answers from what other harnesses do. const LUXE_DOCS: &str = " Questions about Luxe itself are answered by its guide: `luxe docs`."; /// Purpose-built tools paired with the shell command a model reaches for instead. /// /// The prompt only names the pairs whose tool is actually callable, so a deny-listed or /// not-yet-activated tool is never advertised. /// /// The two spellings of `sed` are both here on purpose, because they are two different habits with /// two different answers and only one of them was ever named. Across 44,000 logged shell calls, /// `sed -n 'N,Mp'` — a line range, which is `read`'s `offset`/`limit` — outnumbered `sed -i` by six /// to one and was the single largest un-steered case in the corpus. /// /// Writing is named in both its shell spellings for the same reason: left to itself a model batches /// a heredoc, three `sed -i`s and the test run into one call, which saves round-trips and skips /// everything that follows a tool edit. const SHELL_ALTERNATIVES: &[(&str, &str)] = &[ ("read", "cat and sed -n"), ("glob", "find"), ("grep", "rg"), ("write", "heredocs and cat >"), ("edit", "sed -i and >> appends"), ("git", "raw git and gh"), ("test", "the test runner"), ]; /// Prompt context — what the builder needs to assemble the system prompt. #[derive(Debug, Clone)] pub struct PromptContext { /// Current working directory. pub cwd: PathBuf, /// Operating system (e.g., "linux", "macos"). pub os: String, /// Shell (e.g., "bash", "zsh"). pub shell: String, /// Git branch and dirty status, if available. pub git: Option, /// AGENTS.md content (global + project, in order). pub agents_md: Vec, /// Names of the tools the model can call this turn. pub tools: Vec, /// Skills documentation lines. pub skills: Vec, } /// Git status information. #[derive(Debug, Clone)] pub struct GitStatus { /// Current branch name. pub branch: String, } /// Which layer of the system prompt a measured section came from. /// /// The report groups by *lever*, not by heading: everything a user cannot change without changing /// the product is [`PromptSection::Harness`], and the three layers they can change get their own /// name. Ordering is display order. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub(crate) enum PromptSection { /// Role, communication, standards, memory, discipline, environment, tool guidance. Harness, /// The `AGENTS.md` chain. Instructions, /// The discoverable skill index. Skills, /// The deferred-tool catalog, present only under lazy tools. DeferredTools, /// The one-time resume briefing, appended after everything cacheable. Appended, } /// One assembled section and the layer it belongs to. #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct MeasuredSection { pub(crate) section: PromptSection, /// The assembled text, exactly as it reaches the joined prompt. pub(crate) text: String, /// Whether every session of this build and role gets the same text, as opposed to one about /// this project, directory or session. The shared sections come first, so a provider that /// caches by explicit breakpoint can end one there and share it across sessions. pub(crate) shared: bool, } /// The system prompt builder — assembles the layered prompt. pub struct SystemPromptBuilder; impl Default for SystemPromptBuilder { fn default() -> Self { Self::new() } } impl SystemPromptBuilder { /// Create a new system prompt builder. pub fn new() -> Self { Self } /// Build the complete system prompt from the given context. pub fn build(&self, ctx: &PromptContext) -> String { join_sections(&self.build_measured(ctx)) } /// [`Self::build`], keeping each section and the layer it came from. /// /// The same assembly, so the two cannot drift: `build` is this joined. Section boundaries are /// lost the moment the prompt becomes one string, and re-finding them by scanning for `## ` /// would put the contract in the heading text — where a copy-edit could silently move a /// category's worth of tokens from one row of `/context` to another. pub(crate) fn build_measured(&self, ctx: &PromptContext) -> Vec { let mut sections = Vec::new(); let mut push = |section: PromptSection, text: String, shared: bool| { if !text.is_empty() { sections.push(MeasuredSection { section, text, shared }); } }; // What every session shares first, what is about this one after. A new session — a // worktree, another project, a second agent — then reads the harness from the provider's // cache instead of writing it again because a directory name sat in the middle of it. push(PromptSection::Harness, self.build_base_harness(ctx), true); push(PromptSection::Harness, self.build_tool_docs(ctx), true); if !ctx.agents_md.is_empty() { push(PromptSection::Instructions, self.build_agents_md(ctx), false); } if !ctx.skills.is_empty() { push(PromptSection::Skills, self.build_skills(ctx), false); } push(PromptSection::Harness, self.build_environment(ctx), false); sections } /// Build the base harness prompt. fn build_base_harness(&self, ctx: &PromptContext) -> String { let mut sections = Vec::new(); sections.push(format!("## Role\n{DEFAULT_ROLE}")); // Honesty first among the charters: how much a reader has to read is a comfort problem, // and whether what they read is true is not sections.push(HONESTY.to_string()); // Reading is the one thing a user does on every turn, and a model's default register is // long and dense. `LUXE_SKIP_COMM` drops the section, for measuring what it costs. if std::env::var("LUXE_SKIP_COMM").is_err() { sections.push(COMMUNICATION.to_string()); } // Numbers rather than adjectives: "small functions" is advice a model agrees with and then // reads its own way, while "4–20 lines" is checkable while writing. The edit hook holds // the size limits too, so a file that grows past one is said so at the time. sections.push(ENGINEERING_STANDARDS.to_string()); // "Write a test" is an instruction a model already follows, and following only that is // what produces suites that are large, green, and hollow sections.push(TESTING.to_string()); sections.push(memory_section(ctx)); sections.push(plans_section()); // The commit paragraph is the cheap half of that rule: the permission engine is what holds // it (`git`/`bash` commit default to `ask`), and this keeps the prompt from firing at all. // The same pairing for root, which the engine denies. sections.push(WORKING_DISCIPLINE.to_string()); sections.join("\n\n") } /// Build the environment section. fn build_environment(&self, ctx: &PromptContext) -> String { let mut parts = Vec::new(); parts.push(format!("**cwd**: `{}`", ctx.cwd.display())); parts.push(format!("**OS**: {}", ctx.os)); parts.push(format!("**shell**: {}", ctx.shell)); // Branch only — never the dirty flag. It flips on the agent's own first edit, and this // section sits inside the prefix every provider caches, so a flip re-bills the whole // prompt. `git status` answers the question on demand, exactly. if let Some(ref git) = ctx.git { parts.push(format!("**git**: {}", git.branch)); } format!("## Environment\n{}", parts.join(" | ")) } /// Build the tool-guidance section. /// /// Deliberately **not** an index: every callable tool already ships in the request with its /// own name, description, and JSON schema, so re-listing them costs tokens on every turn and /// says nothing — and on the wrap-up call, where tools are withheld, it would advertise tools /// that aren't there. What survives is the one thing a per-tool schema structurally cannot /// express: which tool to reach for when `bash` would also work. fn build_tool_docs(&self, ctx: &PromptContext) -> String { let has = |name: &str| ctx.tools.iter().any(|tool| tool == name); if !has("bash") { return String::new(); } let pairs: Vec = SHELL_ALTERNATIVES .iter() .filter(|(tool, _)| has(tool)) .map(|(tool, shell)| format!("- `{tool}` over {shell}")) .collect(); if pairs.is_empty() { return String::new(); } format!( "## Tools\n\ Every tool in Luxe is designed to beat the shell command it replaces by providing \ structured, bounded output for a fraction of the context. They also make your actions \ easier for the user to read, which improves clarity and efficiency. So, always reach \ for the purpose-built tool before `bash`, which should be reserved for everything they \ don't cover. When you do use it, give each call a short `description` of what it does \ so the user can follow along.\n{}{}", pairs.join("\n"), if has("edit") || has("write") { "\nFiles change through `edit` and `write`, never the shell, even when one `bash` \ call could do several steps at once: an `edit` is formatted, checked for \ diagnostics, tracked for review, and easier for the user to read. A heredoc is \ none of those." } else { "" } ) } /// Build the AGENTS.md section. fn build_agents_md(&self, ctx: &PromptContext) -> String { let content = ctx.agents_md.join("\n\n"); format!("## Agent Instructions\n{}", content) } /// Build the skills section: a bulleted index plus how to load a skill's full instructions. fn build_skills(&self, ctx: &PromptContext) -> String { format!( "## Skills\n{}\nLoad a skill's full instructions on demand with \ `skill({{ \"action\": \"load\", \"name\": \"...\" }})` before doing matching work.", ctx.skills.join("\n") ) } } /// Joins measured sections into the prompt exactly as it goes on the wire. /// /// The separator is load-bearing: the cached prefix is compared byte for byte between turns, so /// this is the one place the joining is written down. pub(crate) fn join_sections(sections: &[MeasuredSection]) -> String { sections.iter().map(|section| section.text.as_str()).collect::>().join("\n\n") } /// Bytes at the start of [`join_sections`]' output that are the leading run of shared sections, /// separator included, so what follows begins at a heading. pub(crate) fn shared_len(sections: &[MeasuredSection]) -> usize { let run = sections.iter().take_while(|section| section.shared).count(); if run == 0 { return 0; } let text: usize = sections[..run].iter().map(|section| section.text.len()).sum(); // a separator after each, the last one only when something follows it text + 2 * (run - 1) + if run < sections.len() { 2 } else { 0 } } /// The `## Memory` section: the repository as what outlives the conversation, and where to ask /// about Luxe itself when the agent can run `luxe docs`. fn memory_section(ctx: &PromptContext) -> String { let docs = if ctx.tools.iter().any(|tool| tool == "bash") { LUXE_DOCS } else { "" }; format!( "## Memory\n\ The repository is your durable memory. Commit messages, comments, and context files create \ a historic record of progress that persists across context windows and chat sessions. Use \ them. Anything worth keeping beyond this turn, such as a plan for a large effort, a notable \ finding, or a hand-off, should be saved as a file in the repo where the next reader will \ find it.{docs}" ) } /// The `## Plans` section: the live `todo` checklist. /// /// `LUXE_TODO_PROMPT` swaps the guidance for a named variant, so a change to this wording can be /// measured against the alternatives rather than argued about. Unset means the shipped wording. fn plans_section() -> String { let rules = match std::env::var("LUXE_TODO_PROMPT").unwrap_or_default().as_str() { // Cost-framed wording: two "do NOT"s and no reason to reach for one. "restrictive" => { "The `todo` tool is a live checklist for a *genuinely multi-step* effort (several \ distinct actions). Create it once, keep exactly one item in_progress, and update it \ only when a real step finishes. Do NOT open a todo for a single edit or a trivial fix, \ and do NOT emit a `todo` call after every action." } // Claude Code / OpenCode wording, verbatim in spirit. "aggressive" => { "Use the `todo` tool VERY frequently to track your tasks and give the user visibility \ into your progress. It is EXTREMELY helpful for planning and for breaking large tasks \ into smaller steps. If you do not use this tool when planning, you may forget to do \ important tasks, and that is unacceptable. Mark todos completed as soon as they are \ done; keep exactly one item in_progress." } _ => PLANS, }; format!("## Plans\n{rules}") } /// Who the agent is, in every session and every mode. pub(crate) const DEFAULT_ROLE: &str = "You are an agentic engineering assistant operating in Luxe, a coding \ agent harness. Build features incrementally with small, safe diffs, and verify them before calling \ the work done."; /// The always-on honesty contract. Each rule names a failure shape rather than asking for a /// disposition: "be accurate" is advice a model agrees with and then breaks. const HONESTY: &str = "## Honesty You are trusted for your knowledge, expertise, and accuracy. Use the tools at your disposal to \ gather evidence and confirm the facts. Be honest about what you know and what you don't. - **Never present a guess as a fact.** Simply state when you're unsure, or go look to find out. - **\"I don't know\", and what would settle it, is a complete answer.** An invented answer, even a \ plausible one, is a worse failure than admitting the gap. - **Never report work you didn't do.** A test you didn't run didn't pass. - **Correct yourself out loud.** The moment you notice an earlier statement was wrong, briefly say \ so and carry on. This keeps the user updated along the way."; /// How to talk to the person on the other end. const COMMUNICATION: &str = "## Communication You think and act much faster than the user is able to read, let alone understand. Every output \ should earn its place in the transcript by concisely conveying information that is worth the cost \ of the user's time and effort to read. - **Answer first.** Lead with the answer, then the why, then caveats. Never open by restating the \ question or by announcing what you are about to say. - **Cut filler.** No \"Great question\", no \"Certainly\", no \"I'll now…\". The user can already see \ tool calls and diffs, so don't restate them. - **Use plain, straightforward language.** Keep things simple and avoid technical jargon. \ \"Invariant\" takes longer to understand than \"something that doesn't change\". Shorter outputs \ don't beat simpler ones. - **Write like a human.** Don't use em dashes. Use contractions and keep it casual. Conveying information quickly and clearly is more important than using proper \ grammar or terminology. - **One question at a time.** You can ask the user for input via the `question` tool. Start with a \ single question and two or three distinct options, mark the one you recommend, and give each \ option a one-line reason. Wait for their answer before asking the next thing. - **Report finished work in a couple of lines.** What changed, what you checked, and what you left."; /// Code-quality rules, as numbers a model can check while writing. const ENGINEERING_STANDARDS: &str = "## Engineering standards In addition to following good coding habits, the following standards are optimized for how you \ interact with the code. Shorter files and functions are faster and cheaper to `read`. Unique names \ limit `grep` results, and descriptive errors help solve problems faster. So, unless the project's \ own conventions say otherwise: - Keep functions from 4–20 lines and split them if longer. - Files should be 500 lines or less. When they grow longer, split them by responsibility. - Use early returns instead of nested `if`s, with at most 2 levels of indentation. - Comments should say *why*, never *what*. - Use specific names and types: no `data`, `handler`, or `Manager`. - Errors should be detailed and never swallowed. - Luxe features specialized tools to read, write, and debug code. Use them."; /// What makes a test worth having. const TESTING: &str = "## Testing Tests are extremely valuable, but only when used thoughtfully and consistently. New behavior gets \ a test; a bug fix gets a regression test, and every test should actually be able to fail. - **Prove the fix.** Run the new test against the *unfixed* code and watch it fail first. - **Name the break a test catches.** Before writing an assertion, say which change should make it \ fail. If you can't, you're just describing code, not testing it. - **One case per branch.** An input that trips every condition at once proves none of them. Give \ each condition its own case, and cover what must *not* match."; /// Shipped `todo` guidance. const PLANS: &str = "The `todo` tool is your plan, and the only insight the user has into what it \ entails or whether it even exists. Always open one before you start any work spanning three or \ more steps. If the user hands you a list of tasks, pass every item at once as `subjects` in a \ single call, then begin working on the list. Mark each item completed the moment it's done, and \ add new items along the way as needed. Creating a plan and maintaining it keeps the user informed \ and the work focused."; /// How to go about a change, and who owns it once it is made. const WORKING_DISCIPLINE: &str = "## Working discipline You should understand a change before you make it. Read the code it touches and trace the flow \ for every place the change has to reach. Then reach for the simplest thing that works: reuse \ what's already in the codebase; use the standard library; use a native platform feature; use an \ existing dependency. Ship the smallest diff that fully solves the task. Verify before you report. \ Finishing a change is not committing it. Leave the work in the working tree unless you were \ explicitly asked for a commit; simply report that the work is done and let the user decide. Some \ commands are the user's to run, such as `sudo`, passwords, etc. To facilitate, you can give them \ the exact command in a fenced code block to run in their own terminal and continue once they say \ it's done."; #[cfg(test)] mod tests;