thatgfsj-code 0.2.1

package/src/core/state.ts

@@ -0,0 +1,120 @@
+/**
+ * S11: State & Session Management
+ * 
+ * Three layers:
+ * 1. EphemeralState  - in-memory, current session only
+ * 2. PersistentState - survives restarts (file-based)
+ * 3. SessionState    - per-conversation state
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * S11: Ephemeral State — in-memory key-value store
+ */
+export class EphemeralState<T = any> {
+  private data: Map<string, T> = new Map();
+
+  get(key: string): T | undefined { return this.data.get(key); }
+  set(key: string, value: T): void { this.data.set(key, value); }
+  has(key: string): boolean { return this.data.has(key); }
+  delete(key: string): void { this.data.delete(key); }
+  clear(): void { this.data.clear(); }
+  keys(): string[] { return [...this.data.keys()]; }
+  entries(): [string, T][] { return [...this.data.entries()]; }
+}
+
+/**
+ * S11: Persistent State — file-backed key-value store
+ */
+export class PersistentState<T = any> {
+  private filePath: string;
+  private data: Record<string, T> = {};
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.filePath)) {
+        this.data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
+      }
+    } catch {
+      this.data = {};
+    }
+  }
+
+  private save(): void {
+    try {
+      writeFileSync(this.filePath, JSON.stringify(this.data, null, 2), 'utf-8');
+    } catch (error: any) {
+      console.error('[State] Failed to save:', error.message);
+    }
+  }
+
+  get(key: string): T | undefined { return this.data[key]; }
+  set(key: string, value: T): void { this.data[key] = value; this.save(); }
+  has(key: string): boolean { return key in this.data; }
+  delete(key: string): void { delete this.data[key]; this.save(); }
+  clear(): void { this.data = {}; this.save(); }
+  keys(): string[] { return Object.keys(this.data); }
+}
+
+/**
+ * S11: Session State — per-conversation state
+ */
+export class SessionState<T = any> {
+  private sessions: Map<string, EphemeralState<T>> = new Map();
+  private currentSessionId: string | null = null;
+
+  createSession(sessionId: string): void {
+    this.sessions.set(sessionId, new EphemeralState<T>());
+  }
+
+  deleteSession(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  setCurrentSession(sessionId: string): void {
+    if (!this.sessions.has(sessionId)) {
+      this.createSession(sessionId);
+    }
+    this.currentSessionId = sessionId;
+  }
+
+  getCurrentSession(): EphemeralState<T> | null {
+    if (!this.currentSessionId) return null;
+    return this.sessions.get(this.currentSessionId) || null;
+  }
+
+  getSession(sessionId: string): EphemeralState<T> | null {
+    return this.sessions.get(sessionId) || null;
+  }
+}
+
+/**
+ * S11: Global State Manager
+ */
+export class StateManager {
+  ephemeral: EphemeralState;
+  persistent: PersistentState;
+  session: SessionState;
+
+  constructor(dataDir: string = join(process.cwd(), '.thatgfsj', 'state')) {
+    this.ephemeral = new EphemeralState();
+    this.persistent = new PersistentState(join(dataDir, 'persistent.json'));
+    this.session = new SessionState();
+  }
+}
+
+let globalStateManager: StateManager | null = null;
+
+export function getStateManager(): StateManager {
+  if (!globalStateManager) {
+    globalStateManager = new StateManager();
+  }
+  return globalStateManager;
+}

package/src/core/subagent.ts

@@ -0,0 +1,195 @@
+/**
+ * S06: Subagent Manager
+ * Spawn and manage subagents for parallel task execution
+ * 
+ * Subagents enable "infinite parallelism" — complex tasks are broken into
+ * independent subtasks, each run by a separate agent instance.
+ */
+
+import { AIEngine, ChatMessage } from './ai-engine.js';
+import { AIConfig } from './types.js';
+
+export interface SubagentOptions {
+  /** Task prompt for the subagent */
+  prompt: string;
+  /** Custom system prompt (optional) */
+  systemPrompt?: string;
+  /** Tools available to this subagent */
+  tools?: any[];
+  /** Max iterations for this subagent */
+  maxIterations?: number;
+  /** Subagent name for logging */
+  name?: string;
+  /** Working directory */
+  cwd?: string;
+}
+
+export interface SubagentResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  iterations: number;
+  durationMs: number;
+  name: string;
+}
+
+/**
+ * S06: Subagent Manager
+ */
+export class SubagentManager {
+  private config: AIConfig;
+  private activeSubagents: Map<string, {
+    task: Promise<SubagentResult>;
+    startedAt: Date;
+    name: string;
+  }> = new Map();
+  private maxConcurrent = 3;
+
+  constructor(config: AIConfig) {
+    this.config = config;
+  }
+
+  /**
+   * S06: Spawn a subagent to run a task asynchronously
+   */
+  async spawn(options: SubagentOptions): Promise<SubagentResult> {
+    const name = options.name || `subagent_${Date.now()}`;
+    const startedAt = new Date();
+
+    const task = this.runSubagent(name, options, startedAt);
+
+    // Track active subagent
+    this.activeSubagents.set(name, { task, startedAt, name });
+
+    // Auto-cleanup after completion
+    task.then(() => {
+      setTimeout(() => this.activeSubagents.delete(name), 5000);
+    }).catch(() => {
+      this.activeSubagents.delete(name);
+    });
+
+    // Return handle — caller can await or ignore
+    return task;
+  }
+
+  /**
+   * S06: Spawn multiple subagents in parallel (bounded concurrency)
+   */
+  async spawnAll(tasks: SubagentOptions[]): Promise<SubagentResult[]> {
+    const results: SubagentResult[] = [];
+    const queue = [...tasks];
+    const running: Promise<void>[] = [];
+
+    while (queue.length > 0 || running.length > 0) {
+      while (running.length < this.maxConcurrent && queue.length > 0) {
+        const task = queue.shift()!;
+        const p: Promise<void> = this.spawn(task).then(r => { results.push(r); }).then(() => {});
+        running.push(p);
+      }
+
+      if (running.length > 0) {
+        await Promise.race(running).catch(() => {});
+        await Promise.allSettled(running);
+        running.length = 0;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * S06: Run a single subagent task
+   */
+  private async runSubagent(
+    name: string,
+    options: SubagentOptions,
+    startedAt: Date
+  ): Promise<SubagentResult> {
+    const startMs = Date.now();
+    let iterations = 0;
+    const maxIterations = options.maxIterations || 5;
+
+    try {
+      // Create isolated AI engine for subagent
+      const subAI = new AIEngine({
+        ...this.config,
+        model: options.systemPrompt ? (this.config.model || 'unknown') : this.config.model
+      });
+
+      // Register tools if provided
+      if (options.tools) {
+        for (const tool of options.tools) {
+          subAI.registerTool(tool);
+        }
+      }
+
+      // Build messages
+      const messages: ChatMessage[] = [];
+      if (options.systemPrompt) {
+        messages.push({ role: 'system', content: options.systemPrompt });
+      } else {
+        messages.push({
+          role: 'system',
+          content: 'You are ' + (options.name || 'a subagent') + '. Complete the task assigned by the parent agent. Be concise and focused.'
+        });
+      }
+      messages.push({ role: 'user', content: options.prompt });
+
+      // Run agent loop
+      let output = '';
+      for await (const chunk of subAI.chatStream(messages, maxIterations)) {
+        output += chunk;
+        iterations++;
+      }
+
+      return {
+        success: true,
+        output,
+        iterations,
+        durationMs: Date.now() - startMs,
+        name
+      };
+
+    } catch (error: any) {
+      return {
+        success: false,
+        output: '',
+        error: error.message,
+        iterations,
+        durationMs: Date.now() - startMs,
+        name
+      };
+    }
+  }
+
+  /**
+   * S06: Get number of active subagents
+   */
+  getActiveCount(): number {
+    return this.activeSubagents.size;
+  }
+
+  /**
+   * S06: Get active subagent names
+   */
+  getActiveNames(): string[] {
+    return [...this.activeSubagents.values()].map(s => s.name);
+  }
+
+  /**
+   * S06: Abort all active subagents
+   */
+  abortAll(): void {
+    for (const [name] of this.activeSubagents) {
+      // Subagents don't have abort support yet, just remove from tracking
+      this.activeSubagents.delete(name);
+    }
+  }
+
+  /**
+   * S06: Set max concurrent subagents
+   */
+  setMaxConcurrent(max: number) {
+    this.maxConcurrent = max;
+  }
+}

package/src/core/system-prompt.ts

@@ -0,0 +1,163 @@
+/**
+ * S04: System Prompt Builder
+ * Dynamic system prompt construction - not a static string, but a program
+ * that assembles context from multiple sources each turn
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { Tool } from './types.js';
+
+export interface SystemPromptConfig {
+  cwd?: string;
+  tools?: Tool[];
+  includeClaudeMd?: boolean;
+  projectInstructions?: string;
+  permissionMode?: 'accept' | 'deny' | 'ask';
+  date?: Date;
+  model?: string;
+}
+
+/**
+ * S04: System Prompt Builder - assembles prompt from multiple fragments
+ */
+export class SystemPromptBuilder {
+  private config: SystemPromptConfig;
+
+  constructor(config: SystemPromptConfig = {}) {
+    this.config = {
+      cwd: process.cwd(),
+      tools: [],
+      includeClaudeMd: true,
+      permissionMode: 'ask',
+      date: new Date(),
+      model: 'unknown',
+      ...config
+    };
+  }
+
+  build(): string {
+    const fragments: string[] = [];
+    fragments.push(this.buildIdentity());
+    fragments.push(this.buildToolInstructions());
+    fragments.push(this.buildEnvironment());
+    fragments.push(this.buildPermissionMode());
+    fragments.push(this.buildProjectInstructions());
+    fragments.push(this.buildDateInfo());
+    fragments.push(this.buildOutputFormat());
+    return fragments.filter(Boolean).join('\n\n');
+  }
+
+  private buildIdentity(): string {
+    return [
+      'You are Thatgfsj Code, an AI coding assistant.',
+      '',
+      'You have access to tools (file operations, shell commands, git, search) that let you',
+      'read, write, and modify files and run commands.',
+      '',
+      'Be concise, helpful, and show your reasoning when working through problems.',
+      '',
+      'When using tools:',
+      '- Prefer small, targeted operations over large batch changes',
+      '- Confirm destructive operations (rm, git push --force, etc.)',
+      '- Explain what you are going to do before doing it',
+      '- If something is not clear, ask clarifying questions'
+    ].join('\n');
+  }
+
+  private buildToolInstructions(): string {
+    const tools = this.config.tools || [];
+    if (tools.length === 0) {
+      return '## Tools\n\nNo tools are currently registered.';
+    }
+
+    const toolDescs = tools.map(t => {
+      const params = t.parameters
+        .map(p => '  - ' + p.name + ' (' + p.type + (p.required ? ', required' : '') + '): ' + p.description)
+        .join('\n');
+      return '### ' + t.name + '\n' + t.description + '\n\nParameters:\n' + params;
+    }).join('\n\n');
+
+    return '## Tools\n\nYou have access to the following tools:\n\n' + toolDescs + '\n\nTo use a tool, respond with a tool call. Each tool call must include:\n- The tool name\n- Parameters as a JSON object';
+  }
+
+  private buildEnvironment(): string {
+    const cwd = this.config.cwd || process.cwd();
+    return '## Environment\n\nWorking directory: ' + cwd;
+  }
+
+  private buildPermissionMode(): string {
+    const mode = this.config.permissionMode || 'ask';
+    const explanations: Record<string, string> = {
+      accept: 'All tool calls are automatically allowed without confirmation.',
+      deny: 'All tool calls are blocked. You may only read and discuss.',
+      ask: 'Dangerous or destructive commands require your confirmation before execution.'
+    };
+    return '## Permission Mode\n\nCurrent mode: ' + mode + '\n\n' + (explanations[mode] || '');
+  }
+
+  private buildProjectInstructions(): string {
+    const cwd = this.config.cwd || process.cwd();
+    if (this.config.includeClaudeMd !== false) {
+      const paths = [join(cwd, 'CLAUDE.md'), join(cwd, '.claude.md')];
+      for (const path of paths) {
+        if (existsSync(path)) {
+          try {
+            const content = readFileSync(path, 'utf-8');
+            return '## Project Instructions (from ' + path.split(/[/\\]/).pop() + ')\n\n' + content;
+          } catch {
+            // Ignore
+          }
+        }
+      }
+    }
+    if (this.config.projectInstructions) {
+      return '## Project Instructions\n\n' + this.config.projectInstructions;
+    }
+    return '';
+  }
+
+  private buildDateInfo(): string {
+    const now = this.config.date || new Date();
+    const iso = now.toISOString().replace('T', ' ').split('.')[0];
+    return '## Current Time\n\n' + iso;
+  }
+
+  private buildOutputFormat(): string {
+    return [
+      '## Output Format',
+      '',
+      '- Use clear section headers for multi-part responses',
+      '- Use bullet points for lists',
+      '- Use code blocks for code',
+      '- Be concise, avoid unnecessary repetition',
+      '- If you need multiple steps, explain the plan first'
+    ].join('\n');
+  }
+
+  setTools(tools: Tool[]) { this.config.tools = tools; return this; }
+  setCwd(cwd: string) { this.config.cwd = cwd; return this; }
+  setPermissionMode(mode: 'accept' | 'deny' | 'ask') { this.config.permissionMode = mode; return this; }
+  setProjectInstructions(instructions: string) { this.config.projectInstructions = instructions; return this; }
+  setModel(model: string) { this.config.model = model; return this; }
+
+  buildToolsFragment(): string { return this.buildToolInstructions(); }
+
+  injectReminder(reminder: string): string {
+    return '\n## Reminder\n\n' + reminder + '\n';
+  }
+}
+
+let globalBuilder: SystemPromptBuilder | null = null;
+
+export function getSystemPromptBuilder(config?: SystemPromptConfig): SystemPromptBuilder {
+  if (!globalBuilder) globalBuilder = new SystemPromptBuilder(config);
+  return globalBuilder;
+}
+
+export function updateSystemPrompt(tools?: Tool[], permissionMode?: 'accept' | 'deny' | 'ask') {
+  if (globalBuilder) {
+    if (tools) globalBuilder.setTools(tools);
+    if (permissionMode) globalBuilder.setPermissionMode(permissionMode);
+  }
+}

package/src/core/tool-registry.ts

@@ -0,0 +1,157 @@
+/**
+ * Tool Registry - Manages available tools with context support
+ * S02: Enhanced with inputSchema generation and permission metadata
+ */
+
+import { Tool, ToolResult, ToolContext, ToolInputSchema } from './types.js';
+
+export class ToolRegistry {
+  private tools: Map<string, Tool> = new Map();
+  private context: ToolContext = {};
+
+  constructor() {
+    this.registerDefaultTools();
+  }
+
+  setContext(ctx: Partial<ToolContext>) {
+    this.context = { ...this.context, ...ctx };
+  }
+
+  getContext(): ToolContext {
+    return this.context;
+  }
+
+  register(tool: Tool): void {
+    if (this.tools.has(tool.name)) {
+      console.warn(`Tool ${tool.name} already exists, overwriting...`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * S02: Get tools formatted for AI API
+   * Uses inputSchema if available, otherwise builds from parameters
+   */
+  getToolsForAPI() {
+    return Array.from(this.tools.values()).map(tool => ({
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.inputSchema || this.buildInputSchema(tool)
+      }
+    }));
+  }
+
+  /**
+   * S02: Build JSON Schema from legacy parameters array
+   */
+  private buildInputSchema(tool: Tool): ToolInputSchema {
+    return {
+      type: 'object',
+      properties: tool.parameters.reduce((acc, p) => {
+        acc[p.name] = {
+          type: p.type === 'string' ? 'string'
+              : p.type === 'number' ? 'number'
+              : p.type === 'boolean' ? 'boolean'
+              : 'string',
+          description: p.description
+        };
+        return acc;
+      }, {} as Record<string, { type: string; description: string }>),
+      required: tool.parameters.filter(p => p.required).map(p => p.name)
+    };
+  }
+
+  /**
+   * S02: List all tools with their metadata
+   */
+  listAll() {
+    return Array.from(this.tools.values()).map(t => ({
+      name: t.name,
+      description: t.description,
+      permissions: t.metadata?.permissions,
+      tags: t.metadata?.tags,
+      deprecated: t.metadata?.deprecated
+    }));
+  }
+
+  async execute(name: string, params: Record<string, any>): Promise<ToolResult> {
+    const tool = this.tools.get(name);
+
+    if (!tool) {
+      return { success: false, error: `Tool "${name}" not found` };
+    }
+
+    // S02: Validate params against inputSchema
+    const validationError = this.validateParams(tool, params);
+    if (validationError) {
+      return { success: false, error: validationError };
+    }
+
+    try {
+      return await tool.execute(params, this.context);
+    } catch (error: any) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * S02: Validate params against tool's inputSchema
+   */
+  private validateParams(tool: Tool, params: Record<string, any>): string | null {
+    const schema = tool.inputSchema || this.buildInputSchema(tool);
+
+    // Check required
+    if (schema.required) {
+      for (const req of schema.required) {
+        if (params[req] === undefined || params[req] === null) {
+          return `Missing required parameter: ${req}`;
+        }
+      }
+    }
+
+    // Check types
+    for (const [key, value] of Object.entries(params)) {
+      const prop = schema.properties[key];
+      if (prop && value !== undefined) {
+        const expectedType = prop.type;
+        const actualType = typeof value;
+        // Type coercion for string/number
+        if (expectedType === 'number' && actualType === 'string' && !isNaN(Number(value))) {
+          // Auto-coerce strings to numbers — ok
+        } else if (actualType !== expectedType) {
+          return `Invalid type for ${key}: expected ${expectedType}, got ${actualType}`;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  async executeAll(tools: Array<{ name: string; params: Record<string, any> }>): Promise<ToolResult[]> {
+    const results: ToolResult[] = [];
+    for (const { name, params } of tools) {
+      const result = await this.execute(name, params);
+      results.push(result);
+      if (!result.success) break;
+    }
+    return results;
+  }
+
+  private registerDefaultTools(): void {
+    // Tools registered externally via AIEngine
+  }
+}