@codeany/open-agent-sdk 0.1.0

package/src/tools/write.ts

@@ -0,0 +1,42 @@
+/**
+ * FileWriteTool - Write/create files
+ */
+
+import { writeFile, mkdir } from 'fs/promises'
+import { resolve, dirname } from 'path'
+import { defineTool } from './types.js'
+
+export const FileWriteTool = defineTool({
+  name: 'Write',
+  description: 'Write content to a file. Creates the file if it does not exist, or overwrites if it does. Creates parent directories as needed.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'The absolute path to the file to write',
+      },
+      content: {
+        type: 'string',
+        description: 'The content to write to the file',
+      },
+    },
+    required: ['file_path', 'content'],
+  },
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  async call(input, context) {
+    const filePath = resolve(context.cwd, input.file_path)
+
+    try {
+      await mkdir(dirname(filePath), { recursive: true })
+      await writeFile(filePath, input.content, 'utf-8')
+
+      const lines = input.content.split('\n').length
+      const bytes = Buffer.byteLength(input.content, 'utf-8')
+      return `File written: ${filePath} (${lines} lines, ${bytes} bytes)`
+    } catch (err: any) {
+      return { data: `Error writing file: ${err.message}`, is_error: true }
+    }
+  },
+})

package/src/types.ts

@@ -0,0 +1,459 @@
+/**
+ * Core type definitions for the Agent SDK
+ */
+
+import type Anthropic from '@anthropic-ai/sdk'
+
+// --------------------------------------------------------------------------
+// Message Types
+// --------------------------------------------------------------------------
+
+export type MessageRole = 'user' | 'assistant'
+
+export interface ConversationMessage {
+  role: MessageRole
+  content: string | Anthropic.ContentBlockParam[]
+}
+
+export interface UserMessage {
+  type: 'user'
+  message: ConversationMessage
+  uuid: string
+  timestamp: string
+}
+
+export interface AssistantMessage {
+  type: 'assistant'
+  message: {
+    role: 'assistant'
+    content: Anthropic.ContentBlock[]
+  }
+  uuid: string
+  timestamp: string
+  usage?: TokenUsage
+  cost?: number
+}
+
+export type Message = UserMessage | AssistantMessage
+
+// --------------------------------------------------------------------------
+// SDK Message Types (streaming events)
+// --------------------------------------------------------------------------
+
+export type SDKMessage =
+  | SDKAssistantMessage
+  | SDKToolResultMessage
+  | SDKResultMessage
+  | SDKPartialMessage
+  | SDKSystemMessage
+  | SDKCompactBoundaryMessage
+  | SDKStatusMessage
+  | SDKTaskNotificationMessage
+  | SDKRateLimitEvent
+
+export interface SDKAssistantMessage {
+  type: 'assistant'
+  uuid?: string
+  session_id?: string
+  message: {
+    role: 'assistant'
+    content: Anthropic.ContentBlock[]
+  }
+  parent_tool_use_id?: string | null
+}
+
+export interface SDKToolResultMessage {
+  type: 'tool_result'
+  result: {
+    tool_use_id: string
+    tool_name: string
+    output: string
+  }
+}
+
+export interface SDKResultMessage {
+  type: 'result'
+  subtype: 'success' | 'error_max_turns' | 'error_during_execution' | 'error_max_budget_usd' | string
+  uuid?: string
+  session_id?: string
+  is_error?: boolean
+  num_turns?: number
+  result?: string
+  stop_reason?: string | null
+  total_cost_usd?: number
+  duration_ms?: number
+  duration_api_ms?: number
+  usage?: TokenUsage
+  model_usage?: Record<string, { input_tokens: number; output_tokens: number }>
+  permission_denials?: Array<{ tool: string; reason: string }>
+  structured_output?: unknown
+  errors?: string[]
+  /** @deprecated Use total_cost_usd */
+  cost?: number
+}
+
+export interface SDKPartialMessage {
+  type: 'partial_message'
+  partial: {
+    type: 'text' | 'tool_use'
+    text?: string
+    name?: string
+    input?: string
+  }
+}
+
+/** Emitted once at session start with initialization info. */
+export interface SDKSystemMessage {
+  type: 'system'
+  subtype: 'init'
+  uuid?: string
+  session_id: string
+  tools: string[]
+  model: string
+  cwd: string
+  mcp_servers: Array<{ name: string; status: string }>
+  permission_mode: string
+}
+
+/** Marks a compaction boundary in the conversation. */
+export interface SDKCompactBoundaryMessage {
+  type: 'system'
+  subtype: 'compact_boundary'
+  summary?: string
+}
+
+/** Status update during long operations. */
+export interface SDKStatusMessage {
+  type: 'system'
+  subtype: 'status'
+  message: string
+}
+
+/** Task lifecycle notification. */
+export interface SDKTaskNotificationMessage {
+  type: 'system'
+  subtype: 'task_notification'
+  task_id: string
+  status: string
+  message?: string
+}
+
+/** Rate limit event. */
+export interface SDKRateLimitEvent {
+  type: 'system'
+  subtype: 'rate_limit'
+  retry_after_ms?: number
+  message: string
+}
+
+// --------------------------------------------------------------------------
+// Token Usage
+// --------------------------------------------------------------------------
+
+export interface TokenUsage {
+  input_tokens: number
+  output_tokens: number
+  cache_creation_input_tokens?: number
+  cache_read_input_tokens?: number
+}
+
+// --------------------------------------------------------------------------
+// Tool Types
+// --------------------------------------------------------------------------
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  inputSchema: ToolInputSchema
+  call: (input: any, context: ToolContext) => Promise<ToolResult>
+  isReadOnly?: () => boolean
+  isConcurrencySafe?: () => boolean
+  isEnabled?: () => boolean
+  prompt?: (context: ToolContext) => Promise<string>
+}
+
+export interface ToolInputSchema {
+  type: 'object'
+  properties: Record<string, any>
+  required?: string[]
+}
+
+export interface ToolContext {
+  cwd: string
+  abortSignal?: AbortSignal
+}
+
+export interface ToolResult {
+  type: 'tool_result'
+  tool_use_id: string
+  content: string | Anthropic.ToolResultBlockParam['content']
+  is_error?: boolean
+}
+
+// --------------------------------------------------------------------------
+// Permission Types
+// --------------------------------------------------------------------------
+
+export type PermissionMode =
+  | 'default'
+  | 'acceptEdits'
+  | 'bypassPermissions'
+  | 'plan'
+  | 'dontAsk'
+  | 'auto'
+
+export type CanUseToolResult = {
+  behavior: 'allow' | 'deny'
+  updatedInput?: unknown
+  message?: string
+}
+
+export type CanUseToolFn = (
+  tool: ToolDefinition,
+  input: unknown,
+) => Promise<CanUseToolResult>
+
+// --------------------------------------------------------------------------
+// MCP Types
+// --------------------------------------------------------------------------
+
+export type McpServerConfig =
+  | McpStdioConfig
+  | McpSseConfig
+  | McpHttpConfig
+
+export interface McpStdioConfig {
+  type?: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+}
+
+export interface McpSseConfig {
+  type: 'sse'
+  url: string
+  headers?: Record<string, string>
+}
+
+export interface McpHttpConfig {
+  type: 'http'
+  url: string
+  headers?: Record<string, string>
+}
+
+// --------------------------------------------------------------------------
+// Agent Types
+// --------------------------------------------------------------------------
+
+export interface AgentDefinition {
+  description: string
+  prompt: string
+  tools?: string[]
+  disallowedTools?: string[]
+  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit' | string
+  mcpServers?: Array<string | { name: string; tools?: string[] }>
+  skills?: string[]
+  maxTurns?: number
+  criticalSystemReminder_EXPERIMENTAL?: string
+}
+
+export interface ThinkingConfig {
+  type: 'adaptive' | 'enabled' | 'disabled'
+  budgetTokens?: number
+}
+
+// --------------------------------------------------------------------------
+// Sandbox Types
+// --------------------------------------------------------------------------
+
+export interface SandboxSettings {
+  enabled?: boolean
+  autoAllowBashIfSandboxed?: boolean
+  excludedCommands?: string[]
+  allowUnsandboxedCommands?: boolean
+  network?: SandboxNetworkConfig
+  filesystem?: SandboxFilesystemConfig
+  ignoreViolations?: Record<string, string[]>
+  enableWeakerNestedSandbox?: boolean
+  ripgrep?: { command: string; args?: string[] }
+}
+
+export interface SandboxNetworkConfig {
+  allowedDomains?: string[]
+  allowManagedDomainsOnly?: boolean
+  allowLocalBinding?: boolean
+  allowUnixSockets?: string[]
+  allowAllUnixSockets?: boolean
+  httpProxyPort?: number
+  socksProxyPort?: number
+}
+
+export interface SandboxFilesystemConfig {
+  allowWrite?: string[]
+  denyWrite?: string[]
+  denyRead?: string[]
+}
+
+// --------------------------------------------------------------------------
+// Output Format
+// --------------------------------------------------------------------------
+
+export interface OutputFormat {
+  type: 'json_schema'
+  schema: Record<string, unknown>
+}
+
+// --------------------------------------------------------------------------
+// Setting Sources
+// --------------------------------------------------------------------------
+
+export type SettingSource = 'user' | 'project' | 'local'
+
+// --------------------------------------------------------------------------
+// Model Info
+// --------------------------------------------------------------------------
+
+export interface ModelInfo {
+  value: string
+  displayName: string
+  description: string
+  supportsEffort?: boolean
+  supportedEffortLevels?: ('low' | 'medium' | 'high' | 'max')[]
+  supportsAdaptiveThinking?: boolean
+  supportsFastMode?: boolean
+}
+
+export interface AgentOptions {
+  /** LLM model ID */
+  model?: string
+  /** API key. Falls back to CODEANY_API_KEY env var. */
+  apiKey?: string
+  /** API base URL override */
+  baseURL?: string
+  /** Working directory for file/shell tools */
+  cwd?: string
+  /** System prompt override or preset */
+  systemPrompt?: string | { type: 'preset'; preset: 'default'; append?: string }
+  /** Append to default system prompt */
+  appendSystemPrompt?: string
+  /** Available tools (ToolDefinition[] or string[] preset) */
+  tools?: ToolDefinition[] | string[] | { type: 'preset'; preset: 'default' }
+  /** Maximum number of agentic turns per query */
+  maxTurns?: number
+  /** Maximum USD budget per query */
+  maxBudgetUsd?: number
+  /** Extended thinking configuration */
+  thinking?: ThinkingConfig
+  /** Maximum thinking tokens (deprecated, use thinking.budgetTokens) */
+  maxThinkingTokens?: number
+  /** Structured output JSON schema */
+  jsonSchema?: Record<string, unknown>
+  /** Structured output format */
+  outputFormat?: OutputFormat
+  /** Permission handler callback */
+  canUseTool?: CanUseToolFn
+  /** Permission mode controlling tool approval behavior */
+  permissionMode?: PermissionMode
+  /** Abort controller for cancellation */
+  abortController?: AbortController
+  /** Abort signal for cancellation */
+  abortSignal?: AbortSignal
+  /** Whether to include partial streaming events */
+  includePartialMessages?: boolean
+  /** Environment variables */
+  env?: Record<string, string | undefined>
+  /** Tool names to pre-approve without prompting */
+  allowedTools?: string[]
+  /** Tool names to deny */
+  disallowedTools?: string[]
+  /** MCP server configurations */
+  mcpServers?: Record<string, McpServerConfig | any> // supports McpSdkServerConfig
+  /** Custom subagent definitions */
+  agents?: Record<string, AgentDefinition>
+  /** Maximum tokens for responses */
+  maxTokens?: number
+  /** Effort level for reasoning */
+  effort?: 'low' | 'medium' | 'high' | 'max'
+  /** Fallback model if primary is unavailable */
+  fallbackModel?: string
+  /** Continue the most recent session in cwd */
+  continue?: boolean
+  /** Resume a specific session by ID */
+  resume?: string
+  /** Fork a session instead of continuing it */
+  forkSession?: boolean
+  /** Persist session to disk */
+  persistSession?: boolean
+  /** Explicit session ID */
+  sessionId?: string
+  /** Enable file checkpointing (for rewindFiles) */
+  enableFileCheckpointing?: boolean
+  /** Sandbox configuration */
+  sandbox?: SandboxSettings
+  /** Load settings from filesystem */
+  settingSources?: SettingSource[]
+  /** Plugin configurations */
+  plugins?: Array<{ name: string; config?: Record<string, unknown> }>
+  /** Additional working directories */
+  additionalDirectories?: string[]
+  /** Default agent to use */
+  agent?: string
+  /** Debug mode */
+  debug?: boolean
+  /** Debug log file */
+  debugFile?: string
+  /** Tool-specific configuration */
+  toolConfig?: Record<string, unknown>
+  /** Enable prompt suggestions */
+  promptSuggestions?: boolean
+  /** Strict MCP config validation */
+  strictMcpConfig?: boolean
+  /** Extra CLI arguments */
+  extraArgs?: Record<string, string | null>
+  /** SDK betas to enable */
+  betas?: string[]
+  /** Permission prompt tool name override */
+  permissionPromptToolName?: string
+  /** Hook configurations */
+  hooks?: Record<string, Array<{
+    matcher?: string
+    hooks: Array<(input: any, toolUseId: string, context: { signal: AbortSignal }) => Promise<any>>
+    timeout?: number
+  }>>
+}
+
+export interface QueryResult {
+  /** Final text output from the assistant */
+  text: string
+  /** Token usage */
+  usage: TokenUsage
+  /** Number of agentic turns */
+  num_turns: number
+  /** Duration in milliseconds */
+  duration_ms: number
+  /** All conversation messages */
+  messages: Message[]
+}
+
+// --------------------------------------------------------------------------
+// Query Engine Types
+// --------------------------------------------------------------------------
+
+export interface QueryEngineConfig {
+  cwd: string
+  model: string
+  apiKey?: string
+  baseURL?: string
+  tools: ToolDefinition[]
+  systemPrompt?: string
+  appendSystemPrompt?: string
+  maxTurns: number
+  maxBudgetUsd?: number
+  maxTokens: number
+  thinking?: ThinkingConfig
+  jsonSchema?: Record<string, unknown>
+  canUseTool: CanUseToolFn
+  includePartialMessages: boolean
+  abortSignal?: AbortSignal
+  agents?: Record<string, AgentDefinition>
+}

