@codeany/open-agent-sdk 0.2.1 → 0.2.3

package/src/skills/registry.ts

@@ -1,133 +0,0 @@
-/**
- * Skill Registry
- *
- * Central registry for managing skill definitions.
- * Skills can be registered programmatically or loaded from bundled definitions.
- */
-
-import type { SkillDefinition } from './types.js'
-
-/** Internal skill store */
-const skills: Map<string, SkillDefinition> = new Map()
-
-/** Alias -> skill name mapping */
-const aliases: Map<string, string> = new Map()
-
-/**
- * Register a skill definition.
- */
-export function registerSkill(definition: SkillDefinition): void {
-  skills.set(definition.name, definition)
-
-  // Register aliases
-  if (definition.aliases) {
-    for (const alias of definition.aliases) {
-      aliases.set(alias, definition.name)
-    }
-  }
-}
-
-/**
- * Get a skill by name or alias.
- */
-export function getSkill(name: string): SkillDefinition | undefined {
-  // Direct lookup
-  const direct = skills.get(name)
-  if (direct) return direct
-
-  // Alias lookup
-  const resolved = aliases.get(name)
-  if (resolved) return skills.get(resolved)
-
-  return undefined
-}
-
-/**
- * Get all registered skills.
- */
-export function getAllSkills(): SkillDefinition[] {
-  return Array.from(skills.values())
-}
-
-/**
- * Get all user-invocable skills (for /command listing).
- */
-export function getUserInvocableSkills(): SkillDefinition[] {
-  return getAllSkills().filter(
-    (s) => s.userInvocable !== false && (!s.isEnabled || s.isEnabled()),
-  )
-}
-
-/**
- * Check if a skill exists.
- */
-export function hasSkill(name: string): boolean {
-  return skills.has(name) || aliases.has(name)
-}
-
-/**
- * Remove a skill.
- */
-export function unregisterSkill(name: string): boolean {
-  const skill = skills.get(name)
-  if (!skill) return false
-
-  // Remove aliases
-  if (skill.aliases) {
-    for (const alias of skill.aliases) {
-      aliases.delete(alias)
-    }
-  }
-
-  return skills.delete(name)
-}
-
-/**
- * Clear all skills (for testing).
- */
-export function clearSkills(): void {
-  skills.clear()
-  aliases.clear()
-}
-
-/**
- * Format skills listing for system prompt injection.
- *
- * Uses a budget system: skills listing gets a limited character budget
- * to avoid bloating the context window.
- */
-export function formatSkillsForPrompt(
-  contextWindowTokens?: number,
-): string {
-  const invocable = getUserInvocableSkills()
-  if (invocable.length === 0) return ''
-
-  // Budget: 1% of context window in characters (4 chars per token)
-  const CHARS_PER_TOKEN = 4
-  const DEFAULT_BUDGET = 8000
-  const MAX_DESC_CHARS = 250
-  const budget = contextWindowTokens
-    ? Math.floor(contextWindowTokens * 0.01 * CHARS_PER_TOKEN)
-    : DEFAULT_BUDGET
-
-  const lines: string[] = []
-  let used = 0
-
-  for (const skill of invocable) {
-    const desc = skill.description.length > MAX_DESC_CHARS
-      ? skill.description.slice(0, MAX_DESC_CHARS) + '...'
-      : skill.description
-
-    const trigger = skill.whenToUse
-      ? ` TRIGGER when: ${skill.whenToUse}`
-      : ''
-
-    const line = `- ${skill.name}: ${desc}${trigger}`
-
-    if (used + line.length > budget) break
-    lines.push(line)
-    used += line.length
-  }
-
-  return lines.join('\n')
-}

package/src/skills/types.ts

@@ -1,99 +0,0 @@
-/**
- * Skill System Types
- *
- * Skills are reusable prompt templates that extend agent capabilities.
- * They can be invoked by the model via the Skill tool or by users via /skillname.
- */
-
-import type { ToolContext } from '../types.js'
-import type { HookConfig } from '../hooks.js'
-
-/**
- * Content block for skill prompts (compatible with Anthropic API).
- */
-export type SkillContentBlock =
-  | { type: 'text'; text: string }
-  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } }
-
-/**
- * Bundled skill definition.
- *
- * Inspired by Claude Code's skill system. Skills provide specialized
- * capabilities by injecting context-specific prompts with optional
- * tool restrictions and model overrides.
- */
-export interface SkillDefinition {
-  /** Unique skill name (e.g., 'simplify', 'commit') */
-  name: string
-
-  /** Human-readable description */
-  description: string
-
-  /** Alternative names for the skill */
-  aliases?: string[]
-
-  /** When the model should invoke this skill (used in system prompt) */
-  whenToUse?: string
-
-  /** Hint for expected arguments */
-  argumentHint?: string
-
-  /** Tools the skill is allowed to use (empty = all tools) */
-  allowedTools?: string[]
-
-  /** Model override for this skill */
-  model?: string
-
-  /** Whether the skill can be invoked by users via /command */
-  userInvocable?: boolean
-
-  /** Runtime check for availability */
-  isEnabled?: () => boolean
-
-  /** Hook overrides while skill is active */
-  hooks?: HookConfig
-
-  /** Execution context: 'inline' runs in current context, 'fork' spawns a subagent */
-  context?: 'inline' | 'fork'
-
-  /** Subagent type for forked execution */
-  agent?: string
-
-  /**
-   * Generate the prompt content blocks for this skill.
-   *
-   * @param args - User-provided arguments (e.g., from "/simplify focus on error handling")
-   * @param context - Tool execution context (cwd, etc.)
-   * @returns Content blocks to inject into the conversation
-   */
-  getPrompt: (
-    args: string,
-    context: ToolContext,
-  ) => Promise<SkillContentBlock[]>
-}
-
-/**
- * Result of executing a skill.
- */
-export interface SkillResult {
-  /** Whether execution succeeded */
-  success: boolean
-
-  /** Skill name that was executed */
-  skillName: string
-
-  /** Execution status */
-  status: 'inline' | 'forked'
-
-  /** Allowed tools override (for inline execution) */
-  allowedTools?: string[]
-
-  /** Model override */
-  model?: string
-
-  /** Result text (for forked execution) */
-  result?: string
-
-  /** Error message */
-  error?: string
-}

