agentic-qe 3.14.4 → 3.14.6

package/dist/planning/goap-planner.js

@@ -14,6 +14,7 @@
 import { randomUUID } from 'crypto';
 import { safeJsonParse } from '../shared/safe-json.js';
 import { getUnifiedPersistence } from '../kernel/unified-persistence.js';
+import { DEFAULT_MAX_PLAN_STEPS, validateMaxSteps } from './types.js';
 import { getAllQEActions, QE_GOALS } from './actions/qe-action-library.js';
 // ============================================================================
 // MinHeap for A* Open Set (O(log n) insert/extract vs O(n log n) sort+shift)
@@ -223,12 +224,20 @@ export class GOAPPlanner {
      * @returns Optimal plan or null if no plan found
      */
     async findPlan(currentState, goal, constraints) {
+        // Issue #535: reject a malformed step cap up front rather than silently
+        // ignoring it (maxSteps: 0 would otherwise mean "no plan ever").
+        const maxStepsError = validateMaxSteps(constraints?.maxSteps);
+        if (maxStepsError) {
+            throw new Error(maxStepsError);
+        }
         await this.initialize();
         const startTime = Date.now();
         // Try to reuse a similar plan first
         if (this.enablePlanReuse) {
             const reusedPlan = await this.findSimilarPlan(goal, 0.75);
-            if (reusedPlan && this.validatePlanForState(reusedPlan, currentState)) {
+            if (reusedPlan &&
+                this.validatePlanForState(reusedPlan, currentState) &&
+                this.planSatisfiesConstraints(reusedPlan, currentState, goal, constraints)) {
                 // Update reuse stats
                 this.recordPlanReuse(reusedPlan.id, true);
                 const clonedPlan = {
@@ -297,13 +306,20 @@ export class GOAPPlanner {
         // Entries are added on insert, updated when a better path is found, and
         // removed when the node is popped (moved to the closed set).
         const openSetCosts = new Map();
+        // Issue #535: cost-unit heuristic built once per search from the
+        // actions that can actually move each goal key (see buildHeuristic).
+        const heuristic = this.buildHeuristic(goal, availableActions);
+        const startH = heuristic(start);
+        if (!Number.isFinite(startH)) {
+            return null; // some unmet goal key can never be changed by any action
+        }
         // Initialize start node
         const startNode = {
             state: this.cloneState(start),
             action: null,
             parent: null,
             g: 0,
-            h: this.calculateHeuristic(start, goal),
+            h: startH,
             f: 0,
             depth: 0,
         };
@@ -312,7 +328,8 @@ export class GOAPPlanner {
         openSetCosts.set(this.hashState(start), 0);
         // Constraint defaults
         const maxIterations = 10000;
-        const maxPlanLength = 20;
+        // Issue #535: constraints.maxSteps caps the search depth (= plan length).
+        const maxPlanLength = constraints?.maxSteps ?? DEFAULT_MAX_PLAN_STEPS;
         const maxCost = constraints?.maxCost ?? Infinity;
         const maxDuration = constraints?.maxDurationMs ?? Infinity;
         let iterations = 0;
@@ -352,7 +369,10 @@ export class GOAPPlanner {
                 }
                 // Calculate costs
                 const g = current.g + this.getActionCost(action, current.state);
-                const h = this.calculateHeuristic(newState, goal);
+                const h = heuristic(newState);
+                if (!Number.isFinite(h)) {
+                    continue; // dead end: an unmet goal key no action can change
+                }
                 const f = g + h;
                 // Check cost constraints
                 if (g > maxCost) {
@@ -496,46 +516,84 @@ export class GOAPPlanner {
         return true;
     }
     /**
-     * Calculate heuristic distance to goal (admissible)
+     * Build an admissible, cost-unit A* heuristic for `goal` over `actions`.
+     *
+     * Issue #535: the previous heuristic was the raw percentage gap / 100 (e.g.
+     * 0.9 for coverage 0 -> 90) while a single generate-coverage-tests step
+     * costs ~5, so it carried almost no information and A* degenerated into
+     * uniform-cost search: it enumerated every combination of the ~40 cheap
+     * flag-setting library actions and hit the iteration cap before reaching
+     * any deep goal. Now each unmet goal key contributes a lower bound on the
+     * cost still needed to satisfy it:
+     *   - numeric min/max gap reachable by deltas: ceil(gap / largest delta)
+     *     steps x cheapest such action;
+     *   - any key an action can `set` (primitive or {set}) directly: that
+     *     action's cost (one step);
+     *   - unmet key no action can move: Infinity (dead end, pruned).
+     * The per-key bounds are combined with max(), which keeps the heuristic
+     * admissible and consistent even when one action moves several keys.
+     * Costs use the same base as getActionCost() (cost / successRate), whose
+     * risk multiplier only ever increases cost, so the bound never overshoots.
      */
-    calculateHeuristic(state, goal) {
-        let distance = 0;
-        for (const [key, condition] of Object.entries(goal)) {
-            const currentValue = this.getStateValue(state, key);
-            if (typeof condition === 'object' &&
-                condition !== null &&
-                'min' in condition) {
-                const minValue = condition.min;
-                if (typeof currentValue === 'number' && currentValue < minValue) {
-                    // Normalize distance (percentage points to heuristic units)
-                    distance += (minValue - currentValue) / 100;
+    buildHeuristic(goal, actions) {
+        const lowerBoundCost = (a) => a.successRate > 0 && a.successRate < 1 ? a.cost / a.successRate : a.cost;
+        const movers = new Map();
+        for (const key of Object.keys(goal)) {
+            const m = { setCost: Infinity, upDelta: 0, upCost: Infinity, downDelta: 0, downCost: Infinity };
+            for (const action of actions) {
+                if (!Object.hasOwn(action.effects, key))
+                    continue;
+                const effect = action.effects[key];
+                const c = lowerBoundCost(action);
+                if (typeof effect !== 'object' || effect === null) {
+                    m.setCost = Math.min(m.setCost, c);
+                    continue;
                 }
-            }
-            if (typeof condition === 'object' &&
-                condition !== null &&
-                'max' in condition) {
-                const maxValue = condition.max;
-                if (typeof currentValue === 'number' && currentValue > maxValue) {
-                    distance += (currentValue - maxValue) / 100;
+                if ('set' in effect && effect.set !== undefined) {
+                    m.setCost = Math.min(m.setCost, c);
                 }
-            }
-            if (typeof condition === 'object' &&
-                condition !== null &&
-                'eq' in condition) {
-                if (currentValue !== condition.eq) {
-                    distance += 1;
+                if ('delta' in effect && typeof effect.delta === 'number') {
+                    if (effect.delta > 0) {
+                        m.upDelta = Math.max(m.upDelta, effect.delta);
+                        m.upCost = Math.min(m.upCost, c);
+                    }
+                    else if (effect.delta < 0) {
+                        m.downDelta = Math.max(m.downDelta, -effect.delta);
+                        m.downCost = Math.min(m.downCost, c);
+                    }
                 }
             }
-            // Primitive conditions
-            if (typeof condition === 'string' ||
-                typeof condition === 'number' ||
-                typeof condition === 'boolean') {
-                if (currentValue !== condition) {
-                    distance += 1;
+            movers.set(key, m);
+        }
+        return (state) => {
+            let h = 0;
+            for (const [key, condition] of Object.entries(goal)) {
+                if (this.checkCondition(state, key, condition))
+                    continue;
+                const m = movers.get(key);
+                const value = this.getStateValue(state, key);
+                let bound = m.setCost;
+                if (typeof value === 'number' && typeof condition === 'object' && condition !== null) {
+                    if ('min' in condition && typeof condition.min === 'number' && value < condition.min && m.upDelta > 0) {
+                        bound = Math.min(bound, Math.ceil((condition.min - value) / m.upDelta) * m.upCost);
+                    }
+                    else if ('max' in condition && typeof condition.max === 'number' && value > condition.max && m.downDelta > 0) {
+                        bound = Math.min(bound, Math.ceil((value - condition.max) / m.downDelta) * m.downCost);
+                    }
+                    else if ('eq' in condition && typeof condition.eq === 'number') {
+                        // An eq target can be hit by a delta in (at least) one step.
+                        bound = Math.min(bound, m.upCost, m.downCost);
+                    }
+                }
+                else if (typeof value === 'number' && typeof condition === 'number') {
+                    bound = Math.min(bound, m.upCost, m.downCost);
                 }
+                if (!Number.isFinite(bound))
+                    return Infinity;
+                h = Math.max(h, bound);
             }
-        }
-        return distance;
+            return h;
+        };
     }
     /**
      * Get value from nested state using dot notation
@@ -580,31 +638,50 @@ export class GOAPPlanner {
         Object.defineProperty(current, finalKey, { value, writable: true, enumerable: true, configurable: true });
     }
     /**
-     * Create hash of state for deduplication
+     * Create hash of state for deduplication.
+     *
+     * Issue #535: this previously hashed a fixed list of known fields only, so
+     * every action effect on any other key (coverage.gapsIdentified,
+     * quality.unitTestsRun, fleet.specialistAvailable, ... — most of the
+     * seeded action library) produced a successor state that hashed identical
+     * to its already-closed parent and was pruned. That made e.g. the seeded
+     * `achieve-90-percent-coverage` goal unplannable from any state (the
+     * analyze-coverage-gaps -> generate-coverage-tests chain was unreachable).
+     * Now every key in the state participates. Numbers are compared at 1e-6
+     * precision; resources.timeRemaining is bucketed per minute, as before.
      */
     hashState(state) {
-        const key = {
-            // Coverage
-            coverageLine: Math.round(state.coverage.line),
-            coverageBranch: Math.round(state.coverage.branch),
-            coverageFunc: Math.round(state.coverage.function),
-            coverageMeasured: state.coverage.measured,
-            // Quality
-            testsPassing: Math.round(state.quality.testsPassing),
-            securityScore: Math.round(state.quality.securityScore),
-            performanceScore: Math.round(state.quality.performanceScore),
-            // Fleet
-            activeAgents: state.fleet.activeAgents,
-            // PERF: Copy before sort to avoid mutating original array on every A* expansion
-            availableAgents: [...state.fleet.availableAgents].sort().join(','),
-            // Resources (rounded to reduce state space)
-            timeRemaining: Math.floor(state.resources.timeRemaining / 60),
-            parallelSlots: state.resources.parallelSlots,
-            // Context
-            environment: state.context.environment,
-            riskLevel: state.context.riskLevel,
-        };
-        return JSON.stringify(key);
+        return GOAPPlanner.stableStateKey(state, '');
+    }
+    static stableStateKey(value, path) {
+        if (value === null || value === undefined)
+            return String(value);
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                return String(value);
+            // Keep fractional progress distinguishable (codex review: integer
+            // rounding collapsed e.g. custom.progress 0 -> 0.4 into its parent);
+            // only timeRemaining is bucketed (per minute) to bound the space.
+            return path === 'resources.timeRemaining'
+                ? String(Math.floor(value / 60))
+                : String(Math.round(value * 1e6) / 1e6);
+        }
+        if (typeof value === 'string')
+            return JSON.stringify(value);
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        if (Array.isArray(value)) {
+            // Copy before sort to avoid mutating the state's own array.
+            return `[${value.map((v) => GOAPPlanner.stableStateKey(v, path)).sort().join(',')}]`;
+        }
+        if (typeof value === 'object') {
+            const obj = value;
+            const parts = Object.keys(obj)
+                .sort()
+                .map((k) => `${k}:${GOAPPlanner.stableStateKey(obj[k], path ? `${path}.${k}` : k)}`);
+            return `{${parts.join(',')}}`;
+        }
+        return typeof value;
     }
     /**
      * Deep clone world state.
@@ -727,6 +804,21 @@ export class GOAPPlanner {
         await this.initialize();
         return Array.from(this.actions.values()).filter((a) => a.category === category);
     }
+    /**
+     * State keys referenced by any loaded action's preconditions or effects
+     * (seeded library plus custom actions added via addAction()). Used by the
+     * goap_plan tool to validate caller-supplied world-state keys (#535).
+     */
+    getReferencedStateKeys() {
+        const keys = new Set();
+        for (const action of this.actions.values()) {
+            for (const k of Object.keys(action.preconditions))
+                keys.add(k);
+            for (const k of Object.keys(action.effects))
+                keys.add(k);
+        }
+        return [...keys];
+    }
     /**
      * Get available actions based on constraints
      */
@@ -784,6 +876,41 @@ export class GOAPPlanner {
             similarityScore: row.similarity_score ?? undefined,
         };
     }
+    /**
+     * List persisted plan summaries without loading every plan into memory.
+     * Count includes all rows matching the optional status, before pagination.
+     */
+    async listPlanSummaries(status, limit = 20) {
+        await this.initialize();
+        const db = this.ensureDb();
+        const where = status ? ' WHERE status = ?' : '';
+        const args = status ? [status] : [];
+        const boundedLimit = Number.isFinite(limit)
+            ? Math.max(1, Math.min(100, Math.trunc(limit)))
+            : 20;
+        const { count } = db.prepare(`SELECT COUNT(*) AS count FROM goap_plans${where}`)
+            .get(...args);
+        const rows = db.prepare(`
+      SELECT id, status, action_sequence, total_cost, created_at
+      FROM goap_plans${where}
+      ORDER BY created_at DESC, id DESC
+      LIMIT ?
+    `).all(...args, boundedLimit);
+        const plans = rows.map((row) => {
+            const actionIds = safeJsonParse(row.action_sequence);
+            if (!Array.isArray(actionIds)) {
+                throw new Error(`Invalid action sequence in GOAP plan ${row.id}`);
+            }
+            return {
+                id: row.id,
+                status: row.status,
+                stepCount: actionIds.length,
+                totalCost: row.total_cost,
+                createdAt: row.created_at,
+            };
+        });
+        return { plans, count };
+    }
     /**
      * Find a similar plan by goal conditions
      */
@@ -859,6 +986,37 @@ export class GOAPPlanner {
         }
         return true;
     }
+    /**
+     * Issue #535: a reused plan must honour the caller's constraints exactly
+     * like a freshly searched one — otherwise a cached 11-step plan is handed
+     * back for a `maxSteps: 3` request (or one using an excluded action, or
+     * over budget). Also requires that replaying the plan from the current
+     * state actually reaches the goal.
+     */
+    planSatisfiesConstraints(plan, currentState, goal, constraints) {
+        const maxSteps = constraints?.maxSteps ?? DEFAULT_MAX_PLAN_STEPS;
+        if (plan.actions.length > maxSteps)
+            return false;
+        if (constraints?.maxDurationMs !== undefined &&
+            plan.estimatedDurationMs > constraints.maxDurationMs) {
+            return false;
+        }
+        const allowed = new Set(this.getAvailableActions(constraints).map((a) => a.id));
+        if (!plan.actions.every((a) => allowed.has(a.id)))
+            return false;
+        // Replay with the same effective cost fresh search enforces
+        // (getActionCost: success-rate and risk adjusted), not raw totalCost.
+        let state = this.cloneState(currentState);
+        let effectiveCost = 0;
+        for (const action of plan.actions) {
+            effectiveCost += this.getActionCost(action, state);
+            state = this.applyAction(state, action);
+        }
+        if (constraints?.maxCost !== undefined && effectiveCost > constraints.maxCost) {
+            return false;
+        }
+        return this.meetsConditions(state, goal);
+    }
     /**
      * Hash goal conditions for comparison
      */

package/dist/planning/index.d.ts

@@ -7,7 +7,7 @@
  * @version 3.0.0
  */
 export type { V3WorldState, StateConditions, ActionEffects, GOAPAction, GOAPGoal, GOAPPlan, ExecutionStep, PlanConstraints, GOAPGoalRecord, GOAPActionRecord, GOAPPlanRecord, } from './types.js';
-export { DEFAULT_V3_WORLD_STATE } from './types.js';
+export { DEFAULT_V3_WORLD_STATE, DEFAULT_MAX_PLAN_STEPS, validateMaxSteps } from './types.js';
 export { QE_ACTIONS, QE_GOALS, getAllQEActions, getActionsByCategory, getActionsByDomain, getActionsByAgentType, getActionByName, seedQEActions, getActionStats, validateActionLibrary, toGOAPAction, } from './actions/qe-action-library.js';
 export type { QEActionTemplate, QEGoalTemplate } from './actions/qe-action-library.js';
 export { GOAPPlanner, getSharedGOAPPlanner, resetSharedGOAPPlanner, } from './goap-planner.js';

package/dist/planning/index.js

@@ -7,7 +7,7 @@
  * @version 3.0.0
  */
 // Constant exports
-export { DEFAULT_V3_WORLD_STATE } from './types.js';
+export { DEFAULT_V3_WORLD_STATE, DEFAULT_MAX_PLAN_STEPS, validateMaxSteps } from './types.js';
 // Action Library exports
 export { QE_ACTIONS, QE_GOALS, getAllQEActions, getActionsByCategory, getActionsByDomain, getActionsByAgentType, getActionByName, seedQEActions, getActionStats, validateActionLibrary, toGOAPAction, } from './actions/qe-action-library.js';
 // Planner exports

package/dist/planning/plan-executor.d.ts

@@ -32,6 +32,13 @@ export interface ExecutionConfig {
     stepTimeoutMs: number;
     /** Auto-replan if step fails (default: true) */
     replanOnFailure: boolean;
+    /**
+     * Maximum number of successive replans within one execution (default: 3).
+     * Issue #535: once the planner could actually find plans again, an
+     * unbounded failure -> replan -> failure chain could ping-pong forever
+     * between two alternative actions.
+     */
+    maxReplans?: number;
     /** Execute independent steps in parallel (default: false) */
     parallelExecution: boolean;
     /** Record state before/after each step (default: true) */
@@ -210,6 +217,11 @@ export declare class PlanExecutor {
      * @returns Execution result
      */
     executeWithCallbacks(plan: GOAPPlan, onStepStart: (step: ExecutionStep) => void, onStepComplete: (step: ExecutedStep) => void, initialState?: V3WorldState): Promise<ExecutionResult>;
+    /**
+     * Run a plan's steps (and any replacement plans after a failure) without
+     * persisting or resetting execution tracking — see executeWithCallbacks.
+     */
+    private runPlan;
     /**
      * Execute a single step
      */
@@ -224,6 +236,13 @@ export declare class PlanExecutor {
      * `successRate: 0.95` roll.
      */
     private executeRealAction;
+    /**
+     * Race `work` against the per-step timeout, clearing the timer once the
+     * race settles so completed steps don't leave a pending timer behind
+     * (codex review, #535: it kept short-lived processes alive for up to
+     * stepTimeoutMs and accumulated timers across executions).
+     */
+    private withStepTimeout;
     /**
      * Build a task description for an agent
      */
@@ -236,7 +255,7 @@ export declare class PlanExecutor {
      * @param currentState - Current world state at failure point
      * @returns New plan or null if replanning fails
      */
-    replanFromFailure(originalPlan: GOAPPlan, failedStepIndex: number, currentState: V3WorldState): Promise<GOAPPlan | null>;
+    replanFromFailure(originalPlan: GOAPPlan, failedStepIndex: number, currentState: V3WorldState, additionalExcluded?: string[]): Promise<GOAPPlan | null>;
     /**
      * Cancel the current execution
      */