package/src/utils/compact.ts

@@ -0,0 +1,206 @@
+/**
+ * Context Compression / Auto-Compaction
+ *
+ * Summarizes long conversation histories when context window fills up.
+ * Three-tier system:
+ * 1. Auto-compact: triggered when tokens exceed threshold
+ * 2. Micro-compact: cache-aware per-request optimization
+ * 3. Session memory compaction: consolidates across sessions
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import {
+  estimateMessagesTokens,
+  getAutoCompactThreshold,
+} from './tokens.js'
+
+/**
+ * State for tracking auto-compaction across turns.
+ */
+export interface AutoCompactState {
+  compacted: boolean
+  turnCounter: number
+  consecutiveFailures: number
+}
+
+/**
+ * Create initial auto-compact state.
+ */
+export function createAutoCompactState(): AutoCompactState {
+  return {
+    compacted: false,
+    turnCounter: 0,
+    consecutiveFailures: 0,
+  }
+}
+
+/**
+ * Check if auto-compaction should trigger.
+ */
+export function shouldAutoCompact(
+  messages: Anthropic.MessageParam[],
+  model: string,
+  state: AutoCompactState,
+): boolean {
+  if (state.consecutiveFailures >= 3) return false
+
+  const estimatedTokens = estimateMessagesTokens(messages)
+  const threshold = getAutoCompactThreshold(model)
+
+  return estimatedTokens >= threshold
+}
+
+/**
+ * Compact conversation by summarizing with the LLM.
+ *
+ * Sends the entire conversation to the LLM for summarization,
+ * then replaces the history with a compact summary.
+ */
+export async function compactConversation(
+  client: Anthropic,
+  model: string,
+  messages: Anthropic.MessageParam[],
+  state: AutoCompactState,
+): Promise<{
+  compactedMessages: Anthropic.MessageParam[]
+  summary: string
+  state: AutoCompactState
+}> {
+  try {
+    // Strip images before compacting to save tokens
+    const strippedMessages = stripImagesFromMessages(messages)
+
+    // Build compaction prompt
+    const compactionPrompt = buildCompactionPrompt(strippedMessages)
+
+    const response = await client.messages.create({
+      model,
+      max_tokens: 8192,
+      system: 'You are a conversation summarizer. Create a detailed summary of the conversation that preserves all important context, decisions made, files modified, tool outputs, and current state. The summary should allow the conversation to continue seamlessly.',
+      messages: [
+        {
+          role: 'user',
+          content: compactionPrompt,
+        },
+      ],
+    })
+
+    const summary = response.content
+      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n')
+
+    // Replace messages with summary
+    const compactedMessages: Anthropic.MessageParam[] = [
+      {
+        role: 'user',
+        content: `[Previous conversation summary]\n\n${summary}\n\n[End of summary - conversation continues below]`,
+      },
+      {
+        role: 'assistant',
+        content: 'I understand the context from the previous conversation. I\'ll continue from where we left off.',
+      },
+    ]
+
+    return {
+      compactedMessages,
+      summary,
+      state: {
+        compacted: true,
+        turnCounter: state.turnCounter,
+        consecutiveFailures: 0,
+      },
+    }
+  } catch (err: any) {
+    return {
+      compactedMessages: messages,
+      summary: '',
+      state: {
+        ...state,
+        consecutiveFailures: state.consecutiveFailures + 1,
+      },
+    }
+  }
+}
+
+/**
+ * Strip images from messages for compaction safety.
+ */
+function stripImagesFromMessages(
+  messages: Anthropic.MessageParam[],
+): Anthropic.MessageParam[] {
+  return messages.map((msg) => {
+    if (typeof msg.content === 'string') return msg
+
+    const filtered = (msg.content as any[]).filter((block: any) => {
+      return block.type !== 'image'
+    })
+
+    return { ...msg, content: filtered.length > 0 ? filtered : '[content removed for compaction]' }
+  })
+}
+
+/**
+ * Build compaction prompt from messages.
+ */
+function buildCompactionPrompt(messages: Anthropic.MessageParam[]): string {
+  const parts: string[] = ['Please summarize this conversation:\n']
+
+  for (const msg of messages) {
+    const role = msg.role === 'user' ? 'User' : 'Assistant'
+
+    if (typeof msg.content === 'string') {
+      parts.push(`${role}: ${msg.content.slice(0, 5000)}`)
+    } else if (Array.isArray(msg.content)) {
+      const texts: string[] = []
+      for (const block of msg.content as any[]) {
+        if (block.type === 'text') {
+          texts.push(block.text.slice(0, 3000))
+        } else if (block.type === 'tool_use') {
+          texts.push(`[Tool: ${block.name}]`)
+        } else if (block.type === 'tool_result') {
+          const content = typeof block.content === 'string'
+            ? block.content.slice(0, 1000)
+            : '[tool result]'
+          texts.push(`[Tool Result: ${content}]`)
+        }
+      }
+      if (texts.length > 0) {
+        parts.push(`${role}: ${texts.join('\n')}`)
+      }
+    }
+  }
+
+  return parts.join('\n\n')
+}
+
+/**
+ * Micro-compact: optimize messages by truncating large tool results
+ * to fit within token budgets.
+ */
+export function microCompactMessages(
+  messages: Anthropic.MessageParam[],
+  maxToolResultChars: number = 50000,
+): Anthropic.MessageParam[] {
+  return messages.map((msg) => {
+    if (typeof msg.content === 'string') return msg
+    if (!Array.isArray(msg.content)) return msg
+
+    const content = (msg.content as any[]).map((block: any) => {
+      if (block.type === 'tool_result' && typeof block.content === 'string') {
+        if (block.content.length > maxToolResultChars) {
+          return {
+            ...block,
+            content:
+              block.content.slice(0, maxToolResultChars / 2) +
+              '\n...(truncated)...\n' +
+              block.content.slice(-maxToolResultChars / 2),
+          }
+        }
+      }
+      return block
+    })
+
+    return { ...msg, content }
+  })
+}