Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

feat: improve prompts

Hugo Richardd24cce75686b
diff --git a/apps/chat/app/pages/chat/[id].vue b/apps/chat/app/pages/chat/[id].vue
index f719a68..8eea458 100644
--- a/apps/chat/app/pages/chat/[id].vue
+++ b/apps/chat/app/pages/chat/[id].vue
@@ -300,15 +300,10 @@ watch(() => chat.status, (newStatus, oldStatus) => {
:tool-calls="getMessageToolCalls(message)"
:is-loading="chat.status === 'streaming'"
/>
- <template v-for="(part, index) in getContentParts(message)" :key="`${message.id}-${part.type}-${index}${'state' in part ? `-${part.state}` : ''}`">
- <Reasoning
- v-if="part.type === 'reasoning'"
- :text="part.text"
- :is-streaming="part.state !== 'done'"
- />
+ <template v-for="(part, index) in getContentParts(message)" :key="`${message.id}-${part.type}-${index}`">
<!-- Markdown only for assistant (XSS prevention) -->
<MDCCached
- v-else-if="part.type === 'text' && message.role === 'assistant'"
+ v-if="part.type === 'text' && message.role === 'assistant'"
:value="part.text"
:cache-key="`${message.id}-${index}`"
:components
diff --git a/apps/chat/server/api/chats/[id].post.ts b/apps/chat/server/api/chats/[id].post.ts
index ec27fa1..3d9c299 100644
--- a/apps/chat/server/api/chats/[id].post.ts
+++ b/apps/chat/server/api/chats/[id].post.ts
@@ -161,6 +161,12 @@ export default defineEventHandler(async (event) => {
instructions: isAdminChat ? dynamicSystemPrompt : applyComplexity(dynamicSystemPrompt, routerConfig),
tools: effectiveTools,
stopWhen: stepCountIs(effectiveMaxSteps),
+ prepareStep: isAdminChat ? undefined : ({ stepNumber }) => {
+ // Remove tools on the last step to force text output
+ if (stepNumber >= effectiveMaxSteps - 1) {
+ return { activeTools: [] }
+ }
+ },
onStepFinish: (stepResult) => {
const stepDurationMs = Date.now() - stepStartTime
stepDurations.push(stepDurationMs)
diff --git a/apps/chat/server/api/sandbox/shell.post.ts b/apps/chat/server/api/sandbox/shell.post.ts
index 5bbe42e..a219b09 100644
--- a/apps/chat/server/api/sandbox/shell.post.ts
+++ b/apps/chat/server/api/sandbox/shell.post.ts
@@ -11,29 +11,73 @@ const bodySchema = z.object({
{ message: 'Provide either "command" or "commands", not both' },
)
-const BLOCKED_PATTERNS = [
- /\brm\s+-rf?\b/i,
- /\brmdir\b/i,
- /\bmkdir\b/i,
- /\btouch\b/i,
- /\bchmod\b/i,
- /\bchown\b/i,
- /\bsudo\b/i,
- /\bcurl\b/i,
- /\bwget\b/i,
- /\bnc\b/i,
- /\bssh\b/i,
- /\bgit\b/i,
- />\s*\//,
- /\bdd\b/i,
- /\bkill\b/i,
- /\bpkill\b/i,
+const ALLOWED_COMMANDS = new Set([
+ // File discovery
+ 'find',
+ 'ls',
+ 'tree',
+ // Content search
+ 'grep',
+ 'egrep',
+ 'fgrep',
+ // File reading
+ 'cat',
+ 'head',
+ 'tail',
+ 'less',
+ 'more',
+ // Text processing (output filtering)
+ 'wc',
+ 'sort',
+ 'uniq',
+ 'cut',
+ 'awk',
+ 'sed',
+ 'tr',
+ 'column',
+ // Utilities
+ 'echo',
+ 'printf',
+ 'test',
+ '[',
+ 'true',
+ 'false',
+ 'basename',
+ 'dirname',
+ 'realpath',
+ 'file',
+ 'stat',
+ 'du',
+ 'diff',
+ 'comm',
+ 'xargs',
+ 'tee',
+ // String/path helpers
+ 'md5sum',
+ 'sha256sum',
+])
+
+const BLOCKED_SHELL_PATTERNS = [
+ /\$\(/, // command substitution $(...)
+ /`[^`]+`/, // backtick substitution
+ /\beval\b/, // eval
+ /\bexec\b/, // exec
+ /\bsource\b/, // source
+ /\bbash\b/, // nested bash
+ /\bsh\b/, // nested sh
+ /\bzsh\b/, // nested zsh
+ /\benv\b/, // env (can run arbitrary commands)
+ />\s*[^\s|]/, // write redirection (> file)
+ /\bpython\b/, // interpreter
+ /\bnode\b/, // interpreter
+ /\bperl\b/, // interpreter
+ /\bruby\b/, // interpreter
]
const MAX_OUTPUT = 50000
function validateCommand(command: string): void {
- for (const pattern of BLOCKED_PATTERNS) {
+ for (const pattern of BLOCKED_SHELL_PATTERNS) {
if (pattern.test(command)) {
throw createError({
statusCode: 400,
@@ -41,6 +85,22 @@ function validateCommand(command: string): void {
})
}
}
+
+ // Split by pipe, &&, ||, ; to get individual command segments
+ const segments = command.split(/\s*(?:\|(?!\|)|\|\||&&|;)\s*/)
+ for (const segment of segments) {
+ const trimmed = segment.trim()
+ if (!trimmed) continue
+ // Extract the command name (first word, ignoring env-style VAR=val prefixes)
+ const words = trimmed.split(/\s+/)
+ const cmdName = words.find(w => !w.includes('=')) || words[0]!
+ if (!ALLOWED_COMMANDS.has(cmdName)) {
+ throw createError({
+ statusCode: 400,
+ message: `Command not allowed: ${cmdName}`,
+ })
+ }
+ }
}
function truncateOutput(output: string): string {
diff --git a/apps/chat/server/utils/bot/ai.ts b/apps/chat/server/utils/bot/ai.ts
index 217671b..a6eeff7 100644
--- a/apps/chat/server/utils/bot/ai.ts
+++ b/apps/chat/server/utils/bot/ai.ts
@@ -93,6 +93,12 @@ export async function generateAIResponse(
instructions: buildBotSystemPrompt(context, routerConfig, savoirConfig),
tools: savoir.tools,
stopWhen: stepCountIs(effectiveMaxSteps),
+ prepareStep: ({ stepNumber }) => {
+ // Remove tools on the last step to force text output
+ if (stepNumber >= effectiveMaxSteps - 1) {
+ return { activeTools: [] }
+ }
+ },
})
const result = await agent.generate({
diff --git a/apps/chat/server/utils/prompts/bot.ts b/apps/chat/server/utils/prompts/bot.ts
index defd21e..ea5b98f 100644
--- a/apps/chat/server/utils/prompts/bot.ts
+++ b/apps/chat/server/utils/prompts/bot.ts
@@ -1,31 +1,53 @@
import type { AgentConfigData } from '../agent-config'
import type { AgentConfig } from '../router/schema'
import type { ThreadContext } from '../bot/types'
-import { applyAgentConfig, applyComplexity } from './shared'
+import { applyAgentConfig, applyComplexity, applyTemporalContext } from './shared'
export const BOT_SYSTEM_PROMPT = `You are a documentation assistant with bash access to a sandbox containing docs (markdown, JSON, YAML).
+{{TEMPORAL_CONTEXT}}
## Critical Rule
-ALWAYS search AND read the relevant documentation before responding. NEVER just list files — actually read them and provide a concrete, actionable answer. Use the documentation to give the best possible answer with what you know.
+ALWAYS search AND read the relevant documentation before responding. NEVER just list files — actually read them and provide a concrete, actionable answer.
-## Sandbox Structure
-Sources: \`docs/nuxt/\`, \`docs/nuxt-content/\`, \`docs/nuxt-ui/\`, \`docs/nuxt-hub/\`, \`docs/nuxt-image/\`, \`docs/nuxt-studio/\`
+## Fast Search Strategy
+
+Use the fastest command for each task:
+
+| Task | Command | Why fast |
+|------|---------|----------|
+| Find files by content | \`grep -rl "keyword" docs/ --include="*.md" \\| head -5\` | \`-l\` stops at first match per file |
+| Find files by name | \`find docs/ -name "*routing*" -name "*.md"\` | Filesystem-level, no content read |
+| Read file (partial) | \`head -100 docs/path/file.md\` | Stops after N lines |
+| Read file (full) | \`cat docs/path/file.md\` | When you need everything |
+| Search with context | \`grep -n -C3 "keyword" docs/path/file.md\` | Line numbers + surrounding lines |
+| Directory overview | \`find docs/ -maxdepth 2 -type d\` | Fast tree view |
## Workflow
-1. Search for relevant files: \`grep -rl "term" docs/ --include="*.md" | head -5\`
-2. Read the most relevant ones: \`cat docs/path/to/file.md | head -80\`
-3. Synthesize the information into a clear, complete answer with code examples
-Chain commands with \`&&\` when possible. 2-3 well-targeted commands is better than 10 exploratory ones.
+1. **Search**: \`grep -rl "term" docs/ --include="*.md" | head -5\`
+2. **Read** (use \`bash_batch\` for parallel reads): \`head -80 docs/path/file.md\`
+3. **Synthesize**: Provide a clear answer with code examples
+
+Chain with \`&&\` when sequential. Use \`bash_batch\` for independent reads.
+2–3 targeted commands beats 10 exploratory ones.
+
+**ALWAYS provide a text answer.** If you run out of relevant search results, answer with what you have. Never end on a tool call without a final response.
+
+## Good vs Bad Responses
+
+**Good**: Search → read relevant files → concrete answer with code example from the docs.
+**Bad**: List directories → list subdirectories → read one file → vague summary without code.
## Response Style
- Be concise and helpful
+- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.
+- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.
- Include code examples from the documentation
- Try to give a direct answer`
export function buildBotSystemPrompt(context?: ThreadContext, agentConfig?: AgentConfig, savoirConfig?: AgentConfigData | null): string {
- let prompt: string = BOT_SYSTEM_PROMPT
+ let prompt: string = applyTemporalContext(BOT_SYSTEM_PROMPT)
if (savoirConfig) {
prompt = applyAgentConfig(prompt, savoirConfig)
diff --git a/apps/chat/server/utils/prompts/chat.ts b/apps/chat/server/utils/prompts/chat.ts
index 717446d..0c50bd5 100644
--- a/apps/chat/server/utils/prompts/chat.ts
+++ b/apps/chat/server/utils/prompts/chat.ts
@@ -1,5 +1,5 @@
import type { AgentConfigData } from '../agent-config'
-import { applyAgentConfig } from './shared'
+import { applyAgentConfig, applyTemporalContext } from './shared'
export const ADMIN_SYSTEM_PROMPT = `You are an admin assistant for the Savoir application. You help administrators understand app usage, monitor performance, manage users, and debug issues.
@@ -26,46 +26,85 @@ You have access to admin tools that query the application's internal data:
- Be concise but thorough in your analysis.
`
-export const BASE_SYSTEM_PROMPT = `You are an AI assistant that answers questions based on the available sources.
+export const BASE_SYSTEM_PROMPT = `You are an AI assistant that answers questions using documentation available in a sandbox.
+{{TEMPORAL_CONTEXT}}
## CRITICAL: Sources First
-Your knowledge may be outdated. ONLY answer based on what you find in the sources.
+Your training data may be outdated. ONLY answer based on what you find in the sources.
- If you can't find information, say "I couldn't find this in the available sources"
-- NEVER make up information or guess - only state what you found
-- Always cite the source file when quoting content
+- NEVER make up information or guess — only state what you found
+- Always cite the source file path when quoting content
-## Search Strategy
+## Fast Search Strategy
-1. **Explore first** (use relative paths, NEVER recursive):
- \`\`\`bash
- ls docs/ # List available sources (NOT ls -R)
- ls docs/nitro/ # Explore one source
- \`\`\`
+Use the fastest command for each task. Minimize tool calls — batch when possible.
-2. **Search with grep** (always limit results):
- \`\`\`bash
- grep -r "keyword" docs/nitro --include="*.md" -l | head -5
- \`\`\`
+### 1. Discover structure (once per session)
+\`\`\`bash
+find docs/ -maxdepth 2 -type d
+\`\`\`
-3. **Read files with cat**:
- \`\`\`bash
- cat docs/nitro/file.md
- \`\`\`
+### 2. Find files by content (fastest: grep -rl stops at first match per file)
+\`\`\`bash
+grep -rl "keyword" docs/ --include="*.md" | head -10
+\`\`\`
-## IMPORTANT
+### 3. Find files by name
+\`\`\`bash
+find docs/ -name "*routing*" -name "*.md"
+\`\`\`
-- Do NOT output text between tool calls. Use tools silently, then provide your complete answer only at the end.
-- Use "| head -N" to limit output
+### 4. Read files
+\`\`\`bash
+head -100 docs/path/file.md # partial read (fast)
+cat docs/path/file.md # full read when needed
+\`\`\`
+
+### 5. Search with context (line numbers + surrounding lines)
+\`\`\`bash
+grep -n -C3 "keyword" docs/path/file.md
+\`\`\`
+
+## Batch Commands
+
+Use \`bash_batch\` to run multiple reads in parallel when you need several files:
+\`\`\`
+["head -80 docs/nuxt/1.getting-started/1.introduction.md", "head -80 docs/nuxt/1.getting-started/2.installation.md"]
+\`\`\`
+
+## Good vs Bad Examples
+
+**Good** — 2 calls, fast:
+1. \`grep -rl "useAsyncData" docs/nuxt --include="*.md" | head -5\`
+2. \`bash_batch\`: read the top results with \`head -80\`
+
+**Bad** — slow, wasteful:
+1. \`ls docs/\`
+2. \`ls docs/nuxt/\`
+3. \`ls docs/nuxt/1.getting-started/\`
+4. \`cat docs/nuxt/1.getting-started/1.introduction.md\`
+5. \`cat docs/nuxt/1.getting-started/2.installation.md\`
+
+## Rules
+
+- **ALWAYS provide a text answer.** If you run out of relevant search results, answer with what you have. Never end on a tool call without a final response.
+- Do NOT output text between tool calls. Search silently, then provide your complete answer at the end.
+- Use \`| head -N\` to limit output from search commands.
+- Chain commands with \`&&\` when sequential: \`grep -rl "term" docs/ --include="*.md" | head -5 && cat docs/path/file.md\`
+- Prefer \`grep -rl\` over \`grep -r\` — file paths are more useful than content dumps.
+- 2–3 targeted commands beats 10 exploratory ones.
## Response Style
- Be concise and helpful
+- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.
+- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.
- Include relevant code examples when available
- Use markdown formatting
- Cite the source file path
`
export function buildChatSystemPrompt(agentConfigData: AgentConfigData): string {
- return applyAgentConfig(BASE_SYSTEM_PROMPT, agentConfigData)
+ return applyAgentConfig(applyTemporalContext(BASE_SYSTEM_PROMPT), agentConfigData)
}
diff --git a/apps/chat/server/utils/prompts/router.ts b/apps/chat/server/utils/prompts/router.ts
index addbfb4..36b8d43 100644
--- a/apps/chat/server/utils/prompts/router.ts
+++ b/apps/chat/server/utils/prompts/router.ts
@@ -6,19 +6,22 @@ Analyze the user's question and determine the appropriate configuration for the
**trivial** (maxSteps: 4, model: gemini-2.5-flash-lite)
- Simple greetings: "Hello", "Thanks", "Hi there"
- Acknowledgments without questions
+- Examples: "Hi!", "Thank you!", "Got it"
**simple** (maxSteps: 8, model: gemini-2.5-flash-lite)
- Single concept lookups: "What is X?", "How to use Y?"
-- Direct questions with likely clear answers
+- Direct questions with likely one clear answer in one file
+- Examples: "What is useAsyncData?", "How to install Nuxt?", "What does definePageMeta do?"
**moderate** (maxSteps: 15, model: gemini-3-flash)
-- Comparisons: "Difference between X and Y?"
-- Integration questions requiring exploration
-- Questions requiring multiple searches
+- Comparisons or multi-concept questions requiring 2–5 file reads
+- Integration questions requiring exploration of multiple sources
+- Examples: "Difference between useFetch and useAsyncData?", "How to use Nuxt Content with Nuxt UI?", "How to set up authentication?"
**complex** (maxSteps: 25, model: gemini-3-flash or claude-opus-4.5)
-- Debugging scenarios
-- Architecture questions
-- Deep analysis requiring extensive research
+- Debugging scenarios describing errors or unexpected behavior
+- Architecture questions spanning multiple systems
+- Deep analysis requiring cross-referencing many files
+- Examples: "My SSR hydration is failing with this error...", "How to build a multi-tenant app with NuxtHub?", "Design a full auth flow with sessions and roles"
-Use claude-opus-4.5 only for the most complex cases requiring deep reasoning.`
+Use claude-opus-4.5 only for the most complex cases requiring deep reasoning (architecture design, multi-system debugging).`
diff --git a/apps/chat/server/utils/prompts/shared.ts b/apps/chat/server/utils/prompts/shared.ts
index f8452ba..871cc14 100644
--- a/apps/chat/server/utils/prompts/shared.ts
+++ b/apps/chat/server/utils/prompts/shared.ts
@@ -38,12 +38,35 @@ export function applyAgentConfig(basePrompt: string, config: AgentConfigData): s
}
export const COMPLEXITY_HINTS: Record<AgentConfig['complexity'], string> = {
- trivial: 'This is a simple greeting or acknowledgment. Respond briefly without searching.',
- simple: 'This is a straightforward question. Explore with `ls`, then do a targeted search.',
- moderate: 'This requires some research. Explore the sources structure first, then search within relevant directories.',
- complex: 'This is a complex question. Map out the available sources with `ls`, then systematically search relevant areas.',
+ trivial: 'Respond directly without searching.',
+ simple: `One search + one read, then answer:
+1. \`grep -rl "keyword" docs/ --include="*.md" | head -5\`
+2. \`head -100 docs/path/file.md\`
+3. **Answer immediately.**`,
+ moderate: `Search → batch read → answer:
+1. \`find docs/ -maxdepth 2 -type d\` (orient yourself)
+2. \`grep -rl "keyword" docs/relevant-source/ --include="*.md" | head -10\`
+3. \`bash_batch\`: read top 3–5 files with \`head -100\`
+4. **Answer with what you found.**`,
+ complex: `Systematic exploration, then answer:
+1. \`find docs/ -maxdepth 2 -type d\` (map the sources)
+2. Multiple targeted \`grep -rl\` searches across relevant directories
+3. \`bash_batch\`: read files in parallel, use \`grep -n -C3\` for specific sections
+4. Cross-reference sources, then **answer.**`,
}
export function applyComplexity(prompt: string, agentConfig: AgentConfig): string {
- return `${prompt}\n\n## Task Complexity: ${agentConfig.complexity}\n${COMPLEXITY_HINTS[agentConfig.complexity]}`
+ const maxToolCalls = Math.max(1, agentConfig.maxSteps - 2)
+ return `${prompt}\n\n## Step Budget
+You have **${agentConfig.maxSteps} steps** total. Each tool call = 1 step. Your final text answer = 1 step.
+**Use at most ${maxToolCalls} tool calls, then STOP and answer with what you found.** Never exhaust all steps on searching — always reserve the last step to provide your answer.
+
+## Task Complexity: ${agentConfig.complexity}
+${COMPLEXITY_HINTS[agentConfig.complexity]}`
+}
+
+export function applyTemporalContext(prompt: string): string {
+ const now = new Date()
+ const [date] = now.toISOString().split('T')
+ return prompt.replace('{{TEMPORAL_CONTEXT}}', `Current date: ${date}. Documentation may reference older or newer versions — always check what's in the sandbox.`)
}