refactor: extract services layer, Result type, and ErrorCode classification

- Add DI container (src/services/) with AgentExecutionService, ConfigLoaderService, and ExploitationCheckerService — pure domain logic with no Temporal dependencies
- Introduce Result<T, E> type and ErrorCode enum for code-based error classification in classifyErrorForTemporal, replacing scattered string matching
- Consolidate billing/spending cap detection into utils/billing-detection.ts with shared pattern lists across message-handlers, claude-executor, and error-handling
- Extract LogStream abstraction for append-only logging with backpressure, used by both AgentLogger and WorkflowLogger
- Simplify activities.ts from inline lifecycle logic to thin wrappers delegating to services, with heartbeat and error classification
- Expand config-parser with human-readable AJV errors, security validation, and rule type-specific checks

src/audit/audit-session.ts

@@ -18,6 +18,8 @@ import { initializeAuditStructure, type SessionMetadata } from './utils.js';
 import { formatTimestamp } from '../utils/formatting.js';
 import { SessionMutex } from '../utils/concurrency.js';
 import type { AgentEndResult } from '../types/index.js';
+import { PentestError } from '../error-handling.js';
+import { ErrorCode } from '../types/errors.js';
 
 // Global mutex instance
 const sessionMutex = new SessionMutex();
@@ -40,10 +42,22 @@ export class AuditSession {
 
     // Validate required fields
     if (!this.sessionId) {
-      throw new Error('sessionMetadata.id is required');
+      throw new PentestError(
+        'sessionMetadata.id is required',
+        'config',
+        false,
+        { field: 'sessionMetadata.id' },
+        ErrorCode.CONFIG_VALIDATION_FAILED
+      );
     }
     if (!this.sessionMetadata.webUrl) {
-      throw new Error('sessionMetadata.webUrl is required');
+      throw new PentestError(
+        'sessionMetadata.webUrl is required',
+        'config',
+        false,
+        { field: 'sessionMetadata.webUrl' },
+        ErrorCode.CONFIG_VALIDATION_FAILED
+      );
     }
 
     // Components
@@ -124,7 +138,13 @@ export class AuditSession {
    */
   async logEvent(eventType: string, eventData: unknown): Promise<void> {
     if (!this.currentLogger) {
-      throw new Error('No active logger. Call startAgent() first.');
+      throw new PentestError(
+        'No active logger. Call startAgent() first.',
+        'validation',
+        false,
+        {},
+        ErrorCode.AGENT_EXECUTION_FAILED
+      );
     }
 
     // Log to agent-specific log file (JSON format)

src/audit/log-stream.ts

@@ -0,0 +1,127 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * LogStream - Stream composition utility for append-only logging
+ *
+ * Encapsulates the common stream management pattern used by AgentLogger
+ * and WorkflowLogger: opening streams in append mode, handling backpressure,
+ * and proper cleanup.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { ensureDirectory } from '../utils/file-io.js';
+
+/**
+ * LogStream - Manages a single append-only log file stream
+ */
+export class LogStream {
+  private readonly filePath: string;
+  private stream: fs.WriteStream | null = null;
+  private _isOpen: boolean = false;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  /**
+   * Open the stream for writing (creates parent directories, opens in append mode)
+   */
+  async open(): Promise<void> {
+    if (this._isOpen) {
+      return;
+    }
+
+    // Ensure parent directory exists
+    await ensureDirectory(path.dirname(this.filePath));
+
+    // Create write stream in append mode
+    this.stream = fs.createWriteStream(this.filePath, {
+      flags: 'a',
+      encoding: 'utf8',
+      autoClose: true,
+    });
+
+    // Handle stream errors to prevent crashes (log and mark closed)
+    this.stream.on('error', (err) => {
+      console.error(`LogStream error for ${this.filePath}:`, err.message);
+      this._isOpen = false;
+    });
+
+    this._isOpen = true;
+  }
+
+  /**
+   * Write text to the stream with backpressure handling
+   */
+  async write(text: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this._isOpen || !this.stream) {
+        reject(new Error('LogStream not open'));
+        return;
+      }
+
+      const stream = this.stream;
+      let drainHandler: (() => void) | null = null;
+
+      const cleanup = () => {
+        if (drainHandler) {
+          stream.removeListener('drain', drainHandler);
+          drainHandler = null;
+        }
+      };
+
+      const needsDrain = !stream.write(text, 'utf8', (error) => {
+        cleanup();
+        if (error) {
+          reject(error);
+        } else if (!needsDrain) {
+          resolve();
+        }
+      });
+
+      if (needsDrain) {
+        drainHandler = () => {
+          cleanup();
+          resolve();
+        };
+        stream.once('drain', drainHandler);
+      }
+    });
+  }
+
+  /**
+   * Close the stream (flush and close)
+   */
+  async close(): Promise<void> {
+    if (!this._isOpen || !this.stream) {
+      return;
+    }
+
+    return new Promise((resolve) => {
+      this.stream!.end(() => {
+        this._isOpen = false;
+        this.stream = null;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Check if the stream is currently open
+   */
+  get isOpen(): boolean {
+    return this._isOpen;
+  }
+
+  /**
+   * Get the file path this stream writes to
+   */
+  get path(): string {
+    return this.filePath;
+  }
+}

src/audit/logger.ts

@@ -8,10 +8,9 @@
  * Append-Only Agent Logger
  *
  * Provides crash-safe, append-only logging for agent execution.
- * Uses file streams with immediate flush to prevent data loss.
+ * Uses LogStream for stream management with backpressure handling.
  */
 
-import fs from 'fs';
 import {
   generateLogPath,
   generatePromptPath,
@@ -19,6 +18,7 @@ import {
 } from './utils.js';
 import { atomicWrite } from '../utils/file-io.js';
 import { formatTimestamp } from '../utils/formatting.js';
+import { LogStream } from './log-stream.js';
 
 interface LogEvent {
   type: string;
@@ -30,13 +30,11 @@ interface LogEvent {
  * AgentLogger - Manages append-only logging for a single agent execution
  */
 export class AgentLogger {
-  private sessionMetadata: SessionMetadata;
-  private agentName: string;
-  private attemptNumber: number;
-  private timestamp: number;
-  private logPath: string;
-  private stream: fs.WriteStream | null = null;
-  private isOpen: boolean = false;
+  private readonly sessionMetadata: SessionMetadata;
+  private readonly agentName: string;
+  private readonly attemptNumber: number;
+  private readonly timestamp: number;
+  private readonly logStream: LogStream;
 
   constructor(sessionMetadata: SessionMetadata, agentName: string, attemptNumber: number) {
     this.sessionMetadata = sessionMetadata;
@@ -44,26 +42,20 @@ export class AgentLogger {
     this.attemptNumber = attemptNumber;
     this.timestamp = Date.now();
 
-    // Generate log file path
-    this.logPath = generateLogPath(sessionMetadata, agentName, this.timestamp, attemptNumber);
+    // Generate log file path and create stream
+    const logPath = generateLogPath(sessionMetadata, agentName, this.timestamp, attemptNumber);
+    this.logStream = new LogStream(logPath);
   }
 
   /**
    * Initialize the log stream (creates file and opens stream)
    */
   async initialize(): Promise<void> {
-    if (this.isOpen) {
+    if (this.logStream.isOpen) {
       return; // Already initialized
     }
 
-    // Create write stream with append mode and auto-flush
-    this.stream = fs.createWriteStream(this.logPath, {
-      flags: 'a', // Append mode
-      encoding: 'utf8',
-      autoClose: true,
-    });
-
-    this.isOpen = true;
+    await this.logStream.open();
 
     // Write header
     await this.writeHeader();
@@ -83,29 +75,7 @@ export class AgentLogger {
       `========================================\n`,
     ].join('\n');
 
-    return this.writeRaw(header);
-  }
-
-  /**
-   * Write raw text to log file with immediate flush
-   */
-  private writeRaw(text: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-      if (!this.isOpen || !this.stream) {
-        reject(new Error('Logger not initialized'));
-        return;
-      }
-
-      const needsDrain = !this.stream.write(text, 'utf8', (error) => {
-        if (error) reject(error);
-      });
-
-      if (needsDrain) {
-        this.stream.once('drain', resolve);
-      } else {
-        resolve();
-      }
-    });
+    return this.logStream.write(header);
   }
 
   /**
@@ -120,23 +90,14 @@ export class AgentLogger {
     };
 
     const eventLine = `${JSON.stringify(event)}\n`;
-    return this.writeRaw(eventLine);
+    return this.logStream.write(eventLine);
   }
 
   /**
    * Close the log stream
    */
   async close(): Promise<void> {
-    if (!this.isOpen || !this.stream) {
-      return;
-    }
-
-    return new Promise((resolve) => {
-      this.stream!.end(() => {
-        this.isOpen = false;
-        resolve();
-      });
-    });
+    return this.logStream.close();
   }
 
   /**

src/audit/metrics-tracker.ts

@@ -18,6 +18,8 @@ import {
 import { atomicWrite, readJson, fileExists } from '../utils/file-io.js';
 import { formatTimestamp, calculatePercentage } from '../utils/formatting.js';
 import { AGENT_PHASE_MAP, type PhaseName } from '../session-manager.js';
+import { PentestError } from '../error-handling.js';
+import { ErrorCode } from '../types/errors.js';
 import type { AgentName, AgentEndResult } from '../types/index.js';
 
 interface AttemptData {
@@ -159,7 +161,13 @@ export class MetricsTracker {
    */
   async endAgent(agentName: string, result: AgentEndResult): Promise<void> {
     if (!this.data) {
-      throw new Error('MetricsTracker not initialized');
+      throw new PentestError(
+        'MetricsTracker not initialized',
+        'validation',
+        false,
+        {},
+        ErrorCode.AGENT_EXECUTION_FAILED
+      );
     }
 
     // Initialize agent metrics if not exists
@@ -251,7 +259,13 @@ export class MetricsTracker {
     checkpointHash?: string
   ): Promise<void> {
     if (!this.data) {
-      throw new Error('MetricsTracker not initialized');
+      throw new PentestError(
+        'MetricsTracker not initialized',
+        'validation',
+        false,
+        {},
+        ErrorCode.AGENT_EXECUTION_FAILED
+      );
     }
 
     // Ensure originalWorkflowId is set (backfill if missing from old sessions)

src/audit/workflow-logger.ts

@@ -11,10 +11,10 @@
  * Optimized for `tail -f` viewing during concurrent workflow execution.
  */
 
-import fs from 'fs';
-import path from 'path';
-import { generateWorkflowLogPath, ensureDirectory, type SessionMetadata } from './utils.js';
+import fs from 'fs/promises';
+import { generateWorkflowLogPath, type SessionMetadata } from './utils.js';
 import { formatDuration, formatTimestamp } from '../utils/formatting.js';
+import { LogStream } from './log-stream.js';
 
 export interface AgentLogDetails {
   attemptNumber?: number;
@@ -42,38 +42,28 @@ export interface WorkflowSummary {
  * WorkflowLogger - Manages the unified workflow log file
  */
 export class WorkflowLogger {
-  private sessionMetadata: SessionMetadata;
-  private logPath: string;
-  private stream: fs.WriteStream | null = null;
-  private initialized: boolean = false;
+  private readonly sessionMetadata: SessionMetadata;
+  private readonly logStream: LogStream;
 
   constructor(sessionMetadata: SessionMetadata) {
     this.sessionMetadata = sessionMetadata;
-    this.logPath = generateWorkflowLogPath(sessionMetadata);
+    const logPath = generateWorkflowLogPath(sessionMetadata);
+    this.logStream = new LogStream(logPath);
   }
 
   /**
    * Initialize the log stream (creates file and writes header)
    */
   async initialize(): Promise<void> {
-    if (this.initialized) {
+    if (this.logStream.isOpen) {
       return;
     }
 
-    // Ensure directory exists
-    await ensureDirectory(path.dirname(this.logPath));
-
-    // Create write stream with append mode
-    this.stream = fs.createWriteStream(this.logPath, {
-      flags: 'a',
-      encoding: 'utf8',
-      autoClose: true,
-    });
-
-    this.initialized = true;
+    // Open the stream (LogStream.open() handles directory creation)
+    await this.logStream.open();
 
     // Write header only if file is new (empty)
-    const stats = await fs.promises.stat(this.logPath).catch(() => null);
+    const stats = await fs.stat(this.logStream.path).catch(() => null);
     if (!stats || stats.size === 0) {
       await this.writeHeader();
     }
@@ -94,29 +84,7 @@ export class WorkflowLogger {
       ``,
     ].join('\n');
 
-    return this.writeRaw(header);
-  }
-
-  /**
-   * Write raw text to log file with immediate flush
-   */
-  private writeRaw(text: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-      if (!this.initialized || !this.stream) {
-        reject(new Error('WorkflowLogger not initialized'));
-        return;
-      }
-
-      const needsDrain = !this.stream.write(text, 'utf8', (error) => {
-        if (error) reject(error);
-      });
-
-      if (needsDrain) {
-        this.stream.once('drain', resolve);
-      } else {
-        resolve();
-      }
-    });
+    return this.logStream.write(header);
   }
 
   /**
@@ -138,10 +106,10 @@ export class WorkflowLogger {
 
     // Add blank line before phase start for readability
     if (event === 'start') {
-      await this.writeRaw('\n');
+      await this.logStream.write('\n');
     }
 
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -184,7 +152,7 @@ export class WorkflowLogger {
     }
 
     const line = `[${this.formatLogTime()}] [AGENT] ${message}\n`;
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -194,7 +162,7 @@ export class WorkflowLogger {
     await this.ensureInitialized();
 
     const line = `[${this.formatLogTime()}] [${eventType.toUpperCase()}] ${message}\n`;
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -205,7 +173,7 @@ export class WorkflowLogger {
 
     const contextStr = context ? ` (${context})` : '';
     const line = `[${this.formatLogTime()}] [ERROR] ${error.message}${contextStr}\n`;
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -301,7 +269,7 @@ export class WorkflowLogger {
     const params = this.formatToolParams(toolName, parameters);
     const paramStr = params ? `: ${params}` : '';
     const line = `[${this.formatLogTime()}] [${agentName}] [TOOL] ${toolName}${paramStr}\n`;
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -313,7 +281,7 @@ export class WorkflowLogger {
     // Show full content, replacing newlines with escaped version for single-line output
     const escaped = content.replace(/\n/g, '\\n');
     const line = `[${this.formatLogTime()}] [${agentName}] [LLM] Turn ${turn}: ${escaped}\n`;
-    await this.writeRaw(line);
+    await this.logStream.write(line);
   }
 
   /**
@@ -324,42 +292,42 @@ export class WorkflowLogger {
 
     const status = summary.status === 'completed' ? 'COMPLETED' : 'FAILED';
 
-    await this.writeRaw('\n');
-    await this.writeRaw(`================================================================================\n`);
-    await this.writeRaw(`Workflow ${status}\n`);
-    await this.writeRaw(`────────────────────────────────────────\n`);
-    await this.writeRaw(`Workflow ID: ${this.sessionMetadata.id}\n`);
-    await this.writeRaw(`Status:      ${summary.status}\n`);
-    await this.writeRaw(`Duration:    ${formatDuration(summary.totalDurationMs)}\n`);
-    await this.writeRaw(`Total Cost:  $${summary.totalCostUsd.toFixed(4)}\n`);
-    await this.writeRaw(`Agents:      ${summary.completedAgents.length} completed\n`);
+    await this.logStream.write('\n');
+    await this.logStream.write(`================================================================================\n`);
+    await this.logStream.write(`Workflow ${status}\n`);
+    await this.logStream.write(`────────────────────────────────────────\n`);
+    await this.logStream.write(`Workflow ID: ${this.sessionMetadata.id}\n`);
+    await this.logStream.write(`Status:      ${summary.status}\n`);
+    await this.logStream.write(`Duration:    ${formatDuration(summary.totalDurationMs)}\n`);
+    await this.logStream.write(`Total Cost:  $${summary.totalCostUsd.toFixed(4)}\n`);
+    await this.logStream.write(`Agents:      ${summary.completedAgents.length} completed\n`);
 
     if (summary.error) {
-      await this.writeRaw(`Error:       ${summary.error}\n`);
+      await this.logStream.write(`Error:       ${summary.error}\n`);
     }
 
-    await this.writeRaw(`\n`);
-    await this.writeRaw(`Agent Breakdown:\n`);
+    await this.logStream.write(`\n`);
+    await this.logStream.write(`Agent Breakdown:\n`);
 
     for (const agentName of summary.completedAgents) {
       const metrics = summary.agentMetrics[agentName];
       if (metrics) {
         const duration = formatDuration(metrics.durationMs);
         const cost = metrics.costUsd !== null ? `$${metrics.costUsd.toFixed(4)}` : 'N/A';
-        await this.writeRaw(`  - ${agentName} (${duration}, ${cost})\n`);
+        await this.logStream.write(`  - ${agentName} (${duration}, ${cost})\n`);
       } else {
-        await this.writeRaw(`  - ${agentName}\n`);
+        await this.logStream.write(`  - ${agentName}\n`);
       }
     }
 
-    await this.writeRaw(`================================================================================\n`);
+    await this.logStream.write(`================================================================================\n`);
   }
 
   /**
    * Ensure initialized (helper for lazy initialization)
    */
   private async ensureInitialized(): Promise<void> {
-    if (!this.initialized) {
+    if (!this.logStream.isOpen) {
       await this.initialize();
     }
   }
@@ -368,15 +336,6 @@ export class WorkflowLogger {
    * Close the log stream
    */
   async close(): Promise<void> {
-    if (!this.initialized || !this.stream) {
-      return;
-    }
-
-    return new Promise((resolve) => {
-      this.stream!.end(() => {
-        this.initialized = false;
-        resolve();
-      });
-    });
+    return this.logStream.close();
   }
 }