@codeany/open-agent-sdk 0.1.0 → 0.2.0

package/src/index.ts

@@ -6,6 +6,7 @@
  *
  * Features:
  * - 30+ built-in tools (file I/O, shell, web, agents, tasks, teams, etc.)
+ * - Skill system (reusable prompt templates with bundled skills)
  * - MCP server integration (stdio, SSE, HTTP)
  * - Context compression (auto-compact, micro-compact)
  * - Retry with exponential backoff
@@ -14,7 +15,7 @@
  * - Permission system (allow/deny/bypass modes)
  * - Subagent spawning & team coordination
  * - Task management & scheduling
- * - Hook system (pre/post tool use, lifecycle events)
+ * - Hook system with lifecycle integration (pre/post tool use, session, compact)
  * - Token estimation & cost tracking
  * - File state LRU caching
  * - Plan mode for structured workflows
@@ -50,6 +51,26 @@ export type { McpSdkServerConfig } from './sdk-mcp-server.js'
 
 export { QueryEngine } from './engine.js'
 
+// --------------------------------------------------------------------------
+// LLM Providers (Anthropic + OpenAI)
+// --------------------------------------------------------------------------
+
+export {
+  createProvider,
+  AnthropicProvider,
+  OpenAIProvider,
+} from './providers/index.js'
+export type {
+  ApiType,
+  LLMProvider,
+  CreateMessageParams,
+  CreateMessageResponse,
+  NormalizedMessageParam,
+  NormalizedContentBlock,
+  NormalizedTool,
+  NormalizedResponseBlock,
+} from './providers/index.js'
+
 // --------------------------------------------------------------------------
 // Tool System (30+ tools)
 // --------------------------------------------------------------------------
@@ -123,6 +144,9 @@ export {
 
   // Todo
   TodoWriteTool,
+
+  // Skill
+  SkillTool,
 } from './tools/index.js'
 
 // --------------------------------------------------------------------------
@@ -132,6 +156,27 @@ export {
 export { connectMCPServer, closeAllConnections } from './mcp/client.js'
 export type { MCPConnection } from './mcp/client.js'
 
+// --------------------------------------------------------------------------
+// Skill System
+// --------------------------------------------------------------------------
+
+export {
+  registerSkill,
+  getSkill,
+  getAllSkills,
+  getUserInvocableSkills,
+  hasSkill,
+  unregisterSkill,
+  clearSkills,
+  formatSkillsForPrompt,
+  initBundledSkills,
+} from './skills/index.js'
+export type {
+  SkillDefinition,
+  SkillContentBlock,
+  SkillResult,
+} from './skills/index.js'
+
 // --------------------------------------------------------------------------
 // Hook System
 // --------------------------------------------------------------------------
@@ -341,6 +386,7 @@ export type {
 
   // Permission types
   PermissionMode,
+  PermissionBehavior,
   CanUseToolFn,
   CanUseToolResult,
 
@@ -360,6 +406,10 @@ export type {
   // Engine types
   QueryEngineConfig,
 
+  // Content block types
+  ContentBlockParam,
+  ContentBlock,
+
   // Sandbox types
   SandboxSettings,
   SandboxNetworkConfig,

package/src/providers/anthropic.ts

@@ -0,0 +1,60 @@
+/**
+ * Anthropic Messages API Provider
+ *
+ * Wraps the @anthropic-ai/sdk client. Since our internal format is
+ * Anthropic-like, this is mostly a thin pass-through.
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import type {
+  LLMProvider,
+  CreateMessageParams,
+  CreateMessageResponse,
+} from './types.js'
+
+export class AnthropicProvider implements LLMProvider {
+  readonly apiType = 'anthropic-messages' as const
+  private client: Anthropic
+
+  constructor(opts: { apiKey?: string; baseURL?: string }) {
+    this.client = new Anthropic({
+      apiKey: opts.apiKey,
+      baseURL: opts.baseURL,
+    })
+  }
+
+  async createMessage(params: CreateMessageParams): Promise<CreateMessageResponse> {
+    const requestParams: Anthropic.MessageCreateParamsNonStreaming = {
+      model: params.model,
+      max_tokens: params.maxTokens,
+      system: params.system,
+      messages: params.messages as Anthropic.MessageParam[],
+      tools: params.tools
+        ? (params.tools as Anthropic.Tool[])
+        : undefined,
+    }
+
+    // Add extended thinking if configured
+    if (params.thinking?.type === 'enabled' && params.thinking.budget_tokens) {
+      (requestParams as any).thinking = {
+        type: 'enabled',
+        budget_tokens: params.thinking.budget_tokens,
+      }
+    }
+
+    const response = await this.client.messages.create(requestParams)
+
+    return {
+      content: response.content as CreateMessageResponse['content'],
+      stopReason: response.stop_reason || 'end_turn',
+      usage: {
+        input_tokens: response.usage.input_tokens,
+        output_tokens: response.usage.output_tokens,
+        cache_creation_input_tokens:
+          (response.usage as any).cache_creation_input_tokens,
+        cache_read_input_tokens:
+          (response.usage as any).cache_read_input_tokens,
+      },
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,34 @@
+/**
+ * LLM Provider Factory
+ *
+ * Creates the appropriate provider based on API type configuration.
+ */
+
+export type { ApiType, LLMProvider, CreateMessageParams, CreateMessageResponse, NormalizedMessageParam, NormalizedContentBlock, NormalizedTool, NormalizedResponseBlock } from './types.js'
+
+export { AnthropicProvider } from './anthropic.js'
+export { OpenAIProvider } from './openai.js'
+
+import type { ApiType, LLMProvider } from './types.js'
+import { AnthropicProvider } from './anthropic.js'
+import { OpenAIProvider } from './openai.js'
+
+/**
+ * Create an LLM provider based on the API type.
+ *
+ * @param apiType - 'anthropic-messages' or 'openai-completions'
+ * @param opts - API credentials
+ */
+export function createProvider(
+  apiType: ApiType,
+  opts: { apiKey?: string; baseURL?: string },
+): LLMProvider {
+  switch (apiType) {
+    case 'anthropic-messages':
+      return new AnthropicProvider(opts)
+    case 'openai-completions':
+      return new OpenAIProvider(opts)
+    default:
+      throw new Error(`Unsupported API type: ${apiType}. Use 'anthropic-messages' or 'openai-completions'.`)
+  }
+}

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 }]
+    },
+  })
+}