savant-code 0.0.19 → 0.0.21

package/common/src/templates/initial-agents-dir/README.md

@@ -1,314 +0,0 @@
-# Custom Agents
-
-Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a
-single agent trying to handle everything, you can orchestrate teams of focused specialists that work together.
-
-## Getting Started
-
-1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs
-2. **Test your agent**: Run `savant-code` without `--agent` so local `.agents` load, then invoke your agent from a prompt
-3. **Publish your agent**: Run `savant-code publish your-agent-name`
-
-## Need Help?
-
-- For examples, check the `examples/` directory.
-- Join our [Discord community](https://savant-code.com/discord) and ask your questions!
-- Check our [documentation](https://savant-code.com/docs) for more details
-
-# What is SavantCode?
-
-SavantCode is an **open-source AI coding assistant** that edits your codebase through natural language instructions.
-Instead of using one model for everything, it coordinates specialized agents that work together to understand your
-project and make precise changes.
-
-SavantCode beats Claude Code at 61% vs 53% on [our evals](https://github.com/savant0x/savant-code/tree/main/evals)
-across 175+ coding tasks over multiple open-source repos that simulate real-world tasks.
-
-## How SavantCode Works
-
-When you ask SavantCode to "add authentication to my API," it might invoke:
-
-1. A **File Explorer Agent** to scan your codebase to understand the architecture and find relevant files
-2. A **Planner Agent** to plan which files need changes and in what order
-3. An **Editor Agent** to make precise edits
-4. A **Reviewer Agent** to validate changes
-
-This multi-agent approach gives you better context understanding, more accurate edits, and fewer errors compared to
-single-model tools.
-
-## Context Window Management
-
-### Why Agent Workflows?
-
-Modern software projects are complex ecosystems with thousands of files, multiple frameworks, intricate dependencies,
-and domain-specific requirements. A single AI agent trying to understand and modify such systems faces fundamental
-limitations—not just in knowledge, but in the sheer volume of information it can process at once.
-
-### The Solution: Focused Context Windows
-
-Agent workflows elegantly solve this by breaking large tasks into focused sub-problems. When working with large
-codebases (100k+ lines), each specialist agent receives only the narrow context it needs—a security agent sees only auth
-code, not UI components—keeping the context for each agent manageable while ensuring comprehensive coverage.
-
-### Why Not Just Mimic Human Roles?
-
-This is about efficient AI context management, not recreating a human department. Simply creating a "frontend-developer"
-agent misses the point. AI agents don't have human constraints like context-switching or meetings. Their power comes
-from hyper-specialization, allowing them to process a narrow domain more deeply than a human could, then coordinating
-seamlessly with other specialists.
-
-## Agent workflows in action
-
-Here's an example of a `git-committer` agent that creates good commit messages:
-
-```typescript
-export default {
-  id: 'git-committer',
-  displayName: 'Git Committer',
-  model: 'openai/gpt-5-nano',
-  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
-
-  instructionsPrompt:
-    'You create meaningful git commits by analyzing changes, reading relevant files for context, and crafting clear commit messages that explain the "why" behind changes.',
-
-  async *handleSteps() {
-    // Analyze what changed
-    yield { tool: 'run_terminal_command', command: 'git diff' }
-    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
-
-    // Stage files and create commit with good message
-    yield 'STEP_ALL'
-  },
-}
-```
-
-This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear,
-meaningful messages that explain the "why" behind changes.
-
-# Agent Development Guide
-
-This guide covers everything you need to know about building custom SavantCode agents.
-
-## Agent Structure
-
-Each agent is a TypeScript file that exports an `AgentDefinition` object:
-
-```typescript
-export default {
-  id: 'my-agent', // Unique identifier (lowercase, hyphens only)
-  displayName: 'My Agent', // Human-readable name
-  model: 'claude-3-5-sonnet', // AI model to use
-  toolNames: ['read_files', 'write_file'], // Available tools
-  instructionsPrompt: 'You are...', // Agent behavior instructions
-  spawnerPrompt: 'Use this agent when...', // When others should spawn this
-  spawnableAgents: ['helper-agent'], // Agents this can spawn
-
-  // Optional: Programmatic control
-  async *handleSteps() {
-    yield { tool: 'read_files', paths: ['src/config.ts'] }
-    yield 'STEP' // Let AI process and respond
-  },
-}
-```
-
-## Core Properties
-
-### Required Fields
-
-- **`id`**: Unique identifier using lowercase letters and hyphens only
-- **`displayName`**: Human-readable name shown in UI
-- **`model`**: AI model from OpenRouter (see [available models](https://openrouter.ai/models))
-- **`instructionsPrompt`**: Detailed instructions defining the agent's role and behavior
-
-### Optional Fields
-
-- **`toolNames`**: Array of tools the agent can use (defaults to common tools)
-- **`spawnerPrompt`**: Instructions for when other agents should spawn this one
-- **`spawnableAgents`**: Array of agent names this agent can spawn
-- **`handleSteps`**: Generator function for programmatic control
-
-## Available Tools
-
-### File Operations
-
-- **`read_files`**: Read file contents
-- **`write_file`**: Create or modify entire files
-- **`str_replace`**: Make targeted string replacements
-- **`code_search`**: Search for patterns across the codebase
-
-### Execution
-
-- **`run_terminal_command`**: Execute shell commands
-- **`spawn_agents`**: Delegate tasks to other agents
-- **`end_turn`**: Finish the agent's response
-
-### Web & Research
-
-- **`web_search`**: Search the internet for information
-- **`read_url`**: Fetch a URL and extract readable page text
-- **`read_docs`**: Read technical documentation
-- **`browser_logs`**: Navigate and inspect web pages
-
-See `types/tools.ts` for detailed parameter information.
-
-## Programmatic Control
-
-Use the `handleSteps` generator function to mix AI reasoning with programmatic logic:
-
-```typescript
-async *handleSteps() {
-  // Execute a tool
-  yield { tool: 'read_files', paths: ['package.json'] }
-
-  // Let AI process results and respond
-  yield 'STEP'
-
-  // Conditional logic
-  if (needsMoreAnalysis) {
-    yield { tool: 'spawn_agents', agents: ['deep-analyzer'] }
-    yield 'STEP_ALL' // Wait for spawned agents to complete
-  }
-
-  // Final AI response
-  yield 'STEP'
-}
-```
-
-### Control Commands
-
-- **`'STEP'`**: Let AI process and respond once
-- **`'STEP_ALL'`**: Let AI continue until completion
-- **Tool calls**: `{ tool: 'tool_name', ...params }`
-
-## Model Selection
-
-Choose models based on your agent's needs:
-
-- **`anthropic/claude-opus-4.7`**: Best general-purpose capabilities and code generation
-- **`openai/gpt-5.2`**: Best at complex reasoning and planning
-- **`google/gemini-3.1-flash-lite`**: Fast and cost-effective for simple or medium-complexity tasks
-
-**Any model on OpenRouter**: Unlike Claude Code which locks you into Anthropic's models, SavantCode supports any model
-available on [OpenRouter](https://openrouter.ai/models) - from Claude and GPT to specialized models like Qwen, DeepSeek,
-and others. Switch models for different tasks or use the latest releases without waiting for platform updates.
-
-See [OpenRouter](https://openrouter.ai/models) for all available models and pricing.
-
-## Agent Coordination
-
-Agents can spawn other agents to create sophisticated workflows:
-
-```typescript
-// Parent agent spawns specialists
-async *handleSteps() {
-  yield { tool: 'spawn_agents', agents: [
-    'security-scanner',
-    'performance-analyzer',
-    'code-reviewer'
-  ]}
-  yield 'STEP_ALL' // Wait for all to complete
-
-  // Synthesize results
-  yield 'STEP'
-}
-```
-
-**Reuse any published agent**: Compose existing [published agents](https://www.savant-code.com/store) to get a leg up.
-SavantCode agents are the new MCP!
-
-## Best Practices
-
-### Instructions
-
-- Be specific about the agent's role and expertise
-- Include examples of good outputs
-- Specify when the agent should ask for clarification
-- Define the agent's limitations
-
-### Tool Usage
-
-- Start with file exploration tools (`read_files`, `code_search`)
-- Use `str_replace` for targeted edits, `write_file` for major changes
-- Always use `end_turn` to finish responses cleanly
-
-### Error Handling
-
-- Include error checking in programmatic flows
-- Provide fallback strategies for failed operations
-- Log important decisions for debugging
-
-### Performance
-
-- Choose appropriate models for the task complexity
-- Minimize unnecessary tool calls
-- Use spawnable agents for parallel processing
-
-## Testing Your Agent
-
-1. **Local Testing**: Run `savant-code` without `--agent` so local `.agents` load, then invoke your agent from a prompt
-2. **Debug Mode**: Add logging to your `handleSteps` function
-3. **Unit Testing**: Test individual functions in isolation
-4. **Integration Testing**: Test agent coordination workflows
-
-## Publishing & Sharing
-
-1. **Validate**: Ensure your agent works across different codebases
-2. **Document**: Include clear usage instructions
-3. **Publish**: `savant-code publish your-agent-name`
-4. **Maintain**: Update as models and tools evolve
-
-## Advanced Patterns
-
-### Conditional Workflows
-
-```typescript
-async *handleSteps() {
-  const config = yield { tool: 'read_files', paths: ['config.json'] }
-  yield 'STEP'
-
-  if (config.includes('typescript')) {
-    yield { tool: 'spawn_agents', agents: ['typescript-expert'] }
-  } else {
-    yield { tool: 'spawn_agents', agents: ['javascript-expert'] }
-  }
-  yield 'STEP_ALL'
-}
-```
-
-### Iterative Refinement
-
-```typescript
-async *handleSteps() {
-  for (let attempt = 0; attempt < 3; attempt++) {
-    yield { tool: 'run_terminal_command', command: 'npm test' }
-    yield 'STEP'
-
-    if (allTestsPass) break
-
-    yield { tool: 'spawn_agents', agents: ['test-fixer'] }
-    yield 'STEP_ALL'
-  }
-}
-```
-
-## Why Choose SavantCode for Custom Agents
-
-**Deep customizability**: Create sophisticated agent workflows with TypeScript generators that mix AI generation with
-programmatic control. Define custom agents that spawn subagents, implement conditional logic, and orchestrate complex
-multi-step processes that adapt to your specific use cases.
-
-**Fully customizable SDK**: Build SavantCode's capabilities directly into your applications with a complete TypeScript
-SDK. Create custom tools, integrate with your CI/CD pipeline, build AI-powered development environments, or embed
-intelligent coding assistance into your products.
-
-Learn more about the SDK [here](https://www.npmjs.com/package/@savant-code/sdk).
-
-## Community & Support
-
-- **Discord**: [Join our community](https://savant-code.com/discord) for help and inspiration
-- **Examples**: Study the `examples/` directory for patterns
-- **Documentation**: [savant-code.com/docs](https://savant-code.com/docs) and check `types/` for detailed type information
-- **Issues**: [Report bugs and request features on GitHub](https://github.com/savant0x/savant-code/issues)
-- **Support**: [support@savant-code.com](mailto:support@savant-code.com)
-
-Happy agent building! 🤖

package/common/src/templates/initial-agents-dir/examples/01-basic-diff-reviewer.ts

@@ -1,17 +0,0 @@
-import type { AgentDefinition } from '../types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: 'basic-diff-reviewer',
-  displayName: 'Basic Diff Reviewer',
-  model: 'anthropic/claude-4-sonnet-20250522',
-  toolNames: ['read_files', 'run_terminal_command'],
-
-  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
-
-  instructionsPrompt: `Execute the following steps:
-1. Run git diff
-2. Read the files that have changed
-3. Review the changes and suggest improvements`,
-}
-
-export default definition

package/common/src/templates/initial-agents-dir/examples/02-intermediate-git-committer.ts

@@ -1,78 +0,0 @@
-import type {
-  AgentDefinition,
-  AgentStepContext,
-  ToolCall,
-} from '../types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: 'git-committer',
-  displayName: 'Intermediate Git Committer',
-  model: 'anthropic/claude-4-sonnet-20250522',
-  toolNames: ['read_files', 'run_terminal_command', 'add_message', 'end_turn'],
-
-  inputSchema: {
-    prompt: {
-      type: 'string',
-      description: 'What changes to commit',
-    },
-  },
-
-  spawnerPrompt:
-    'Spawn when you need to commit code changes to git with an appropriate commit message',
-
-  systemPrompt:
-    'You are an expert software developer. Your job is to create a git commit with a really good commit message.',
-
-  instructionsPrompt:
-    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting.',
-
-  handleSteps: function* ({ agentState, prompt, params }: AgentStepContext) {
-    // Step 1: Run git diff and git log to analyze changes.
-    yield {
-      toolName: 'run_terminal_command',
-      input: {
-        command: 'git diff',
-        process_type: 'SYNC',
-        timeout_seconds: 30,
-      },
-    } satisfies ToolCall
-
-    yield {
-      toolName: 'run_terminal_command',
-      input: {
-        command: 'git log --oneline -10',
-        process_type: 'SYNC',
-        timeout_seconds: 30,
-      },
-    } satisfies ToolCall
-
-    // Step 2: Put words in AI's mouth so it will read files next.
-    yield {
-      toolName: 'add_message',
-      input: {
-        role: 'assistant',
-        content:
-          "I've analyzed the git diff and recent commit history. Now I'll read any relevant files to better understand the context of these changes.",
-      },
-      includeToolCall: false,
-    } satisfies ToolCall
-
-    // Step 3: Let AI generate a step to decide which files to read.
-    yield 'STEP'
-
-    // Step 4: Put words in AI's mouth to analyze the changes and create a commit.
-    yield {
-      toolName: 'add_message',
-      input: {
-        role: 'assistant',
-        content:
-          "Now I'll analyze the changes and create a commit with a good commit message.",
-      },
-      includeToolCall: false,
-    } satisfies ToolCall
-
-    yield 'STEP_ALL'
-  },
-}
-
-export default definition

package/common/src/templates/initial-agents-dir/examples/03-advanced-file-explorer.ts

@@ -1,76 +0,0 @@
-import type { AgentDefinition, ToolCall } from '../types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: 'advanced-file-explorer',
-  displayName: 'Dora the File Explorer',
-  model: 'openai/gpt-5.1',
-
-  spawnerPrompt:
-    'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
-
-  includeMessageHistory: false,
-  toolNames: ['spawn_agents', 'set_output'],
-  spawnableAgents: [`savant-code/scout@0.0.1`],
-
-  inputSchema: {
-    prompt: {
-      description: 'What you need to accomplish by exploring the codebase',
-      type: 'string',
-    },
-    params: {
-      type: 'object',
-      properties: {
-        prompts: {
-          description:
-            'List of 1-4 different parts of the codebase that could be useful to explore',
-          type: 'array',
-          items: {
-            type: 'string',
-          },
-        },
-      },
-      required: ['prompts'],
-      additionalProperties: false,
-    },
-  },
-  outputMode: 'structured_output',
-  outputSchema: {
-    type: 'object',
-    properties: {
-      results: {
-        type: 'string',
-        description: 'The results of the file exploration',
-      },
-    },
-    required: ['results'],
-    additionalProperties: false,
-  },
-
-  handleSteps: function* ({ prompt, params }) {
-    const rawPrompts = params?.prompts
-    const prompts: string[] = Array.isArray(rawPrompts)
-      ? rawPrompts.filter((item): item is string => typeof item === 'string')
-      : []
-    const filePickerPrompts = prompts.map(
-        (focusPrompt) =>
-          `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`,
-      ),
-      { toolResult: spawnResult } = yield {
-        toolName: 'spawn_agents',
-        input: {
-          agents: filePickerPrompts.map((promptText) => ({
-            agent_type: 'savant-code/scout@0.0.1',
-            prompt: promptText,
-          })),
-        },
-      } satisfies ToolCall
-    yield {
-      toolName: 'set_output',
-      input: {
-        results: spawnResult,
-      },
-    } satisfies ToolCall
-  },
-}
-
-export default definition

package/common/src/templates/initial-agents-dir/my-custom-agent.ts

@@ -1,40 +0,0 @@
-/*
- *  EDIT ME to create your own agent!
- *
- *  Run your agent with:
- *  > savant-code
- *  Inside savant-code:
- *  > @my-custom-agent please review my recent changes
- *
- *  Finally, you can publish your agent with:
- *  > savant-code publish my-custom-agent
- *  Then users from around the world can run it!
- */
-
-import type { AgentDefinition } from './types/agent-definition'
-
-const definition: AgentDefinition = {
-  id: 'my-custom-agent',
-  displayName: 'My Custom Agent',
-
-  model: 'x-ai/grok-4-fast',
-  spawnableAgents: ['savant-code/file-explorer@0.0.6'],
-
-  // Check out .agents/types/tools.ts for more information on the tools you can include.
-  toolNames: ['run_terminal_command', 'read_files', 'spawn_agents'],
-
-  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
-
-  instructionsPrompt: `Review the code changes and suggest improvements.
-Execute the following steps:
-1. Run git diff
-2. Spawn a file explorer to find all relevant files
-3. Read any relevant files
-4. Review the changes and suggest improvements`,
-
-  // See also:
-  // - types/agent-definition.ts file for more fields you can add
-  // - the examples directory for more ideas!
-}
-
-export default definition

package/common/src/templates/initial-agents-dir/package.json

@@ -1,6 +0,0 @@
-{
-  "name": "savant-code-agents",
-  "version": "0.0.1",
-  "description": "This directory contains your custom Savant-Code agents. Each agent is a TypeScript file that defines an AI agent with specific capabilities and behavior.",
-  "license": "Apache-2.0"
-}

package/common/src/templates/initial-agents-dir/skills/README.md

@@ -1,66 +0,0 @@
-# Skills
-
-Skills are reusable instruction sets that agents can load on-demand via the `skill` tool.
-
-## Creating a Skill
-
-1. Create a directory with your skill name (lowercase alphanumeric with hyphens):
-   ```text
-   .agents/skills/my-skill/
-   ```
-
-2. Create a `SKILL.md` file with YAML frontmatter:
-   ```markdown
-   ---
-   name: my-skill
-   description: A short description of what this skill does
-   license: MIT
-   metadata:
-     category: development
-   ---
-
-   # My Skill
-
-   Instructions and content for the skill...
-   ```
-
-## Frontmatter Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Skill name (1-64 chars, lowercase alphanumeric with hyphens, must match directory name) |
-| `description` | Yes | Short description (1-1024 chars) used for agent discovery |
-| `license` | No | License identifier (e.g., "MIT", "Apache-2.0") |
-| `metadata` | No | Key-value pairs for additional categorization |
-
-## Name Validation
-
-Skill names must:
-
-- Be 1-64 characters long
-- Use only lowercase letters, numbers, and hyphens
-- Not start or end with a hyphen
-- Not contain consecutive hyphens
-- Match the directory name exactly
-
-Valid examples: `git-release`, `api-design`, `review2`
-Invalid examples: `Git-Release`, `my--skill`, `-skill`, `skill-`
-
-## Discovery Locations
-
-Skills are discovered from these locations (in order of precedence):
-
-1. `~/.agents/skills/` (global, lowest priority)
-2. `.agents/skills/` (project, highest priority)
-
-Project skills override global skills with the same name.
-
-## How Agents Use Skills
-
-Agents see available skills listed in the `skill` tool description. When an agent needs a skill's instructions, it calls:
-
-```typescript
-skill({ name: "my-skill" })
-```
-
-The full SKILL.md content is then returned to the agent.

package/common/src/templates/initial-agents-dir/skills/example-skill/SKILL.md

@@ -1,29 +0,0 @@
----
-name: example-skill
-description: An example skill demonstrating the SKILL.md format
-license: MIT
-metadata:
-  category: examples
-  audience: developers
----
-
-# Example Skill
-
-This is an example skill that demonstrates the SKILL.md format.
-
-## When to use this skill
-
-Use this skill when you need an example of how skills work.
-
-## Instructions
-
-1. Skills are loaded on-demand via the `skill` tool
-2. The agent sees available skills listed in the tool description
-3. When needed, the agent calls `skill({ name: "example-skill" })` to load the full content
-4. The skill content is then available in the conversation context
-
-## Notes
-
-- Skills should have clear, specific descriptions
-- The name must be lowercase alphanumeric with hyphens
-- The name must match the directory name