@ttfw/envoi 1.0.0

package/dist/lib/tick.js

@@ -0,0 +1,424 @@
+/**
+ * Tick runner with transport stall handling and retry policy.
+ *
+ * Provides functions to handle transport stalls during ORCHESTRATE or BUILD phases.
+ * When a stall is detected:
+ * 1. Check if repo is dirty
+ * 2. Rollback if needed
+ * 3. Return BLOCKED_TRANSPORT_STALLED with evidence
+ *
+ * Retry policy (M21):
+ * - Attempt 1: Retry same task unchanged
+ * - Attempt 2: Retry with degraded settings
+ * - Attempt 3+: Block and require human action
+ */
+import { rollbackToCommit } from './rollback.js';
+import { isWorktreeClean } from './git.js';
+import { resetRetryState, recordTransportStall } from './state.js';
+/**
+ * Maximum retry attempts before blocking.
+ */
+export const MAX_RETRY_ATTEMPTS = 3;
+/**
+ * Recovery prompt to prepend when retrying after a transport stall.
+ *
+ * This prompt reminds the model that previous work may have been lost
+ * and to read files before making assumptions about their state.
+ */
+export const RECOVERY_PROMPT = `IMPORTANT: This is a retry after a transport stall. The previous attempt may have been interrupted.
+
+Do NOT assume your previous edits were applied. The connection may have stalled:
+- Before any changes were made
+- In the middle of changes (partial writes)
+- After changes were made but before confirmation
+
+BEFORE making any edits:
+1. Read the relevant files to verify their current state
+2. Check if your intended changes already exist
+3. Proceed based on the actual file contents, not your memory of what you tried to do
+
+If the task appears completed, verify and report success. If not, complete it from the current state.`;
+/**
+ * Returns the recovery prompt to prepend when retrying.
+ *
+ * The recovery prompt is used on any retry (retry_unchanged or retry_degraded)
+ * to remind the model that previous work may have been lost.
+ *
+ * @param retryCount - Current retry count (0 = first attempt, no recovery prompt)
+ * @returns Recovery prompt string if retrying, empty string for first attempt
+ */
+export function getRecoveryPrompt(retryCount) {
+    if (retryCount < 1) {
+        return '';
+    }
+    return RECOVERY_PROMPT;
+}
+/**
+ * Builds the full prompt with optional recovery prefix.
+ *
+ * If retrying after a stall, prepends the recovery prompt to the original prompt.
+ *
+ * @param originalPrompt - The original prompt content
+ * @param retryCount - Current retry count (0 = first attempt)
+ * @returns Full prompt with recovery prefix if applicable
+ */
+export function buildPromptWithRecovery(originalPrompt, retryCount) {
+    const recovery = getRecoveryPrompt(retryCount);
+    if (!recovery) {
+        return originalPrompt;
+    }
+    return `${recovery}\n\n---\n\n${originalPrompt}`;
+}
+/**
+ * Computes the retry action based on the current retry count.
+ *
+ * Retry policy:
+ * - retry_count 0 or 1 → retry_unchanged (first failure, try again)
+ * - retry_count 2 → retry_degraded (second failure, use safer settings)
+ * - retry_count >= 3 → block (third failure, require human)
+ *
+ * @param retryCount - Current retry count from state (before this attempt)
+ * @returns The action to take
+ */
+export function getRetryAction(retryCount) {
+    if (retryCount < 1) {
+        return 'retry_unchanged';
+    }
+    else if (retryCount < 2) {
+        return 'retry_degraded';
+    }
+    else {
+        return 'block';
+    }
+}
+/**
+ * Computes the full retry decision including degraded settings if needed.
+ *
+ * @param retryCount - Current retry count from state
+ * @param originalMaxTurns - Original max_turns from config (default 50)
+ * @param originalDiffLimits - Original diff limits from config
+ * @returns Full retry decision with settings and reason
+ */
+export function computeRetryDecision(retryCount, originalMaxTurns = 50, originalDiffLimits = { max_files_touched: 20, max_lines_changed: 500 }) {
+    const action = getRetryAction(retryCount);
+    const newRetryCount = retryCount + 1;
+    if (action === 'retry_unchanged') {
+        return {
+            action,
+            retry_count: newRetryCount,
+            reason: `Retry attempt ${newRetryCount}/${MAX_RETRY_ATTEMPTS}: retrying unchanged`,
+        };
+    }
+    if (action === 'retry_degraded') {
+        const degraded_settings = computeDegradedSettings(originalMaxTurns, originalDiffLimits);
+        return {
+            action,
+            retry_count: newRetryCount,
+            degraded_settings,
+            reason: `Retry attempt ${newRetryCount}/${MAX_RETRY_ATTEMPTS}: retrying with degraded settings (max_turns=${degraded_settings.max_turns}, max_files=${degraded_settings.diff_limits.max_files_touched}, max_lines=${degraded_settings.diff_limits.max_lines_changed})`,
+        };
+    }
+    // action === 'block'
+    return {
+        action,
+        retry_count: newRetryCount,
+        reason: `Retry limit reached (${MAX_RETRY_ATTEMPTS} attempts). Blocking for human intervention.`,
+    };
+}
+/**
+ * Computes degraded settings for retry attempt 2.
+ *
+ * Applies conservative reductions:
+ * - max_turns: 50% of original, minimum 5
+ * - max_files_touched: 50% of original, minimum 5
+ * - max_lines_changed: 50% of original, minimum 100
+ * - prefer_patch_mode: true
+ *
+ * @param originalMaxTurns - Original max_turns from config
+ * @param originalDiffLimits - Original diff limits from config
+ * @returns Degraded settings
+ */
+export function computeDegradedSettings(originalMaxTurns, originalDiffLimits) {
+    return {
+        max_turns: Math.max(5, Math.floor(originalMaxTurns / 2)),
+        diff_limits: {
+            max_files_touched: Math.max(5, Math.floor(originalDiffLimits.max_files_touched / 2)),
+            max_lines_changed: Math.max(100, Math.floor(originalDiffLimits.max_lines_changed / 2)),
+        },
+        prefer_patch_mode: true,
+    };
+}
+/**
+ * Checks if retry is allowed based on current retry count.
+ *
+ * @param retryCount - Current retry count
+ * @returns true if retry is allowed, false if blocked
+ */
+export function canRetry(retryCount) {
+    return retryCount < MAX_RETRY_ATTEMPTS - 1;
+}
+/**
+ * Formats retry decision as human-readable message.
+ *
+ * @param decision - The retry decision
+ * @returns Formatted message
+ */
+export function formatRetryDecision(decision) {
+    const lines = [decision.reason];
+    if (decision.degraded_settings) {
+        lines.push('Degraded settings:');
+        lines.push(`  - max_turns: ${decision.degraded_settings.max_turns}`);
+        lines.push(`  - max_files: ${decision.degraded_settings.diff_limits.max_files_touched}`);
+        lines.push(`  - max_lines: ${decision.degraded_settings.diff_limits.max_lines_changed}`);
+        lines.push(`  - patch_mode: ${decision.degraded_settings.prefer_patch_mode}`);
+    }
+    if (decision.action === 'block') {
+        lines.push('');
+        lines.push('Human action required: Review logs, fix issues, then reset retry state.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Applies degraded settings to a EnvoiConfig.
+ *
+ * Used during retry attempt 2 to run with more conservative settings.
+ * Creates a new config object without mutating the original.
+ *
+ * Settings applied:
+ * - builder.claude_code.max_turns: reduced to degraded value
+ * - diff_limits.default_max_files_touched: reduced to degraded value
+ * - diff_limits.default_max_lines_changed: reduced to degraded value
+ * - builder.default_mode: set to 'patch' if allow_patch_mode is true and prefer_patch_mode is set
+ *
+ * @param config - Original EnvoiConfig
+ * @param degraded - Degraded settings to apply
+ * @returns New config with degraded settings applied
+ */
+export function applyDegradedConfig(config, degraded) {
+    return {
+        ...config,
+        builder: {
+            ...config.builder,
+            // Prefer patch mode if available and degraded settings request it
+            default_mode: degraded.prefer_patch_mode && config.builder.allow_patch_mode
+                ? 'patch'
+                : config.builder.default_mode,
+            claude_code: {
+                ...config.builder.claude_code,
+                max_turns: degraded.max_turns,
+            },
+        },
+        diff_limits: {
+            ...config.diff_limits,
+            default_max_files_touched: degraded.diff_limits.max_files_touched,
+            default_max_lines_changed: degraded.diff_limits.max_lines_changed,
+        },
+    };
+}
+/**
+ * Extracts relevant settings from config for computing degraded settings.
+ *
+ * @param config - EnvoiConfig to extract from
+ * @returns Object with max_turns and diff_limits for degradation computation
+ */
+export function extractDegradationInputs(config) {
+    return {
+        max_turns: config.builder.claude_code.max_turns,
+        diff_limits: {
+            max_files_touched: config.diff_limits.default_max_files_touched,
+            max_lines_changed: config.diff_limits.default_max_lines_changed,
+        },
+    };
+}
+/**
+ * Convenience function to degrade a config based on retry count.
+ *
+ * If retry action is 'retry_degraded', applies degraded settings to config.
+ * Otherwise, returns the original config unchanged.
+ *
+ * @param config - Original config
+ * @param retryCount - Current retry count
+ * @returns Degraded config if appropriate, original config otherwise
+ */
+export function getDegradedConfigIfNeeded(config, retryCount) {
+    const action = getRetryAction(retryCount);
+    if (action !== 'retry_degraded') {
+        return config;
+    }
+    const inputs = extractDegradationInputs(config);
+    const degraded = computeDegradedSettings(inputs.max_turns, inputs.diff_limits);
+    return applyDegradedConfig(config, degraded);
+}
+/**
+ * Determines if retry state should be reset based on tick outcome.
+ *
+ * Retry state is reset on:
+ * - SUCCESS: Task completed successfully
+ * - STOP: Task failed with a STOP code (not a transport issue)
+ *
+ * Retry state is NOT reset on:
+ * - BLOCKED_STALL: Transport stall, may retry
+ * - BLOCKED_OTHER: Other blocked conditions
+ *
+ * @param outcome - The tick outcome
+ * @returns true if retry state should be reset
+ */
+export function shouldResetRetryState(outcome) {
+    return outcome === 'SUCCESS' || outcome === 'STOP';
+}
+/**
+ * Updates tick state based on completion outcome.
+ *
+ * On SUCCESS or STOP:
+ * - Resets retry_count to 0
+ * - Clears last_error_kind and last_request_id
+ *
+ * On BLOCKED_STALL:
+ * - Records the stall (increments retry_count, sets error fields)
+ *
+ * On BLOCKED_OTHER:
+ * - No changes to retry state
+ *
+ * @param state - Current tick state
+ * @param outcome - The tick outcome
+ * @param stallInfo - Stall info if outcome is BLOCKED_STALL
+ * @returns Updated tick state
+ */
+export function updateStateForOutcome(state, outcome, stallInfo) {
+    if (shouldResetRetryState(outcome)) {
+        return resetRetryState(state);
+    }
+    if (outcome === 'BLOCKED_STALL' && stallInfo) {
+        return recordTransportStall(state, stallInfo.errorKind, stallInfo.requestId);
+    }
+    // BLOCKED_OTHER - no changes
+    return state;
+}
+/**
+ * Convenience function to handle successful tick completion.
+ *
+ * Resets all retry state fields to clear recovery mode.
+ * Call this when a tick completes with SUCCESS verdict.
+ *
+ * @param state - Current tick state
+ * @returns Updated state with retry fields cleared
+ */
+export function handleTickSuccess(state) {
+    return resetRetryState(state);
+}
+/**
+ * Convenience function to handle tick failure with STOP code.
+ *
+ * Resets retry state because STOP is a definitive failure,
+ * not a transient transport issue that might benefit from retry.
+ *
+ * @param state - Current tick state
+ * @returns Updated state with retry fields cleared
+ */
+export function handleTickStop(state) {
+    return resetRetryState(state);
+}
+/**
+ * Convenience function to handle transport stall.
+ *
+ * Increments retry_count and records error information.
+ * Call this when a tick is blocked due to transport stall.
+ *
+ * @param state - Current tick state
+ * @param requestId - Request ID from the stall (for debugging)
+ * @returns Updated state with incremented retry count
+ */
+export function handleTickStall(state, requestId) {
+    return recordTransportStall(state, 'transport_stalled', requestId);
+}
+/**
+ * Handles a transport stall during tick execution.
+ *
+ * When a stall is detected:
+ * 1. Checks if the git worktree is dirty
+ * 2. If dirty, rolls back to the base commit
+ * 3. Returns a BLOCKED result with stall evidence
+ *
+ * @param stallError - The structured stall error
+ * @param baseCommit - The commit to rollback to if needed
+ * @param options - Optional handling options
+ * @returns StallHandlingResult with rollback status and stall evidence
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeWithStallDetection(config, invocation, 'BUILD');
+ * if (!result.ok) {
+ *   const stallResult = await handleTransportStall(result.error, baseCommit);
+ *   // stallResult.blockedCode === 'BLOCKED_TRANSPORT_STALLED'
+ * }
+ * ```
+ */
+export async function handleTransportStall(stallError, baseCommit, options = {}) {
+    // Check if worktree is dirty
+    const cleanCheck = isWorktreeClean();
+    const wasDirty = !cleanCheck;
+    let rollbackPerformed = false;
+    let rollbackResult = null;
+    // If dirty and rollback not skipped, perform rollback
+    if (wasDirty && !options.skipRollback) {
+        rollbackResult = rollbackToCommit(baseCommit);
+        rollbackPerformed = rollbackResult.ok;
+    }
+    return {
+        status: 'BLOCKED',
+        blockedCode: 'BLOCKED_TRANSPORT_STALLED',
+        stage: stallError.stage,
+        requestId: stallError.request_id,
+        rawError: stallError.raw_error,
+        rollbackPerformed,
+        rollbackResult,
+        wasDirty,
+        baseCommit,
+    };
+}
+/**
+ * Checks if a stall occurred and handles it if so.
+ *
+ * This is a convenience wrapper that combines stall detection with handling.
+ *
+ * @param error - Any error that might be a stall
+ * @param stage - The stage where the error occurred
+ * @param baseCommit - The commit to rollback to if needed
+ * @param options - Optional handling options
+ * @returns StallHandlingResult if stall detected, null otherwise
+ */
+export async function checkAndHandleStall(stallError, baseCommit, options = {}) {
+    if (!stallError) {
+        return null;
+    }
+    return handleTransportStall(stallError, baseCommit, options);
+}
+/**
+ * Creates a human-readable message for a stall handling result.
+ *
+ * @param result - The stall handling result
+ * @returns Formatted message string
+ */
+export function formatStallResult(result) {
+    const lines = [
+        `Transport stall detected during ${result.stage}`,
+        `Status: ${result.blockedCode}`,
+    ];
+    if (result.requestId) {
+        lines.push(`Request ID: ${result.requestId}`);
+    }
+    if (result.wasDirty) {
+        if (result.rollbackPerformed) {
+            lines.push(`Rollback: performed to ${result.baseCommit.substring(0, 7)}`);
+        }
+        else {
+            lines.push(`Rollback: skipped (repo was dirty)`);
+        }
+    }
+    else {
+        lines.push(`Rollback: not needed (repo was clean)`);
+    }
+    lines.push(`Error: ${result.rawError.substring(0, 100)}${result.rawError.length > 100 ? '...' : ''}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=tick.js.map

package/dist/lib/tick.js.map

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

package/dist/lib/transport.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Transport layer utilities for Claude invocations.
+ *
+ * Provides stall detection and timeout wrapper for reliable
+ * handling of connection issues, timeouts, and transport failures.
+ */
+import type { ClaudeCodeCliConfig } from '../types/config.js';
+import type { ClaudeInvocation, ClaudeResponse } from '../types/claude.js';
+import type { TransportStallError, TransportStallStage } from '../types/preflight.js';
+/**
+ * Result of stall pattern detection.
+ */
+export interface StallDetectionResult {
+    /** Whether a stall pattern was detected */
+    stalled: boolean;
+    /** Request ID if found in error output */
+    request_id: string | null;
+    /** Which pattern was matched, if any */
+    matched_pattern: string | null;
+}
+/**
+ * Detects transport stall patterns in error output.
+ *
+ * Checks for known patterns that indicate connection issues:
+ * - "Connection stalled" - Cursor/CLI connection issue
+ * - "streamFromAgentBackend" - Backend stream failure
+ * - "ECONNRESET" - Connection reset by peer
+ * - "ETIMEDOUT" - Connection timeout
+ * - "socket hang up" - Socket disconnection
+ *
+ * Also extracts Request ID if present for debugging.
+ *
+ * @param error - Error message or stderr output to analyze
+ * @returns Detection result with stalled flag and optional request_id
+ *
+ * @example
+ * ```typescript
+ * const result = isTransportStall('Connection stalled. Request ID: abc123');
+ * // result.stalled === true
+ * // result.request_id === 'abc123'
+ * ```
+ */
+export declare function isTransportStall(error: string): StallDetectionResult;
+/**
+ * Creates a TransportStallError from error information.
+ *
+ * @param stage - The stage where the stall occurred (ORCHESTRATE or BUILD)
+ * @param rawError - The raw error message
+ * @param requestId - Optional request ID extracted from error
+ * @returns Structured TransportStallError
+ */
+export declare function createTransportStallError(stage: TransportStallStage, rawError: string, requestId?: string | null): TransportStallError;
+/**
+ * Result type for invokeWithStallDetection.
+ * Either a successful ClaudeResponse or a TransportStallError.
+ */
+export type InvokeResult = {
+    ok: true;
+    response: ClaudeResponse;
+} | {
+    ok: false;
+    error: TransportStallError;
+};
+/**
+ * Invokes Claude Code CLI with stall detection.
+ *
+ * Wraps the standard invokeClaudeCode function and:
+ * 1. Catches timeout errors and converts to TransportStallError
+ * 2. Detects stall patterns in error output
+ * 3. Returns structured error for transport failures
+ *
+ * @param config - Claude Code CLI configuration
+ * @param invocation - Invocation parameters
+ * @param stage - The stage (ORCHESTRATE or BUILD) for error context
+ * @returns InvokeResult with either response or stall error
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeWithStallDetection(config, invocation, 'BUILD');
+ * if (result.ok) {
+ *   console.log('Success:', result.response.result);
+ * } else {
+ *   console.log('Stall:', result.error.raw_error);
+ * }
+ * ```
+ */
+export declare function invokeWithStallDetection(config: ClaudeCodeCliConfig, invocation: ClaudeInvocation, stage: TransportStallStage): Promise<InvokeResult>;
+/**
+ * Result of normalizing an error for transport stall detection.
+ */
+export interface NormalizedError {
+    /** Whether this error represents a transport stall */
+    isStall: boolean;
+    /** Structured stall error if isStall is true */
+    stallError: TransportStallError | null;
+    /** The original error wrapped as Error */
+    originalError: Error;
+    /** Raw error message extracted from the error */
+    message: string;
+}
+/**
+ * Normalizes any error type into a consistent format for stall detection.
+ *
+ * Handles:
+ * - ClaudeError: extracts message + stderr, checks for timeout
+ * - Error: extracts message
+ * - string: wraps in Error
+ * - unknown: converts to string and wraps in Error
+ *
+ * @param error - Any error type (ClaudeError, Error, string, unknown)
+ * @param stage - The stage where the error occurred (ORCHESTRATE or BUILD)
+ * @returns Normalized error with stall detection result
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await invokeClaudeCode(config, invocation);
+ * } catch (error) {
+ *   const normalized = normalizeTransportError(error, 'BUILD');
+ *   if (normalized.isStall) {
+ *     handleStall(normalized.stallError);
+ *   } else {
+ *     throw normalized.originalError;
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Type guard to check if an error is a TransportStallError.
+ *
+ * @param error - Any value to check
+ * @returns True if the error is a TransportStallError
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeWithStallDetection(config, invocation, 'BUILD');
+ * if (!result.ok && isTransportStallError(result.error)) {
+ *   console.log('Stage:', result.error.stage);
+ *   console.log('Request ID:', result.error.request_id);
+ * }
+ * ```
+ */
+export declare function isTransportStallError(error: unknown): error is TransportStallError;
+export declare function normalizeTransportError(error: unknown, stage: TransportStallStage): NormalizedError;
+//# sourceMappingURL=transport.d.ts.map

package/dist/lib/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/lib/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAoBtF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wCAAwC;IACxC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,CA2BpE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,mBAAmB,CAarB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,YAAY,CAAC,CAyCvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,0CAA0C;IAC1C,aAAa,EAAE,KAAK,CAAC;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAYlF;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,mBAAmB,GACzB,eAAe,CAmCjB"}