@ttfw/envoi 1.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EACV,SAAS,EAET,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAWrF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,GAAG,SAAS,CAKhF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAKnE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAK5E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,SAAS,CAAC,gBAAgB,CAAC,GACzC,SAAS,CAKX;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,gBAAgB,GACtB,SAAS,CAiBX;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAY3D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAczD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,GAClB,SAAS,CAKX;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,GAClB,SAAS,CAMX;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAK9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,kBAAkB,GACxB,SAAS,CASX;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAK/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,SAAS,CAOX;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAO3D"}

package/dist/lib/state.js

@@ -0,0 +1,258 @@
+/**
+ * State management utilities for tick execution.
+ *
+ * Provides functions to create and update tick state during execution.
+ */
+import { randomBytes } from 'node:crypto';
+import { TickPhase } from '../types/state.js';
+/**
+ * Generates a unique run ID for a tick.
+ *
+ * @returns A unique identifier string
+ */
+export function generateRunId() {
+    // Generate 16 random bytes and encode as hex (32 chars)
+    return randomBytes(16).toString('hex');
+}
+/**
+ * Creates initial tick state.
+ *
+ * @param config - Envoi configuration
+ * @param baseCommit - Git HEAD commit SHA at start
+ * @returns Initial tick state
+ */
+export function createInitialState(config, baseCommit) {
+    return {
+        phase: TickPhase.LOCK,
+        run_id: generateRunId(),
+        started_at: new Date().toISOString(),
+        base_commit: baseCommit,
+        config,
+        task: null,
+        builder_result: null,
+        errors: [],
+    };
+}
+/**
+ * Transitions tick state to a new phase.
+ *
+ * @param state - Current tick state
+ * @param newPhase - Phase to transition to
+ * @returns Updated tick state
+ */
+export function transitionPhase(state, newPhase) {
+    return {
+        ...state,
+        phase: newPhase,
+    };
+}
+/**
+ * Adds an error to the tick state.
+ *
+ * @param state - Current tick state
+ * @param error - Error message to add
+ * @returns Updated tick state
+ */
+export function addError(state, error) {
+    return {
+        ...state,
+        errors: [...state.errors, error],
+    };
+}
+/**
+ * Updates task in tick state.
+ *
+ * @param state - Current tick state
+ * @param task - Task to set
+ * @returns Updated tick state
+ */
+export function setTask(state, task) {
+    return {
+        ...state,
+        task,
+    };
+}
+/**
+ * Updates builder result in tick state.
+ *
+ * @param state - Current tick state
+ * @param builderResult - Builder result to set
+ * @returns Updated tick state
+ */
+export function setBuilderResult(state, builderResult) {
+    return {
+        ...state,
+        builder_result: builderResult,
+    };
+}
+/**
+ * Appends a stop history entry to guardrail state, capping at 50 entries.
+ *
+ * @param state - Current tick state
+ * @param entry - Stop history entry to add
+ * @returns Updated tick state
+ */
+export function appendStopHistory(state, entry) {
+    const guardrail = state.guardrail ?? {
+        force_patch_until_success: false,
+        last_risk_flags: [],
+        stop_history: [],
+    };
+    // Add entry and cap to 50 entries (keep most recent)
+    const updatedHistory = [...guardrail.stop_history, entry].slice(-50);
+    return {
+        ...state,
+        guardrail: {
+            ...guardrail,
+            stop_history: updatedHistory,
+        },
+    };
+}
+/**
+ * Clears force patch flag (sets force_patch_until_success to false).
+ *
+ * Called when a patch succeeds to reset escalation state.
+ *
+ * @param state - Current tick state
+ * @returns Updated tick state
+ */
+export function clearForcePatch(state) {
+    if (!state.guardrail) {
+        return state;
+    }
+    return {
+        ...state,
+        guardrail: {
+            ...state.guardrail,
+            force_patch_until_success: false,
+        },
+    };
+}
+/**
+ * Sets force patch flag (sets force_patch_until_success to true).
+ *
+ * Called to enable escalation mode when guardrails trigger.
+ *
+ * @param state - Current tick state
+ * @returns Updated tick state
+ */
+export function setForcePatch(state) {
+    const guardrail = state.guardrail ?? {
+        force_patch_until_success: false,
+        last_risk_flags: [],
+        stop_history: [],
+    };
+    return {
+        ...state,
+        guardrail: {
+            ...guardrail,
+            force_patch_until_success: true,
+        },
+    };
+}
+/**
+ * Updates the task fingerprint in tick state.
+ *
+ * @param state - Current tick state
+ * @param fingerprint - SHA256 fingerprint of the current task
+ * @returns Updated tick state
+ */
+export function updateTaskFingerprint(state, fingerprint) {
+    return {
+        ...state,
+        task_fingerprint: fingerprint,
+    };
+}
+/**
+ * Updates failure tracking when a task fails.
+ *
+ * Increments failure_streak and updates last_failed_fingerprint.
+ *
+ * @param state - Current tick state
+ * @param fingerprint - SHA256 fingerprint of the failed task
+ * @returns Updated tick state
+ */
+export function recordTaskFailure(state, fingerprint) {
+    return {
+        ...state,
+        last_failed_fingerprint: fingerprint,
+        failure_streak: (state.failure_streak ?? 0) + 1,
+    };
+}
+/**
+ * Resets failure streak when a task succeeds.
+ *
+ * @param state - Current tick state
+ * @returns Updated tick state
+ */
+export function resetFailureStreak(state) {
+    return {
+        ...state,
+        failure_streak: 0,
+    };
+}
+/**
+ * Appends a verify history entry, capping at 50 entries.
+ *
+ * @param state - Current tick state
+ * @param entry - Verify history entry to add
+ * @returns Updated tick state
+ */
+export function appendVerifyHistory(state, entry) {
+    const currentHistory = state.verify_history ?? [];
+    // Add entry and cap to 50 entries (keep most recent)
+    const updatedHistory = [...currentHistory, entry].slice(-50);
+    return {
+        ...state,
+        verify_history: updatedHistory,
+    };
+}
+/**
+ * Increments the retry count for transport stall recovery.
+ *
+ * @param state - Current tick state
+ * @returns Updated tick state with incremented retry_count
+ */
+export function incrementRetryCount(state) {
+    return {
+        ...state,
+        retry_count: (state.retry_count ?? 0) + 1,
+    };
+}
+/**
+ * Records a transport stall error in state.
+ *
+ * Used to track the last error kind and request ID for debugging
+ * and retry policy decisions.
+ *
+ * @param state - Current tick state
+ * @param errorKind - Kind of error (e.g., 'transport_stalled')
+ * @param requestId - Request ID from the stall (for debugging)
+ * @returns Updated tick state
+ */
+export function recordTransportStall(state, errorKind, requestId) {
+    return {
+        ...state,
+        last_error_kind: errorKind,
+        last_request_id: requestId,
+        retry_count: (state.retry_count ?? 0) + 1,
+    };
+}
+/**
+ * Resets retry state after a successful tick.
+ *
+ * Clears retry_count, last_error_kind, and last_request_id.
+ * Called when a tick completes successfully to reset recovery state.
+ *
+ * @param state - Current tick state
+ * @returns Updated tick state with cleared retry fields
+ */
+export function resetRetryState(state) {
+    return {
+        ...state,
+        retry_count: 0,
+        last_error_kind: undefined,
+        last_request_id: undefined,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/lib/state.js.map

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

package/dist/lib/tick.d.ts

@@ -0,0 +1,310 @@
+/**
+ * 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 type { TransportStallError, TransportStallStage } from '../types/preflight.js';
+import type { RollbackResultNew } from './rollback.js';
+import type { DiffLimits } from '../types/task.js';
+import type { EnvoiConfig } from '../types/config.js';
+import type { TickState } from '../types/state.js';
+/**
+ * Maximum retry attempts before blocking.
+ */
+export declare 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 declare const RECOVERY_PROMPT = "IMPORTANT: This is a retry after a transport stall. The previous attempt may have been interrupted.\n\nDo NOT assume your previous edits were applied. The connection may have stalled:\n- Before any changes were made\n- In the middle of changes (partial writes)\n- After changes were made but before confirmation\n\nBEFORE making any edits:\n1. Read the relevant files to verify their current state\n2. Check if your intended changes already exist\n3. Proceed based on the actual file contents, not your memory of what you tried to do\n\nIf 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 declare function getRecoveryPrompt(retryCount: number): string;
+/**
+ * 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 declare function buildPromptWithRecovery(originalPrompt: string, retryCount: number): string;
+/**
+ * Action to take based on retry count.
+ */
+export type RetryAction = 'retry_unchanged' | 'retry_degraded' | 'block';
+/**
+ * Degraded settings applied on retry attempt 2.
+ */
+export interface DegradedSettings {
+    /** Reduced max_turns for builder (50% of original, minimum 5) */
+    max_turns: number;
+    /** Stricter diff limits (50% of original) */
+    diff_limits: DiffLimits;
+    /** Prefer patch mode if available */
+    prefer_patch_mode: boolean;
+}
+/**
+ * Result of computing retry action.
+ */
+export interface RetryDecision {
+    /** The action to take */
+    action: RetryAction;
+    /** Current retry count (after this attempt) */
+    retry_count: number;
+    /** Degraded settings if action is 'retry_degraded' */
+    degraded_settings?: DegradedSettings;
+    /** Human-readable reason for the decision */
+    reason: string;
+}
+/**
+ * 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 declare function getRetryAction(retryCount: number): RetryAction;
+/**
+ * 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 declare function computeRetryDecision(retryCount: number, originalMaxTurns?: number, originalDiffLimits?: DiffLimits): RetryDecision;
+/**
+ * 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 declare function computeDegradedSettings(originalMaxTurns: number, originalDiffLimits: DiffLimits): DegradedSettings;
+/**
+ * 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 declare function canRetry(retryCount: number): boolean;
+/**
+ * Formats retry decision as human-readable message.
+ *
+ * @param decision - The retry decision
+ * @returns Formatted message
+ */
+export declare function formatRetryDecision(decision: RetryDecision): string;
+/**
+ * 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 declare function applyDegradedConfig(config: EnvoiConfig, degraded: DegradedSettings): EnvoiConfig;
+/**
+ * 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 declare function extractDegradationInputs(config: EnvoiConfig): {
+    max_turns: number;
+    diff_limits: DiffLimits;
+};
+/**
+ * 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 declare function getDegradedConfigIfNeeded(config: EnvoiConfig, retryCount: number): EnvoiConfig;
+/**
+ * Tick outcome types for retry state management.
+ */
+export type TickOutcome = 'SUCCESS' | 'STOP' | 'BLOCKED_STALL' | 'BLOCKED_OTHER';
+/**
+ * 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 declare function shouldResetRetryState(outcome: TickOutcome): boolean;
+/**
+ * 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 declare function updateStateForOutcome(state: TickState, outcome: TickOutcome, stallInfo?: {
+    errorKind: string;
+    requestId: string | null;
+}): TickState;
+/**
+ * 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 declare function handleTickSuccess(state: TickState): TickState;
+/**
+ * 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 declare function handleTickStop(state: TickState): TickState;
+/**
+ * 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 declare function handleTickStall(state: TickState, requestId: string | null): TickState;
+/**
+ * Result of handling a transport stall.
+ */
+export interface StallHandlingResult {
+    /** Always 'BLOCKED' for stall handling */
+    status: 'BLOCKED';
+    /** The blocked code */
+    blockedCode: 'BLOCKED_TRANSPORT_STALLED';
+    /** The stage where the stall occurred */
+    stage: TransportStallStage;
+    /** Request ID if available */
+    requestId: string | null;
+    /** Raw error message */
+    rawError: string;
+    /** Whether rollback was performed */
+    rollbackPerformed: boolean;
+    /** Rollback result if performed */
+    rollbackResult: RollbackResultNew | null;
+    /** Whether repo was dirty before rollback */
+    wasDirty: boolean;
+    /** Base commit used for rollback */
+    baseCommit: string;
+}
+/**
+ * Options for stall handling.
+ */
+export interface StallHandlingOptions {
+    /** Skip rollback (for testing) */
+    skipRollback?: boolean;
+}
+/**
+ * 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 declare function handleTransportStall(stallError: TransportStallError, baseCommit: string, options?: StallHandlingOptions): Promise<StallHandlingResult>;
+/**
+ * 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 declare function checkAndHandleStall(stallError: TransportStallError | null, baseCommit: string, options?: StallHandlingOptions): Promise<StallHandlingResult | null>;
+/**
+ * Creates a human-readable message for a stall handling result.
+ *
+ * @param result - The stall handling result
+ * @returns Formatted message string
+ */
+export declare function formatStallResult(result: StallHandlingResult): string;
+//# sourceMappingURL=tick.d.ts.map

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

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