zerg-ztc 0.1.0

package/src/agent/agent.ts

@@ -0,0 +1,407 @@
+// Standard library
+import { existsSync, readFileSync } from 'fs';
+import { extname } from 'path';
+
+// Local
+import { Message, ToolCall, AgentEvent } from '../types.js';
+import { AnthropicBackend, AgentBackend, BackendRequest, BackendResponse, ContentBlock, LlmMessage, RequestContentBlock, TokenUsage } from './backends/index.js';
+import { AllowAllPolicy, Policy } from './runtime/policy.js';
+import { NoopTracer, Tracer } from './runtime/tracing.js';
+import { defaultTools, executeTool, getToolDefinitions, getTool } from './tools/index.js';
+
+// --- Types ---
+
+export interface AgentConfig {
+  model?: string;
+  apiKey?: string;
+  apiEndpoint?: string;
+  maxTokens?: number;
+  maxIterations?: number;
+  tools?: typeof defaultTools;
+  systemPrompt?: string;
+  backend?: AgentBackend;
+  policy?: Policy;
+  tracer?: Tracer;
+}
+
+export class AgentError extends Error {
+  constructor(message: string, public code?: string) {
+    super(message);
+    this.name = 'AgentError';
+  }
+}
+
+export type EventHandler = (event: AgentEvent) => void;
+
+// --- Agent Class ---
+
+export class Agent {
+  private config: Required<AgentConfig>;
+  private eventHandlers: Set<EventHandler> = new Set();
+  private backend: AgentBackend;
+  private policy: Policy;
+  private tracer: Tracer;
+  private streamChunkSize = 32;
+  
+  constructor(config: AgentConfig = {}) {
+    const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY || '';
+    
+    this.config = {
+      model: config.model || 'claude-opus-4-20250514',
+      apiKey,
+      apiEndpoint: config.apiEndpoint || 'https://api.anthropic.com/v1/messages',
+      maxTokens: config.maxTokens || 4096,
+      maxIterations: config.maxIterations || 10,
+      tools: config.tools || defaultTools,
+      systemPrompt: config.systemPrompt || this.getDefaultSystemPrompt(),
+      backend: config.backend || new AnthropicBackend({ apiKey, apiEndpoint: config.apiEndpoint }),
+      policy: config.policy || new AllowAllPolicy(),
+      tracer: config.tracer || new NoopTracer()
+    };
+
+    this.backend = this.config.backend;
+    this.policy = this.config.policy;
+    this.tracer = this.config.tracer;
+  }
+
+  hasApiKey(): boolean {
+    return !!this.config.apiKey && this.config.apiKey.length > 0;
+  }
+
+  private getDefaultSystemPrompt(): string {
+    return `You are ZTC (Zerg Terminal Client), an AI assistant that helps users interact with the Zerg continual AI system and manage local development tasks.
+
+You have access to tools for:
+- Reading and writing files
+- Listing directory contents  
+- Running shell commands
+- Querying the Zerg system
+
+Be concise and helpful. When using tools, explain what you're doing briefly. If a task requires multiple steps, proceed through them systematically.`;
+  }
+
+  // Event handling
+  on(handler: EventHandler): () => void {
+    this.eventHandlers.add(handler);
+    return () => this.eventHandlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    for (const handler of this.eventHandlers) {
+      handler(event);
+    }
+  }
+
+  // Convert messages to API format
+  private formatMessages(messages: Message[]): LlmMessage[] {
+    return messages
+      .filter((m): m is Message & { role: 'user' | 'assistant' } => m.role === 'user' || m.role === 'assistant')
+      .map(m => ({
+        role: m.role,
+        content: m.role === 'user' ? this.buildContentBlocks(m.content) : m.content
+      }));
+  }
+
+  private contentLength(content: string | RequestContentBlock[]): number {
+    if (typeof content === 'string') return content.length;
+    return content.reduce((sum, block) => {
+      if (block.type === 'text') return sum + block.text.length;
+      return sum + block.data.length;
+    }, 0);
+  }
+
+  private buildContentBlocks(content: string): string | RequestContentBlock[] {
+    const trimmed = content.trimStart();
+    if (trimmed.startsWith('[') && trimmed.includes('"tool_use_id"')) {
+      return content;
+    }
+
+    const imageRegex = /\[image ([^\]]+)\]/g;
+    let match: RegExpExecArray | null;
+    let cursor = 0;
+    const blocks: RequestContentBlock[] = [];
+
+    while ((match = imageRegex.exec(content)) !== null) {
+      const start = match.index;
+      const end = match.index + match[0].length;
+      if (start > cursor) {
+        blocks.push({ type: 'text', text: content.slice(cursor, start) });
+      }
+      const path = match[1].trim();
+      const imageBlock = this.loadImageBlock(path);
+      if (imageBlock) {
+        blocks.push(imageBlock);
+      } else {
+        blocks.push({ type: 'text', text: match[0] });
+      }
+      cursor = end;
+    }
+
+    if (blocks.length === 0) return content;
+    if (cursor < content.length) {
+      blocks.push({ type: 'text', text: content.slice(cursor) });
+    }
+
+    const merged: RequestContentBlock[] = [];
+    for (const block of blocks) {
+      const last = merged[merged.length - 1];
+      if (block.type === 'text' && last?.type === 'text') {
+        last.text += block.text;
+        continue;
+      }
+      merged.push(block);
+    }
+
+    const hasImage = merged.some(block => block.type === 'image');
+    return hasImage ? merged : content;
+  }
+
+  private loadImageBlock(path: string): RequestContentBlock | null {
+    try {
+      if (!existsSync(path)) return null;
+      const ext = extname(path).toLowerCase();
+      const mediaType = this.getImageMediaType(ext);
+      if (!mediaType) return null;
+      const buffer = readFileSync(path);
+      return {
+        type: 'image',
+        mediaType,
+        data: buffer.toString('base64'),
+        path
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private getImageMediaType(ext: string): string | null {
+    switch (ext) {
+      case '.png':
+        return 'image/png';
+      case '.jpg':
+      case '.jpeg':
+        return 'image/jpeg';
+      case '.webp':
+        return 'image/webp';
+      case '.gif':
+        return 'image/gif';
+      case '.bmp':
+        return 'image/bmp';
+      case '.tif':
+      case '.tiff':
+        return 'image/tiff';
+      case '.heic':
+      case '.heif':
+        return 'image/heic';
+      default:
+        return null;
+    }
+  }
+
+  // Type guards
+  private isTextBlock(block: ContentBlock): block is { type: 'text'; text: string } {
+    return block.type === 'text';
+  }
+
+  private isToolUseBlock(block: ContentBlock): block is { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> } {
+    return block.type === 'tool_use';
+  }
+
+  private buildRequest(messages: Message[]): BackendRequest {
+    return {
+      model: this.config.model,
+      maxTokens: this.config.maxTokens,
+      system: this.config.systemPrompt,
+      messages: this.formatMessages(messages),
+      tools: getToolDefinitions(this.config.tools)
+    };
+  }
+
+  private estimateUsage(request: BackendRequest, response: BackendResponse): TokenUsage {
+    const inputChars = request.system.length + request.messages.reduce((sum, msg) => sum + this.contentLength(msg.content), 0);
+    const outputChars = response.content
+      .filter(this.isTextBlock)
+      .reduce((sum, block) => sum + block.text.length, 0);
+    const inputTokens = Math.max(1, Math.ceil(inputChars / 4));
+    const outputTokens = Math.max(1, Math.ceil(outputChars / 4));
+    return {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      estimated: true
+    };
+  }
+
+  private mergeUsage(current: TokenUsage | null, next: TokenUsage): TokenUsage {
+    if (!current) return next;
+    return {
+      inputTokens: current.inputTokens + next.inputTokens,
+      outputTokens: current.outputTokens + next.outputTokens,
+      totalTokens: current.totalTokens + next.totalTokens,
+      estimated: current.estimated || next.estimated
+    };
+  }
+
+  private async emitStreamText(text: string): Promise<void> {
+    this.emit({ type: 'stream_start' });
+    for (let i = 0; i < text.length; i += this.streamChunkSize) {
+      const chunk = text.slice(i, i + this.streamChunkSize);
+      this.emit({ type: 'stream_delta', content: chunk });
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+    this.emit({ type: 'stream_end' });
+  }
+
+  // Main execution loop
+  async run(messages: Message[]): Promise<{ content: string; toolCalls: ToolCall[]; usage?: TokenUsage }> {
+    if (!this.hasApiKey()) {
+      throw new AgentError('No API key configured. Use /config key <key> to set one.', 'NO_API_KEY');
+    }
+
+    const allToolCalls: ToolCall[] = [];
+    let iterations = 0;
+    let finalContent = '';
+    let totalUsage: TokenUsage | null = null;
+
+    while (iterations < this.config.maxIterations) {
+      iterations++;
+      this.emit({ type: 'thinking_start' });
+
+      try {
+        // Call the API
+        const request = this.buildRequest(messages);
+        this.tracer.event({ type: 'api_request', timestamp: new Date() });
+        const response = await this.callAPI(request);
+        this.tracer.event({ type: 'api_response', timestamp: new Date(), data: { stopReason: response.stopReason } });
+        this.emit({ type: 'thinking_end' });
+
+        const usage = response.usage ?? this.estimateUsage(request, response);
+        totalUsage = this.mergeUsage(totalUsage, usage);
+        this.emit({ type: 'token_usage', usage: totalUsage });
+
+        // Check for tool use
+        const toolUseBlocks = response.content.filter(this.isToolUseBlock);
+
+        if (toolUseBlocks.length === 0) {
+          // No tools, extract text and finish
+          const textBlocks = response.content.filter(this.isTextBlock);
+          finalContent = textBlocks.map(b => b.text).join('\n');
+          await this.emitStreamText(finalContent);
+          break;
+        }
+
+        // Execute tools
+        const toolResults: Array<{ tool_use_id: string; content: string }> = [];
+        
+        for (const toolBlock of toolUseBlocks) {
+          const toolCall: ToolCall = {
+            id: toolBlock.id,
+            name: toolBlock.name,
+            args: toolBlock.input,
+            status: 'running',
+            startedAt: new Date()
+          };
+          allToolCalls.push(toolCall);
+          
+          const tool = getTool(toolBlock.name, this.config.tools);
+          const policyDecision = this.policy.evaluateTool({
+            name: toolBlock.name,
+            args: toolBlock.input,
+            capabilities: tool?.capabilities || []
+          });
+
+          if (!policyDecision.allowed) {
+            const reason = policyDecision.reason || 'Policy denied tool execution';
+            toolCall.status = 'error';
+            toolCall.error = reason;
+            toolCall.completedAt = new Date();
+            toolResults.push({ tool_use_id: toolBlock.id, content: `Error: ${reason}` });
+            this.emit({ type: 'tool_error', tool: toolBlock.name, error: reason });
+            this.tracer.event({
+              type: 'policy_denied',
+              timestamp: new Date(),
+              data: { tool: toolBlock.name, reason }
+            });
+            continue;
+          }
+
+          this.tracer.event({
+            type: 'tool_start',
+            timestamp: new Date(),
+            data: { tool: toolBlock.name }
+          });
+          this.emit({ type: 'tool_start', tool: toolBlock.name, args: toolBlock.input });
+
+          try {
+            const result = await executeTool(
+              toolBlock.name, 
+              toolBlock.input,
+              this.config.tools
+            );
+            
+            toolCall.status = 'complete';
+            toolCall.result = result;
+            toolCall.completedAt = new Date();
+            
+            toolResults.push({ tool_use_id: toolBlock.id, content: result });
+            this.emit({ type: 'tool_end', tool: toolBlock.name, result });
+            this.tracer.event({
+              type: 'tool_end',
+              timestamp: new Date(),
+              data: { tool: toolBlock.name }
+            });
+          } catch (err) {
+            const error = (err as Error).message;
+            toolCall.status = 'error';
+            toolCall.error = error;
+            toolCall.completedAt = new Date();
+            
+            toolResults.push({ tool_use_id: toolBlock.id, content: `Error: ${error}` });
+            this.emit({ type: 'tool_error', tool: toolBlock.name, error });
+            this.tracer.event({
+              type: 'tool_error',
+              timestamp: new Date(),
+              data: { tool: toolBlock.name, error }
+            });
+          }
+        }
+
+        // Add assistant message with tool use
+        const textContent = response.content
+          .filter(this.isTextBlock)
+          .map(b => b.text)
+          .join('\n');
+        
+        messages.push({
+          id: `assistant_${Date.now()}`,
+          role: 'assistant',
+          content: textContent || '[Using tools...]',
+          timestamp: new Date(),
+          toolCalls: allToolCalls.slice(-toolUseBlocks.length)
+        });
+
+        // Add tool results as user message (API format)
+        messages.push({
+          id: `tool_${Date.now()}`,
+          role: 'user',
+          content: JSON.stringify(toolResults),
+          timestamp: new Date()
+        });
+
+      } catch (err) {
+        const error = (err as Error).message;
+        this.emit({ type: 'error', error });
+        throw err;
+      }
+    }
+
+    return { content: finalContent, toolCalls: allToolCalls, usage: totalUsage || undefined };
+  }
+
+  // API call
+  private async callAPI(request: BackendRequest): Promise<BackendResponse> {
+    return this.backend.generate(request);
+  }
+}
+
+export default Agent;

package/src/agent/backends/anthropic.ts

@@ -0,0 +1,76 @@
+import { AgentBackend, BackendRequest, BackendResponse } from './types.js';
+
+interface AnthropicBackendConfig {
+  apiKey: string;
+  apiEndpoint?: string;
+}
+
+interface AnthropicResponse {
+  content: BackendResponse['content'];
+  stop_reason: string;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+  };
+}
+
+export class AnthropicBackend implements AgentBackend {
+  private apiKey: string;
+  private apiEndpoint: string;
+
+  constructor(config: AnthropicBackendConfig) {
+    this.apiKey = config.apiKey;
+    this.apiEndpoint = config.apiEndpoint || 'https://api.anthropic.com/v1/messages';
+  }
+
+  async generate(request: BackendRequest): Promise<BackendResponse> {
+    const body = {
+      model: request.model,
+      max_tokens: request.maxTokens,
+      system: request.system,
+      messages: request.messages.map(message => ({
+        role: message.role,
+        content: typeof message.content === 'string'
+          ? message.content
+          : message.content.map(block => (
+            block.type === 'text'
+              ? { type: 'text', text: block.text }
+              : { type: 'image', source: { type: 'base64', media_type: block.mediaType, data: block.data } }
+          ))
+      })),
+      tools: request.tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters
+      }))
+    };
+
+    const response = await fetch(this.apiEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01'
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json() as AnthropicResponse;
+    const inputTokens = data.usage?.input_tokens ?? 0;
+    const outputTokens = data.usage?.output_tokens ?? 0;
+    return {
+      content: data.content,
+      stopReason: data.stop_reason,
+      usage: data.usage ? {
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens
+      } : undefined
+    };
+  }
+}

