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: bash tool improvements and compaction

Hugo Richardc8ab2490f4f8
diff --git a/apps/chat/app/composables/useModels.ts b/apps/chat/app/composables/useModels.ts
index fb0693e..d262da5 100644
--- a/apps/chat/app/composables/useModels.ts
+++ b/apps/chat/app/composables/useModels.ts
@@ -16,11 +16,11 @@ export function formatModelName(modelId: string): string {
export function useModels() {
const models = [
'google/gemini-3-flash',
- 'anthropic/claude-sonnet-4.5',
+ 'anthropic/claude-sonnet-4.6',
'anthropic/claude-opus-4.6',
]
- const model = useCookie<string>('model', { default: () => 'anthropic/claude-sonnet-4.5' })
+ const model = useCookie<string>('model', { default: () => 'anthropic/claude-sonnet-4.6' })
return {
models,
diff --git a/apps/chat/package.json b/apps/chat/package.json
index 89c4979..2c1a382 100644
--- a/apps/chat/package.json
+++ b/apps/chat/package.json
@@ -8,6 +8,7 @@
"preview": "nuxt preview",
"postinstall": "nuxt prepare",
"typecheck": "nuxt typecheck",
+ "test": "bun test",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"db:generate": "nuxt db generate",
@@ -35,6 +36,7 @@
"@octokit/auth-app": "^8.2.0",
"@octokit/rest": "^22.0.1",
"@onmax/nuxt-better-auth": "0.0.2-alpha.21",
+ "@savoir/sdk": "workspace:*",
"@shelve/cli": "^4.1.7",
"@upstash/redis": "^1.36.2",
"@vercel/analytics": "^1.6.1",
diff --git a/apps/chat/server/api/chats/[id].post.ts b/apps/chat/server/api/chats/[id].post.ts
index f6ac145..33147e6 100644
--- a/apps/chat/server/api/chats/[id].post.ts
+++ b/apps/chat/server/api/chats/[id].post.ts
@@ -1,4 +1,4 @@
-import { convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse, streamText, type UIMessage } from 'ai'
+import { convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse, type UIMessage } from 'ai'
import { z } from 'zod'
import { db, schema } from '@nuxthub/db'
import { kv } from '@nuxthub/kv'
@@ -11,7 +11,8 @@ import { KV_KEYS } from '../../utils/sandbox/types'
import { adminTools } from '../../utils/chat/admin-tools'
import { ADMIN_SYSTEM_PROMPT, buildChatSystemPrompt } from '../../utils/prompts/chat'
import { applyComplexity } from '../../utils/prompts/shared'
-import { createAgent, type RoutingResult } from '../../utils/create-agent'
+import { createAgent } from '../../utils/agent/create-agent'
+import type { RoutingResult } from '../../utils/agent/types'
defineRouteMeta({
openAPI: {
@@ -308,27 +309,10 @@ export default defineEventHandler(async (event) => {
const result = await agent.stream({
messages: await convertToModelMessages(messages),
+ options: {},
abortSignal: abortController.signal,
})
writer.merge(result.toUIMessageStream())
-
- // Fallback: if the agent exhausted all steps on tool calls without
- // producing any text, do one final call with NO tools to force a response.
- const agentText = await result.text
- if (!agentText?.trim()) {
- log.info('chat', `[${requestId}] Agent produced no text, forcing fallback response`)
- const agentResponse = await result.response
- const convertedMessages = await convertToModelMessages(messages)
- const fallback = streamText({
- model: effectiveModel,
- messages: [
- ...convertedMessages,
- ...agentResponse.messages,
- ],
- abortSignal: abortController.signal,
- })
- writer.merge(fallback.toUIMessageStream())
- }
},
onFinish: async ({ messages: responseMessages }) => {
const dbStartTime = Date.now()
diff --git a/apps/chat/server/api/sandbox/shell.post.ts b/apps/chat/server/api/sandbox/shell.post.ts
index a219b09..083f5f6 100644
--- a/apps/chat/server/api/sandbox/shell.post.ts
+++ b/apps/chat/server/api/sandbox/shell.post.ts
@@ -1,5 +1,6 @@
import { z } from 'zod'
import { useLogger } from 'evlog'
+import { validateShellCommand } from '@savoir/sdk'
import { getOrCreateSandbox } from '../../utils/sandbox/manager'
const bodySchema = z.object({
@@ -11,95 +12,17 @@ const bodySchema = z.object({
{ message: 'Provide either "command" or "commands", not both' },
)
-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_SHELL_PATTERNS) {
- if (pattern.test(command)) {
- throw createError({
- statusCode: 400,
- message: `Command contains blocked pattern: ${command.slice(0, 50)}`,
- })
- }
- }
-
- // 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}`,
- })
- }
+ const validation = validateShellCommand(command, {
+ allowedBaseDirectory: '/vercel/sandbox',
+ })
+ if (!validation.ok) {
+ throw createError({
+ statusCode: 400,
+ message: validation.reason,
+ })
}
}
diff --git a/apps/chat/server/utils/agent/README.md b/apps/chat/server/utils/agent/README.md
new file mode 100644
index 0000000..2cae317
--- /dev/null
+++ b/apps/chat/server/utils/agent/README.md
@@ -0,0 +1,12 @@
+# Agent Utilities Structure
+
+This directory groups the server-side agent orchestration logic by responsibility:
+
+- `create-agent.ts` - `ToolLoopAgent` assembly and lifecycle hooks (`prepareCall`, `prepareStep`)
+- `context-management.ts` - context compaction logic (`compactContext`)
+- `step-policy.ts` - step budgeting and tool-loop guardrails (`shouldForceTextOnlyStep`)
+- `sanitize.ts` - message sanitation before model calls (`sanitizeToolCallInputs`)
+- `schemas.ts` - Zod schemas for call options
+- `types.ts` - shared types for routing and agent execution context
+
+This is the canonical server agent module layout (no legacy compatibility layer).
diff --git a/apps/chat/server/utils/agent/context-management.ts b/apps/chat/server/utils/agent/context-management.ts
new file mode 100644
index 0000000..c927348
--- /dev/null
+++ b/apps/chat/server/utils/agent/context-management.ts
@@ -0,0 +1,61 @@
+import { pruneMessages, type StepResult, type ToolSet } from 'ai'
+import type { ModelMessage } from '@ai-sdk/provider-utils'
+
+export function compactContext({
+ messages,
+ steps,
+ tokenThreshold = 40_000,
+ minTrimSavings = 20_000,
+ protectLastUserMessages = 3,
+}: {
+ messages: ModelMessage[]
+ steps: StepResult<ToolSet>[]
+ tokenThreshold?: number
+ minTrimSavings?: number
+ protectLastUserMessages?: number
+}): ModelMessage[] {
+ if (messages.length === 0) return messages
+
+ const lastStep = steps[steps.length - 1]
+ const currentTokens = lastStep?.usage?.inputTokens ?? 0
+ if (currentTokens <= tokenThreshold) return messages
+
+ let cutoffIndex = 0
+ let seenUsers = 0
+ for (let i = messages.length - 1; i >= 0; i--) {
+ if (messages[i]?.role === 'user') {
+ seenUsers++
+ if (seenUsers >= protectLastUserMessages) {
+ cutoffIndex = i
+ break
+ }
+ }
+ }
+
+ if (cutoffIndex === 0) return messages
+
+ let toolChars = 0
+ for (let i = 0; i < cutoffIndex; i++) {
+ const message = messages[i]
+ if (!Array.isArray(message?.content)) continue
+ for (const part of message.content) {
+ if (part.type === 'tool-call' || part.type === 'tool-result') {
+ toolChars += JSON.stringify(part).length
+ }
+ }
+ }
+
+ const estimatedSavings = Math.ceil(toolChars / 4)
+ if (estimatedSavings < minTrimSavings) return messages
+
+ const messagesToProtect = messages.length - cutoffIndex
+ const toolCallsOption = messagesToProtect === 0
+ ? 'all'
+ : (`before-last-${messagesToProtect}-messages` as const)
+
+ return pruneMessages({
+ messages,
+ toolCalls: toolCallsOption,
+ emptyMessages: 'remove',
+ })
+}
diff --git a/apps/chat/server/utils/agent/create-agent.test.ts b/apps/chat/server/utils/agent/create-agent.test.ts
new file mode 100644
index 0000000..96ae05c
--- /dev/null
+++ b/apps/chat/server/utils/agent/create-agent.test.ts
@@ -0,0 +1,83 @@
+// @ts-expect-error bun test types are runtime-provided in this workspace
+import { describe, expect, test } from 'bun:test'
+import { compactContext } from './context-management'
+import { shouldForceTextOnlyStep } from './step-policy'
+
+describe('compactContext', () => {
+ test('keeps context unchanged when token usage is low', () => {
+ const messages = [
+ { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+ { role: 'assistant', content: [{ type: 'text', text: 'hi' }] },
+ ] as any
+
+ const result = compactContext({
+ messages,
+ steps: [{ usage: { inputTokens: 1000 } }] as any,
+ })
+
+ expect(result).toBe(messages)
+ })
+
+ test('prunes old tool calls when token usage is high', () => {
+ const messages = [
+ { role: 'user', content: [{ type: 'text', text: 'first' }] },
+ {
+ role: 'assistant',
+ content: [
+ { type: 'tool-call', toolName: 'bash', input: { command: 'ls -la' }, toolCallId: '1' },
+ ],
+ },
+ {
+ role: 'tool',
+ content: [
+ { type: 'tool-result', toolName: 'bash', output: 'x'.repeat(120_000), toolCallId: '1' },
+ ],
+ },
+ { role: 'user', content: [{ type: 'text', text: 'second' }] },
+ { role: 'assistant', content: [{ type: 'text', text: 'done' }] },
+ ] as any
+
+ const result = compactContext({
+ messages,
+ steps: [{ usage: { inputTokens: 60_000 } }] as any,
+ protectLastUserMessages: 1,
+ minTrimSavings: 1000,
+ })
+
+ expect(result.length).toBeLessThanOrEqual(messages.length)
+ })
+})
+
+describe('shouldForceTextOnlyStep', () => {
+ test('forces text-only on last two steps', () => {
+ expect(shouldForceTextOnlyStep({
+ stepNumber: 8,
+ maxSteps: 10,
+ steps: [],
+ } as any)).toBe(true)
+ expect(shouldForceTextOnlyStep({
+ stepNumber: 9,
+ maxSteps: 10,
+ steps: [],
+ } as any)).toBe(true)
+ })
+
+ test('forces text-only on long tool streak after midpoint', () => {
+ const toolSteps = Array.from({ length: 4 }, () => ({ toolCalls: [{ toolName: 'bash' }] }))
+ const shouldForce = shouldForceTextOnlyStep({
+ stepNumber: 7,
+ maxSteps: 10,
+ steps: toolSteps as any,
+ })
+ expect(shouldForce).toBe(true)
+ })
+
+ test('keeps tools available early in loop', () => {
+ const shouldForce = shouldForceTextOnlyStep({
+ stepNumber: 2,
+ maxSteps: 10,
+ steps: [{ toolCalls: [{ toolName: 'bash' }] }] as any,
+ })
+ expect(shouldForce).toBe(false)
+ })
+})
diff --git a/apps/chat/server/utils/agent/create-agent.ts b/apps/chat/server/utils/agent/create-agent.ts
new file mode 100644
index 0000000..7082e03
--- /dev/null
+++ b/apps/chat/server/utils/agent/create-agent.ts
@@ -0,0 +1,121 @@
+import { stepCountIs, ToolLoopAgent, type StepResult, type ToolSet } from 'ai'
+import { log } from 'evlog'
+import { DEFAULT_MODEL } from '../router/schema'
+import { getAgentConfig } from '../agent-config'
+import { compactContext } from './context-management'
+import { callOptionsSchema } from './schemas'
+import { sanitizeToolCallInputs } from './sanitize'
+import { countConsecutiveToolSteps, shouldForceTextOnlyStep } from './step-policy'
+import type { AgentCallOptions, AgentExecutionContext, CreateAgentOptions } from './types'
+
+export function createAgent({
+ tools,
+ route,
+ buildPrompt,
+ resolveModel,
+ admin,
+ onRouted,
+ onStepFinish,
+ onFinish,
+}: CreateAgentOptions) {
+ let isAdminMode = false
+ let maxSteps = 15
+
+ return new ToolLoopAgent({
+ model: DEFAULT_MODEL,
+ callOptionsSchema,
+ prepareCall: async ({ options, ...settings }) => {
+ const modelOverride = (options as AgentCallOptions | undefined)?.model
+ const customContext = (options as AgentCallOptions | undefined)?.context
+
+ if (admin) {
+ isAdminMode = true
+ maxSteps = admin.maxSteps ?? 15
+ const effectiveModel = modelOverride ?? DEFAULT_MODEL
+ const executionContext: AgentExecutionContext = {
+ mode: 'admin',
+ effectiveModel,
+ maxSteps,
+ customContext,
+ }
+ return {
+ ...settings,
+ model: effectiveModel,
+ instructions: admin.systemPrompt,
+ tools: admin.tools,
+ stopWhen: stepCountIs(maxSteps),
+ experimental_context: executionContext,
+ }
+ }
+
+ isAdminMode = false
+
+ const [routerConfig, agentConfig] = await Promise.all([
+ route(),
+ getAgentConfig(),
+ ])
+
+ const effectiveMaxSteps = Math.round(routerConfig.maxSteps * agentConfig.maxStepsMultiplier)
+ const routedModel = resolveModel?.(routerConfig, agentConfig)
+ ?? agentConfig.defaultModel
+ ?? DEFAULT_MODEL
+ const effectiveModel = modelOverride ?? routedModel
+
+ maxSteps = effectiveMaxSteps
+ onRouted?.({ routerConfig, agentConfig, effectiveModel, effectiveMaxSteps })
+
+ const executionContext: AgentExecutionContext = {
+ mode: 'chat',
+ effectiveModel,
+ maxSteps: effectiveMaxSteps,
+ routerConfig,
+ agentConfig,
+ customContext,
+ }
+
+ return {
+ ...settings,
+ model: effectiveModel,
+ instructions: buildPrompt(routerConfig, agentConfig),
+ tools,
+ stopWhen: stepCountIs(effectiveMaxSteps),
+ experimental_context: executionContext,
+ }
+ },
+ prepareStep: ({ stepNumber, messages, steps }) => {
+ sanitizeToolCallInputs(messages)
+ const normalizedSteps = (steps as StepResult<ToolSet>[] | undefined) ?? []
+ const compactedMessages = compactContext({
+ messages,
+ steps: normalizedSteps,
+ })
+
+ if (isAdminMode) {
+ if (compactedMessages !== messages) {
+ return { messages: compactedMessages }
+ }
+ return
+ }
+
+ // Prevent tool-only endings: reserve end of loop for synthesis.
+ if (shouldForceTextOnlyStep({ stepNumber, maxSteps, steps: normalizedSteps })) {
+ log.info(
+ 'agent',
+ `Forcing text-only step at ${stepNumber + 1}/${maxSteps} (tool streak=${countConsecutiveToolSteps(normalizedSteps)})`,
+ )
+ return {
+ tools: {},
+ toolChoice: 'none' as const,
+ activeTools: [],
+ ...(compactedMessages !== messages ? { messages: compactedMessages } : {}),
+ }
+ }
+
+ if (compactedMessages !== messages) {
+ return { messages: compactedMessages }
+ }
+ },
+ onStepFinish,
+ onFinish,
+ })
+}
diff --git a/apps/chat/server/utils/agent/sanitize.ts b/apps/chat/server/utils/agent/sanitize.ts
new file mode 100644
index 0000000..5d9c9c2
--- /dev/null
+++ b/apps/chat/server/utils/agent/sanitize.ts
@@ -0,0 +1,24 @@
+import { log } from 'evlog'
+import type { ModelMessage } from '@ai-sdk/provider-utils'
+
+/**
+ * Ensure all tool-call `input` fields in messages are valid JSON objects.
+ * The Anthropic API rejects requests where `input` is a string instead of an object.
+ * This can happen when the AI SDK carries forward a raw JSON string from a previous step.
+ */
+export function sanitizeToolCallInputs(messages: ModelMessage[]): ModelMessage[] {
+ for (const message of messages) {
+ if (message.role !== 'assistant' || !Array.isArray(message.content)) continue
+ for (const part of message.content) {
+ if (part.type === 'tool-call' && typeof part.input === 'string') {
+ log.warn('agent', `Sanitizing tool-call input for ${part.toolName}: input was a string, parsing to object`)
+ try {
+ part.input = JSON.parse(part.input)
+ } catch {
+ part.input = {}
+ }
+ }
+ }
+ }
+ return messages
+}
diff --git a/apps/chat/server/utils/agent/schemas.ts b/apps/chat/server/utils/agent/schemas.ts
new file mode 100644
index 0000000..16af33b
--- /dev/null
+++ b/apps/chat/server/utils/agent/schemas.ts
@@ -0,0 +1,6 @@
+import { z } from 'zod'
+
+export const callOptionsSchema = z.object({
+ model: z.string().optional(),
+ context: z.record(z.string(), z.unknown()).optional(),
+})
diff --git a/apps/chat/server/utils/agent/step-policy.ts b/apps/chat/server/utils/agent/step-policy.ts
new file mode 100644
index 0000000..8d5b385
--- /dev/null
+++ b/apps/chat/server/utils/agent/step-policy.ts
@@ -0,0 +1,36 @@
+import type { StepResult, ToolSet } from 'ai'
+
+export function countConsecutiveToolSteps(steps: StepResult<ToolSet>[]): number {
+ let streak = 0
+ for (let i = steps.length - 1; i >= 0; i--) {
+ const step = steps[i]
+ if (!step) break
+ if (step.toolCalls && step.toolCalls.length > 0) {
+ streak++
+ continue
+ }
+ break
+ }
+ return streak
+}
+
+export function shouldForceTextOnlyStep({
+ stepNumber,
+ maxSteps,
+ steps,
+}: {
+ stepNumber: number
+ maxSteps: number
+ steps: StepResult<ToolSet>[]
+}): boolean {
+ // Always reserve the last 2 steps for final user-facing output.
+ if (stepNumber >= maxSteps - 2) return true
+
+ const toolStreak = countConsecutiveToolSteps(steps)
+ const pastMidpoint = stepNumber >= Math.max(3, Math.floor(maxSteps * 0.6))
+
+ // If the model is stuck in a tool-only streak deep in the loop, force synthesis.
+ if (pastMidpoint && toolStreak >= 4) return true
+
+ return false
+}
diff --git a/apps/chat/server/utils/agent/types.ts b/apps/chat/server/utils/agent/types.ts
new file mode 100644
index 0000000..98226cc
--- /dev/null
+++ b/apps/chat/server/utils/agent/types.ts
@@ -0,0 +1,36 @@
+import type { z } from 'zod'
+import type { AgentConfig } from '../router/schema'
+import type { AgentConfigData } from '../agent-config'
+
+export interface RoutingResult {
+ routerConfig: AgentConfig
+ agentConfig: AgentConfigData
+ effectiveModel: string
+ effectiveMaxSteps: number
+}
+
+export interface AgentExecutionContext {
+ mode: 'admin' | 'chat'
+ effectiveModel: string
+ maxSteps: number
+ routerConfig?: AgentConfig
+ agentConfig?: AgentConfigData
+ customContext?: Record<string, unknown>
+}
+
+export interface CreateAgentOptions {
+ tools: Record<string, any>
+ route: () => Promise<AgentConfig>
+ buildPrompt: (routerConfig: AgentConfig, agentConfig: AgentConfigData) => string
+ resolveModel?: (routerConfig: AgentConfig, agentConfig: AgentConfigData) => string
+ admin?: {
+ tools: Record<string, any>
+ systemPrompt: string
+ maxSteps?: number
+ }
+ onRouted?: (result: RoutingResult) => void
+ onStepFinish?: (stepResult: any) => void
+ onFinish?: (result: any) => void
+}
+
+export type AgentCallOptions = z.infer<typeof import('./schemas').callOptionsSchema>
diff --git a/apps/chat/server/utils/bot/ai.ts b/apps/chat/server/utils/bot/ai.ts
index fe5e209..387c563 100644
--- a/apps/chat/server/utils/bot/ai.ts
+++ b/apps/chat/server/utils/bot/ai.ts
@@ -3,7 +3,7 @@ import { log } from 'evlog'
import { type AgentConfig, agentConfigSchema, DEFAULT_MODEL, getDefaultConfig, ROUTER_MODEL } from '../router/schema'
import { ROUTER_SYSTEM_PROMPT } from '../prompts/router'
import { buildBotSystemPrompt, buildBotUserMessage } from '../prompts/bot'
-import { createAgent } from '../create-agent'
+import { createAgent } from '../agent/create-agent'
import { createInternalSavoir } from './savoir'
import type { ThreadContext } from './types'
@@ -81,6 +81,7 @@ export async function generateAIResponse(
const result = await agent.generate({
prompt: buildBotUserMessage(question, context),
+ options: {},
})
const durationMs = Date.now() - startTime
diff --git a/apps/chat/server/utils/create-agent.ts b/apps/chat/server/utils/create-agent.ts
deleted file mode 100644
index e1afa2a..0000000
--- a/apps/chat/server/utils/create-agent.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-import { stepCountIs, ToolLoopAgent } from 'ai'
-import type { ModelMessage } from '@ai-sdk/provider-utils'
-import { log } from 'evlog'
-import type { AgentConfig } from './router/schema'
-import { DEFAULT_MODEL } from './router/schema'
-import type { AgentConfigData } from './agent-config'
-import { getAgentConfig } from './agent-config'
-
-/**
- * Ensure all tool-call `input` fields in messages are valid JSON objects.
- * The Anthropic API rejects requests where `input` is a string instead of an object.
- * This can happen when the AI SDK carries forward a raw JSON string from a previous step.
- */
-function sanitizeToolCallInputs(messages: ModelMessage[]): ModelMessage[] {
- for (const message of messages) {
- if (message.role !== 'assistant' || !Array.isArray(message.content)) continue
- for (const part of message.content) {
- if (part.type === 'tool-call' && typeof part.input === 'string') {
- log.warn('agent', `Sanitizing tool-call input for ${part.toolName}: input was a string, parsing to object`)
- try {
- part.input = JSON.parse(part.input)
- } catch {
- part.input = {}
- }
- }
- }
- }
- return messages
-}
-
-export interface RoutingResult {
- routerConfig: AgentConfig
- agentConfig: AgentConfigData
- effectiveModel: string
- effectiveMaxSteps: number
-}
-
-interface CreateAgentOptions {
- tools: Record<string, any>
- route: () => Promise<AgentConfig>
- buildPrompt: (routerConfig: AgentConfig, agentConfig: AgentConfigData) => string
- resolveModel?: (routerConfig: AgentConfig, agentConfig: AgentConfigData) => string
- admin?: {
- tools: Record<string, any>
- systemPrompt: string
- maxSteps?: number
- }
- onRouted?: (result: RoutingResult) => void
- onStepFinish?: (stepResult: any) => void
- onFinish?: (result: any) => void
-}
-
-export function createAgent({
- tools,
- route,
- buildPrompt,
- resolveModel,
- admin,
- onRouted,
- onStepFinish,
- onFinish,
-}: CreateAgentOptions) {
- let isAdminMode = false
- let maxSteps = 15
-
- return new ToolLoopAgent({
- model: DEFAULT_MODEL,
- prepareCall: async ({ ...settings }) => {
- if (admin) {
- isAdminMode = true
- maxSteps = admin.maxSteps ?? 15
- return {
- ...settings,
- instructions: admin.systemPrompt,
- tools: admin.tools,
- stopWhen: stepCountIs(maxSteps),
- }
- }
-
- isAdminMode = false
-
- const [routerConfig, agentConfig] = await Promise.all([
- route(),
- getAgentConfig(),
- ])
-
- const effectiveMaxSteps = Math.round(routerConfig.maxSteps * agentConfig.maxStepsMultiplier)
- const effectiveModel = resolveModel?.(routerConfig, agentConfig)
- ?? agentConfig.defaultModel
- ?? DEFAULT_MODEL
-
- maxSteps = effectiveMaxSteps
-
- onRouted?.({ routerConfig, agentConfig, effectiveModel, effectiveMaxSteps })
-
- return {
- ...settings,
- model: effectiveModel,
- instructions: buildPrompt(routerConfig, agentConfig),
- tools,
- stopWhen: stepCountIs(effectiveMaxSteps),
- }
- },
- prepareStep: ({ stepNumber, messages }) => {
- sanitizeToolCallInputs(messages)
-
- if (isAdminMode) return
- // Force text output on the last step by removing all tools
- if (stepNumber >= maxSteps - 1) {
- return { toolChoice: 'none' as const, activeTools: [] }
- }
- },
- onStepFinish,
- onFinish,
- })
-}
diff --git a/apps/chat/server/utils/prompts/chat.ts b/apps/chat/server/utils/prompts/chat.ts
index 98b82e7..88d9a07 100644
--- a/apps/chat/server/utils/prompts/chat.ts
+++ b/apps/chat/server/utils/prompts/chat.ts
@@ -92,6 +92,10 @@ bash_batch: [
- **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.
+- Keep tool usage bounded: after a few tool calls, switch to synthesis and answer with the best available evidence.
+- Do not chase exhaustive search near the step limit. Prioritize delivering a clear final answer.
+- Never answer with placeholder text like "Done", "Finished", or "Complete". Provide a real answer or explicitly state what is missing.
+- If a tool fails, adapt once with a different command. Do not repeat the same failing command in a loop.
- Use \`| head -N\` on all search output to keep context small.
- Use \`grep -rlE "term1\\|term2"\` for multi-keyword search in one command.
- Prefer \`grep -rl\` over \`grep -r\` — file paths are more useful than content dumps.
diff --git a/apps/chat/server/utils/prompts/router.ts b/apps/chat/server/utils/prompts/router.ts
index cca7fe6..6eb24e7 100644
--- a/apps/chat/server/utils/prompts/router.ts
+++ b/apps/chat/server/utils/prompts/router.ts
@@ -13,7 +13,7 @@ Analyze the user's question and determine the appropriate configuration for the
- 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: claude-sonnet-4.5)
+**moderate** (maxSteps: 15, model: claude-sonnet-4.6)
- 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?"
diff --git a/apps/chat/server/utils/router/schema.ts b/apps/chat/server/utils/router/schema.ts
index 4b9e377..950726e 100644
--- a/apps/chat/server/utils/router/schema.ts
+++ b/apps/chat/server/utils/router/schema.ts
@@ -12,7 +12,7 @@ export const agentConfigSchema = z.object({
model: z.enum([
'google/gemini-3-flash',
- 'anthropic/claude-sonnet-4.5',
+ 'anthropic/claude-sonnet-4.6',
'anthropic/claude-opus-4.6',
]).describe('flash for trivial/simple, sonnet for moderate, opus for complex'),
@@ -26,7 +26,7 @@ export function getDefaultConfig(): AgentConfig {
return {
complexity: 'moderate',
maxSteps: 15,
- model: 'anthropic/claude-sonnet-4.5',
+ model: 'anthropic/claude-sonnet-4.6',
reasoning: 'Default fallback configuration',
}
}
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 6f203c0..ceebc4d 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -40,6 +40,7 @@
"build": "tsdown",
"dev": "tsdown --watch",
"typecheck": "tsc --noEmit",
+ "test": "bun test",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"prepublishOnly": "bun run build"
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index e8d5979..78e9049 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -2,6 +2,8 @@ import { SavoirClient } from './client'
import { createBashBatchTool, createBashTool } from './tools'
import type { AgentConfig, GenerateResult, ReportUsageOptions, SavoirConfig } from './types'
+export { ALLOWED_BASH_COMMANDS, BLOCKED_SHELL_PATTERNS, isPathWithinDirectory, pathMatchesGlob, validateShellCommand } from './shell-policy'
+
export type { SavoirConfig, ShellResponse, ShellBatchResponse, ShellCommandResult, SyncOptions, SyncResponse, SnapshotResponse, GitHubSource, YouTubeSource, SourcesResponse, SyncSourceResponse, ToolCallInfo, ToolCallCallback, ToolCallState, ToolExecutionResult, CommandResult, AgentConfig, GenerateResult, ReportUsageOptions } from './types'
export { SavoirError, NetworkError } from './errors'
export { SavoirClient } from './client'
diff --git a/packages/sdk/src/shell-policy.test.ts b/packages/sdk/src/shell-policy.test.ts
new file mode 100644
index 0000000..8770ae6
--- /dev/null
+++ b/packages/sdk/src/shell-policy.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test'
+import { isPathWithinDirectory, pathMatchesGlob, validateShellCommand } from './shell-policy'
+
+describe('validateShellCommand', () => {
+ test('accepts allowed command', () => {
+ const result = validateShellCommand('ls -la docs/')
+ expect(result).toEqual({ ok: true })
+ })
+
+ test('rejects blocked shell pattern', () => {
+ const result = validateShellCommand('ls $(pwd)')
+ expect(result.ok).toBe(false)
+ })
+
+ test('rejects disallowed command', () => {
+ const result = validateShellCommand('curl https://example.com')
+ expect(result).toEqual({
+ ok: false,
+ reason: 'Command not allowed: curl',
+ })
+ })
+
+ test('rejects absolute path outside sandbox', () => {
+ const result = validateShellCommand('cat /etc/passwd', {
+ allowedBaseDirectory: '/vercel/sandbox',
+ })
+ expect(result).toEqual({
+ ok: false,
+ reason: 'Path outside sandbox is not allowed: /etc/passwd',
+ })
+ })
+})
+
+describe('path utils', () => {
+ test('isPathWithinDirectory works for nested path', () => {
+ expect(isPathWithinDirectory('/vercel/sandbox/docs/file.md', '/vercel/sandbox')).toBe(true)
+ expect(isPathWithinDirectory('/etc/passwd', '/vercel/sandbox')).toBe(false)
+ })
+
+ test('pathMatchesGlob matches recursive patterns', () => {
+ expect(pathMatchesGlob('/vercel/sandbox/docs/a/b.md', 'docs/**', '/vercel/sandbox')).toBe(true)
+ expect(pathMatchesGlob('/vercel/sandbox/src/index.ts', 'docs/**', '/vercel/sandbox')).toBe(false)
+ })
+})
diff --git a/packages/sdk/src/shell-policy.ts b/packages/sdk/src/shell-policy.ts
new file mode 100644
index 0000000..decadc5
--- /dev/null
+++ b/packages/sdk/src/shell-policy.ts
@@ -0,0 +1,175 @@
+import path from 'node:path'
+
+export const ALLOWED_BASH_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',
+])
+
+export 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
+]
+
+export function isPathWithinDirectory(filePath: string, directory: string): boolean {
+ const resolvedPath = path.resolve(filePath)
+ const resolvedDir = path.resolve(directory)
+ return resolvedPath.startsWith(`${resolvedDir}${path.sep}`) || resolvedPath === resolvedDir
+}
+
+export function pathMatchesGlob(filePath: string, glob: string, baseDir: string): boolean {
+ const resolvedPath = path.resolve(filePath)
+ const resolvedBase = path.resolve(baseDir)
+
+ if (!isPathWithinDirectory(resolvedPath, resolvedBase)) {
+ return false
+ }
+
+ const relativePath = path.relative(resolvedBase, resolvedPath).replace(/\\/g, '/')
+
+ try {
+ const globRegex = glob
+ .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+ .replace(/\*\*/g, '<<<GLOBSTAR>>>')
+ .replace(/\*/g, '[^/]*')
+ .replace(/<<<GLOBSTAR>>>/g, '.*')
+ .replace(/\//g, '\\/')
+
+ const regex = new RegExp(`^${globRegex}`)
+ if (regex.test(relativePath)) {
+ return true
+ }
+
+ if (glob.endsWith('/**') && !relativePath.endsWith('/')) {
+ return regex.test(`${relativePath}/`)
+ }
+
+ return false
+ } catch {
+ return false
+ }
+}
+
+export interface ShellValidationOptions {
+ allowedCommands?: Set<string>
+ blockedPatterns?: RegExp[]
+ allowedBaseDirectory?: string
+}
+
+export type ShellValidationResult =
+ | { ok: true }
+ | { ok: false, reason: string }
+
+function extractPotentialPathTokens(command: string): string[] {
+ const tokenRegex = /(?:^|\s)(\/[^\s|;&]+|\.{1,2}\/[^\s|;&]+)/g
+ const tokens: string[] = []
+
+ let match: RegExpExecArray | null = null
+ while ((match = tokenRegex.exec(command)) !== null) {
+ const [, token] = match
+ if (token) {
+ tokens.push(token.replace(/^['"]|['"]$/g, ''))
+ }
+ }
+
+ return tokens
+}
+
+function validatePaths(command: string, allowedBaseDirectory?: string): ShellValidationResult {
+ if (!allowedBaseDirectory) {
+ return { ok: true }
+ }
+
+ const tokens = extractPotentialPathTokens(command)
+ for (const token of tokens) {
+ if (token.startsWith('../')) {
+ return { ok: false, reason: `Path traversal is not allowed: ${token}` }
+ }
+ if (token.startsWith('/')) {
+ if (!isPathWithinDirectory(token, allowedBaseDirectory)) {
+ return { ok: false, reason: `Path outside sandbox is not allowed: ${token}` }
+ }
+ }
+ }
+
+ return { ok: true }
+}
+
+export function validateShellCommand(
+ command: string,
+ options?: ShellValidationOptions,
+): ShellValidationResult {
+ const blockedPatterns = options?.blockedPatterns ?? BLOCKED_SHELL_PATTERNS
+ const allowedCommands = options?.allowedCommands ?? ALLOWED_BASH_COMMANDS
+
+ for (const pattern of blockedPatterns) {
+ if (pattern.test(command)) {
+ return { ok: false, reason: `Command contains blocked pattern: ${command.slice(0, 50)}` }
+ }
+ }
+
+ const segments = command.split(/\s*(?:\|(?!\|)|\|\||&&|;)\s*/)
+ for (const segment of segments) {
+ const trimmed = segment.trim()
+ if (!trimmed) continue
+ const words = trimmed.split(/\s+/)
+ const cmdName = words.find(w => !w.includes('=')) || words[0]
+ if (!cmdName || !allowedCommands.has(cmdName)) {
+ return { ok: false, reason: `Command not allowed: ${cmdName || 'unknown'}` }
+ }
+ }
+
+ return validatePaths(command, options?.allowedBaseDirectory)
+}
diff --git a/packages/sdk/src/tools/shell.ts b/packages/sdk/src/tools/shell.ts
index dce842d..1a4206f 100644
--- a/packages/sdk/src/tools/shell.ts
+++ b/packages/sdk/src/tools/shell.ts
@@ -2,6 +2,7 @@ import { tool } from 'ai'
import { z } from 'zod'
import type { SavoirClient } from '../client'
import type { ToolCallCallback, ToolExecutionResult, CommandResult } from '../types'
+import { validateShellCommand } from '../shell-policy'
export function createBashTool(client: SavoirClient, onToolCall?: ToolCallCallback) {
return tool({
@@ -26,6 +27,13 @@ Use standard Unix commands to explore and read files.`,
const startTime = Date.now()
try {
+ const validation = validateShellCommand(command, {
+ allowedBaseDirectory: '/vercel/sandbox',
+ })
+ if (!validation.ok) {
+ throw new Error(validation.reason)
+ }
+
const apiResult = await client.bash(command)
const durationMs = Date.now() - startTime
@@ -111,6 +119,15 @@ Maximum 10 commands per batch.`,
const startTime = Date.now()
try {
+ for (const command of commands) {
+ const validation = validateShellCommand(command, {
+ allowedBaseDirectory: '/vercel/sandbox',
+ })
+ if (!validation.ok) {
+ throw new Error(validation.reason)
+ }
+ }
+
const apiResult = await client.bashBatch(commands)
const durationMs = Date.now() - startTime
diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json
index cb6ef60..fa83dc6 100644
--- a/packages/sdk/tsconfig.json
+++ b/packages/sdk/tsconfig.json
@@ -9,5 +9,6 @@
"skipLibCheck": true,
"noEmit": true
},
- "include": ["src"]
+ "include": ["src"],
+ "exclude": ["src/**/*.test.ts"]
}