@codeany/open-agent-sdk 0.1.0 → 0.2.1

package/src/providers/openai.ts

@@ -0,0 +1,315 @@
+/**
+ * OpenAI Chat Completions API Provider
+ *
+ * Converts between the SDK's internal Anthropic-like message format
+ * and OpenAI's Chat Completions API format.
+ *
+ * Uses native fetch (no openai SDK dependency required).
+ */
+
+import type {
+  LLMProvider,
+  CreateMessageParams,
+  CreateMessageResponse,
+  NormalizedMessageParam,
+  NormalizedContentBlock,
+  NormalizedTool,
+  NormalizedResponseBlock,
+} from './types.js'
+
+// --------------------------------------------------------------------------
+// OpenAI-specific types (minimal, just what we need)
+// --------------------------------------------------------------------------
+
+interface OpenAIChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content?: string | null
+  tool_calls?: OpenAIToolCall[]
+  tool_call_id?: string
+}
+
+interface OpenAIToolCall {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+interface OpenAITool {
+  type: 'function'
+  function: {
+    name: string
+    description: string
+    parameters: Record<string, any>
+  }
+}
+
+interface OpenAIChatResponse {
+  id: string
+  choices: Array<{
+    index: number
+    message: {
+      role: 'assistant'
+      content: string | null
+      tool_calls?: OpenAIToolCall[]
+    }
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | string
+  }>
+  usage?: {
+    prompt_tokens: number
+    completion_tokens: number
+    total_tokens: number
+  }
+}
+
+// --------------------------------------------------------------------------
+// Provider
+// --------------------------------------------------------------------------
+
+export class OpenAIProvider implements LLMProvider {
+  readonly apiType = 'openai-completions' as const
+  private apiKey: string
+  private baseURL: string
+
+  constructor(opts: { apiKey?: string; baseURL?: string }) {
+    this.apiKey = opts.apiKey || ''
+    this.baseURL = (opts.baseURL || 'https://api.openai.com/v1').replace(/\/$/, '')
+  }
+
+  async createMessage(params: CreateMessageParams): Promise<CreateMessageResponse> {
+    // Convert to OpenAI format
+    const messages = this.convertMessages(params.system, params.messages)
+    const tools = params.tools ? this.convertTools(params.tools) : undefined
+
+    const body: Record<string, any> = {
+      model: params.model,
+      max_tokens: params.maxTokens,
+      messages,
+    }
+
+    if (tools && tools.length > 0) {
+      body.tools = tools
+    }
+
+    // Make API call
+    const response = await fetch(`${this.baseURL}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const errBody = await response.text().catch(() => '')
+      const err: any = new Error(
+        `OpenAI API error: ${response.status} ${response.statusText}: ${errBody}`,
+      )
+      err.status = response.status
+      throw err
+    }
+
+    const data = (await response.json()) as OpenAIChatResponse
+
+    // Convert response back to normalized format
+    return this.convertResponse(data)
+  }
+
+  // --------------------------------------------------------------------------
+  // Message Conversion: Internal → OpenAI
+  // --------------------------------------------------------------------------
+
+  private convertMessages(
+    system: string,
+    messages: NormalizedMessageParam[],
+  ): OpenAIChatMessage[] {
+    const result: OpenAIChatMessage[] = []
+
+    // System prompt as first message
+    if (system) {
+      result.push({ role: 'system', content: system })
+    }
+
+    for (const msg of messages) {
+      if (msg.role === 'user') {
+        this.convertUserMessage(msg, result)
+      } else if (msg.role === 'assistant') {
+        this.convertAssistantMessage(msg, result)
+      }
+    }
+
+    return result
+  }
+
+  private convertUserMessage(
+    msg: NormalizedMessageParam,
+    result: OpenAIChatMessage[],
+  ): void {
+    if (typeof msg.content === 'string') {
+      result.push({ role: 'user', content: msg.content })
+      return
+    }
+
+    // Content blocks may contain text and/or tool_result blocks
+    const textParts: string[] = []
+    const toolResults: Array<{ tool_use_id: string; content: string }> = []
+
+    for (const block of msg.content) {
+      if (block.type === 'text') {
+        textParts.push(block.text)
+      } else if (block.type === 'tool_result') {
+        toolResults.push({
+          tool_use_id: block.tool_use_id,
+          content: block.content,
+        })
+      }
+    }
+
+    // Tool results become separate tool messages
+    for (const tr of toolResults) {
+      result.push({
+        role: 'tool',
+        tool_call_id: tr.tool_use_id,
+        content: tr.content,
+      })
+    }
+
+    // Text parts become a user message
+    if (textParts.length > 0) {
+      result.push({ role: 'user', content: textParts.join('\n') })
+    }
+  }
+
+  private convertAssistantMessage(
+    msg: NormalizedMessageParam,
+    result: OpenAIChatMessage[],
+  ): void {
+    if (typeof msg.content === 'string') {
+      result.push({ role: 'assistant', content: msg.content })
+      return
+    }
+
+    // Extract text and tool_use blocks
+    const textParts: string[] = []
+    const toolCalls: OpenAIToolCall[] = []
+
+    for (const block of msg.content) {
+      if (block.type === 'text') {
+        textParts.push(block.text)
+      } else if (block.type === 'tool_use') {
+        toolCalls.push({
+          id: block.id,
+          type: 'function',
+          function: {
+            name: block.name,
+            arguments: typeof block.input === 'string'
+              ? block.input
+              : JSON.stringify(block.input),
+          },
+        })
+      }
+    }
+
+    const assistantMsg: OpenAIChatMessage = {
+      role: 'assistant',
+      content: textParts.length > 0 ? textParts.join('\n') : null,
+    }
+
+    if (toolCalls.length > 0) {
+      assistantMsg.tool_calls = toolCalls
+    }
+
+    result.push(assistantMsg)
+  }
+
+  // --------------------------------------------------------------------------
+  // Tool Conversion: Internal → OpenAI
+  // --------------------------------------------------------------------------
+
+  private convertTools(tools: NormalizedTool[]): OpenAITool[] {
+    return tools.map((t) => ({
+      type: 'function' as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.input_schema,
+      },
+    }))
+  }
+
+  // --------------------------------------------------------------------------
+  // Response Conversion: OpenAI → Internal
+  // --------------------------------------------------------------------------
+
+  private convertResponse(data: OpenAIChatResponse): CreateMessageResponse {
+    const choice = data.choices[0]
+    if (!choice) {
+      return {
+        content: [{ type: 'text', text: '' }],
+        stopReason: 'end_turn',
+        usage: { input_tokens: 0, output_tokens: 0 },
+      }
+    }
+
+    const content: NormalizedResponseBlock[] = []
+
+    // Add text content
+    if (choice.message.content) {
+      content.push({ type: 'text', text: choice.message.content })
+    }
+
+    // Add tool calls
+    if (choice.message.tool_calls) {
+      for (const tc of choice.message.tool_calls) {
+        let input: any
+        try {
+          input = JSON.parse(tc.function.arguments)
+        } catch {
+          input = tc.function.arguments
+        }
+
+        content.push({
+          type: 'tool_use',
+          id: tc.id,
+          name: tc.function.name,
+          input,
+        })
+      }
+    }
+
+    // If no content at all, add empty text
+    if (content.length === 0) {
+      content.push({ type: 'text', text: '' })
+    }
+
+    // Map finish_reason to our normalized stop reasons
+    const stopReason = this.mapFinishReason(choice.finish_reason)
+
+    return {
+      content,
+      stopReason,
+      usage: {
+        input_tokens: data.usage?.prompt_tokens || 0,
+        output_tokens: data.usage?.completion_tokens || 0,
+      },
+    }
+  }
+
+  private mapFinishReason(
+    reason: string,
+  ): 'end_turn' | 'max_tokens' | 'tool_use' | string {
+    switch (reason) {
+      case 'stop':
+        return 'end_turn'
+      case 'length':
+        return 'max_tokens'
+      case 'tool_calls':
+        return 'tool_use'
+      default:
+        return reason
+    }
+  }
+}

package/src/providers/types.ts

@@ -0,0 +1,85 @@
+/**
+ * LLM Provider Abstraction Types
+ *
+ * Defines a provider interface that normalizes API differences between
+ * Anthropic Messages API and OpenAI Chat Completions API.
+ *
+ * Internally the SDK uses Anthropic-like message format as the canonical
+ * representation. Providers convert to/from their native API format.
+ */
+
+// --------------------------------------------------------------------------
+// API Type
+// --------------------------------------------------------------------------
+
+export type ApiType = 'anthropic-messages' | 'openai-completions'
+
+// --------------------------------------------------------------------------
+// Normalized Request
+// --------------------------------------------------------------------------
+
+export interface CreateMessageParams {
+  model: string
+  maxTokens: number
+  system: string
+  messages: NormalizedMessageParam[]
+  tools?: NormalizedTool[]
+  thinking?: { type: string; budget_tokens?: number }
+}
+
+/**
+ * Normalized message format (Anthropic-like).
+ * This is the internal representation used throughout the SDK.
+ */
+export interface NormalizedMessageParam {
+  role: 'user' | 'assistant'
+  content: string | NormalizedContentBlock[]
+}
+
+export type NormalizedContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: any }
+  | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean }
+  | { type: 'image'; source: any }
+  | { type: 'thinking'; thinking: string }
+
+export interface NormalizedTool {
+  name: string
+  description: string
+  input_schema: {
+    type: 'object'
+    properties: Record<string, any>
+    required?: string[]
+  }
+}
+
+// --------------------------------------------------------------------------
+// Normalized Response
+// --------------------------------------------------------------------------
+
+export interface CreateMessageResponse {
+  content: NormalizedResponseBlock[]
+  stopReason: 'end_turn' | 'max_tokens' | 'tool_use' | string
+  usage: {
+    input_tokens: number
+    output_tokens: number
+    cache_creation_input_tokens?: number
+    cache_read_input_tokens?: number
+  }
+}
+
+export type NormalizedResponseBlock =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: any }
+
+// --------------------------------------------------------------------------
+// Provider Interface
+// --------------------------------------------------------------------------
+
+export interface LLMProvider {
+  /** The API type this provider implements. */
+  readonly apiType: ApiType
+
+  /** Send a message and get a response. */
+  createMessage(params: CreateMessageParams): Promise<CreateMessageResponse>
+}

package/src/session.ts

@@ -8,7 +8,7 @@
 import { readFile, writeFile, mkdir, readdir, stat } from 'fs/promises'
 import { join } from 'path'
 import type { Message } from './types.js'
-import type Anthropic from '@anthropic-ai/sdk'
+import type { NormalizedMessageParam } from './providers/types.js'
 
 /**
  * Session metadata.
@@ -28,7 +28,7 @@ export interface SessionMetadata {
  */
 export interface SessionData {
   metadata: SessionMetadata
-  messages: Anthropic.MessageParam[]
+  messages: NormalizedMessageParam[]
 }
 
 /**
@@ -51,7 +51,7 @@ function getSessionPath(sessionId: string): string {
  */
 export async function saveSession(
   sessionId: string,
-  messages: Anthropic.MessageParam[],
+  messages: NormalizedMessageParam[],
   metadata: Partial<SessionMetadata>,
 ): Promise<void> {
   const dir = getSessionPath(sessionId)
@@ -146,7 +146,7 @@ export async function forkSession(
  */
 export async function getSessionMessages(
   sessionId: string,
-): Promise<Anthropic.MessageParam[]> {
+): Promise<NormalizedMessageParam[]> {
   const data = await loadSession(sessionId)
   return data?.messages || []
 }
@@ -156,7 +156,7 @@ export async function getSessionMessages(
  */
 export async function appendToSession(
   sessionId: string,
-  message: Anthropic.MessageParam,
+  message: NormalizedMessageParam,
 ): Promise<void> {
   const data = await loadSession(sessionId)
   if (!data) return

package/src/skills/bundled/commit.ts

@@ -0,0 +1,38 @@
+/**
+ * Bundled Skill: commit
+ *
+ * Create a git commit with a well-crafted message based on staged changes.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const COMMIT_PROMPT = `Create a git commit for the current changes. Follow these steps:
+
+1. Run \`git status\` and \`git diff --cached\` to understand what's staged
+2. If nothing is staged, run \`git diff\` to see unstaged changes and suggest what to stage
+3. Analyze the changes and draft a concise commit message that:
+   - Uses imperative mood ("Add feature" not "Added feature")
+   - Summarizes the "why" not just the "what"
+   - Keeps the first line under 72 characters
+   - Adds a body with details if the change is complex
+4. Create the commit
+
+Do NOT push to remote unless explicitly asked.`
+
+export function registerCommitSkill(): void {
+  registerSkill({
+    name: 'commit',
+    description: 'Create a git commit with a well-crafted message based on staged changes.',
+    aliases: ['ci'],
+    allowedTools: ['Bash', 'Read', 'Glob', 'Grep'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = COMMIT_PROMPT
+      if (args.trim()) {
+        prompt += `\n\nAdditional instructions: ${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/debug.ts

@@ -0,0 +1,48 @@
+/**
+ * Bundled Skill: debug
+ *
+ * Systematic debugging of an issue using structured investigation.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const DEBUG_PROMPT = `Debug the described issue using a systematic approach:
+
+1. **Reproduce**: Understand and reproduce the issue
+   - Read relevant error messages or logs
+   - Identify the failing component
+
+2. **Investigate**: Trace the root cause
+   - Read the relevant source code
+   - Add logging or use debugging tools if needed
+   - Check recent changes that might have introduced the issue (\`git log --oneline -20\`)
+
+3. **Hypothesize**: Form a theory about the cause
+   - State your hypothesis clearly before attempting a fix
+
+4. **Fix**: Implement the minimal fix
+   - Make the smallest change that resolves the issue
+   - Don't refactor unrelated code
+
+5. **Verify**: Confirm the fix works
+   - Run relevant tests
+   - Check for regressions`
+
+export function registerDebugSkill(): void {
+  registerSkill({
+    name: 'debug',
+    description: 'Systematic debugging of an issue using structured investigation.',
+    aliases: ['investigate', 'diagnose'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = DEBUG_PROMPT
+      if (args.trim()) {
+        prompt += `\n\n## Issue Description\n${args}`
+      } else {
+        prompt += `\n\nAsk the user to describe the issue they're experiencing.`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Bundled Skills Initialization
+ *
+ * Registers all built-in skills at SDK startup.
+ */
+
+import { registerSimplifySkill } from './simplify.js'
+import { registerCommitSkill } from './commit.js'
+import { registerReviewSkill } from './review.js'
+import { registerDebugSkill } from './debug.js'
+import { registerTestSkill } from './test.js'
+
+let initialized = false
+
+/**
+ * Initialize all bundled skills.
+ * Safe to call multiple times (idempotent).
+ */
+export function initBundledSkills(): void {
+  if (initialized) return
+  initialized = true
+
+  registerSimplifySkill()
+  registerCommitSkill()
+  registerReviewSkill()
+  registerDebugSkill()
+  registerTestSkill()
+}

package/src/skills/bundled/review.ts

@@ -0,0 +1,41 @@
+/**
+ * Bundled Skill: review
+ *
+ * Review code changes (PR or local diff) for issues and improvements.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const REVIEW_PROMPT = `Review the current code changes for potential issues. Follow these steps:
+
+1. Run \`git diff\` to see uncommitted changes, or \`git diff main...HEAD\` for branch changes
+2. For each changed file, analyze:
+   - **Correctness**: Logic errors, edge cases, off-by-one errors
+   - **Security**: Injection vulnerabilities, auth issues, data exposure
+   - **Performance**: N+1 queries, unnecessary allocations, blocking I/O
+   - **Style**: Naming, consistency with surrounding code, readability
+   - **Testing**: Are the changes adequately tested?
+3. Provide a summary with:
+   - Critical issues (must fix)
+   - Suggestions (nice to have)
+   - Questions (need clarification)
+
+Be specific: reference file names, line numbers, and suggest fixes.`
+
+export function registerReviewSkill(): void {
+  registerSkill({
+    name: 'review',
+    description: 'Review code changes for correctness, security, performance, and style issues.',
+    aliases: ['review-pr', 'cr'],
+    allowedTools: ['Bash', 'Read', 'Glob', 'Grep'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = REVIEW_PROMPT
+      if (args.trim()) {
+        prompt += `\n\nFocus area: ${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/simplify.ts

@@ -0,0 +1,51 @@
+/**
+ * Bundled Skill: simplify
+ *
+ * Reviews changed code for reuse opportunities, code quality issues,
+ * and efficiency improvements, then fixes any issues found.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const SIMPLIFY_PROMPT = `Review the recently changed code for three categories of improvements. Launch 3 parallel Agent sub-tasks:
+
+## Task 1: Reuse Analysis
+Look for:
+- Duplicated code that could be consolidated
+- Existing utilities or helpers that could replace new code
+- Patterns that should be extracted into shared functions
+- Re-implementations of functionality that already exists elsewhere
+
+## Task 2: Code Quality
+Look for:
+- Overly complex logic that could be simplified
+- Poor naming or unclear intent
+- Missing edge case handling
+- Unnecessary abstractions or over-engineering
+- Dead code or unused imports
+
+## Task 3: Efficiency
+Look for:
+- Unnecessary allocations or copies
+- N+1 query patterns or redundant I/O
+- Blocking operations that could be async
+- Inefficient data structures for the access pattern
+- Unnecessary re-computation
+
+After all three analyses complete, fix any issues found. Prioritize by impact.`
+
+export function registerSimplifySkill(): void {
+  registerSkill({
+    name: 'simplify',
+    description: 'Review changed code for reuse, quality, and efficiency, then fix any issues found.',
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = SIMPLIFY_PROMPT
+      if (args.trim()) {
+        prompt += `\n\n## Additional Focus\n${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/test.ts

@@ -0,0 +1,43 @@
+/**
+ * Bundled Skill: test
+ *
+ * Run tests and analyze failures.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const TEST_PROMPT = `Run the project's test suite and analyze the results:
+
+1. **Discover**: Find the test runner configuration
+   - Look for package.json scripts, jest.config, vitest.config, pytest.ini, etc.
+   - Identify the appropriate test command
+
+2. **Execute**: Run the tests
+   - Run the full test suite or specific tests if specified
+   - Capture output including failures and errors
+
+3. **Analyze**: If tests fail:
+   - Read the failing test to understand what it expects
+   - Read the source code being tested
+   - Identify why the test is failing
+   - Fix the issue (in tests or source as appropriate)
+
+4. **Re-verify**: Run the failing tests again to confirm the fix`
+
+export function registerTestSkill(): void {
+  registerSkill({
+    name: 'test',
+    description: 'Run tests and analyze failures, fixing any issues found.',
+    aliases: ['run-tests'],
+    allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = TEST_PROMPT
+      if (args.trim()) {
+        prompt += `\n\nSpecific test target: ${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}