@cyanautomation/kaseki-agent 1.4.1

package/src/utils/http-client-factory.ts

@@ -0,0 +1,157 @@
+/**
+ * HTTP client factory for creating API requests with retry logic.
+ * Consolidates HTTP fetch + error handling patterns across kaseki-api-client.ts.
+ */
+
+export interface HttpRequestOptions {
+  method: 'GET' | 'POST' | 'DELETE';
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+export interface RetryConfig {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+}
+
+/**
+ * Default retry configuration for HTTP requests.
+ */
+const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 8000,
+};
+
+/**
+ * Creates an HTTP request factory with retry logic.
+ */
+export class HttpClientFactory {
+  private retryConfig: RetryConfig;
+
+  constructor(retryConfig: Partial<RetryConfig> = {}) {
+    this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...retryConfig };
+  }
+
+  /**
+   * Create and execute an HTTP request with automatic retry on failure.
+   */
+  async request<T>(
+    url: string,
+    options: HttpRequestOptions,
+    parser: (data: unknown) => T,
+    description: string = 'HTTP request'
+  ): Promise<T> {
+    return this.retryWithBackoff(async () => {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        let errorDetail: string | undefined;
+        try {
+          const errorData: unknown = await response.json();
+          errorDetail = this.parseErrorDetail(errorData);
+        } catch {
+          // Ignore non-JSON error payloads
+        }
+        throw new Error(`${description} failed: ${errorDetail ?? response.statusText}`);
+      }
+
+      const data: unknown = await response.json();
+      return parser(data);
+    }, description);
+  }
+
+  /**
+   * Create and execute an HTTP request that returns text content.
+   */
+  async requestText(url: string, options: HttpRequestOptions, description: string = 'HTTP request'): Promise<string> {
+    return this.retryWithBackoff(async () => {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        throw new Error(`${description} failed: ${response.status}`);
+      }
+
+      return response.text();
+    }, description);
+  }
+
+  /**
+   * Create and execute an HTTP request that returns binary data.
+   */
+  async requestBlob(url: string, options: HttpRequestOptions, description: string = 'HTTP request'): Promise<Blob> {
+    return this.retryWithBackoff(async () => {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        throw new Error(`${description} failed: ${response.status}`);
+      }
+
+      return response.blob();
+    }, description);
+  }
+
+  /**
+   * Execute a function with exponential backoff retry.
+   */
+  private async retryWithBackoff<T>(
+    fn: () => Promise<T>,
+    description: string = 'Operation'
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.retryConfig.maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Don't retry on 4xx errors (except 429 Too Many Requests)
+        const is4xxError =
+          lastError.message.includes('400') ||
+          lastError.message.includes('401') ||
+          lastError.message.includes('403') ||
+          lastError.message.includes('404');
+
+        if (is4xxError && !lastError.message.includes('429')) {
+          throw lastError;
+        }
+
+        // If this is the last attempt, throw
+        if (attempt === this.retryConfig.maxAttempts - 1) {
+          throw lastError;
+        }
+
+        // Calculate backoff with exponential increase
+        const delayMs = Math.min(
+          this.retryConfig.initialDelayMs * Math.pow(2, attempt),
+          this.retryConfig.maxDelayMs
+        );
+
+        // Wait before retrying
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+
+    throw lastError || new Error(`${description} failed after ${this.retryConfig.maxAttempts} attempts`);
+  }
+
+  /**
+   * Parse error detail from a response body.
+   */
+  private parseErrorDetail(value: unknown): string | undefined {
+    if (!this.isRecord(value)) {
+      return undefined;
+    }
+    const detail = value.detail;
+    return typeof detail === 'string' ? detail : undefined;
+  }
+
+  /**
+   * Type guard for checking if a value is an object/record.
+   */
+  private isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+}

package/src/utils/progress-normalizer.test.ts

