@codeany/open-agent-sdk 0.1.0

package/src/tools/agent-tool.ts

@@ -0,0 +1,153 @@
+/**
+ * AgentTool - Spawn subagents for parallel/delegated work
+ *
+ * Supports built-in agents (Explore, Plan) and custom agent definitions.
+ * Agents run as nested query loops with their own context and tool sets.
+ */
+
+import type { ToolDefinition, ToolContext, ToolResult, AgentDefinition } from '../types.js'
+import { QueryEngine } from '../engine.js'
+import { getAllBaseTools, filterTools } from './index.js'
+import { toApiTool } from './types.js'
+
+// Store for registered agent definitions
+let registeredAgents: Record<string, AgentDefinition> = {}
+
+/**
+ * Register agent definitions for the AgentTool to use.
+ */
+export function registerAgents(agents: Record<string, AgentDefinition>): void {
+  registeredAgents = { ...registeredAgents, ...agents }
+}
+
+/**
+ * Clear registered agents.
+ */
+export function clearAgents(): void {
+  registeredAgents = {}
+}
+
+/**
+ * Built-in agent definitions.
+ */
+const BUILTIN_AGENTS: Record<string, AgentDefinition> = {
+  Explore: {
+    description: 'Fast agent for exploring codebases. Use for finding files, searching code, and answering questions about the codebase.',
+    prompt: 'You are a codebase exploration agent. Search through files and code to answer questions. Be thorough but efficient. Use Glob to find files, Grep to search content, and Read to examine files.',
+    tools: ['Read', 'Glob', 'Grep', 'Bash'],
+  },
+  Plan: {
+    description: 'Software architect agent for designing implementation plans. Returns step-by-step plans and identifies critical files.',
+    prompt: 'You are a software architect. Design implementation plans for the given task. Identify critical files, consider trade-offs, and provide step-by-step plans. Use search tools to understand the codebase before planning.',
+    tools: ['Read', 'Glob', 'Grep', 'Bash'],
+  },
+}
+
+export const AgentTool: ToolDefinition = {
+  name: 'Agent',
+  description: 'Launch a subagent to handle complex, multi-step tasks autonomously. Subagents have their own context and can run specialized tool sets.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'The task for the agent to perform',
+      },
+      description: {
+        type: 'string',
+        description: 'A short (3-5 word) description of the task',
+      },
+      subagent_type: {
+        type: 'string',
+        description: 'The type of agent to use (e.g., "Explore", "Plan", or a custom agent name)',
+      },
+      model: {
+        type: 'string',
+        description: 'Optional model override for this agent',
+      },
+      name: {
+        type: 'string',
+        description: 'Name for the spawned agent',
+      },
+      run_in_background: {
+        type: 'boolean',
+        description: 'Whether to run in background',
+      },
+    },
+    required: ['prompt', 'description'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  isEnabled: () => true,
+  async prompt() {
+    return 'Launch a subagent to handle complex tasks autonomously.'
+  },
+  async call(input: any, context: ToolContext): Promise<ToolResult> {
+    const agentType = input.subagent_type || 'general-purpose'
+
+    // Find agent definition
+    const agentDef = registeredAgents[agentType] || BUILTIN_AGENTS[agentType]
+
+    // Determine tools for subagent
+    let tools = getAllBaseTools()
+    if (agentDef?.tools) {
+      tools = filterTools(tools, agentDef.tools)
+    }
+
+    // Remove AgentTool from subagent to prevent infinite recursion
+    tools = tools.filter(t => t.name !== 'Agent')
+
+    // Build system prompt
+    const systemPrompt = agentDef?.prompt ||
+      'You are a helpful assistant. Complete the given task using the available tools.'
+
+    // Create subagent engine
+    const engine = new QueryEngine({
+      cwd: context.cwd,
+      model: input.model || process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+      tools,
+      systemPrompt,
+      maxTurns: agentDef?.maxTurns || 10,
+      maxTokens: 16384,
+      canUseTool: async () => ({ behavior: 'allow' }),
+      includePartialMessages: false,
+    })
+
+    // Run the subagent
+    let resultText = ''
+    let toolCalls: string[] = []
+
+    try {
+      for await (const event of engine.submitMessage(input.prompt)) {
+        if (event.type === 'assistant') {
+          for (const block of event.message.content) {
+            if ('text' in block && block.text) {
+              resultText = block.text
+            }
+            if ('name' in block) {
+              toolCalls.push(block.name as string)
+            }
+          }
+        }
+      }
+    } catch (err: any) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Subagent error: ${err.message}`,
+        is_error: true,
+      }
+    }
+
+    const output = resultText || '(Subagent completed with no text output)'
+    const toolSummary = toolCalls.length > 0
+      ? `\n[Tools used: ${toolCalls.join(', ')}]`
+      : ''
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: output + toolSummary,
+    }
+  },
+}

package/src/tools/ask-user.ts

@@ -0,0 +1,79 @@
+/**
+ * AskUserQuestionTool - Interactive user questions
+ *
+ * In SDK mode, returns a permission_request event and waits
+ * for the consumer to provide an answer.
+ * In non-interactive mode, returns a default or denies.
+ */
+
+import type { ToolDefinition, ToolResult } from '../types.js'
+
+// Callback for handling user questions (set by the agent)
+let questionHandler: ((question: string, options?: string[]) => Promise<string>) | null = null
+
+/**
+ * Set the question handler for AskUserQuestion.
+ */
+export function setQuestionHandler(
+  handler: (question: string, options?: string[]) => Promise<string>,
+): void {
+  questionHandler = handler
+}
+
+/**
+ * Clear the question handler.
+ */
+export function clearQuestionHandler(): void {
+  questionHandler = null
+}
+
+export const AskUserQuestionTool: ToolDefinition = {
+  name: 'AskUserQuestion',
+  description: 'Ask the user a question and wait for their response. Use when you need clarification or input from the user.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      question: { type: 'string', description: 'The question to ask the user' },
+      options: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Optional list of choices for the user',
+      },
+      allow_multiselect: {
+        type: 'boolean',
+        description: 'Whether to allow multiple selections (for options)',
+      },
+    },
+    required: ['question'],
+  },
+  isReadOnly: () => true,
+  isConcurrencySafe: () => false,
+  isEnabled: () => true,
+  async prompt() { return 'Ask the user a question.' },
+  async call(input: any): Promise<ToolResult> {
+    if (questionHandler) {
+      try {
+        const answer = await questionHandler(input.question, input.options)
+        return {
+          type: 'tool_result',
+          tool_use_id: '',
+          content: answer,
+        }
+      } catch (err: any) {
+        return {
+          type: 'tool_result',
+          tool_use_id: '',
+          content: `User declined to answer: ${err.message}`,
+          is_error: true,
+        }
+      }
+    }
+
+    // Non-interactive: return informative message
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `[Non-interactive mode] Question: ${input.question}${input.options ? `\nOptions: ${input.options.join(', ')}` : ''}\n\nNo user available to answer. Proceeding with best judgment.`,
+    }
+  },
+}

package/src/tools/bash.ts

@@ -0,0 +1,75 @@
+/**
+ * BashTool - Execute shell commands
+ */
+
+import { spawn } from 'child_process'
+import { defineTool } from './types.js'
+
+export const BashTool = defineTool({
+  name: 'Bash',
+  description: 'Execute a bash command and return its output. Use for running shell commands, scripts, and system operations.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'The bash command to execute',
+      },
+      timeout: {
+        type: 'number',
+        description: 'Optional timeout in milliseconds (max 600000, default 120000)',
+      },
+    },
+    required: ['command'],
+  },
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  async call(input, context) {
+    const { command, timeout: userTimeout } = input
+    const timeoutMs = Math.min(userTimeout || 120000, 600000)
+
+    return new Promise<string>((resolve) => {
+      const chunks: Buffer[] = []
+      const errChunks: Buffer[] = []
+
+      const proc = spawn('bash', ['-c', command], {
+        cwd: context.cwd,
+        env: { ...process.env },
+        timeout: timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      proc.stdout?.on('data', (data: Buffer) => chunks.push(data))
+      proc.stderr?.on('data', (data: Buffer) => errChunks.push(data))
+
+      if (context.abortSignal) {
+        context.abortSignal.addEventListener('abort', () => {
+          proc.kill('SIGTERM')
+        }, { once: true })
+      }
+
+      proc.on('close', (code) => {
+        const stdout = Buffer.concat(chunks).toString('utf-8')
+        const stderr = Buffer.concat(errChunks).toString('utf-8')
+
+        let output = ''
+        if (stdout) output += stdout
+        if (stderr) output += (output ? '\n' : '') + stderr
+        if (code !== 0 && code !== null) {
+          output += `\nExit code: ${code}`
+        }
+
+        // Truncate very large outputs
+        if (output.length > 100000) {
+          output = output.slice(0, 50000) + '\n...(truncated)...\n' + output.slice(-50000)
+        }
+
+        resolve(output || '(no output)')
+      })
+
+      proc.on('error', (err) => {
+        resolve(`Error executing command: ${err.message}`)
+      })
+    })
+  },
+})

package/src/tools/config-tool.ts

@@ -0,0 +1,89 @@
+/**
+ * ConfigTool - Dynamic configuration management
+ *
+ * Get/set global configuration and session settings.
+ */
+
+import type { ToolDefinition, ToolResult } from '../types.js'
+
+// In-memory config store
+const configStore = new Map<string, unknown>()
+
+/**
+ * Get a config value.
+ */
+export function getConfig(key: string): unknown {
+  return configStore.get(key)
+}
+
+/**
+ * Set a config value.
+ */
+export function setConfig(key: string, value: unknown): void {
+  configStore.set(key, value)
+}
+
+/**
+ * Clear all config.
+ */
+export function clearConfig(): void {
+  configStore.clear()
+}
+
+export const ConfigTool: ToolDefinition = {
+  name: 'Config',
+  description: 'Get or set configuration values. Supports session-scoped settings.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['get', 'set', 'list'],
+        description: 'Operation to perform',
+      },
+      key: { type: 'string', description: 'Config key' },
+      value: { description: 'Config value (for set)' },
+    },
+    required: ['action'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Manage configuration settings.' },
+  async call(input: any): Promise<ToolResult> {
+    switch (input.action) {
+      case 'get': {
+        if (!input.key) {
+          return { type: 'tool_result', tool_use_id: '', content: 'key required for get', is_error: true }
+        }
+        const value = configStore.get(input.key)
+        return {
+          type: 'tool_result',
+          tool_use_id: '',
+          content: value !== undefined ? JSON.stringify(value) : `Config key "${input.key}" not found`,
+        }
+      }
+      case 'set': {
+        if (!input.key) {
+          return { type: 'tool_result', tool_use_id: '', content: 'key required for set', is_error: true }
+        }
+        configStore.set(input.key, input.value)
+        return {
+          type: 'tool_result',
+          tool_use_id: '',
+          content: `Config set: ${input.key} = ${JSON.stringify(input.value)}`,
+        }
+      }
+      case 'list': {
+        const entries = Array.from(configStore.entries())
+        if (entries.length === 0) {
+          return { type: 'tool_result', tool_use_id: '', content: 'No config values set.' }
+        }
+        const lines = entries.map(([k, v]) => `${k} = ${JSON.stringify(v)}`)
+        return { type: 'tool_result', tool_use_id: '', content: lines.join('\n') }
+      }
+      default:
+        return { type: 'tool_result', tool_use_id: '', content: `Unknown action: ${input.action}`, is_error: true }
+    }
+  },
+}

package/src/tools/cron-tools.ts

@@ -0,0 +1,153 @@
+/**
+ * Cron/Scheduling Tools
+ *
+ * CronCreate, CronDelete, CronList - Schedule recurring tasks.
+ * RemoteTrigger - Manage remote scheduled agent triggers.
+ */
+
+import type { ToolDefinition, ToolResult } from '../types.js'
+
+/**
+ * Cron job definition.
+ */
+export interface CronJob {
+  id: string
+  name: string
+  schedule: string // cron expression
+  command: string
+  enabled: boolean
+  createdAt: string
+  lastRunAt?: string
+  nextRunAt?: string
+}
+
+// In-memory cron store
+const cronStore = new Map<string, CronJob>()
+let cronCounter = 0
+
+/**
+ * Get all cron jobs.
+ */
+export function getAllCronJobs(): CronJob[] {
+  return Array.from(cronStore.values())
+}
+
+/**
+ * Clear all cron jobs.
+ */
+export function clearCronJobs(): void {
+  cronStore.clear()
+  cronCounter = 0
+}
+
+export const CronCreateTool: ToolDefinition = {
+  name: 'CronCreate',
+  description: 'Create a scheduled recurring task (cron job). Supports cron expressions for scheduling.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'Job name' },
+      schedule: { type: 'string', description: 'Cron expression (e.g., "*/5 * * * *" for every 5 minutes)' },
+      command: { type: 'string', description: 'Command or prompt to execute' },
+    },
+    required: ['name', 'schedule', 'command'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Create a scheduled cron job.' },
+  async call(input: any): Promise<ToolResult> {
+    const id = `cron_${++cronCounter}`
+    const job: CronJob = {
+      id,
+      name: input.name,
+      schedule: input.schedule,
+      command: input.command,
+      enabled: true,
+      createdAt: new Date().toISOString(),
+    }
+    cronStore.set(id, job)
+
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `Cron job created: ${id} "${job.name}" schedule="${job.schedule}"`,
+    }
+  },
+}
+
+export const CronDeleteTool: ToolDefinition = {
+  name: 'CronDelete',
+  description: 'Delete a scheduled cron job.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'Cron job ID to delete' },
+    },
+    required: ['id'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Delete a cron job.' },
+  async call(input: any): Promise<ToolResult> {
+    if (!cronStore.has(input.id)) {
+      return { type: 'tool_result', tool_use_id: '', content: `Cron job not found: ${input.id}`, is_error: true }
+    }
+    cronStore.delete(input.id)
+    return { type: 'tool_result', tool_use_id: '', content: `Cron job deleted: ${input.id}` }
+  },
+}
+
+export const CronListTool: ToolDefinition = {
+  name: 'CronList',
+  description: 'List all scheduled cron jobs.',
+  inputSchema: { type: 'object', properties: {} },
+  isReadOnly: () => true,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'List cron jobs.' },
+  async call(): Promise<ToolResult> {
+    const jobs = getAllCronJobs()
+    if (jobs.length === 0) {
+      return { type: 'tool_result', tool_use_id: '', content: 'No cron jobs scheduled.' }
+    }
+    const lines = jobs.map(j =>
+      `[${j.id}] ${j.enabled ? '✓' : '✗'} "${j.name}" schedule="${j.schedule}" command="${j.command.slice(0, 50)}"`
+    )
+    return { type: 'tool_result', tool_use_id: '', content: lines.join('\n') }
+  },
+}
+
+export const RemoteTriggerTool: ToolDefinition = {
+  name: 'RemoteTrigger',
+  description: 'Manage remote scheduled agent triggers. Supports list, get, create, update, and run operations.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['list', 'get', 'create', 'update', 'run'],
+        description: 'Operation to perform',
+      },
+      id: { type: 'string', description: 'Trigger ID (for get/update/run)' },
+      name: { type: 'string', description: 'Trigger name (for create)' },
+      schedule: { type: 'string', description: 'Cron schedule (for create/update)' },
+      prompt: { type: 'string', description: 'Agent prompt (for create/update)' },
+    },
+    required: ['action'],
+  },
+  isReadOnly: () => false,
+  isConcurrencySafe: () => true,
+  isEnabled: () => true,
+  async prompt() { return 'Manage remote agent triggers.' },
+  async call(input: any): Promise<ToolResult> {
+    // RemoteTrigger operations are typically handled by the remote backend
+    // In standalone SDK mode, we provide a stub implementation
+    return {
+      type: 'tool_result',
+      tool_use_id: '',
+      content: `RemoteTrigger ${input.action}: This feature requires a connected remote backend. In standalone SDK mode, use CronCreate/CronList/CronDelete for local scheduling.`,
+    }
+  },
+}

package/src/tools/edit.ts

@@ -0,0 +1,74 @@
+/**
+ * FileEditTool - Precise string replacement in files
+ */
+
+import { readFile, writeFile } from 'fs/promises'
+import { resolve } from 'path'
+import { defineTool } from './types.js'
+
+export const FileEditTool = defineTool({
+  name: 'Edit',
+  description: 'Perform exact string replacements in files. The old_string must match exactly (including whitespace and indentation). Use replace_all to change every occurrence.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'The absolute path to the file to modify',
+      },
+      old_string: {
+        type: 'string',
+        description: 'The exact text to find and replace',
+      },
+      new_string: {
+        type: 'string',
+        description: 'The replacement text',
+      },
+      replace_all: {
+        type: 'boolean',
+        description: 'Replace all occurrences (default false)',
+      },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+  },
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  async call(input, context) {
+    const filePath = resolve(context.cwd, input.file_path)
+    const { old_string, new_string, replace_all } = input
+
+    if (old_string === new_string) {
+      return { data: 'Error: old_string and new_string are identical', is_error: true }
+    }
+
+    try {
+      let content = await readFile(filePath, 'utf-8')
+
+      if (!content.includes(old_string)) {
+        return { data: `Error: old_string not found in ${filePath}. Make sure it matches exactly including whitespace.`, is_error: true }
+      }
+
+      if (!replace_all) {
+        // Check uniqueness
+        const count = content.split(old_string).length - 1
+        if (count > 1) {
+          return {
+            data: `Error: old_string appears ${count} times in the file. Provide more context to make it unique, or set replace_all: true.`,
+            is_error: true,
+          }
+        }
+        content = content.replace(old_string, new_string)
+      } else {
+        content = content.split(old_string).join(new_string)
+      }
+
+      await writeFile(filePath, content, 'utf-8')
+      return `File edited: ${filePath}`
+    } catch (err: any) {
+      if (err.code === 'ENOENT') {
+        return { data: `Error: File not found: ${filePath}`, is_error: true }
+      }
+      return { data: `Error editing file: ${err.message}`, is_error: true }
+    }
+  },
+})

package/src/tools/glob.ts

@@ -0,0 +1,77 @@
+/**
+ * GlobTool - File pattern matching
+ */
+
+import { resolve } from 'path'
+import { defineTool } from './types.js'
+
+export const GlobTool = defineTool({
+  name: 'Glob',
+  description: 'Find files matching a glob pattern. Returns matching file paths sorted by modification time. Supports patterns like "**/*.ts", "src/**/*.js".',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      pattern: {
+        type: 'string',
+        description: 'The glob pattern to match files against',
+      },
+      path: {
+        type: 'string',
+        description: 'The directory to search in (defaults to cwd)',
+      },
+    },
+    required: ['pattern'],
+  },
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  async call(input, context) {
+    const searchDir = input.path ? resolve(context.cwd, input.path) : context.cwd
+    const { pattern } = input
+
+    try {
+      // Use Node.js glob (available in Node 22+) or fall back to bash find
+      const { glob } = await import('fs/promises')
+
+      // @ts-ignore - glob is available in Node 22+
+      if (typeof glob === 'function') {
+        const matches: string[] = []
+        // @ts-ignore
+        for await (const entry of glob(pattern, { cwd: searchDir })) {
+          matches.push(entry)
+          if (matches.length >= 500) break
+        }
+        if (matches.length === 0) {
+          return `No files matching pattern "${pattern}" in ${searchDir}`
+        }
+        return matches.join('\n')
+      }
+    } catch {
+      // Fall through to bash-based approach
+    }
+
+    // Fallback: use bash find/glob
+    const { spawn } = await import('child_process')
+    return new Promise<string>((resolvePromise) => {
+      // Use bash glob expansion or find
+      const cmd = `shopt -s globstar nullglob 2>/dev/null; cd ${JSON.stringify(searchDir)} && ls -1d ${pattern} 2>/dev/null | head -500`
+      const proc = spawn('bash', ['-c', cmd], {
+        cwd: searchDir,
+        timeout: 30000,
+      })
+
+      const chunks: Buffer[] = []
+      proc.stdout?.on('data', (d: Buffer) => chunks.push(d))
+      proc.on('close', () => {
+        const result = Buffer.concat(chunks).toString('utf-8').trim()
+        if (!result) {
+          resolvePromise(`No files matching pattern "${pattern}" in ${searchDir}`)
+        } else {
+          resolvePromise(result)
+        }
+      })
+      proc.on('error', () => {
+        resolvePromise(`Error searching for files with pattern "${pattern}"`)
+      })
+    })
+  },
+})