savant-code 0.0.16 → 0.0.19

package/WINDOWS.md

@@ -0,0 +1,238 @@
+# SavantCode for Windows dev setup
+
+Welcome!
+
+For development, we have a shared windows machine, via shadow.tech.
+
+## Accessing the machine
+
+You can access the machine either from the browser or with the desktop app:
+
+1. Shadow.tech Web viewer:
+
+- Go to https://pc.shadow.tech/home
+
+2. Shadow.tech desktop app:
+
+- They claim its better, idk.
+- https://shadow.tech/download/
+
+Supposedly you can also use Window's Remote Desktop to access the machine instead, but I've not tried it.
+Shadow.tech claims their protocol is better optimized for lower bandwidth use & hence smoother performance.
+
+## Set-up guide:
+
+You shouldn't need this - but just in case you stop using Shadow.tech, or make a new account, here's a guide on how
+to get from a blank Windows install to a SavantCode install.
+
+Surprisingly: most guides in fact recommend running everything in an Admin PowerShell, contra to advice to not use
+sudo on eg: Linux/macOS.
+
+- Install Choco: Open PowerShell as Admin, and run the command from https://chocolatey.org/install
+- Install NVM: Restart PowerShell (still as Admin) and run `choco install nvm -y`
+- Install Node: Restart PowerShell (still as Admin) and run `nvm install node`
+- Install SavantCode: Run `npm i -g savant-code`
+
+---
+
+## Common Windows Issues & Troubleshooting
+
+Running into problems? Here are solutions to the most common Windows-specific issues.
+
+### Issue: "Failed to determine latest version" or release metadata on First Run
+
+**Symptom**:
+```powershell
+PS C:\> savant-code
+❌ Failed to determine latest version
+Please check your internet connection and try again
+```
+
+**Cause**:
+Some release wrappers or older installations may check public release metadata during startup. This can fail when:
+
+- Corporate firewall blocks `github.com`
+- Proxy settings not configured
+- Network connectivity issues
+- VPN required for external access
+
+**Solutions**:
+
+1. **Set the `HTTPS_PROXY` environment variable** (if behind corporate proxy or a restricted network):
+
+   SavantCode natively supports proxy environment variables. This is the recommended fix:
+
+   **PowerShell:**
+   ```powershell
+   $env:HTTPS_PROXY = "http://your-proxy-server:port"
+   savant-code
+   ```
+
+   **CMD:**
+   ```cmd
+   set HTTPS_PROXY=http://your-proxy-server:port
+   savant-code
+   ```
+
+   To make it permanent, add `HTTPS_PROXY` to your Windows System Environment Variables (Settings → System →
+   Advanced → Environment Variables).
+
+2. **Verify network access**:
+   ```powershell
+   curl https://registry.npmjs.org/savant-code/latest
+   ```
+   If this fails, you have a network/firewall issue.
+
+3. **Configure npm proxy** (for the `npm install` step only):
+   ```powershell
+   npm config set proxy http://your-proxy-server:port
+   npm config set https-proxy http://your-proxy-server:port
+   ```
+   Note: This only helps with `npm install`. SavantCode's own downloads use `HTTPS_PROXY` instead.
+
+4. **Disable VPN temporarily** or whitelist `registry.npmjs.org` and `savant-code.com` in your firewall
+
+5. **Clear npm cache and reinstall**:
+   ```powershell
+   npm cache clean --force
+   npm uninstall -g savant-code
+   npm install -g savant-code
+   ```
+
+**Reference**: Issue [#294](https://github.com/savant0x/savant-code/issues/294)
+
+---
+
+### Issue: "Bash is required but was not found" Error
+
+**Symptom**:
+```text
+Bash is required but was not found on this Windows system.
+```
+
+**Cause**:
+SavantCode requires bash for command execution. This error appears when:
+
+- Git for Windows is not installed
+- You're not running inside WSL
+- bash.exe is not in your PATH
+
+**Solutions**:
+
+1. **Install Git for Windows** (recommended):
+   - Download from https://git-scm.com/download/win
+   - This installs `bash.exe` which SavantCode will automatically detect
+   - Works in PowerShell, CMD, or Git Bash terminals
+
+2. **Use WSL (Windows Subsystem for Linux)**:
+   - Provides full Linux environment with native bash
+   - Install: `wsl --install` in PowerShell (Admin)
+   - Run savant-code inside WSL for best compatibility
+
+3. **Set custom bash path** (advanced):
+   - If bash.exe is installed in a non-standard location:
+   ```powershell
+   set SAVANT_CODE_GIT_BASH_PATH=C:\path\to\bash.exe
+   ```
+
+**Reference**: Issue [#274](https://github.com/savant0x/savant-code/issues/274)
+
+---
+
+### Issue: Git Commands Fail on Windows
+
+**Symptom**:
+Git operations (commit, rebase, complex commands) fail with syntax errors or unexpected behavior.
+
+**Cause**:
+Complex git commands may have issues with Windows path handling or shell escaping.
+
+**Solutions**:
+
+1. **Ensure Git for Windows is installed**:
+   - Download from https://git-scm.com/download/win
+   - SavantCode uses bash.exe from Git for Windows for command execution
+
+2. **Use WSL for complex operations**:
+   - Provides full Linux environment with native bash
+   - Install: `wsl --install` in PowerShell (Admin)
+   - Run savant-code inside WSL for best compatibility
+
+**Reference**: Issue [#274](https://github.com/savant0x/savant-code/issues/274)
+
+---
+
+### Issue: Login Browser Window Fails to Open
+
+**Symptom**:
+```text
+Press ENTER to open your browser and finish logging in...
+
+Caught exception: Error: Executable not found in $PATH: "start"
+Error: Executable not found in $PATH: "start"
+TLCWeb > Unable to login. Please try again by typing "login" in the terminal.
+```
+
+**Cause**:
+When running SavantCode in Git Bash (MINGW64), the `start` command is not available in PATH. The browser auto-open
+feature fails.
+
+**Solutions**:
+
+1. **Manually open the login URL** (easiest):
+   - SavantCode displays the login URL after the error
+   - Copy the full URL starting with `https://savant-code.com/login?auth_code=...`
+   - Paste into your browser
+   - Complete login in browser
+   - Return to terminal - login will succeed
+
+2. **Use native Windows terminals**:
+   - PowerShell: `powershell`
+   - Command Prompt: `cmd`
+   - These have `start` command available
+
+3. **Clear cache if login still fails** (per issue #299):
+   ```powershell
+   npm cache clean --force
+   npm uninstall -g savant-code
+   npm install -g savant-code
+   ```
+
+**Reference**: Issue [#299](https://github.com/savant0x/savant-code/issues/299)
+
+---
+
+### Message: "Update available: error → [version]"
+
+**What it means**:
+This is **not an error** - it's an informational message indicating:
+
+- Your local binary needs to be downloaded/updated
+- "error" is a placeholder version (not a real error state)
+- SavantCode will automatically download the correct version
+
+**What to do**:
+
+- Wait for the download to complete: "Download complete! Starting SavantCode..."
+- If download fails, check your internet connection
+- If it persists, try the solutions in "Failed to determine latest version" above
+
+**Reference**: Issue [#299](https://github.com/savant0x/savant-code/issues/299)
+
+---
+
+### Still Having Issues?
+
+If these solutions don't resolve your problem:
+
+1. **Search existing issues**: https://github.com/savant0x/savant-code/issues
+2. **Open a new issue**: https://github.com/savant0x/savant-code/issues/new
+3. **Join Discord community**: https://savant-code.com/discord
+
+When reporting issues, please include:
+
+- Windows version: `winver` command
+- PowerShell/Git Bash/CMD
+- Node version: `node --version`
+- Full error message
+- Steps to reproduce

package/agents/README.md

@@ -0,0 +1,41 @@
+<!-- markdownlint-disable MD041 -->
+<img src="../assets/banner.png" alt="@savant-code/agents — Public agent definitions for the Savant CLI" width="650" />
+
+# @savant-code/agents
+
+Public agent definitions shipped with the Savant CLI (Detective, Forge, Verifier, Recorder, Thinker, Scout, Researcher,
+Scribe, Orchestrator).
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-%23000000?style=flat-square&logo=apache&logoColor=%2300fbff)](../LICENSE)[![ECHO](https://img.shields.io/badge/ECHO-v0.2.0-%23000000?style=flat-square&logo=github&logoColor=%2300fbff)](../ECHO.md)[![Status](https://img.shields.io/badge/Status-internal-%23ff9500?style=flat-square&logo=github&logoColor=%2300fbff)](../README.md)
+
+## Purpose
+
+The agents in this workspace are the **separation-of-duties specialists** that execute the Perfection Loop FSM (RED →
+GREEN → AUDIT → SELF-CORRECT → COMPLETE). Each agent is restricted to a small tool set per ECHO Law 13 — Detective reads
+and searches only; Forge writes only; Verifier reads only; Recorder archives FIDs; Thinker reasons sequentially, etc. The
+Orchestrator in `agents/savant/` routes work across agents and is the only one allowed to spawn child agents.
+
+## Quick Start
+
+```bash
+# From the repo root
+bun install
+
+# Validate all agents
+bun --cwd agents typecheck
+```
+
+For full Quick Start including how agents are wired into the CLI runtime, see the [root README](../README.md#features).
+
+## License
+
+[Apache-2.0](../LICENSE) — see [LICENSE](../LICENSE) for full text.
+
+---
+
+<div align="center">
+
+_Part of the [savant-code/savant-code monorepo](https://github.com/savant0x/savant-code), governed by the [ECHO Protocol v0.2.0](../ECHO.md)._
+
+**Savant** • 2026
+</div>

package/agents/base-chat.ts

@@ -0,0 +1,44 @@
+import { SAVANT_FREE_DEEPSEEK_V4_FLASH_FIREWORKS_MODEL_ID } from '@savant-code/common/constants/savant-free-models'
+
+import { publisher } from './constants'
+
+import type { SecretAgentDefinition } from './types/secret-agent-definition'
+
+/**
+ * Conversational agent behind savant-free.com/chat. Runs with no filesystem, but
+ * can spawn researcher-web to look things up on the live internet and call
+ * gravity_index to recommend third-party developer services. The chat server
+ * may override `model` per request (DeepSeek Flash vs Pro for full-access
+ * users).
+ */
+const definition: SecretAgentDefinition = {
+  id: 'base-chat',
+  publisher,
+  model: SAVANT_FREE_DEEPSEEK_V4_FLASH_FIREWORKS_MODEL_ID,
+  displayName: 'SavantFree Chat',
+  spawnerPrompt: 'General-purpose chat assistant for savant-free.com/chat.',
+  inputSchema: {
+    prompt: {
+      type: 'string',
+      description: 'The user message to respond to.',
+    },
+  },
+  outputMode: 'last_message',
+  toolNames: ['spawn_agents', 'gravity_index', 'suggest_followups'],
+  spawnableAgents: ['researcher-web', 'thinker-gemini'],
+
+  systemPrompt: `You are SavantFree Chat, a friendly, sharp assistant made by SavantFree (savant-free.com), the home of free AI coding tools. You are chatting with a user in a web interface that renders markdown.`,
+  instructionsPrompt: `Be direct and helpful. Use markdown when it improves clarity (code blocks, lists, tables), and keep answers as short as they can be while fully answering the question.
+
+When the user is choosing a third-party developer service (database, auth, payments, hosting, email, monitoring, analytics, AI APIs, storage, CMS, search, etc.) or asks what provider to use for something, use the gravity_index tool instead of answering from memory: \`search\` with a query that includes their stack and constraints when they want a recommendation, or \`browse\`/\`list_categories\`/\`get_service\` to explore options. Ground your answer in the result. When a search result includes a tracked setup link (\`credential_request.setup_url\` or \`click_url\`), present that exact URL prominently as a markdown link like "Get your {service} API key" — never swap in the vendor homepage for it. Since you can't edit the user's files, share the relevant setup steps and env vars in chat instead of trying to install anything.
+
+You can search the live internet by spawning the researcher-web agent. Spawn it whenever the answer depends on current or recent information (news, prices, releases, versions, schedules, scores, docs), whenever the user asks you to look something up, or whenever you are not confident in your knowledge. Give it a focused question; you can spawn several in parallel for independent questions. After it reports back, answer the user in your own words and cite source URLs when useful. Don't spawn it for questions you can already answer well (general knowledge, coding help, writing, math).
+
+Whenever a question needs real reasoning, spawn the thinker-gemini agent and let it do the thinking — do not reason it out yourself in your reply. This is your default for anything beyond a quick lookup: math or logic problems, puzzles, debugging, code design, architecture and trade-off decisions, planning, comparisons, "why/how" explanations, estimates, or any multi-step question. When in doubt, spawn the thinker. First gather any context you need (spawn researcher-web for current info, call gravity_index for service questions), then spawn the thinker. It sees the full conversation, including everything your tools returned, so give it a short, focused prompt naming the problem — don't repeat the gathered context. It is fine (often good) to spawn the thinker even when you think you know the answer; let it verify the reasoning. Wait for its conclusion, then write the final answer to the user in your own words. Skip the thinker only for trivial, purely factual, or conversational messages (greetings, simple definitions, quick lookups) where there is nothing to reason about.
+
+You do not have access to the user's files or a filesystem — if asked to do something that requires those, say so briefly and help with what you can instead.
+
+End every response by calling the suggest_followups tool with exactly 3 followups the user is likely to want next — natural next questions, deeper dives, or related directions that build on what you just said. Make them specific to this conversation, not generic. For each followup give a short \`label\` (2–5 words, the card title) and a full \`prompt\` (the complete message sent verbatim when the user clicks it, phrased in the user's first-person voice, e.g. "Show me how to…"). Call it last, after your written answer (and after any tool/subagent calls). Skip it only when there is no sensible next step (e.g. the user said goodbye).`,
+}
+
+export default definition

package/agents/basher.ts

@@ -0,0 +1,107 @@
+import { GEMINI_3_1_FLASH_LITE_MODEL_ID } from '@savant-code/common/constants/gemini'
+
+import { publisher } from './constants'
+
+import type {
+  AgentDefinition,
+  AgentStepContext,
+} from './types/agent-definition'
+
+const basher: AgentDefinition = {
+  id: 'basher',
+  publisher,
+  model: GEMINI_3_1_FLASH_LITE_MODEL_ID,
+  displayName: 'Basher',
+  spawnerPrompt:
+    'Runs a single terminal command and (recommended) describes its output using an LLM using the what_to_summarize field. A lightweight shell command executor. Every basher spawn MUST include params: { command: "<shell>" }.',
+
+  inputSchema: {
+    params: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description:
+            "The terminal command to run in bash shell. Don't forget this field!",
+        },
+        what_to_summarize: {
+          type: 'string',
+          description:
+            'What information from the command output is desired. Be specific about what to look for or extract. This is optional, and if not provided, the basher will return the full command output without summarization.',
+        },
+        timeout_seconds: {
+          type: 'number',
+          description: 'Set to -1 for no timeout. Default 30',
+        },
+      },
+      required: ['command'],
+    },
+  },
+  outputMode: 'last_message',
+  includeMessageHistory: false,
+  toolNames: ['run_terminal_command'],
+  systemPrompt: `You are part of the Savant ECHO Protocol system. You are an expert at analyzing the output of a terminal command.
+
+Your job is to:
+1. Review the terminal command and its output
+2. Analyze the output based on what the user requested
+3. Provide a clear, concise description of the relevant information
+
+When describing command output:
+- Use excerpts from the actual output when possible (especially for errors, key values, or specific data)
+- Focus on the information the user requested
+- Be concise but thorough
+- If the output is very long, summarize the key points rather than reproducing everything
+- Don't include any follow up recommendations, suggestions, or offers to help`,
+  instructionsPrompt: `The user has provided a command to run and specified what information they want from the output.
+
+Run the command and then describe the relevant information from the output, following the user's instructions about what to focus on.
+
+Do not use any tools! Only analyze the output of the command.`,
+  handleSteps: function* ({ params }: AgentStepContext) {
+    const command = params?.command as string | undefined
+    if (!command) {
+      // Using console.error because agents run in a sandboxed environment without access to structured logger
+      // eslint-disable-next-line no-console -- sandboxed agent env: no structured logger available
+      console.error('Basher agent: missing required "command" parameter')
+      yield {
+        toolName: 'set_output',
+        input: { output: 'Error: Missing required "command" parameter' },
+      }
+      return
+    }
+
+    const timeout_seconds = params?.timeout_seconds as number | undefined
+    const what_to_summarize = params?.what_to_summarize as string | undefined
+
+    // Run the command
+    const { toolResult } = yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command,
+        ...(timeout_seconds !== undefined && { timeout_seconds }),
+      },
+    }
+
+    if (!what_to_summarize) {
+      // Return the raw command output without summarization
+      const result = toolResult?.[0]
+      // Only return object values (command output objects), not plain strings
+      const output =
+        result?.type === 'json' && typeof result.value === 'object'
+          ? result.value
+          : ''
+      yield {
+        toolName: 'set_output',
+        input: { output },
+        includeToolCall: false,
+      }
+      return
+    }
+
+    // Let the model analyze and describe the output
+    yield 'STEP'
+  },
+}
+
+export default basher

package/agents/browser-use/browser-use.test.ts

@@ -0,0 +1,211 @@
+ 
+/**
+ * Test script for the browser-use agent.
+ *
+ * Runs the agent on browser tasks one at a time, writing full event traces
+ * to files for analysis. Each task produces a trace file in debug/browser-agent-traces/.
+ *
+ * Usage:
+ *   bun agents/browser-use/browser-use.test.ts [taskIndex]
+ *
+ * If taskIndex is provided, runs only that task (0-based). Otherwise runs all tasks.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { SavantCodeClient, loadLocalAgents } from '@savant-code/sdk'
+
+import type { AgentDefinition } from '@savant-code/sdk'
+
+const TRACE_DIR = path.join(process.cwd(), 'debug', 'browser-agent-traces')
+
+interface TaskDefinition {
+  name: string
+  prompt: string
+  url?: string
+}
+
+const TASKS: TaskDefinition[] = [
+  {
+    name: 'wikipedia-search',
+    prompt:
+      'Navigate to Wikipedia, search for "TypeScript programming language", and tell me the first sentence of the article.',
+    url: 'https://en.wikipedia.org',
+  },
+  {
+    name: 'hacker-news-top',
+    prompt:
+      'Navigate to Hacker News and tell me the titles of the top 3 stories on the front page.',
+    url: 'https://news.ycombinator.com',
+  },
+  {
+    name: 'example-form',
+    prompt:
+      'Navigate to https://httpbin.org/forms/post and fill out the form with: customer name "Test User", telephone "555-1234", size "Medium", topping "Bacon", and submit the form. Report what the server response shows.',
+    url: 'https://httpbin.org/forms/post',
+  },
+]
+
+interface TraceEvent {
+  timestamp: string
+  type: string
+  data: Record<string, unknown>
+}
+
+async function runTask(
+  client: SavantCodeClient,
+  task: TaskDefinition,
+  agentDefinitions: AgentDefinition[],
+  taskIndex: number,
+): Promise<{ success: boolean; traceFile: string; output: unknown }> {
+  const events: TraceEvent[] = []
+  const startTime = Date.now()
+
+  console.log(`\n${'='.repeat(60)}`)
+  console.log(`Task ${taskIndex}: ${task.name}`)
+  console.log(`Prompt: ${task.prompt}`)
+  console.log(`${'='.repeat(60)}\n`)
+
+  const runState = await client.run({
+    agent: 'browser-use',
+    prompt: task.prompt,
+    params: task.url ? { url: task.url } : undefined,
+    agentDefinitions,
+    maxAgentSteps: 30,
+    handleEvent: (event) => {
+      events.push({
+        timestamp: new Date().toISOString(),
+        type: event.type,
+        data: event as Record<string, unknown>,
+      })
+
+      if (event.type === 'text') {
+        process.stdout.write(event.text ?? '')
+      } else if (event.type === 'tool_call') {
+        console.log(`\n[Tool Call] ${event.toolName}`)
+      } else if (event.type === 'tool_result') {
+        const preview = JSON.stringify(event.output)?.slice(0, 200)
+        console.log(`[Tool Result] ${preview}...`)
+      } else if (event.type === 'error') {
+        console.error(`[Error] ${event.message}`)
+      } else if (event.type === 'subagent_start') {
+        console.log(`[Subagent Start] ${event.agentType}`)
+      } else if (event.type === 'subagent_finish') {
+        console.log(`[Subagent Finish] ${event.agentType}`)
+      }
+    },
+  })
+
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1)
+  const output = runState.output
+
+  const trace = {
+    task: {
+      name: task.name,
+      prompt: task.prompt,
+      url: task.url,
+    },
+    duration: `${duration}s`,
+    output,
+    eventCount: events.length,
+    events,
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const traceFile = path.join(TRACE_DIR, `${timestamp}_${task.name}.json`)
+  fs.writeFileSync(traceFile, JSON.stringify(trace, null, 2))
+
+  const success = output?.type !== 'error'
+
+  console.log(`\n${'─'.repeat(60)}`)
+  console.log(`Result: ${success ? '✅ SUCCESS' : '❌ FAILURE'}`)
+  console.log(`Duration: ${duration}s`)
+  console.log(`Events: ${events.length}`)
+  console.log(`Trace: ${traceFile}`)
+
+  if (output?.type === 'error') {
+    console.log(`Error: ${output.message}`)
+  } else if (output?.type === 'structuredOutput') {
+    const data = output.value as Record<string, unknown> | null
+    console.log(`Status: ${data?.overallStatus}`)
+    console.log(`Summary: ${data?.summary}`)
+    if (data && Array.isArray(data.lessons) && data.lessons.length > 0) {
+      console.log(`Lessons:`)
+      for (const lesson of data.lessons) {
+        console.log(`  - ${lesson}`)
+      }
+    }
+  }
+  console.log(`${'─'.repeat(60)}`)
+
+  return { success, traceFile, output }
+}
+
+async function main() {
+  fs.mkdirSync(TRACE_DIR, { recursive: true })
+
+  const taskIndexArg = process.argv[2]
+  const tasksToRun =
+    taskIndexArg !== undefined
+      ? [
+          {
+            task: TASKS[parseInt(taskIndexArg, 10)],
+            index: parseInt(taskIndexArg, 10),
+          },
+        ]
+      : TASKS.map((task, index) => ({ task, index }))
+
+  if (tasksToRun.some((t) => !t.task)) {
+    console.error(
+      `Invalid task index: ${taskIndexArg}. Available: 0-${TASKS.length - 1}`,
+    )
+    process.exit(1)
+  }
+
+  const agents = await loadLocalAgents({
+    agentsPath: path.join(process.cwd(), 'agents'),
+    verbose: true,
+  })
+  const agentDefinitions = Object.values(agents) as AgentDefinition[]
+
+  const browserAgent = agentDefinitions.find((a) => a.id === 'browser-use')
+  if (!browserAgent) {
+    console.error('browser-use agent not found in agents/ directory')
+    process.exit(1)
+  }
+  console.log(`Loaded browser-use agent (model: ${browserAgent.model})`)
+
+  const client = new SavantCodeClient({
+    apiKey: process.env.SAVANT_CODE_API_KEY,
+    cwd: process.cwd(),
+  })
+
+  const results: Array<{ name: string; success: boolean; traceFile: string }> =
+    []
+
+  for (const { task, index } of tasksToRun) {
+    const result = await runTask(client, task, agentDefinitions, index)
+    results.push({
+      name: task.name,
+      success: result.success,
+      traceFile: result.traceFile,
+    })
+  }
+
+  console.log(`\n${'='.repeat(60)}`)
+  console.log('SUMMARY')
+  console.log(`${'='.repeat(60)}`)
+  for (const r of results) {
+    console.log(`  ${r.success ? '✅' : '❌'} ${r.name} → ${r.traceFile}`)
+  }
+  const passed = results.filter((r) => r.success).length
+  console.log(`\n${passed}/${results.length} tasks passed`)
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error('Fatal error:', err)
+    process.exit(1)
+  })
+}