@@ -0,0 +1,442 @@
+import { normalizeProgressEvent, toStructuredProgress } from './progress-normalizer';
+
+describe('progress-normalizer', () => {
+  describe('normalizeProgressEvent', () => {
+    it('should preserve existing message and updatedAt', () => {
+      const event = {
+        stage: 'building',
+        message: 'Building the project',
+        updatedAt: '2026-05-05T10:00:00Z',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result).toEqual(event);
+    });
+
+    it('should use detail as message when message is missing but detail is provided', () => {
+      const event = {
+        stage: 'building',
+        detail: 'Compiling TypeScript',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.message).toBe('Compiling TypeScript');
+      expect(result.stage).toBe('building');
+    });
+
+    it('should use stage as message when both message and detail are missing', () => {
+      const event = {
+        stage: 'testing',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.message).toBe('testing');
+    });
+
+    it('should not override message if it already exists', () => {
+      const event = {
+        stage: 'testing',
+        message: 'Running tests',
+        detail: 'This should be ignored',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.message).toBe('Running tests');
+    });
+
+    it('should use timestamp as updatedAt when updatedAt is missing', () => {
+      const event = {
+        stage: 'running',
+        message: 'Agent running',
+        timestamp: '2026-05-05T10:30:00Z',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.updatedAt).toBe('2026-05-05T10:30:00Z');
+    });
+
+    it('should not override updatedAt if it already exists', () => {
+      const event = {
+        stage: 'running',
+        updatedAt: '2026-05-05T10:30:00Z',
+        timestamp: '2026-05-05T10:00:00Z',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.updatedAt).toBe('2026-05-05T10:30:00Z');
+    });
+
+    it('should handle non-string stage (should not set message)', () => {
+      const event = {
+        stage: 123,
+        detail: 'Some detail',
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.message).toBeUndefined();
+    });
+
+    it('should ignore non-string message and non-string detail', () => {
+      const event = {
+        stage: 'running',
+        message: null,
+        detail: undefined,
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.message).toBe('running');
+    });
+
+    it('should ignore non-string timestamp', () => {
+      const event = {
+        stage: 'running',
+        timestamp: 12345,
+      };
+      const result = normalizeProgressEvent(event);
+      expect(result.updatedAt).toBeUndefined();
+    });
+
+    it('should handle empty event object', () => {
+      const event = {};
+      const result = normalizeProgressEvent(event);
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('toStructuredProgress', () => {
+    it('should create valid StructuredProgress with all fields', () => {
+      const event = {
+        stage: 'building',
+        message: 'Compiling',
+        percentComplete: 50,
+        updatedAt: '2026-05-05T10:00:00Z',
+      };
+      const result = toStructuredProgress(event);
+      expect(result).toEqual({
+        stage: 'building',
+        message: 'Compiling',
+        percentComplete: 50,
+        updatedAt: '2026-05-05T10:00:00Z',
+      });
+    });
+
+    it('should use fallbackStage when stage is missing', () => {
+      const event = { message: 'Processing' };
+      const result = toStructuredProgress(event);
+      expect(result?.stage).toBe('running');
+      expect(result?.message).toBe('Processing');
+    });
+
+    it('should use custom fallbackStage parameter', () => {
+      const event = { message: 'Processing' };
+      const result = toStructuredProgress(event, 'custom-stage');
+      expect(result?.stage).toBe('custom-stage');
+    });
+
+    it('should use fallbackStage when stage is not a string', () => {
+      const event = {
+        stage: 123,
+        message: 'Processing',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.stage).toBe('running');
+    });
+
+    it('should trim whitespace from stage', () => {
+      const event = {
+        stage: '  building  ',
+        message: 'Compiling',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.stage).toBe('building');
+    });
+
+    it('should return null when stage (and fallback) is empty after trim', () => {
+      const event = {
+        stage: '   ',
+      };
+      const result = toStructuredProgress(event);
+      expect(result).toBeNull();
+    });
+
+    it('should return null when fallbackStage is empty', () => {
+      const event = { message: 'Processing' };
+      const result = toStructuredProgress(event, '');
+      expect(result).toBeNull();
+    });
+
+    it('should prioritize message over detail', () => {
+      const event = {
+        stage: 'building',
+        message: 'Using this message',
+        detail: 'Not this one',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.message).toBe('Using this message');
+    });
+
+    it('should use detail when message is missing', () => {
+      const event = {
+        stage: 'building',
+        detail: 'Using this detail',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.message).toBe('Using this detail');
+    });
+
+    it('should use stage as message fallback', () => {
+      const event = {
+        stage: 'building',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.message).toBe('building');
+    });
+
+    it('should ignore non-string message', () => {
+      const event = {
+        stage: 'building',
+        message: 123,
+        detail: 'Detail message',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.message).toBe('Detail message');
+    });
+
+    it('should ignore non-string detail', () => {
+      const event = {
+        stage: 'building',
+        message: 'Main message',
+        detail: null,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.message).toBe('Main message');
+    });
+
+    it('should prioritize percentComplete over percent', () => {
+      const event = {
+        stage: 'running',
+        percentComplete: 75,
+        percent: 50,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBe(75);
+    });
+
+    it('should use percent when percentComplete is missing', () => {
+      const event = {
+        stage: 'running',
+        percent: 60,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBe(60);
+    });
+
+    it('should ignore non-number percentComplete', () => {
+      const event = {
+        stage: 'running',
+        percentComplete: '75',
+        percent: 50,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBe(50);
+    });
+
+    it('should ignore non-number percent', () => {
+      const event = {
+        stage: 'running',
+        percent: '60',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBeUndefined();
+    });
+
+    it('should prioritize updatedAt over timestamp', () => {
+      const event = {
+        stage: 'running',
+        updatedAt: '2026-05-05T10:30:00Z',
+        timestamp: '2026-05-05T10:00:00Z',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.updatedAt).toBe('2026-05-05T10:30:00Z');
+    });
+
+    it('should use timestamp when updatedAt is missing', () => {
+      const event = {
+        stage: 'running',
+        timestamp: '2026-05-05T10:00:00Z',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.updatedAt).toBe('2026-05-05T10:00:00Z');
+    });
+
+    it('should ignore non-string updatedAt', () => {
+      const event = {
+        stage: 'running',
+        updatedAt: 12345,
+        timestamp: '2026-05-05T10:00:00Z',
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.updatedAt).toBe('2026-05-05T10:00:00Z');
+    });
+
+    it('should ignore non-string timestamp', () => {
+      const event = {
+        stage: 'running',
+        timestamp: 12345,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.updatedAt).toBeUndefined();
+    });
+
+    it('should handle undefined percentComplete and timestamp', () => {
+      const event = {
+        stage: 'running',
+        message: 'In progress',
+      };
+      const result = toStructuredProgress(event);
+      expect(result).toEqual({
+        stage: 'running',
+        message: 'In progress',
+        percentComplete: undefined,
+        updatedAt: undefined,
+      });
+    });
+
+    it('should handle percentComplete of 0', () => {
+      const event = {
+        stage: 'running',
+        percentComplete: 0,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBe(0);
+    });
+
+    it('should handle percentComplete of 100', () => {
+      const event = {
+        stage: 'completed',
+        percentComplete: 100,
+      };
+      const result = toStructuredProgress(event);
+      expect(result?.percentComplete).toBe(100);
+    });
+
+    it('should return null when stage is empty string (no fallback even with fallback parameter)', () => {
+      const event = {
+        stage: '',
+      };
+      const result = toStructuredProgress(event, 'fallback-stage');
+      expect(result).toBeNull();
+    });
+
+  });
+
+  describe('integration: normalizeProgressEvent → toStructuredProgress', () => {
+    it('should work together with field remapping without mutating the source event', () => {
+      const event = {
+        stage: 'testing',
+        detail: 'Running unit tests',
+        percent: 75,
+        timestamp: '2026-05-05T10:00:00Z',
+        runId: 'run-123',
+      };
+
+      const normalized = normalizeProgressEvent(event);
+      const structured = toStructuredProgress(normalized);
+
+      expect(normalized).toEqual({
+        stage: 'testing',
+        detail: 'Running unit tests',
+        percent: 75,
+        timestamp: '2026-05-05T10:00:00Z',
+        runId: 'run-123',
+        message: 'Running unit tests',
+        updatedAt: '2026-05-05T10:00:00Z',
+      });
+      const originalEvent = { ...event };
+      expect(event).toEqual(originalEvent);
+      expect(event).not.toHaveProperty('message');
+      expect(event).not.toHaveProperty('updatedAt');
+      expect(structured).toEqual({
+        stage: 'testing',
+        message: 'Running unit tests',
+        percentComplete: 75,
+        updatedAt: '2026-05-05T10:00:00Z',
+      });
+    });
+
+    it('should preserve client-visible fields from a progress.jsonl event', () => {
+      const line = JSON.stringify({
+        timestamp: '2026-05-05T10:00:00.000Z',
+        updatedAt: '2026-05-05T10:00:00.000Z',
+        stage: 'pi coding agent',
+        message: 'working; events=5, tool starts=2, tool ends=1',
+        percentComplete: 45,
+        counts: { assistant_message: 2, tool_start: 2, tool_end: 1 },
+        toolStartCount: 2,
+        toolEndCount: 1,
+        messageUpdateCount: 2,
+        reason: 'events',
+      });
+
+      const normalized = normalizeProgressEvent(JSON.parse(line));
+      const structured = toStructuredProgress(normalized);
+
+      expect(normalized).toMatchObject({
+        timestamp: '2026-05-05T10:00:00.000Z',
+        updatedAt: '2026-05-05T10:00:00.000Z',
+        stage: 'pi coding agent',
+        message: 'working; events=5, tool starts=2, tool ends=1',
+        percentComplete: 45,
+        counts: { assistant_message: 2, tool_start: 2, tool_end: 1 },
+        toolStartCount: 2,
+        toolEndCount: 1,
+        messageUpdateCount: 2,
+        reason: 'events',
+      });
+
+      // Structured status progress is intentionally limited to the public
+      // StructuredProgress contract; richer progress.jsonl/log fields remain
+      // client-visible through the progress/events log endpoints.
+      expect(structured).toEqual({
+        stage: 'pi coding agent',
+        message: 'working; events=5, tool starts=2, tool ends=1',
+        percentComplete: 45,
+        updatedAt: '2026-05-05T10:00:00.000Z',
+      });
+    });
+
+    it('should strip shell diagnostics accidentally interleaved into live progress messages', () => {
+      const structured = toStructuredProgress({
+        stage: 'dependency install info',
+        message: 'cache hit flags=--ignore-scripts/usr/local/bin/kaseki-agent: line 378: /usr/local/bin/scripts/allowlist-helper.sh: No such file or directory',
+        timestamp: '2026-05-07T12:24:48.758Z',
+      });
+
+      expect(structured).toEqual({
+        stage: 'dependency install info',
+        message: 'cache hit flags=--ignore-scripts',
+        percentComplete: undefined,
+        updatedAt: '2026-05-07T12:24:48.758Z',
+      });
+    });
+
+    it('should strip git clone stderr accidentally interleaved into live progress messages', () => {
+      const structured = toStructuredProgress({
+        stage: 'pi coding agent',
+        message: "working; events=1079, tool starts=8, tool ends=8Cloning into '/workspace/repo'...",
+        timestamp: '2026-05-07T12:56:25.853Z',
+      });
+
+      expect(structured).toEqual({
+        stage: 'pi coding agent',
+        message: 'working; events=1079, tool starts=8, tool ends=8',
+        percentComplete: undefined,
+        updatedAt: '2026-05-07T12:56:25.853Z',
+      });
+    });
+
+    it('should handle missing fields gracefully in pipeline', () => {
+      const event = {
+        stage: 'running',
+      };
+      const normalized = normalizeProgressEvent(event);
+      const structured = toStructuredProgress(normalized);
+      expect(structured?.stage).toBe('running');
+      expect(structured?.message).toBe('running');
+      expect(structured?.percentComplete).toBeUndefined();
+      expect(structured?.updatedAt).toBeUndefined();
+    });
+  });
+});

package/src/utils/progress-normalizer.ts

@@ -0,0 +1,68 @@
+import { StructuredProgress } from '../kaseki-api-types';
+
+const SHELL_DIAGNOSTIC_PATTERN = /\/[^\s:]+(?:\/[^\s:]+)*:\s+line\s+\d+:\s+.*$/;
+const GIT_CLONE_STDERR_PATTERN = /Cloning into '[^']+'\.\.\.$/;
+
+export function sanitizeProgressMessage(message: string): string {
+  return message
+    .replace(SHELL_DIAGNOSTIC_PATTERN, '')
+    .replace(GIT_CLONE_STDERR_PATTERN, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Normalize a progress event by ensuring common fields are standardized.
+ * Ensures message is populated from stage/detail, and timestamp is normalized to updatedAt.
+ */
+export function normalizeProgressEvent(event: Record<string, unknown>): Record<string, unknown> {
+  const normalized: Record<string, unknown> = { ...event };
+  if (typeof normalized.stage === 'string') {
+    if (typeof normalized.message !== 'string' && typeof normalized.detail === 'string') {
+      normalized.message = sanitizeProgressMessage(normalized.detail);
+    }
+    if (typeof normalized.message !== 'string') {
+      normalized.message = normalized.stage;
+    } else {
+      normalized.message = sanitizeProgressMessage(normalized.message);
+    }
+  }
+  if (typeof normalized.updatedAt !== 'string' && typeof normalized.timestamp === 'string') {
+    normalized.updatedAt = normalized.timestamp;
+  }
+  return normalized;
+}
+
+/**
+ * Convert a progress event to a StructuredProgress object.
+ * Always ensures stage is present; returns null only if event is invalid.
+ */
+export function toStructuredProgress(
+  event: Record<string, unknown>,
+  fallbackStage: string = 'running'
+): StructuredProgress | null {
+  const stage = typeof event.stage === 'string' ? event.stage.trim() : fallbackStage;
+  if (!stage) {
+    return null;
+  }
+
+  const message =
+    typeof event.message === 'string'
+      ? sanitizeProgressMessage(event.message)
+      : typeof event.detail === 'string'
+        ? sanitizeProgressMessage(event.detail)
+        : undefined;
+
+  const numericPercent = typeof event.percentComplete === 'number' ? event.percentComplete : undefined;
+  const percentFromPercent = typeof event.percent === 'number' ? event.percent : undefined;
+  const percentComplete = numericPercent ?? percentFromPercent;
+  const updatedAt =
+    typeof event.updatedAt === 'string' ? event.updatedAt : typeof event.timestamp === 'string' ? event.timestamp : undefined;
+
+  return {
+    stage,
+    percentComplete,
+    message: message || stage,
+    updatedAt,
+  };
+}