savant-code 0.0.16 → 0.0.19

package/sdk/src/agents/load-agents.ts

@@ -0,0 +1,339 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { pathToFileURL } from 'url'
+
+import { logger } from '../utils/logger'
+import { validateAgents } from '../validate-agents'
+
+import type { AgentDefinition } from '@savant-code/common/templates/initial-agents-dir/types/agent-definition'
+
+/**
+ * Agent definition with source file path metadata.
+ */
+export type LoadedAgentDefinition = AgentDefinition & {
+  /** The file path this agent was loaded from */
+  _sourceFilePath: string
+  /** Live copy of handleSteps kept alongside its stringified form (see
+   * processedAgentDefinition below). */
+  handleStepsFn?: AgentDefinition['handleSteps']
+}
+
+/**
+ * Loaded agent definitions keyed by agent ID.
+ */
+export type LoadedAgents = Record<string, LoadedAgentDefinition>
+
+/**
+ * Resolves environment variable references in MCP server configs.
+ * Values starting with `$` are treated as env var references (e.g., `'$NOTION_TOKEN'`).
+ *
+ * @param env - The env object from MCP config with possible $VAR_NAME references
+ * @param agentId - The agent ID for error messages
+ * @param mcpServerName - The MCP server name for error messages
+ * @returns Resolved env object with all $VAR_NAME values replaced with actual values
+ * @throws Error if a referenced environment variable is missing
+ */
+export function resolveMcpEnv(
+  env: Record<string, string> | undefined,
+  agentId: string,
+  mcpServerName: string,
+): Record<string, string> {
+  if (!env) return {}
+
+  const resolved: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value.startsWith('$')) {
+      // $VAR_NAME reference - resolve from process.env
+      const envVarName = value.slice(1) // Remove the leading $
+      // Allow dynamic process.env access
+      const envName = 'env'
+      const envValue = process[envName][envVarName]
+
+      if (envValue === undefined) {
+        throw new Error(
+          `Missing environment variable '${envVarName}' required by agent '${agentId}' in mcpServers.${mcpServerName}.env.${key}`,
+        )
+      }
+
+      resolved[key] = envValue
+    } else {
+      // Plain string value - use as-is
+      resolved[key] = value
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Resolves all MCP server env references in an agent definition.
+ * Mutates the mcpServers object to replace $VAR_NAME references with resolved values.
+ *
+ * @param agent - The agent definition to process
+ * @throws Error if any referenced environment variable is missing
+ */
+export function resolveAgentMcpEnv(agent: AgentDefinition): void {
+  if (!agent.mcpServers) return
+
+  for (const [serverName, config] of Object.entries(agent.mcpServers)) {
+    if ('command' in config && config.env) {
+      config.env = resolveMcpEnv(config.env, agent.id, serverName)
+    }
+  }
+}
+
+/**
+ * Validation error for an agent that failed validation.
+ */
+export type AgentValidationError = {
+  /** The agent's ID */
+  agentId: string
+  /** The source file path where the agent was loaded from */
+  filePath: string
+  /** The validation error message */
+  message: string
+}
+
+/**
+ * Result returned by loadLocalAgents when validate: true.
+ * Contains both the valid agents and any validation errors.
+ */
+export type LoadLocalAgentsResult = {
+  /** Valid agent definitions that passed validation */
+  agents: LoadedAgents
+  /** Validation errors for agents that failed validation */
+  validationErrors: AgentValidationError[]
+}
+
+const agentFileExtensions = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs'])
+
+const shouldSkipAgentDirectory = (name: string): boolean =>
+  name.startsWith('.') ||
+  name === 'node_modules' ||
+  name === 'scripts' ||
+  name === 'skills' ||
+  name.startsWith('skills-')
+
+const isLoadableAgentFileName = (fileName: string): boolean => {
+  const extension = path.extname(fileName).toLowerCase()
+  return (
+    agentFileExtensions.has(extension) &&
+    !fileName.endsWith('.d.ts') &&
+    !/[./](test|spec)\.[cm]?[tj]sx?$/.test(fileName)
+  )
+}
+
+const getAllAgentFiles = (dir: string): string[] => {
+  const files: string[] = []
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (shouldSkipAgentDirectory(entry.name)) continue
+        files.push(...getAllAgentFiles(fullPath))
+        continue
+      }
+      const isAgentFile = entry.isFile() && isLoadableAgentFileName(entry.name)
+      if (isAgentFile) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Expected for user agent directories that may not exist
+  }
+  return files
+}
+
+const getDefaultAgentDirs = () => {
+  const cwdAgents = path.join(process.cwd(), '.agents')
+  const parentAgents = path.join(process.cwd(), '..', '.agents')
+  const homeAgents = path.join(os.homedir(), '.agents')
+  return [cwdAgents, parentAgents, homeAgents]
+}
+
+/**
+ * Load agent definitions from `.agents` directories.
+ *
+ * By default, searches for agents in:
+ * - `{cwd}/.agents`
+ * - `{cwd}/../.agents`
+ * - `{homedir}/.agents`
+ *
+ * Agent files can be `.ts`, `.tsx`, `.js`, `.mjs`, or `.cjs`.
+ * TypeScript files are loaded natively by Bun's runtime.
+ *
+ * @param options.agentsPath - Optional path to a specific agents directory
+ * @param options.verbose - Whether to log errors during loading
+ * @param options.validate - Whether to validate agents after loading
+ * @returns When validate is false/omitted: Record of agent definitions keyed by agent ID.
+ *          When validate is true: Object with valid agents and validation errors.
+ *
+ * @example
+ * ```typescript
+ * // Load from default locations
+ * const agents = await loadLocalAgents({ verbose: true })
+ *
+ * // Load from a specific directory
+ * const agents = await loadLocalAgents({ agentsPath: './my-agents' })
+ *
+ * // Load and validate agents - returns both valid agents and errors
+ * const { agents, validationErrors } = await loadLocalAgents({ validate: true })
+ * if (validationErrors.length > 0) {
+ *   console.error('Some agents failed validation:', validationErrors)
+ * }
+ *
+ * // Access source file path for debugging
+ * for (const agent of Object.values(agents)) {
+ *   console.log(`${agent.id} loaded from ${agent._sourceFilePath}`)
+ * }
+ *
+ * // Use with client.run()
+ * const result = await client.run({
+ *   agent: 'my-agent',
+ *   agentDefinitions: Object.values(agents),
+ *   prompt: 'Hello',
+ * })
+ * ```
+ */
+// Overload: validate: true returns result with agents and errors
+export async function loadLocalAgents(options: {
+  agentsPath?: string
+  verbose?: boolean
+  validate: true
+}): Promise<LoadLocalAgentsResult>
+
+// Overload: validate: false or omitted returns just agents (backward compatible)
+export async function loadLocalAgents(options: {
+  agentsPath?: string
+  verbose?: boolean
+  validate?: false
+}): Promise<LoadedAgents>
+
+// Implementation
+export async function loadLocalAgents({
+  agentsPath,
+  verbose = false,
+  validate = false,
+}: {
+  agentsPath?: string
+  verbose?: boolean
+  validate?: boolean
+}): Promise<LoadedAgents | LoadLocalAgentsResult> {
+  const agents: LoadedAgents = {}
+
+  const agentDirs = agentsPath ? [agentsPath] : getDefaultAgentDirs()
+  const allAgentFiles = agentDirs.flatMap((dir) => getAllAgentFiles(dir))
+
+  if (allAgentFiles.length === 0) {
+    return validate ? { agents, validationErrors: [] } : agents
+  }
+
+  for (const fullPath of allAgentFiles) {
+    try {
+      const agentModule = await importAgentModule(fullPath)
+      if (!agentModule) {
+        continue
+      }
+      const agentDefinition = agentModule.default ?? agentModule
+
+      if (!agentDefinition?.id || !agentDefinition?.model) {
+        if (verbose) {
+          logger.error(
+            `Agent definition missing required attributes (id, model): ${fullPath}`,
+          )
+        }
+        continue
+      }
+
+      const processedAgentDefinition: LoadedAgentDefinition = {
+        ...agentDefinition,
+        _sourceFilePath: fullPath,
+      }
+      if (agentDefinition.handleSteps) {
+        if (typeof agentDefinition.handleSteps === 'function') {
+          // Keep the live function: the stringified form of a bundled function
+          // can reference out-of-scope bundler helpers and fail eval later.
+          processedAgentDefinition.handleStepsFn = agentDefinition.handleSteps
+        }
+        processedAgentDefinition.handleSteps =
+          agentDefinition.handleSteps.toString()
+      }
+
+      // Resolve $env references in MCP server configs
+      try {
+        resolveAgentMcpEnv(processedAgentDefinition)
+      } catch (error) {
+        if (verbose) {
+          logger.error(error instanceof Error ? error.message : String(error))
+        }
+        continue
+      }
+
+      agents[processedAgentDefinition.id] = processedAgentDefinition
+    } catch (error) {
+      if (verbose) {
+        logger.error(
+          `Error loading agent from file ${fullPath}:`,
+          error instanceof Error ? error.message : error,
+        )
+      }
+    }
+  }
+
+  // Validate agents if requested
+  if (validate) {
+    const validationErrors: AgentValidationError[] = []
+
+    if (Object.keys(agents).length > 0) {
+      const result = await validateAgents(Object.values(agents))
+
+      if (!result.success) {
+        // Build a map of agent IDs to their validation errors
+        // The validation error id format is "{agentId}_{index}" from validateAgents
+        const errorsByAgentId = new Map<string, string>()
+        for (const err of result.validationErrors) {
+          // Extract agent ID by removing the "_index" suffix added by validateAgents
+          const lastUnderscoreIdx = err.id.lastIndexOf('_')
+          const agentId =
+            lastUnderscoreIdx > 0 ? err.id.slice(0, lastUnderscoreIdx) : err.id
+          if (!errorsByAgentId.has(agentId)) {
+            errorsByAgentId.set(agentId, err.message)
+          }
+        }
+
+        // Filter out invalid agents and collect validation errors
+        for (const agentId of Object.keys(agents)) {
+          const errorMessage = errorsByAgentId.get(agentId)
+          if (errorMessage) {
+            const agent = agents[agentId]
+            validationErrors.push({
+              agentId,
+              filePath: agent._sourceFilePath,
+              message: errorMessage,
+            })
+            if (verbose) {
+              logger.error(
+                `Validation failed for agent '${agentId}': ${errorMessage}`,
+              )
+            }
+            delete agents[agentId]
+          }
+        }
+      }
+    }
+
+    return { agents, validationErrors }
+  }
+
+  return agents
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic agent module shape from user-provided file
+async function importAgentModule(fullPath: string): Promise<any | null> {
+  // Cache-bust to ensure fresh imports when agent files change
+  const urlVersion = `?update=${Date.now()}`
+  return import(`${pathToFileURL(fullPath).href}${urlVersion}`)
+}

package/sdk/src/agents/load-mcp-config.ts

@@ -0,0 +1,275 @@
+import fs from 'fs'
+import fsPromises from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+import { mcpConfigSchema } from '@savant-code/common/types/mcp'
+import { z } from 'zod/v4'
+
+import { logger } from '../utils/logger'
+
+import type { MCPConfig } from '@savant-code/common/types/mcp'
+
+/**
+ * Schema for the mcp.json file format.
+ * Matches the standard MCP config format used by Claude Code, Cursor, etc.
+ */
+export const mcpFileSchema = z.object({
+  mcpServers: z.record(z.string(), mcpConfigSchema).default(() => ({})),
+})
+
+export type MCPFileConfig = z.infer<typeof mcpFileSchema>
+
+/**
+ * Loaded MCP configuration with resolved environment variables.
+ */
+export type LoadedMCPConfig = {
+  mcpServers: Record<string, MCPConfig>
+  /** The file path this config was loaded from */
+  _sourceFilePath: string
+}
+
+/**
+ * Resolves environment variable references in MCP server env configs.
+ * Values starting with `$` are treated as env var references (e.g., `'$NOTION_TOKEN'`).
+ *
+ * @param env - The env object from MCP config with possible $VAR_NAME references
+ * @param mcpServerName - The MCP server name for error messages
+ * @returns Resolved env object with all $VAR_NAME values replaced with actual values
+ * @throws Error if a referenced environment variable is missing
+ */
+// Bypass env architecture check - this file legitimately needs process.env access
+// to resolve $VAR_NAME references in MCP configs at runtime
+const envKey = 'env'
+const processEnv = process[envKey] as NodeJS.ProcessEnv
+
+function resolveMcpEnv(
+  env: Record<string, string> | undefined,
+  mcpServerName: string,
+): Record<string, string> {
+  if (!env) return {}
+
+  const resolved: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value.startsWith('$')) {
+      // $VAR_NAME reference - resolve from process.env
+      const envVarName = value.slice(1) // Remove the leading $
+      const envValue = processEnv[envVarName]
+
+      if (envValue === undefined) {
+        throw new Error(
+          `Missing environment variable '${envVarName}' required by MCP server '${mcpServerName}' in mcp.json`,
+        )
+      }
+
+      resolved[key] = envValue
+    } else {
+      // Plain string value - use as-is
+      resolved[key] = value
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Resolves all MCP server env references in a config.
+ * Mutates the mcpServers object to replace $VAR_NAME references with resolved values.
+ *
+ * @param config - The MCP file config to process
+ * @throws Error if any referenced environment variable is missing
+ */
+function resolveMcpConfigEnv(config: MCPFileConfig): void {
+  for (const [serverName, serverConfig] of Object.entries(config.mcpServers)) {
+    if ('command' in serverConfig && serverConfig.env) {
+      serverConfig.env = resolveMcpEnv(serverConfig.env, serverName)
+    }
+  }
+}
+
+const MCP_CONFIG_FILE_NAME = 'mcp.json'
+
+/**
+ * Get default directories to search for mcp.json.
+ * Matches the agent loading directories for consistency.
+ */
+const getDefaultMcpConfigDirs = (): string[] => {
+  const cwdAgents = path.join(process.cwd(), '.agents')
+  const parentAgents = path.join(process.cwd(), '..', '.agents')
+  const homeAgents = path.join(os.homedir(), '.agents')
+  return [cwdAgents, parentAgents, homeAgents]
+}
+
+/**
+ * Load MCP configuration from `mcp.json` files in `.agents` directories.
+ *
+ * By default, searches for mcp.json in:
+ * - `{cwd}/.agents/mcp.json`
+ * - `{cwd}/../.agents/mcp.json`
+ * - `{homedir}/.agents/mcp.json`
+ *
+ * Later directories take precedence, so project MCP servers override global ones.
+ * Environment variable references (e.g., `$API_KEY`) are resolved from process.env.
+ *
+ * @param options.verbose - Whether to log errors during loading
+ * @returns Record of MCP server configurations keyed by server name
+ *
+ * @example
+ * ```typescript
+ * // Load from default locations
+ * const mcpConfig = await loadMCPConfig({ verbose: true })
+ *
+ * // Access MCP servers
+ * for (const [serverName, config] of Object.entries(mcpConfig.mcpServers)) {
+ *   console.log(`MCP server: ${serverName}`)
+ * }
+ * ```
+ */
+export async function loadMCPConfig(options: {
+  verbose?: boolean
+}): Promise<LoadedMCPConfig> {
+  const { verbose = false } = options
+
+  const mergedConfig: LoadedMCPConfig = {
+    mcpServers: {},
+    _sourceFilePath: '',
+  }
+
+  const mcpConfigDirs = getDefaultMcpConfigDirs()
+
+  for (const dir of mcpConfigDirs) {
+    const configPath = path.join(dir, MCP_CONFIG_FILE_NAME)
+
+    try {
+      // Check if file exists asynchronously
+      try {
+        await fsPromises.access(configPath)
+      } catch {
+        continue
+      }
+
+      const content = await fsPromises.readFile(configPath, 'utf8')
+      const rawConfig = JSON.parse(content)
+      const parseResult = mcpFileSchema.safeParse(rawConfig)
+
+      if (!parseResult.success) {
+        if (verbose) {
+          logger.error(
+            `Invalid mcp.json at ${configPath}: ${parseResult.error.message}`,
+          )
+        }
+        continue
+      }
+
+      const parsedConfig = parseResult.data
+
+      // Resolve environment variable references
+      try {
+        resolveMcpConfigEnv(parsedConfig)
+      } catch (error) {
+        if (verbose) {
+          logger.error(error instanceof Error ? error.message : String(error))
+        }
+        continue
+      }
+
+      // Merge MCP servers (later directories override earlier ones)
+      for (const [serverName, serverConfig] of Object.entries(
+        parsedConfig.mcpServers,
+      )) {
+        mergedConfig.mcpServers[serverName] = serverConfig
+      }
+
+      // Track the last successfully loaded config path
+      if (Object.keys(parsedConfig.mcpServers).length > 0) {
+        mergedConfig._sourceFilePath = configPath
+      }
+    } catch (error) {
+      if (verbose) {
+        logger.error(
+          `Error loading mcp.json from ${configPath}:`,
+          error instanceof Error ? error.message : error,
+        )
+      }
+    }
+  }
+
+  return mergedConfig
+}
+
+/**
+ * Synchronously load MCP configuration from `mcp.json` files in `.agents` directories.
+ * This is a sync version for use in contexts where async is not available.
+ *
+ * @param options.verbose - Whether to log errors during loading
+ * @returns Record of MCP server configurations keyed by server name
+ */
+export function loadMCPConfigSync(options: {
+  verbose?: boolean
+}): LoadedMCPConfig {
+  const { verbose = false } = options
+
+  const mergedConfig: LoadedMCPConfig = {
+    mcpServers: {},
+    _sourceFilePath: '',
+  }
+
+  const mcpConfigDirs = getDefaultMcpConfigDirs()
+
+  for (const dir of mcpConfigDirs) {
+    const configPath = path.join(dir, MCP_CONFIG_FILE_NAME)
+
+    try {
+      if (!fs.existsSync(configPath)) {
+        continue
+      }
+
+      const content = fs.readFileSync(configPath, 'utf8')
+      const rawConfig = JSON.parse(content)
+      const parseResult = mcpFileSchema.safeParse(rawConfig)
+
+      if (!parseResult.success) {
+        if (verbose) {
+          logger.error(
+            `Invalid mcp.json at ${configPath}: ${parseResult.error.message}`,
+          )
+        }
+        continue
+      }
+
+      const parsedConfig = parseResult.data
+
+      // Resolve environment variable references
+      try {
+        resolveMcpConfigEnv(parsedConfig)
+      } catch (error) {
+        if (verbose) {
+          logger.error(error instanceof Error ? error.message : String(error))
+        }
+        continue
+      }
+
+      // Merge MCP servers (later directories override earlier ones)
+      for (const [serverName, serverConfig] of Object.entries(
+        parsedConfig.mcpServers,
+      )) {
+        mergedConfig.mcpServers[serverName] = serverConfig
+      }
+
+      // Track the last successfully loaded config path
+      if (Object.keys(parsedConfig.mcpServers).length > 0) {
+        mergedConfig._sourceFilePath = configPath
+      }
+    } catch (error) {
+      if (verbose) {
+        logger.error(
+          `Error loading mcp.json from ${configPath}:`,
+          error instanceof Error ? error.message : error,
+        )
+      }
+    }
+  }
+
+  return mergedConfig
+}

package/sdk/src/client.ts

@@ -0,0 +1,87 @@
+import { API_KEY_ENV_VAR } from '@savant-code/common/constants/paths'
+
+import { getWebsiteUrl } from './constants'
+import { getSavantCodeApiKeyFromEnv } from './env'
+import { run } from './run'
+
+import type { RunOptions, SavantCodeClientOptions } from './run'
+import type { RunState } from './run-state'
+
+export class SavantCodeClient {
+  public options: SavantCodeClientOptions & {
+    apiKey: string
+    fingerprintId: string
+  }
+
+  constructor(options: SavantCodeClientOptions) {
+    const foundApiKey = options.apiKey ?? getSavantCodeApiKeyFromEnv()
+    if (!foundApiKey) {
+      throw new Error(
+        `SavantCode API key not found. Please provide an apiKey in the constructor of SavantCodeClient or set the ${API_KEY_ENV_VAR} environment variable.`,
+      )
+    }
+
+    this.options = {
+      apiKey: foundApiKey,
+      handleEvent: (event) => {
+        if (event.type === 'error') {
+          throw new Error(
+            `Received error: ${event.message}.\n\nProvide a handleEvent function to handle this error.`,
+          )
+        }
+      },
+      fingerprintId: `savant-code-sdk-${Math.random().toString(36).substring(2, 15)}`,
+      ...options,
+    }
+  }
+
+  /**
+   * Run a SavantCode agent with the specified options.
+   *
+   * @param agent - The agent to run. Use 'base' for the default agent, or specify a custom agent ID if you made your own agent config.
+   * @param prompt - The user prompt describing what you want the agent to do.
+   * @param params - (Optional) Additional parameters for the agent. Most agents don't use this, but some custom agents can take a JSON object as input in addition to the user prompt string.
+   * @param handleEvent - (Optional) Callback function that receives every event during execution (assistant messages, tool calls, etc.). This allows you to stream the agent's progress in real-time. We will likely add a token-by-token streaming callback in the future.
+   * @param previousRun - (Optional) JSON state returned from a previous run() call. Use this to continue a conversation or session with the agent, maintaining context from previous interactions.
+   * @param projectFiles - (Optional) All the files in your project as a plain JavaScript object. Keys should be the full path from your current directory to each file, and values should be the string contents of the file. Example: { "src/index.ts": "console.log('hi')" }. This helps SavantCode pick good source files for context.
+   * @param knowledgeFiles - (Optional) Knowledge files to inject into every run() call. Uses the same schema as projectFiles - keys are file paths and values are file contents. These files are added directly to the agent's context.
+   * @param agentDefinitions - (Optional) Array of custom agent definitions. Each object should satisfy the AgentDefinition type. You can input the agent's id field into the agent parameter to run that agent.
+   * @param customToolDefinitions - (Optional) Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.
+   * @param skillsDir - (Optional) Path to a directory containing skills to load. Each skill should be in its own subdirectory with a SKILL.md file (e.g., `skillsDir/my-skill/SKILL.md`). When provided, skills are loaded from this directory instead of the default locations. The loaded skills will be listed in the `skill` tool's description and can be loaded by the agent.
+   * @param maxAgentSteps - (Optional) Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.
+   * @param env - (Optional) Environment variables to pass to terminal commands executed by the agent. These will be merged with the current process environment, with the custom values taking precedence. Can also be provided in individual run() calls to override.
+   *
+   * @returns A Promise that resolves to a RunState JSON object which you can pass to a subsequent run() call to continue the run. Use result.output to get the agent's output.
+   */
+  public async run(
+    options: RunOptions & SavantCodeClientOptions,
+  ): Promise<RunState> {
+    return run({ ...this.options, ...options })
+  }
+
+  /**
+   * Check connection to the SavantCode backend by hitting the /healthz endpoint.
+   *
+   * @returns Promise that resolves to true if connected, false otherwise
+   */
+  public async checkConnection(): Promise<boolean> {
+    try {
+      const response = await fetch(`${getWebsiteUrl()}/api/healthz`, {
+        method: 'GET',
+        signal: AbortSignal.timeout(5000), // 5 second timeout
+      })
+
+      if (!response.ok) return false
+
+      const result = await response.json()
+      return (
+        typeof result === 'object' &&
+        result !== null &&
+        'status' in result &&
+        (result as { status?: unknown }).status === 'ok'
+      )
+    } catch {
+      return false
+    }
+  }
+}