@bluehawks/cli 1.0.0

package/src/core/api/client.ts

@@ -0,0 +1,300 @@
+/**
+ * Bluehawks CLI - API Client
+ * OpenAI-compatible API client with streaming support
+ */
+
+import {
+    API_BASE_URL,
+    DEFAULT_MODEL,
+    DEFAULT_MAX_TOKENS,
+    DEFAULT_TEMPERATURE,
+    DEFAULT_TIMEOUT_MS,
+    MAX_RETRIES,
+    RETRY_DELAY_MS,
+} from '../../config/constants.js';
+import {
+    type APIClientOptions,
+    type ChatCompletionRequest,
+    type ChatCompletionResponse,
+    type ChatCompletionChunk,
+    type Message,
+    type ToolCall,
+    type ToolDefinition,
+    type ToolResult,
+    type StreamDelta,
+    APIError,
+} from './types.js';
+
+export class APIClient {
+    private baseUrl: string;
+    private apiKey: string;
+    private model: string;
+    private maxTokens: number;
+    private temperature: number;
+    private timeout: number;
+
+    constructor(options: APIClientOptions = {}) {
+        this.baseUrl = options.baseUrl || process.env.BLUEHAWKS_API_URL || API_BASE_URL;
+        this.apiKey = options.apiKey || process.env.BLUEHAWKS_API_KEY || '';
+        this.model = options.model || process.env.BLUEHAWKS_MODEL || DEFAULT_MODEL;
+        this.maxTokens = options.maxTokens || DEFAULT_MAX_TOKENS;
+        this.temperature = options.temperature || DEFAULT_TEMPERATURE;
+        this.timeout = options.timeout || DEFAULT_TIMEOUT_MS;
+    }
+
+    /**
+     * Create a chat completion (non-streaming)
+     */
+    async createChatCompletion(
+        messages: Message[],
+        tools?: ToolDefinition[],
+        toolChoice?: ChatCompletionRequest['tool_choice']
+    ): Promise<ChatCompletionResponse> {
+        const request: ChatCompletionRequest = {
+            model: this.model,
+            messages,
+            max_tokens: this.maxTokens,
+            temperature: this.temperature,
+            stream: false,
+        };
+
+        if (tools && tools.length > 0) {
+            request.tools = tools;
+            request.tool_choice = toolChoice || 'auto';
+        }
+
+        const response = await this.makeRequest<ChatCompletionResponse>('/chat/completions', request);
+
+        return response;
+    }
+
+    /**
+     * Create a streaming chat completion
+     */
+    async *createStreamingChatCompletion(
+        messages: Message[],
+        _tools?: ToolDefinition[],
+        _toolChoice?: ChatCompletionRequest['tool_choice']
+    ): AsyncGenerator<ChatCompletionChunk> {
+        const request: ChatCompletionRequest = {
+            model: this.model,
+            messages,
+            max_tokens: this.maxTokens,
+            temperature: this.temperature,
+            stream: true,
+        };
+
+        // Note: Many vLLM backends don't support tool_choice in streaming mode
+        // So we skip sending tools for streaming requests.
+        // For tool-based workflows, use non-streaming createChatCompletion instead.
+
+        const response = await this.fetchWithRetry('/chat/completions', {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(request),
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new APIError(`API request failed: ${response.status}`, response.status, errorBody);
+        }
+
+        if (!response.body) {
+            throw new APIError('Response body is empty');
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed === 'data: [DONE]') continue;
+                    if (!trimmed.startsWith('data: ')) continue;
+
+                    try {
+                        const data = trimmed.slice(6);
+                        const chunk = JSON.parse(data) as ChatCompletionChunk;
+                        yield chunk;
+                    } catch {
+                        // Skip invalid JSON
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    /**
+     * Convenience method to stream and collect tool calls
+     */
+    async streamChatCompletion(
+        messages: Message[],
+        tools?: ToolDefinition[],
+        onChunk?: (content: string) => void,
+        onToolCalls?: (toolCalls: ToolCall[]) => void
+    ): Promise<{ content: string; toolCalls: ToolCall[]; finishReason: string }> {
+        let content = '';
+        const toolCalls: ToolCall[] = [];
+        const toolCallsMap = new Map<number, ToolCall>();
+        let finishReason = 'stop';
+
+        for await (const chunk of this.createStreamingChatCompletion(messages, tools)) {
+            for (const choice of chunk.choices) {
+                if (choice.finish_reason) {
+                    finishReason = choice.finish_reason;
+                }
+
+                const deltaContent = choice.delta.content;
+                if (typeof deltaContent === 'string') {
+                    content += deltaContent;
+                    onChunk?.(deltaContent);
+                }
+
+                const deltaToolCalls = choice.delta.tool_calls as StreamDelta['tool_calls'];
+                if (deltaToolCalls) {
+                    for (const tc of deltaToolCalls) {
+                        const index = tc.index ?? 0;
+                        const existing = toolCallsMap.get(index);
+                        if (existing) {
+                            // Append to existing tool call
+                            if (tc.function?.arguments) {
+                                existing.function.arguments += tc.function.arguments;
+                            }
+                        } else if (tc.id) {
+                            // New tool call
+                            const newToolCall: ToolCall = {
+                                id: tc.id,
+                                type: 'function',
+                                function: {
+                                    name: tc.function?.name || '',
+                                    arguments: tc.function?.arguments || '',
+                                },
+                            };
+                            toolCallsMap.set(index, newToolCall);
+                        }
+                    }
+                }
+            }
+        }
+
+        // Convert map to array
+        toolCalls.push(...toolCallsMap.values());
+
+        if (toolCalls.length > 0) {
+            onToolCalls?.(toolCalls);
+        }
+
+        return { content, toolCalls, finishReason };
+    }
+
+    /**
+     * Send tool results back to the API
+     */
+    async sendToolResults(
+        messages: Message[],
+        toolResults: ToolResult[],
+        tools?: ToolDefinition[],
+        onChunk?: (content: string) => void,
+        onToolCalls?: (toolCalls: ToolCall[]) => void
+    ): Promise<{ content: string; toolCalls: ToolCall[]; finishReason: string }> {
+        // Add tool results as messages
+        const toolMessages: Message[] = toolResults.map((result) => ({
+            role: 'tool' as const,
+            tool_call_id: result.tool_call_id,
+            content: result.content,
+        }));
+
+        const allMessages = [...messages, ...toolMessages];
+        return this.streamChatCompletion(allMessages, tools, onChunk, onToolCalls);
+    }
+
+    private getHeaders(): Record<string, string> {
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+        };
+
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+
+        return headers;
+    }
+
+    private async makeRequest<T>(endpoint: string, body: unknown): Promise<T> {
+        const response = await this.fetchWithRetry(endpoint, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new APIError(`API request failed: ${response.status}`, response.status, errorBody);
+        }
+
+        return response.json() as Promise<T>;
+    }
+
+    private async fetchWithRetry(
+        endpoint: string,
+        options: RequestInit,
+        retries = MAX_RETRIES
+    ): Promise<Response> {
+        const url = `${this.baseUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            // Retry on 5xx errors
+            if (response.status >= 500 && retries > 0) {
+                await this.delay(RETRY_DELAY_MS * (MAX_RETRIES - retries + 1));
+                return this.fetchWithRetry(endpoint, options, retries - 1);
+            }
+
+            return response;
+        } catch (error) {
+            clearTimeout(timeoutId);
+
+            if (retries > 0 && error instanceof Error && error.name !== 'AbortError') {
+                await this.delay(RETRY_DELAY_MS * (MAX_RETRIES - retries + 1));
+                return this.fetchWithRetry(endpoint, options, retries - 1);
+            }
+
+            throw new APIError(`Network error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    private delay(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    // Getters for current configuration
+    get currentModel(): string {
+        return this.model;
+    }
+
+    get currentBaseUrl(): string {
+        return this.baseUrl;
+    }
+}
+
+// Export singleton instance
+export const apiClient = new APIClient();

package/src/core/api/index.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+export * from './types.js';

package/src/core/api/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Bluehawks CLI - API Types
+ * OpenAI-compatible API type definitions
+ */
+
+// Message Types
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface Message {
+    role: MessageRole;
+    content: string | ContentPart[];
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+
+export interface ContentPart {
+    type: 'text' | 'image_url';
+    text?: string;
+    image_url?: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+
+// Tool Types
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, ToolParameterSchema>;
+            required?: string[];
+        };
+    };
+}
+
+export interface ToolParameterSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    items?: ToolParameterSchema;
+    properties?: Record<string, ToolParameterSchema>;
+    required?: string[];
+}
+
+export interface ToolResult {
+    tool_call_id: string;
+    content: string;
+    isError?: boolean;
+}
+
+// API Request/Response Types
+export interface ChatCompletionRequest {
+    model: string;
+    messages: Message[];
+    tools?: ToolDefinition[];
+    tool_choice?: 'auto' | 'none' | 'required' | { type: 'function'; function: { name: string } };
+    max_tokens?: number;
+    temperature?: number;
+    stream?: boolean;
+    stop?: string[];
+}
+
+export interface ChatCompletionResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Choice[];
+    usage?: Usage;
+}
+
+export interface Choice {
+    index: number;
+    message: Message;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+
+// Streaming Types
+export interface StreamDelta {
+    content?: string;
+    tool_calls?: Array<{
+        index?: number;
+        id?: string;
+        type?: 'function';
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+}
+
+export interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: StreamChoice[];
+}
+
+export interface StreamChoice {
+    index: number;
+    delta: StreamDelta;
+    finish_reason: string | null;
+}
+
+// API Client Options
+export interface APIClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+}
+
+// Streaming callback types
+export type StreamCallback = (chunk: string) => void;
+export type ToolCallCallback = (toolCalls: ToolCall[]) => void;
+
+// API Error
+export class APIError extends Error {
+    constructor(
+        message: string,
+        public statusCode?: number,
+        public response?: unknown
+    ) {
+        super(message);
+        this.name = 'APIError';
+    }
+}

package/src/core/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './manager.js';

package/src/core/hooks/manager.ts

@@ -0,0 +1,212 @@
+/**
+ * Bluehawks CLI - Hooks Manager
+ * Central registry for hook handlers
+ */
+
+import { spawn } from 'node:child_process';
+import type {
+    HookEvent,
+    HookHandler,
+    HookInput,
+    HookOutput,
+    HooksConfig,
+} from './types.js';
+
+export class HooksManager {
+    private handlers: Map<HookEvent, HookHandler[]> = new Map();
+
+    constructor() {
+        // Initialize empty handler arrays for each event
+        const events: HookEvent[] = [
+            'SessionStart',
+            'UserPromptSubmit',
+            'PreToolUse',
+            'PostToolUse',
+            'PostToolUseFailure',
+            'Stop',
+            'SessionEnd',
+        ];
+        for (const event of events) {
+            this.handlers.set(event, []);
+        }
+    }
+
+    /**
+     * Register a hook handler
+     */
+    register(handler: HookHandler): void {
+        const handlers = this.handlers.get(handler.event) || [];
+        handlers.push(handler);
+        this.handlers.set(handler.event, handlers);
+    }
+
+    /**
+     * Register multiple handlers from config
+     */
+    registerFromConfig(config: HooksConfig): void {
+        for (const [event, handlers] of Object.entries(config)) {
+            for (const handler of handlers || []) {
+                this.register({
+                    ...handler,
+                    event: event as HookEvent,
+                    id: handler.id || `${event}-${Date.now()}`,
+                    name: handler.name || handler.command || 'anonymous',
+                });
+            }
+        }
+    }
+
+    /**
+     * Unregister a hook handler by ID
+     */
+    unregister(handlerId: string): boolean {
+        for (const [event, handlers] of this.handlers) {
+            const index = handlers.findIndex((h) => h.id === handlerId);
+            if (index !== -1) {
+                handlers.splice(index, 1);
+                this.handlers.set(event, handlers);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Execute all handlers for an event
+     */
+    async execute(event: HookEvent, input: HookInput): Promise<HookOutput[]> {
+        const handlers = this.handlers.get(event) || [];
+        const results: HookOutput[] = [];
+
+        for (const handler of handlers) {
+            // Check matcher if present
+            if (handler.matcher && 'toolName' in input) {
+                const pattern = typeof handler.matcher === 'string'
+                    ? new RegExp(handler.matcher)
+                    : handler.matcher;
+                if (!pattern.test(input.toolName)) {
+                    continue;
+                }
+            }
+
+            try {
+                const result = await this.executeHandler(handler, input);
+                if (result) {
+                    results.push(result);
+                    // Stop processing if handler blocks
+                    if (result.block) {
+                        break;
+                    }
+                }
+            } catch (error) {
+                console.error(`Hook error (${handler.name}):`, error);
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Execute a single handler
+     */
+    private async executeHandler(
+        handler: HookHandler,
+        input: HookInput
+    ): Promise<HookOutput | void> {
+        const timeout = handler.timeout || 30000;
+
+        // If handler has inline function
+        if (handler.handler) {
+            return Promise.race([
+                handler.handler(input),
+                new Promise<void>((_, reject) =>
+                    setTimeout(() => reject(new Error('Hook timeout')), timeout)
+                ),
+            ]);
+        }
+
+        // If handler has command
+        if (handler.command) {
+            return this.executeCommand(handler.command, input, timeout);
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Execute a shell command hook
+     */
+    private executeCommand(
+        command: string,
+        input: HookInput,
+        timeout: number
+    ): Promise<HookOutput | void> {
+        return new Promise((resolve, reject) => {
+            const proc = spawn('sh', ['-c', command], {
+                env: {
+                    ...process.env,
+                    HOOK_INPUT: JSON.stringify(input),
+                },
+                timeout,
+            });
+
+            let stdout = '';
+            let stderr = '';
+
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+
+            proc.on('close', (code) => {
+                if (code !== 0) {
+                    // Non-zero exit = block action
+                    resolve({
+                        block: true,
+                        blockReason: stderr || `Hook exited with code ${code}`,
+                    });
+                } else {
+                    // Try to parse JSON output
+                    try {
+                        if (stdout.trim()) {
+                            resolve(JSON.parse(stdout) as HookOutput);
+                        } else {
+                            resolve(undefined);
+                        }
+                    } catch {
+                        resolve(undefined);
+                    }
+                }
+            });
+
+            proc.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+
+    /**
+     * Get all registered handlers
+     */
+    getHandlers(event?: HookEvent): HookHandler[] {
+        if (event) {
+            return this.handlers.get(event) || [];
+        }
+        return Array.from(this.handlers.values()).flat();
+    }
+
+    /**
+     * Clear all handlers
+     */
+    clear(): void {
+        for (const event of this.handlers.keys()) {
+            this.handlers.set(event, []);
+        }
+    }
+}
+
+// Singleton instance
+export const hooksManager = new HooksManager();