use crate::db::repository::feedback_ledger::FeedbackLedgerRepository;
use std::path::PathBuf;
const CORE_BRAIN_FILES: &[(&str, &str)] =
&[("SOUL.md", "personality"), ("USER.md", "user profile")];
pub(crate) const CONTEXTUAL_BRAIN_FILES: &[(&str, &str)] = &[
("IDENTITY.md", "identity — social/cron replies only"),
("AGENTS.md", "workspace rules"),
("CODE.md", "coding standards"),
("TOOLS.md", "tool notes & config"),
("SECURITY.md", "security policies"),
("MEMORY.md", "long-term memory"),
("BOOT.md", "startup config"),
("BOOTSTRAP.md", "bootstrap config"),
("HEARTBEAT.md", "heartbeat config"),
];
const BRAIN_FILES: &[(&str, &str)] = &[
("SOUL.md", "personality"),
("USER.md", "user"),
("AGENTS.md", "agents"),
("SECURITY.md", "security"),
("MEMORY.md", "memory"),
("BOOT.md", "boot"),
("BOOTSTRAP.md", "bootstrap"),
("HEARTBEAT.md", "heartbeat"),
];
pub(crate) const BRAIN_PREAMBLE: &str = r#"You are OpenCrabs, an AI orchestration agent with powerful tools to help with software development tasks.
IMPORTANT: You have access to tools for file operations and code exploration. USE THEM PROACTIVELY!
TOOL CALL PROTOCOL — CRITICAL:
- Always call tools directly — never write code yourself, never describe what you plan to do. Just call the tool immediately.
- Do NOT output markdown code blocks (```bash, ```sh, ```python, etc.) — invoke the `bash` / `python` tool instead. Code blocks are TEXT, the system will NOT execute them.
- WRONG: writing ```bash\ngit status\n``` or "Let me run `git log`" — nothing runs.
- RIGHT: emit a tool_call for `bash` with {"command": "git status"} via the structured tool-call API.
- NEVER claim to have run a command, read a file, or fetched a URL when you haven't actually invoked the corresponding tool. If you need work done, call the tool. If you can't, say so.
- Thinking/reasoning is fine, but the final action MUST be either a tool_call or a direct answer — not a code block pretending to be one, not a narration of what you'd do.
- NEVER emit IDE-style inline edit formats. These look like agent tool calls but are NOT — they were trained into you by Cursor / Aider / Cline / continue.dev datasets and don't work here. Specifically forbidden patterns:
```lang|CODE_EDIT_BLOCK|/abs/path/file.ext ← Cursor-style
```search_and_replace
<<<<<<< SEARCH ... ======= ... >>>>>>> REPLACE ← Aider conflict-marker style
```diff with file headers ← unified-diff dumps
To edit a file: call the `edit_file` tool (or `write_file` for new files) with the structured tool-call API. If the file is large, read it first via `read_file`, then call `edit_file` with the precise `old_text` / `new_text`. The system will REJECT any inline-edit format and the change will NOT apply — you will have just leaked the file contents to the channel.
CRITICAL RULE: After calling tools and getting results, you MUST provide a final text response to the user.
DO NOT keep calling tools in a loop. Call the necessary tools, get results, then respond with text.
When asked to analyze or explore a codebase:
1. Use 'ls' tool with recursive=true to list all directories and files
2. Use 'glob' tool with patterns like "**/*.rs", "**/*.toml", "**/*.md" to find files
3. Use 'grep' tool to search for patterns, functions, or keywords in code
4. Use 'read_file' tool to read specific files you've identified
5. Use 'bash' tool for git operations like: git log, git diff, git branch
When asked to make changes:
1. Use 'read_file' first to understand the current code
2. Use 'edit_file' to modify existing files
3. Use 'write_file' to create new files
4. Use 'bash' to run tests or build commands
Available tools and their REQUIRED parameters (use exact parameter names):
- ls: List directory contents. Params: path (string), recursive (bool)
- glob: Find files matching patterns. Params: pattern (string, REQUIRED — e.g. "**/*.rs")
- grep: Search for text in files. Params: pattern (string, REQUIRED — the search text), path (string), regex (bool), case_insensitive (bool), file_pattern (string), limit (int), context (int)
- read_file: Read file contents. Params: path (string, REQUIRED)
- edit_file: Modify existing files. Params: path (string, REQUIRED), operation (string, REQUIRED)
- write_file: Create new files. Params: path (string, REQUIRED), content (string, REQUIRED)
- bash: Run shell commands. Params: command (string, REQUIRED)
- execute_code: Test code snippets. Params: language (string, REQUIRED), code (string, REQUIRED)
- web_search: Search the internet. Params: query (string, REQUIRED)
- http_request: Call external APIs. Params: method (string, REQUIRED), url (string, REQUIRED)
- task_manager: Track multi-step work. Params: operation (string, REQUIRED)
- session_context: Remember important facts. Params: operation (string, REQUIRED)
- session_search: Search across sessions. Params: operation (string, REQUIRED — "search" or "list"), query (string), n (int)
- plan: Create structured plans. Params: operation (string, REQUIRED)
CRITICAL: PLAN TOOL USAGE
When a user says "create a plan", "make a plan", or describes a complex multi-step task, you MUST use the plan tool immediately.
DO NOT write a text description of a plan. DO NOT explain what should be done. CALL THE TOOL.
Mandatory steps for plan creation:
1. IMMEDIATELY call plan tool with operation='create' to create a new plan
2. Call plan tool with operation='add_task' for each task (call multiple times)
- IMPORTANT: The 'description' field MUST contain detailed implementation steps
- Include: specific files to create/modify, functions to implement, commands to run
- Format: Use numbered steps or bullet points for clarity
- Be concrete: "Create Login.jsx component with email/password form fields and validation"
NOT vague: "Create login component"
3. Call plan tool with operation='finalize' — this auto-approves the plan immediately
4. Begin executing tasks in order right away using start_task/complete_task — no waiting
NEVER generate text plans. ALWAYS use the plan tool for planning requests.
ALWAYS explore first before answering questions about a codebase. Don't guess - use the tools!
SELF-AWARENESS — CHECK WHAT YOU ALREADY HAVE BEFORE BUILDING NEW:
Before proposing to implement a feature from scratch (STT, TTS, browser automation, messaging channels, token compression, PDF rendering, etc.):
1. Check your tool list in this request — is there already a tool for this? Use it instead of bash+pip+third-party libraries.
2. Check the "Built-in features compiled into this binary" line in Runtime Info below — is the capability already baked into the OpenCrabs binary you're running? If yes, USE it; don't re-implement it.
3. Check the relevant brain file (TOOLS.md for tool usage, AGENTS.md for project conventions) before deciding the right surface.
Skipping these checks wastes the user's time, ships duplicate code, and makes the agent look unaware of its own runtime.
WEB / GITHUB / BROWSER ROUTING — pick the right surface, not the heaviest one:
- Web research, docs, "what's the latest X", "find me info about Y": use `exa_search` (if available) → `brave_search` (if available) → `web_search`. Never reach for `browser_navigate` to read pages.
- Anything on GitHub (issues, PRs, releases, comments, file contents, commits, checks, code search, workflow runs): use the `gh` CLI via `bash`. It is preinstalled, authenticated, returns structured JSON (`--json`, `--jq`), and is far cheaper than navigating github.com in a browser.
- `browser_navigate` is for: (a) the user explicitly asking you to open / interact with a page, (b) tasks that require clicking / typing / submitting / scrolling / running JS against live DOM, (c) genuine last resort after every search route has been tried and failed. It is slow, token-heavy, and steals window focus in headed mode — never the default.
RECURSIVE SELF-IMPROVEMENT:
You have three tools for improving yourself over time:
- feedback_analyze: Query your performance history (tool success rates, failure patterns, recent events). Call with query='summary' or query='tool_stats' or query='failures'.
- feedback_record: Manually log observations — user corrections, patterns you notice, strategies that work well.
- self_improve: Propose or apply changes to your brain files (SOUL.md, TOOLS.md, etc.). Runs autonomously — no human approval needed. Changes are logged to ~/.opencrabs/rsi/improvements.md and archived in ~/.opencrabs/rsi/history/.
Your tool executions are automatically tracked. When you notice recurring failures, user frustration, or repeated corrections:
1. Call feedback_analyze with query='failures' to understand what's going wrong
2. Call feedback_record to log the pattern you observed
3. Call self_improve with action='apply' to apply a concrete improvement — brain file is edited, improvement is logged to rsi/improvements.md, and a daily archive entry is created
Do NOT call these tools every turn. Use them when you notice a pattern across multiple interactions, or when a user explicitly corrects you in a way that could apply to future conversations. Report significant improvements to the TUI or connected channels so the user knows what changed."#;
pub struct BrainLoader {
workspace_path: PathBuf,
}
impl BrainLoader {
pub fn new(workspace_path: PathBuf) -> Self {
Self { workspace_path }
}
pub fn resolve_path() -> PathBuf {
crate::config::opencrabs_home()
}
pub fn load_file(&self, name: &str) -> Option<String> {
let path = self.workspace_path.join(name);
std::fs::read_to_string(&path).ok()
}
pub fn build_system_brain(
&self,
runtime_info: Option<&RuntimeInfo>,
slash_commands_section: Option<&str>,
) -> String {
let mut prompt = String::with_capacity(8192);
prompt.push_str(BRAIN_PREAMBLE);
prompt.push_str("\n\n");
for (filename, label) in BRAIN_FILES {
if let Some(content) = self.load_file(filename) {
let trimmed = content.trim();
if !trimmed.is_empty() {
prompt.push_str(&format!(
"--- {} ({}) ---\n{}\n\n",
filename, label, trimmed
));
}
}
}
if let Some(info) = runtime_info {
prompt.push_str("--- Runtime Info ---\n");
if let Some(ref model) = info.model {
prompt.push_str(&format!("Model: {}\n", model));
}
if let Some(ref provider) = info.provider {
prompt.push_str(&format!("Provider: {}\n", provider));
}
if let Some(ref wd) = info.working_directory {
prompt.push_str(&format!("Working directory: {}\n", wd));
push_home_anchor_and_expansion_rule(&mut prompt);
}
prompt.push_str(&format!("OS: {}\n", std::env::consts::OS));
prompt.push_str(&format!(
"Timestamp: {}\n",
chrono::Utc::now().format("%Y-%m-%d %H:%M:%S UTC")
));
prompt.push('\n');
}
if let Some(commands_section) = slash_commands_section
&& !commands_section.is_empty()
{
prompt.push_str("--- Available Slash Commands ---\n");
prompt.push_str(commands_section);
prompt.push_str("\n\n");
}
prompt
}
pub fn build_core_brain(
&self,
runtime_info: Option<&RuntimeInfo>,
slash_commands_section: Option<&str>,
) -> String {
let mut prompt = String::with_capacity(4096);
prompt.push_str(BRAIN_PREAMBLE);
prompt.push_str("\n\n");
for (filename, label) in CORE_BRAIN_FILES {
if let Some(content) = self.load_file(filename) {
let trimmed = content.trim();
if !trimmed.is_empty() {
prompt.push_str(&format!(
"--- {} ({}) ---\n{}\n\n",
filename, label, trimmed
));
}
}
}
let available: Vec<(&str, &str)> = CONTEXTUAL_BRAIN_FILES
.iter()
.filter(|(name, _)| self.workspace_path.join(name).exists())
.copied()
.collect();
let known: std::collections::HashSet<String> = CORE_BRAIN_FILES
.iter()
.chain(CONTEXTUAL_BRAIN_FILES.iter())
.map(|(n, _)| n.to_lowercase())
.collect();
let mut extras: Vec<String> = std::fs::read_dir(&self.workspace_path)
.ok()
.map(|entries| {
entries
.filter_map(|e| e.ok())
.filter_map(|e| {
let name = e.file_name().to_string_lossy().to_string();
(name.ends_with(".md") && !known.contains(&name.to_lowercase()))
.then_some(name)
})
.collect()
})
.unwrap_or_default();
extras.sort();
if !available.is_empty() || !extras.is_empty() {
let brain_dir = crate::brain::tools::error::collapse_home(&self.workspace_path);
prompt.push_str(&format!(
"--- Available Context Files (in {}/) ---\n",
brain_dir
));
prompt.push_str(&format!(
"Brain directory: {}/ (all files below live here)\n\
Load on demand with the `load_brain_file` tool when relevant — \
do NOT load unless the request actually needs that context. \
Use `write_opencrabs_file` to update or edit a brain file.\n\n",
brain_dir
));
for (name, desc) in &available {
prompt.push_str(&format!("- **{}**: {}\n", name, desc));
}
for name in &extras {
prompt.push_str(&format!("- **{}**: (user-created)\n", name));
}
let has = |name: &str| available.iter().any(|(n, _)| *n == name);
prompt.push_str("\nLoad proactively when:\n");
if has("USER.md") {
prompt.push_str("- User asks personal questions or preferences → load USER.md\n");
}
if has("MEMORY.md") {
prompt.push_str(
"- Starting a project session or recalling past work → load MEMORY.md\n",
);
}
if has("AGENTS.md") || has("SECURITY.md") || has("CODE.md") {
let files: Vec<&str> = ["AGENTS.md", "SECURITY.md", "CODE.md"]
.iter()
.copied()
.filter(|n| has(n))
.collect();
prompt.push_str(&format!(
"- Policy / rule / safety / coding standards check → load {}\n",
files.join(", ")
));
}
if has("TOOLS.md") {
prompt
.push_str("- Working with environment-specific tool configs → load TOOLS.md\n");
}
prompt.push('\n');
if has("MEMORY.md") {
prompt.push_str(
"Write proactively to MEMORY.md (via `write_opencrabs_file`) when:\n\
- You discover a fact, pattern, or context that would be valuable across sessions\n\
- The user corrects you on something non-obvious that isn't already in MEMORY.md\n\
- You learn project-specific knowledge (integrations, team structure, workflows)\n\
- A self-heal event fires (phantom tool call, gaslighting strip) — record what \
triggered it and the correct behavior so you avoid it next time\n\
Do NOT write ephemeral task details or anything derivable from code/git. \
Load MEMORY.md first to avoid duplicates before writing.\n\n",
);
}
}
if let Some(info) = runtime_info {
prompt.push_str("--- Runtime Info ---\n");
if let Some(ref model) = info.model {
prompt.push_str(&format!("Model: {}\n", model));
}
if let Some(ref provider) = info.provider {
prompt.push_str(&format!("Provider: {}\n", provider));
}
if let Some(ref wd) = info.working_directory {
prompt.push_str(&format!("Working directory: {}\n", wd));
push_home_anchor_and_expansion_rule(&mut prompt);
}
prompt.push_str(&format!("OS: {}\n", std::env::consts::OS));
prompt.push_str(&format!(
"Timestamp: {}\n",
chrono::Utc::now().format("%Y-%m-%d %H:%M:%S UTC")
));
push_known_paths(&mut prompt);
push_compiled_features(&mut prompt);
prompt.push('\n');
}
if let Some(commands_section) = slash_commands_section
&& !commands_section.is_empty()
{
prompt.push_str("--- Available Slash Commands ---\n");
prompt.push_str(commands_section);
prompt.push_str("\n\n");
}
prompt
}
}
pub async fn build_feedback_digest(pool: crate::db::Pool) -> Option<String> {
let repo = FeedbackLedgerRepository::new(pool);
let total = repo.total_count().await.ok()?;
if total < 10 {
return None; }
let mut out = String::from("--- Performance History ---\n");
out.push_str(&format!("Total tool executions recorded: {total}\n"));
if let Ok(stats) = repo.stats_by_dimension("tool_").await {
let mut header_written = false;
for s in stats
.iter()
.filter(|s| s.failures > 0 && s.success_rate < 0.9)
.take(5)
{
if !header_written {
out.push_str("Tools with notable failure rates:\n");
header_written = true;
}
out.push_str(&format!(
" {} — {:.0}% success ({} ok, {} fail)\n",
s.dimension,
s.success_rate * 100.0,
s.successes,
s.failures
));
}
}
if let Ok(entries) = repo.by_event_type("tool_failure", 5).await
&& !entries.is_empty()
{
out.push_str("Recent failures:\n");
for e in &entries {
let meta = e.metadata.as_deref().unwrap_or("(no details)");
let short: String = meta.chars().take(80).collect();
out.push_str(&format!(" {} — {}\n", e.dimension, short));
}
}
if let Ok(corrections) = repo.by_event_type("user_correction", 50).await
&& !corrections.is_empty()
{
out.push_str(&format!(
"User corrections recorded: {}\n",
corrections.len()
));
}
out.push_str(
"Use feedback_analyze for deeper analysis. \
If you see patterns, use self_improve to apply fixes autonomously.\n\n",
);
Some(out)
}
#[derive(Debug, Clone, Default)]
pub struct RuntimeInfo {
pub model: Option<String>,
pub provider: Option<String>,
pub working_directory: Option<String>,
}
fn push_home_anchor_and_expansion_rule(prompt: &mut String) {
if let Some(home) = dirs::home_dir().and_then(|p| p.to_str().map(String::from)) {
prompt.push_str(&format!(
"Home: {} (the '~' in paths above expands to this)\n",
home
));
}
prompt.push_str(
"Path expansion: when invoking shell tools (bash, etc.), pass `~/...` paths verbatim — \
the shell expands `~` for you. Do NOT substitute `/Users/<name>/...` yourself; if you \
need an absolute form, copy the `Home:` line above exactly.\n",
);
}
pub(crate) fn compiled_features() -> Vec<&'static str> {
let mut out = Vec::new();
if cfg!(feature = "telegram") {
out.push("telegram");
}
if cfg!(feature = "whatsapp") {
out.push("whatsapp");
}
if cfg!(feature = "discord") {
out.push("discord");
}
if cfg!(feature = "slack") {
out.push("slack");
}
if cfg!(feature = "trello") {
out.push("trello");
}
if cfg!(feature = "local-stt") {
out.push("local-stt");
}
if cfg!(feature = "local-tts") {
out.push("local-tts");
}
if cfg!(feature = "browser") {
out.push("browser");
}
if cfg!(feature = "rtk") {
out.push("rtk");
}
if cfg!(feature = "pdfium") {
out.push("pdfium");
}
if cfg!(feature = "profiling") {
out.push("profiling");
}
out
}
pub(crate) fn push_compiled_features(prompt: &mut String) {
let features = compiled_features();
if features.is_empty() {
return;
}
prompt.push_str(&format!(
"Built-in features compiled into this binary: {}\n\
Before implementing any of these capabilities from scratch, USE the built-in. \
If the user asks for a feature listed here, it already works — don't re-build it. \
If they ask for a Cargo feature NOT in this list (e.g. `pdfium`), tell them to \
rebuild with `--features <name>` instead of writing fresh code.\n",
features.join(", ")
));
}
pub(crate) fn push_known_paths(prompt: &mut String) {
prompt.push_str(
"\nKnown paths (under ~/.opencrabs/):\n\
- Logs: ~/.opencrabs/logs/opencrabs.YYYY-MM-DD (daily, today is the most relevant)\n\
- Config: ~/.opencrabs/config.toml\n\
- Keys: ~/.opencrabs/keys.toml\n\
- Brain files: ~/.opencrabs/{SOUL,USER,AGENTS,TOOLS,MEMORY,CODE}.md\n\
- Plans: ~/.opencrabs/agents/session/.opencrabs_plan_<session-id>.json\n\
When the user asks to check logs, read today's file at \
~/.opencrabs/logs/opencrabs.<today UTC date>. Do NOT grep the repo \
working directory for log files — opencrabs never writes logs there.\n",
);
}
#[cfg(test)]
#[path = "prompt_builder_tests.rs"]
mod prompt_builder_tests;
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
#[test]
fn test_build_prompt_no_files() {
let dir = TempDir::new().unwrap();
let loader = BrainLoader::new(dir.path().to_path_buf());
let prompt = loader.build_system_brain(None, None);
assert!(prompt.contains("You are OpenCrabs"));
assert!(prompt.contains("CRITICAL RULE"));
}
#[test]
fn test_build_prompt_with_soul() {
let dir = TempDir::new().unwrap();
std::fs::write(dir.path().join("SOUL.md"), "I am a helpful crab.").unwrap();
let loader = BrainLoader::new(dir.path().to_path_buf());
let prompt = loader.build_system_brain(None, None);
assert!(prompt.contains("You are OpenCrabs"));
assert!(prompt.contains("I am a helpful crab."));
assert!(prompt.contains("SOUL.md"));
}
#[test]
fn test_build_prompt_with_runtime_info() {
let dir = TempDir::new().unwrap();
let loader = BrainLoader::new(dir.path().to_path_buf());
let info = RuntimeInfo {
model: Some("claude-sonnet-4-20250514".to_string()),
provider: Some("anthropic".to_string()),
working_directory: Some("/home/user/project".to_string()),
};
let prompt = loader.build_system_brain(Some(&info), None);
assert!(prompt.contains("claude-sonnet-4-20250514"));
assert!(prompt.contains("anthropic"));
assert!(prompt.contains("/home/user/project"));
}
#[test]
fn test_skips_empty_files() {
let dir = TempDir::new().unwrap();
std::fs::write(dir.path().join("SOUL.md"), " \n ").unwrap();
let loader = BrainLoader::new(dir.path().to_path_buf());
let prompt = loader.build_system_brain(None, None);
assert!(!prompt.contains("--- SOUL.md ("));
}
}