agentic-qe 3.14.4 → 3.14.6

package/dist/mcp/tools/planning/world-state.js

@@ -0,0 +1,274 @@
+/**
+ * GOAP world-state detection for the planning MCP tools (issue #535).
+ *
+ * `goap_status {type:"world"}` and `goap_plan`'s auto-detected start state
+ * used to return a static copy of DEFAULT_V3_WORLD_STATE (fleet frozen at
+ * `activeAgents: 0`, coverage 0, securityScore 100, ...) and label it as real
+ * data. This module builds the state from sources that are actually live in
+ * the MCP server process and records, per field, where each value came from:
+ *
+ *   - 'live'     — read from the running fleet (the same queen/kernel state
+ *                  `agent_list` reads)
+ *   - 'measured' — read from a coverage report on disk
+ *                  (`coverage/coverage-summary.json`, istanbul json-summary)
+ *   - 'caller'   — supplied by the caller (goap_plan `currentState`)
+ *   - 'default'  — not measured; the planner's DEFAULT_V3_WORLD_STATE value
+ *                  is used as an assumption and must not be reported as real
+ *
+ * @module mcp/tools/planning/world-state
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DEFAULT_V3_WORLD_STATE, QE_GOALS, getAllQEActions, } from '../../../planning/index.js';
+import { findProjectRoot } from '../../../kernel/project-root.js';
+/** Every leaf field the planner's world state carries (for provenance). */
+const TRACKED_FIELDS = [
+    'coverage.line',
+    'coverage.branch',
+    'coverage.function',
+    'coverage.target',
+    'coverage.measured',
+    'quality.testsPassing',
+    'quality.totalTests',
+    'quality.securityScore',
+    'quality.performanceScore',
+    'fleet.activeAgents',
+    'fleet.availableAgents',
+    'fleet.maxAgents',
+    'resources.timeRemaining',
+    'resources.memoryAvailable',
+    'resources.parallelSlots',
+    'context.environment',
+    'context.riskLevel',
+    'patterns.available',
+    'patterns.reusable',
+];
+const COVERAGE_SUMMARY_RELATIVE = path.join('coverage', 'coverage-summary.json');
+const MAX_COVERAGE_SUMMARY_BYTES = 32 * 1024 * 1024;
+// ============================================================================
+// Live sources
+// ============================================================================
+/**
+ * Read the in-process fleet via core-handlers' fleet state — the same queen
+ * `agent_list` reads. Returns null when no fleet is initialized. Dynamic
+ * import: core-handlers transitively imports the tool registry, which
+ * imports this module's callers (a static import would be circular).
+ */
+export async function readLiveFleet() {
+    try {
+        const { getFleetState, isFleetInitialized } = await import('../../handlers/core-handlers.js');
+        if (!isFleetInitialized())
+            return null;
+        const { queen, kernel } = getFleetState();
+        if (!queen || !kernel)
+            return null;
+        const agents = queen.listAllAgents();
+        const availableAgents = [
+            ...new Set(agents.filter((a) => a.status === 'running' || a.status === 'idle').map((a) => a.type)),
+        ].sort();
+        return {
+            activeAgents: agents.filter((a) => a.status === 'running').length,
+            maxAgents: kernel.getConfig().maxConcurrentAgents,
+            availableAgents,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isPercent(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100;
+}
+/**
+ * Read `coverage/coverage-summary.json` (istanbul/v8 json-summary reporter)
+ * under the project root. Fixed relative path — no caller-controlled input
+ * reaches the filesystem. Returns null when absent, oversized, or malformed.
+ */
+export function readCoverageSummary(projectRoot = findProjectRoot()) {
+    const file = path.join(projectRoot, COVERAGE_SUMMARY_RELATIVE);
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile() || stat.size > MAX_COVERAGE_SUMMARY_BYTES)
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const line = parsed.total?.lines?.pct;
+        const branch = parsed.total?.branches?.pct;
+        const fn = parsed.total?.functions?.pct;
+        if (!isPercent(line) || !isPercent(branch) || !isPercent(fn))
+            return null;
+        return {
+            line,
+            branch,
+            function: fn,
+            source: COVERAGE_SUMMARY_RELATIVE,
+            measuredAt: stat.mtime.toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Detection
+// ============================================================================
+function cloneDefaultState() {
+    const d = DEFAULT_V3_WORLD_STATE;
+    return {
+        coverage: { ...d.coverage },
+        quality: { ...d.quality },
+        fleet: { ...d.fleet, availableAgents: [...d.fleet.availableAgents] },
+        resources: { ...d.resources },
+        context: { ...d.context },
+        patterns: { ...d.patterns },
+    };
+}
+/**
+ * Build the current world state from live/measured sources, falling back to
+ * DEFAULT_V3_WORLD_STATE per field and recording which is which.
+ */
+export async function detectWorldState(sources = {}) {
+    const state = cloneDefaultState();
+    const provenance = {};
+    for (const field of TRACKED_FIELDS)
+        provenance[field] = 'default';
+    const fleet = await (sources.readFleet ?? readLiveFleet)();
+    if (fleet) {
+        state.fleet.activeAgents = fleet.activeAgents;
+        state.fleet.maxAgents = fleet.maxAgents;
+        state.fleet.availableAgents = [...fleet.availableAgents];
+        provenance['fleet.activeAgents'] = 'live';
+        provenance['fleet.maxAgents'] = 'live';
+        provenance['fleet.availableAgents'] = 'live';
+    }
+    const coverage = (sources.readCoverage ?? (() => readCoverageSummary()))();
+    let coverageReport;
+    if (coverage) {
+        state.coverage.line = coverage.line;
+        state.coverage.branch = coverage.branch;
+        state.coverage.function = coverage.function;
+        state.coverage.measured = true;
+        for (const f of ['coverage.line', 'coverage.branch', 'coverage.function', 'coverage.measured']) {
+            provenance[f] = 'measured';
+        }
+        coverageReport = { source: coverage.source, measuredAt: coverage.measuredAt };
+    }
+    return { state, provenance, fleetInitialized: fleet !== null, coverageReport };
+}
+const percent = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 100 ? null : 'a number between 0 and 100';
+const nonNegativeInt = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0 ? null : 'a non-negative integer';
+const nonNegative = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? null : 'a non-negative number';
+const bool = (v) => (typeof v === 'boolean' ? null : 'a boolean');
+const stringList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string') ? null : 'an array of strings';
+const oneOf = (...allowed) => (v) => typeof v === 'string' && allowed.includes(v) ? null : `one of ${allowed.join(', ')}`;
+/** Schema of the known V3WorldState leaves. */
+const FIELD_CHECKS = {
+    'coverage.line': percent,
+    'coverage.branch': percent,
+    'coverage.function': percent,
+    'coverage.target': percent,
+    'coverage.measured': bool,
+    'quality.testsPassing': percent,
+    'quality.totalTests': nonNegativeInt,
+    'quality.securityScore': percent,
+    'quality.performanceScore': percent,
+    'fleet.activeAgents': nonNegativeInt,
+    'fleet.availableAgents': stringList,
+    'fleet.maxAgents': nonNegativeInt,
+    'resources.timeRemaining': nonNegative,
+    'resources.memoryAvailable': nonNegative,
+    'resources.parallelSlots': nonNegativeInt,
+    'context.environment': oneOf('development', 'staging', 'production'),
+    'context.riskLevel': oneOf('low', 'medium', 'high'),
+    'patterns.available': nonNegativeInt,
+    'patterns.reusable': nonNegativeInt,
+};
+const SECTIONS = ['coverage', 'quality', 'fleet', 'resources', 'context', 'patterns'];
+let libraryFlagKeys = null;
+/** Extra state keys the seeded action library / goals read or write. */
+function plannerFlagKeys() {
+    if (!libraryFlagKeys) {
+        const keys = new Set();
+        for (const action of getAllQEActions()) {
+            for (const k of Object.keys(action.preconditions))
+                keys.add(k);
+            for (const k of Object.keys(action.effects))
+                keys.add(k);
+        }
+        for (const goal of QE_GOALS) {
+            for (const k of Object.keys(goal.conditions))
+                keys.add(k);
+        }
+        libraryFlagKeys = keys;
+    }
+    return libraryFlagKeys;
+}
+/**
+ * Validate a caller-supplied world state (issue #535, codex review): known
+ * fields must match the V3WorldState schema (types, 0-100 percentages,
+ * enums); other keys are accepted only if a loaded planner action (seeded
+ * or custom), the seeded library, or the goal references them (planner
+ * flags such as `coverage.gapsIdentified`) and hold a primitive value.
+ * Returns an error message, or null when valid.
+ */
+export function validateWorldStatePatch(provided, extraAllowedKeys = []) {
+    if (typeof provided !== 'object' || provided === null || Array.isArray(provided)) {
+        return 'currentState must be an object';
+    }
+    const flags = new Set([...plannerFlagKeys(), ...extraAllowedKeys]);
+    for (const [section, patch] of Object.entries(provided)) {
+        if (!SECTIONS.includes(section)) {
+            return `currentState.${section} is not a world-state section (expected one of ${SECTIONS.join(', ')})`;
+        }
+        if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+            return `currentState.${section} must be an object`;
+        }
+        for (const [key, value] of Object.entries(patch)) {
+            const field = `${section}.${key}`;
+            const check = FIELD_CHECKS[field];
+            if (check) {
+                const expected = check(value);
+                if (expected)
+                    return `currentState.${field} must be ${expected}, got ${JSON.stringify(value)}`;
+                continue;
+            }
+            if (!flags.has(field)) {
+                return `currentState.${field} is not a known world-state field`;
+            }
+            if (typeof value !== 'boolean' &&
+                typeof value !== 'string' &&
+                !(typeof value === 'number' && Number.isFinite(value))) {
+                return `currentState.${field} must be a boolean, string or finite number, got ${JSON.stringify(value)}`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Overlay a caller-supplied (possibly partial) world state onto a detected
+ * one, section by section, marking every overridden leaf as 'caller'.
+ * Callers must run validateWorldStatePatch() first; this only merges.
+ */
+export function overlayCallerState(detected, provided) {
+    const state = detected.state;
+    const provenance = { ...detected.provenance };
+    for (const section of SECTIONS) {
+        const patch = provided[section];
+        if (typeof patch !== 'object' || patch === null || Array.isArray(patch))
+            continue;
+        for (const [key, value] of Object.entries(patch)) {
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                continue;
+            state[section][key] = Array.isArray(value) ? [...value] : value;
+            provenance[`${section}.${key}`] = 'caller';
+        }
+    }
+    return { ...detected, provenance };
+}
+/** Field paths whose values are assumptions rather than observations. */
+export function defaultedFields(provenance) {
+    return Object.entries(provenance)
+        .filter(([, source]) => source === 'default')
+        .map(([field]) => field)
+        .sort();
+}
+//# sourceMappingURL=world-state.js.map

package/dist/mcp/types.d.ts

@@ -60,9 +60,11 @@ export interface ToolResult<T = unknown> {
     metadata?: ToolResultMetadata;
 }
 /**
- * Data source tracking for audit/transparency
+ * Data source tracking for audit/transparency.
+ * 'estimated': computed from real inputs mixed with assumed/default values
+ * (the result names which ones) — never presented as fully real (#535).
  */
-export type DataSource = 'real' | 'demo' | 'fallback';
+export type DataSource = 'real' | 'demo' | 'fallback' | 'estimated';
 /**
  * Tool result metadata
  */

package/dist/planning/goap-planner.d.ts

@@ -120,9 +120,26 @@ export declare class GOAPPlanner {
      */
     private checkCondition;
     /**
-     * Calculate heuristic distance to goal (admissible)
-     */
-    private calculateHeuristic;
+     * 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.
+     */
+    private buildHeuristic;
     /**
      * Get value from nested state using dot notation
      */
@@ -133,9 +150,20 @@ export declare class GOAPPlanner {
      */
     private setStateValue;
     /**
-     * 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.
      */
     private hashState;
+    private static stableStateKey;
     /**
      * Deep clone world state.
      * PERF-008: Manual structured clone avoids JSON.parse/stringify overhead.
@@ -163,6 +191,12 @@ export declare class GOAPPlanner {
      * Get actions by category
      */
     getActionsByCategory(category: GOAPAction['category']): Promise<GOAPAction[]>;
+    /**
+     * 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(): string[];
     /**
      * Get available actions based on constraints
      */
@@ -175,6 +209,20 @@ export declare class GOAPPlanner {
      * Get plan by ID
      */
     getPlan(planId: string): Promise<GOAPPlan | null>;
+    /**
+     * List persisted plan summaries without loading every plan into memory.
+     * Count includes all rows matching the optional status, before pagination.
+     */
+    listPlanSummaries(status?: string, limit?: number): Promise<{
+        plans: Array<{
+            id: string;
+            status: string;
+            stepCount: number;
+            totalCost: number;
+            createdAt: string;
+        }>;
+        count: number;
+    }>;
     /**
      * Find a similar plan by goal conditions
      */
@@ -191,6 +239,14 @@ export declare class GOAPPlanner {
      * Validate that a plan can be executed from current state
      */
     private validatePlanForState;
+    /**
+     * 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.
+     */
+    private planSatisfiesConstraints;
     /**
      * Hash goal conditions for comparison
      */