package/src/agent/backends/gemini.ts

@@ -0,0 +1,107 @@
+import { AgentBackend, BackendRequest, BackendResponse, ContentBlock } from './types.js';
+
+interface GeminiConfig {
+  apiKey: string;
+  apiEndpoint?: string;
+}
+
+interface GeminiCandidate {
+  content?: {
+    parts?: Array<{
+      text?: string;
+      functionCall?: {
+        name?: string;
+        args?: Record<string, unknown>;
+      };
+    }>;
+  };
+  finishReason?: string;
+}
+
+interface GeminiResponse {
+  candidates?: GeminiCandidate[];
+  usageMetadata?: {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+  };
+}
+
+export class GeminiBackend implements AgentBackend {
+  private apiKey: string;
+  private apiEndpoint: string;
+
+  constructor(config: GeminiConfig) {
+    this.apiKey = config.apiKey;
+    this.apiEndpoint = config.apiEndpoint || 'https://generativelanguage.googleapis.com/v1beta/models';
+  }
+
+  async generate(request: BackendRequest): Promise<BackendResponse> {
+    const url = `${this.apiEndpoint}/${encodeURIComponent(request.model)}:generateContent?key=${this.apiKey}`;
+    const mapParts = (content: BackendRequest['messages'][number]['content']) => {
+      if (typeof content === 'string') {
+        return [{ text: content }];
+      }
+      return content.map(block => {
+        if (block.type === 'text') {
+          return { text: block.text };
+        }
+        return { inlineData: { mimeType: block.mediaType, data: block.data } };
+      });
+    };
+    const body = {
+      systemInstruction: { parts: [{ text: request.system }] },
+      contents: request.messages.map(m => ({
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: mapParts(m.content)
+      })),
+      tools: [{
+        functionDeclarations: request.tools.map(t => ({
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        }))
+      }]
+    };
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json() as GeminiResponse;
+    const candidate = data.candidates?.[0];
+    const blocks: ContentBlock[] = [];
+    const parts = candidate?.content?.parts || [];
+
+    for (const part of parts) {
+      if (part.text) {
+        blocks.push({ type: 'text', text: part.text });
+      }
+      if (part.functionCall?.name) {
+        blocks.push({
+          type: 'tool_use',
+          id: `${part.functionCall.name}_${Date.now()}`,
+          name: part.functionCall.name,
+          input: part.functionCall.args || {}
+        });
+      }
+    }
+
+    const inputTokens = data.usageMetadata?.promptTokenCount ?? 0;
+    const outputTokens = data.usageMetadata?.candidatesTokenCount ?? 0;
+    const totalTokens = data.usageMetadata?.totalTokenCount ?? (inputTokens + outputTokens);
+
+    return {
+      content: blocks,
+      stopReason: candidate?.finishReason || 'unknown',
+      usage: data.usageMetadata ? { inputTokens, outputTokens, totalTokens } : undefined
+    };
+  }
+}