package/src/tool-helper.ts

@@ -1,127 +0,0 @@
-/**
- * tool() helper - Create tools using Zod schemas
- *
- * Compatible with open-agent-sdk's tool() function.
- *
- * Usage:
- *   import { tool } from 'open-agent-sdk'
- *   import { z } from 'zod'
- *
- *   const weatherTool = tool(
- *     'get_weather',
- *     'Get weather for a city',
- *     { city: z.string().describe('City name') },
- *     async ({ city }) => {
- *       return { content: [{ type: 'text', text: `Weather in ${city}: 22°C` }] }
- *     }
- *   )
- */
-
-import { z, type ZodRawShape, type ZodObject } from 'zod'
-import { zodToJsonSchema } from 'zod-to-json-schema'
-import type { ToolDefinition, ToolResult, ToolContext } from './types.js'
-
-/**
- * Tool annotations (MCP standard).
- */
-export interface ToolAnnotations {
-  readOnlyHint?: boolean
-  destructiveHint?: boolean
-  idempotentHint?: boolean
-  openWorldHint?: boolean
-}
-
-/**
- * Tool call result (MCP-compatible).
- */
-export interface CallToolResult {
-  content: Array<
-    | { type: 'text'; text: string }
-    | { type: 'image'; data: string; mimeType: string }
-    | { type: 'resource'; resource: { uri: string; text?: string; blob?: string } }
-  >
-  isError?: boolean
-}
-
-/**
- * SDK MCP tool definition.
- */
-export interface SdkMcpToolDefinition<T extends ZodRawShape = ZodRawShape> {
-  name: string
-  description: string
-  inputSchema: ZodObject<T>
-  handler: (args: z.infer<ZodObject<T>>, extra: unknown) => Promise<CallToolResult>
-  annotations?: ToolAnnotations
-}
-
-/**
- * Create a tool using Zod schema.
- *
- * Compatible with open-agent-sdk's tool() function.
- */
-export function tool<T extends ZodRawShape>(
-  name: string,
-  description: string,
-  inputSchema: T,
-  handler: (args: z.infer<ZodObject<T>>, extra: unknown) => Promise<CallToolResult>,
-  extras?: { annotations?: ToolAnnotations },
-): SdkMcpToolDefinition<T> {
-  return {
-    name,
-    description,
-    inputSchema: z.object(inputSchema),
-    handler,
-    annotations: extras?.annotations,
-  }
-}
-
-/**
- * Convert an SdkMcpToolDefinition to a ToolDefinition for the engine.
- */
-export function sdkToolToToolDefinition(sdkTool: SdkMcpToolDefinition<any>): ToolDefinition {
-  const jsonSchema = zodToJsonSchema(sdkTool.inputSchema, { target: 'openApi3' }) as any
-
-  return {
-    name: sdkTool.name,
-    description: sdkTool.description,
-    inputSchema: {
-      type: 'object',
-      properties: jsonSchema.properties || {},
-      required: jsonSchema.required || [],
-    },
-    isReadOnly: () => sdkTool.annotations?.readOnlyHint ?? false,
-    isConcurrencySafe: () => sdkTool.annotations?.readOnlyHint ?? false,
-    isEnabled: () => true,
-    async prompt() { return sdkTool.description },
-    async call(input: any, _context: ToolContext): Promise<ToolResult> {
-      try {
-        const parsed = sdkTool.inputSchema.parse(input)
-        const result = await sdkTool.handler(parsed, {})
-
-        // Convert MCP content blocks to string
-        const text = result.content
-          .map((block) => {
-            if (block.type === 'text') return block.text
-            if (block.type === 'image') return `[Image: ${block.mimeType}]`
-            if (block.type === 'resource') return block.resource.text || `[Resource: ${block.resource.uri}]`
-            return JSON.stringify(block)
-          })
-          .join('\n')
-
-        return {
-          type: 'tool_result',
-          tool_use_id: '',
-          content: text,
-          is_error: result.isError || false,
-        }
-      } catch (err: any) {
-        return {
-          type: 'tool_result',
-          tool_use_id: '',
-          content: `Error: ${err.message}`,
-          is_error: true,
-        }
-      }
-    },
-  }
-}

package/src/tools/agent-tool.ts

@@ -1,164 +0,0 @@
-/**
- * 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 { createProvider, type ApiType } from '../providers/index.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.'
-
-    // Inherit provider and model from parent agent context, fall back to env vars
-    const subModel = input.model || context.model || process.env.CODEANY_MODEL || 'claude-sonnet-4-6'
-    const provider = context.provider ?? createProvider(
-      (context.apiType || process.env.CODEANY_API_TYPE as ApiType) || 'anthropic-messages',
-      {
-        apiKey: process.env.CODEANY_API_KEY,
-        baseURL: process.env.CODEANY_BASE_URL,
-      },
-    )
-
-    // Create subagent engine
-    const engine = new QueryEngine({
-      cwd: context.cwd,
-      model: subModel,
-      provider,
-      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

@@ -1,79 +0,0 @@
-/**
- * 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

@@ -1,75 +0,0 @@
-/**
- * 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}`)
-      })
-    })
-  },
-})