@ginkoai/cli 1.6.2 → 1.7.0

package/dist/lib/context-metrics.js

@@ -0,0 +1,372 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-07
+ * @tags: [context-metrics, token-estimation, pressure-monitoring, epic-004, sprint-4]
+ * @related: [orchestrate.ts, event-logger.ts, agent-heartbeat.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: []
+ */
+/**
+ * Model context limits configuration
+ * Values are approximate and based on model documentation
+ */
+export const MODEL_LIMITS = {
+    // Claude models
+    'claude-opus-4-5-20251101': 200000,
+    'claude-sonnet-4-20250514': 200000,
+    'claude-3-5-sonnet-20241022': 200000,
+    'claude-3-opus-20240229': 200000,
+    'claude-3-sonnet-20240229': 200000,
+    'claude-3-haiku-20240307': 200000,
+    // OpenAI models
+    'gpt-4-turbo': 128000,
+    'gpt-4-turbo-preview': 128000,
+    'gpt-4o': 128000,
+    'gpt-4o-mini': 128000,
+    'gpt-4': 8192,
+    'gpt-3.5-turbo': 16385,
+    // Google models
+    'gemini-pro': 1000000,
+    'gemini-1.5-pro': 1000000,
+    'gemini-1.5-flash': 1000000,
+    // Default fallback
+    default: 128000,
+};
+/**
+ * Default pressure thresholds
+ */
+export const DEFAULT_THRESHOLDS = {
+    optimal: 0.5,
+    elevated: 0.7,
+    warning: 0.85,
+};
+// ============================================================
+// Token Estimation
+// ============================================================
+/**
+ * Estimate token count from text using character-based heuristic.
+ *
+ * Heuristic: ~4 characters per token for English text.
+ * This is a rough approximation that works well for typical code/prose.
+ *
+ * More accurate methods:
+ * - tiktoken (OpenAI's tokenizer)
+ * - Anthropic SDK count_tokens
+ *
+ * We use character heuristic for:
+ * - Zero dependencies
+ * - Fast calculation
+ * - Good enough for pressure monitoring (within ~10%)
+ *
+ * @param text - Text to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Heuristic: ~4 characters per token for English/code
+    // This aligns with typical tokenizer behavior for mixed content
+    const charCount = text.length;
+    const estimated = Math.ceil(charCount / 4);
+    return estimated;
+}
+/**
+ * Estimate tokens for structured content (messages, tool calls, etc.)
+ *
+ * @param content - Structured content to estimate
+ * @returns Estimated token count with breakdown
+ */
+export function estimateStructuredTokens(content) {
+    const breakdown = {};
+    let total = 0;
+    // System prompt
+    if (content.systemPrompt) {
+        breakdown.systemPrompt = estimateTokens(content.systemPrompt);
+        total += breakdown.systemPrompt;
+    }
+    // Context/preamble
+    if (content.context) {
+        breakdown.context = estimateTokens(content.context);
+        total += breakdown.context;
+    }
+    // Messages
+    if (content.messages && content.messages.length > 0) {
+        let messageTokens = 0;
+        for (const msg of content.messages) {
+            // Role tokens (~3-5 tokens per message for formatting)
+            messageTokens += 4;
+            messageTokens += estimateTokens(msg.content);
+        }
+        breakdown.messages = messageTokens;
+        total += messageTokens;
+    }
+    // Tool calls
+    if (content.toolCalls && content.toolCalls.length > 0) {
+        let toolTokens = 0;
+        for (const call of content.toolCalls) {
+            // Tool name and structure (~10 tokens overhead per call)
+            toolTokens += 10;
+            toolTokens += estimateTokens(call.name);
+            toolTokens += estimateTokens(JSON.stringify(call.input));
+            if (call.output) {
+                toolTokens += estimateTokens(JSON.stringify(call.output));
+            }
+        }
+        breakdown.toolCalls = toolTokens;
+        total += toolTokens;
+    }
+    return { total, breakdown };
+}
+// ============================================================
+// Pressure Calculation
+// ============================================================
+/**
+ * Get context limit for a model
+ *
+ * @param model - Model identifier
+ * @returns Context limit in tokens
+ */
+export function getContextLimit(model) {
+    // Check for exact match
+    if (MODEL_LIMITS[model]) {
+        return MODEL_LIMITS[model];
+    }
+    // Check for partial match (e.g., "claude-3" matches "claude-3-opus")
+    for (const [key, value] of Object.entries(MODEL_LIMITS)) {
+        if (model.includes(key) || key.includes(model)) {
+            return value;
+        }
+    }
+    // Default fallback
+    return MODEL_LIMITS.default;
+}
+/**
+ * Calculate pressure ratio
+ *
+ * @param estimatedTokens - Current estimated token usage
+ * @param contextLimit - Model's context limit
+ * @returns Pressure ratio (0.0 - 1.0, clamped)
+ */
+export function calculatePressure(estimatedTokens, contextLimit) {
+    if (contextLimit <= 0)
+        return 1.0;
+    const pressure = estimatedTokens / contextLimit;
+    return Math.min(1.0, Math.max(0.0, pressure));
+}
+/**
+ * Classify pressure into zones
+ *
+ * @param pressure - Pressure ratio (0.0 - 1.0)
+ * @param thresholds - Optional custom thresholds
+ * @returns Pressure zone classification
+ */
+export function getPressureZone(pressure, thresholds = DEFAULT_THRESHOLDS) {
+    if (pressure < thresholds.optimal)
+        return 'optimal';
+    if (pressure < thresholds.elevated)
+        return 'elevated';
+    if (pressure < thresholds.warning)
+        return 'warning';
+    return 'critical';
+}
+/**
+ * Get pressure zone color for display
+ *
+ * @param zone - Pressure zone
+ * @returns Chalk color name
+ */
+export function getPressureColor(zone) {
+    switch (zone) {
+        case 'optimal':
+            return 'green';
+        case 'elevated':
+            return 'yellow';
+        case 'warning':
+            return 'red';
+        case 'critical':
+            return 'magenta';
+    }
+}
+// ============================================================
+// Context Monitor Class
+// ============================================================
+/**
+ * Context pressure monitor for orchestrator agents.
+ *
+ * Tracks metrics over time and provides pressure monitoring.
+ * Designed to be updated each orchestration cycle.
+ */
+export class ContextMonitor {
+    model;
+    contextLimit;
+    thresholds;
+    // Tracked metrics
+    messageCount = 0;
+    toolCallCount = 0;
+    eventsSinceStart = 0;
+    accumulatedTokens = 0;
+    // History for trend analysis
+    pressureHistory = [];
+    maxHistorySize = 100;
+    constructor(options = {}) {
+        this.model = options.model || 'claude-opus-4-5-20251101';
+        this.contextLimit = options.contextLimit || getContextLimit(this.model);
+        this.thresholds = { ...DEFAULT_THRESHOLDS, ...options.thresholds };
+    }
+    /**
+     * Record a message (increments counter and estimates tokens)
+     */
+    recordMessage(content) {
+        this.messageCount++;
+        this.accumulatedTokens += estimateTokens(content);
+        this.recordPressure();
+    }
+    /**
+     * Record a tool call (increments counter and estimates tokens)
+     */
+    recordToolCall(name, input, output) {
+        this.toolCallCount++;
+        this.accumulatedTokens += 10; // Overhead
+        this.accumulatedTokens += estimateTokens(name);
+        this.accumulatedTokens += estimateTokens(JSON.stringify(input));
+        if (output) {
+            this.accumulatedTokens += estimateTokens(JSON.stringify(output));
+        }
+        this.recordPressure();
+    }
+    /**
+     * Record an event (session activity)
+     */
+    recordEvent() {
+        this.eventsSinceStart++;
+    }
+    /**
+     * Add tokens directly (for bulk updates)
+     */
+    addTokens(count) {
+        this.accumulatedTokens += count;
+        this.recordPressure();
+    }
+    /**
+     * Get current metrics snapshot
+     */
+    getMetrics() {
+        const pressure = calculatePressure(this.accumulatedTokens, this.contextLimit);
+        return {
+            estimatedTokens: this.accumulatedTokens,
+            contextLimit: this.contextLimit,
+            pressure,
+            messageCount: this.messageCount,
+            toolCallCount: this.toolCallCount,
+            eventsSinceStart: this.eventsSinceStart,
+            model: this.model,
+            measuredAt: new Date(),
+        };
+    }
+    /**
+     * Get current pressure ratio
+     */
+    getPressure() {
+        return calculatePressure(this.accumulatedTokens, this.contextLimit);
+    }
+    /**
+     * Get current pressure zone
+     */
+    getZone() {
+        return getPressureZone(this.getPressure(), this.thresholds);
+    }
+    /**
+     * Check if pressure exceeds a threshold
+     */
+    isAboveThreshold(threshold) {
+        return this.getPressure() >= threshold;
+    }
+    /**
+     * Check if respawn is recommended (pressure > 80%)
+     */
+    shouldRespawn() {
+        return this.isAboveThreshold(0.8);
+    }
+    /**
+     * Check if warning should be logged (pressure > 70%)
+     */
+    shouldWarn() {
+        return this.isAboveThreshold(0.7);
+    }
+    /**
+     * Get pressure trend (increasing, stable, decreasing)
+     */
+    getTrend() {
+        if (this.pressureHistory.length < 5)
+            return 'stable';
+        const recent = this.pressureHistory.slice(-5);
+        const first = recent[0].pressure;
+        const last = recent[recent.length - 1].pressure;
+        const delta = last - first;
+        if (delta > 0.05)
+            return 'increasing';
+        if (delta < -0.05)
+            return 'decreasing';
+        return 'stable';
+    }
+    /**
+     * Reset metrics (for new session)
+     */
+    reset() {
+        this.messageCount = 0;
+        this.toolCallCount = 0;
+        this.eventsSinceStart = 0;
+        this.accumulatedTokens = 0;
+        this.pressureHistory = [];
+    }
+    /**
+     * Record pressure snapshot for history
+     */
+    recordPressure() {
+        const pressure = this.getPressure();
+        this.pressureHistory.push({ timestamp: new Date(), pressure });
+        // Trim history if too large
+        if (this.pressureHistory.length > this.maxHistorySize) {
+            this.pressureHistory = this.pressureHistory.slice(-this.maxHistorySize);
+        }
+    }
+    /**
+     * Format metrics for display
+     */
+    formatMetrics() {
+        const metrics = this.getMetrics();
+        const zone = this.getZone();
+        const trend = this.getTrend();
+        const pressurePercent = (metrics.pressure * 100).toFixed(1);
+        const tokenK = (metrics.estimatedTokens / 1000).toFixed(1);
+        const limitK = (metrics.contextLimit / 1000).toFixed(0);
+        const trendIcon = trend === 'increasing' ? '↑' : trend === 'decreasing' ? '↓' : '→';
+        return `${tokenK}K/${limitK}K tokens (${pressurePercent}% ${trendIcon}) [${zone}]`;
+    }
+}
+// ============================================================
+// Singleton Instance
+// ============================================================
+let globalMonitor = null;
+/**
+ * Get or create the global context monitor
+ */
+export function getContextMonitor(options) {
+    if (!globalMonitor) {
+        globalMonitor = new ContextMonitor(options);
+    }
+    return globalMonitor;
+}
+/**
+ * Reset the global context monitor (for testing or session restart)
+ */
+export function resetContextMonitor() {
+    if (globalMonitor) {
+        globalMonitor.reset();
+    }
+    globalMonitor = null;
+}
+export default ContextMonitor;
+//# sourceMappingURL=context-metrics.js.map

package/dist/lib/context-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-metrics.js","sourceRoot":"","sources":["../../src/lib/context-metrics.ts"],"names":[],"mappings":"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"}

package/dist/lib/dead-letter-queue.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-07
+ * @tags: [dead-letter-queue, dlq, resilience, event-retry, epic-004]
+ * @related: [event-queue.ts, event-logger.ts, api-client.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, uuid]
+ */
+import { Event } from './event-logger.js';
+/**
+ * Dead Letter Queue Entry
+ *
+ * Captures failed sync attempts for later retry
+ */
+export interface DeadLetterEntry {
+    id: string;
+    originalEvent: Event;
+    failureReason: string;
+    failedAt: Date;
+    retryCount: number;
+    lastRetryAt?: Date;
+    status: 'pending' | 'retrying' | 'resolved' | 'abandoned';
+}
+/**
+ * DLQ Configuration
+ */
+interface DLQConfig {
+    maxRetries: number;
+    retryDelays: number[];
+    abandonedThreshold: number;
+}
+/**
+ * Add event to Dead Letter Queue
+ *
+ * Called when event sync fails after all retries in event-queue.ts
+ *
+ * @param event - Original event that failed to sync
+ * @param reason - Failure reason description
+ * @returns DLQ entry ID
+ */
+export declare function addToDeadLetter(event: Event, reason: string): Promise<string>;
+/**
+ * Get all DLQ entries, optionally filtered by status
+ *
+ * @param status - Optional status filter
+ * @returns Array of DLQ entries
+ */
+export declare function getDeadLetterEntries(status?: 'pending' | 'retrying' | 'resolved' | 'abandoned'): Promise<DeadLetterEntry[]>;
+/**
+ * Get a specific DLQ entry by ID
+ *
+ * @param entryId - DLQ entry ID
+ * @returns DLQ entry or null if not found
+ */
+export declare function getDeadLetterEntry(entryId: string): Promise<DeadLetterEntry | null>;
+/**
+ * Retry a specific DLQ entry
+ *
+ * Attempts to sync the event again, respecting retry count and delays
+ *
+ * @param entryId - DLQ entry ID to retry
+ * @param config - Optional DLQ configuration
+ * @returns Success status and updated entry
+ */
+export declare function retryDeadLetter(entryId: string, config?: Partial<DLQConfig>): Promise<{
+    success: boolean;
+    entry: DeadLetterEntry;
+    error?: string;
+}>;
+/**
+ * Auto-retry eligible DLQ entries
+ *
+ * Called periodically to retry pending entries that meet delay requirements
+ *
+ * @param config - Optional DLQ configuration
+ * @returns Number of entries retried
+ */
+export declare function autoRetryDeadLetters(config?: Partial<DLQConfig>): Promise<number>;
+/**
+ * Delete a resolved or abandoned DLQ entry
+ *
+ * @param entryId - DLQ entry ID to delete
+ */
+export declare function deleteDeadLetterEntry(entryId: string): Promise<void>;
+/**
+ * Clean up old resolved/abandoned entries
+ *
+ * @param olderThanDays - Delete entries older than N days (default 30)
+ * @returns Number of entries deleted
+ */
+export declare function cleanupDeadLetters(olderThanDays?: number): Promise<number>;
+/**
+ * Get DLQ statistics
+ *
+ * @returns Summary of DLQ state
+ */
+export declare function getDeadLetterStats(): Promise<{
+    pending: number;
+    retrying: number;
+    resolved: number;
+    abandoned: number;
+    total: number;
+    oldestPending?: Date;
+}>;
+export {};
+//# sourceMappingURL=dead-letter-queue.d.ts.map

package/dist/lib/dead-letter-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-queue.d.ts","sourceRoot":"","sources":["../../src/lib/dead-letter-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,KAAK,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;CAC3D;AAED;;GAEG;AACH,UAAU,SAAS;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAuCD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GACzD,OAAO,CAAC,eAAe,EAAE,CAAC,CAqC5B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAqBzF;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAC9B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+GvE;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAC9B,OAAO,CAAC,MAAM,CAAC,CA4CjB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1E;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,GAAE,MAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BpF;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB,CAAC,CAwBD"}