package/src/agent/backends/inception.ts

@@ -0,0 +1,23 @@
+import { OpenAICompatibleBackend } from './openai_compatible.js';
+import { AgentBackend, BackendRequest, BackendResponse } from './types.js';
+
+interface InceptionConfig {
+  apiKey: string;
+  apiEndpoint?: string;
+}
+
+export class InceptionBackend implements AgentBackend {
+  private backend: OpenAICompatibleBackend;
+
+  constructor(config: InceptionConfig) {
+    this.backend = new OpenAICompatibleBackend({
+      apiKey: config.apiKey,
+      baseUrl: config.apiEndpoint || 'https://api.inceptionlabs.ai/v1',
+      apiPath: '/chat/completions'
+    });
+  }
+
+  async generate(request: BackendRequest): Promise<BackendResponse> {
+    return this.backend.generate(request);
+  }
+}

package/src/agent/backends/index.ts

@@ -0,0 +1,16 @@
+export { AnthropicBackend } from './anthropic.js';
+export { OpenAIBackend } from './openai.js';
+export { OpenAICompatibleBackend } from './openai_compatible.js';
+export { InceptionBackend } from './inception.js';
+export { GeminiBackend } from './gemini.js';
+export type {
+  AgentBackend,
+  BackendRequest,
+  BackendResponse,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  LlmMessage,
+  RequestContentBlock,
+  TokenUsage
+} from './types.js';

package/src/agent/backends/openai.ts

@@ -0,0 +1,23 @@
+import { OpenAICompatibleBackend } from './openai_compatible.js';
+import { AgentBackend, BackendRequest, BackendResponse } from './types.js';
+
+interface OpenAIConfig {
+  apiKey: string;
+  apiEndpoint?: string;
+}
+
+export class OpenAIBackend implements AgentBackend {
+  private backend: OpenAICompatibleBackend;
+
+  constructor(config: OpenAIConfig) {
+    this.backend = new OpenAICompatibleBackend({
+      apiKey: config.apiKey,
+      baseUrl: config.apiEndpoint || 'https://api.openai.com/v1',
+      apiPath: '/chat/completions'
+    });
+  }
+
+  async generate(request: BackendRequest): Promise<BackendResponse> {
+    return this.backend.generate(request);
+  }
+}