agentic-qe 3.14.4 → 3.14.6

package/dist/mcp/tools/planning/goap-plan.js

@@ -9,7 +9,16 @@
  */
 import { MCPToolBase, } from '../base.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
-import { getSharedGOAPPlanner, DEFAULT_V3_WORLD_STATE, } from '../../../planning/index.js';
+import { getSharedGOAPPlanner, validateMaxSteps, } from '../../../planning/index.js';
+import { detectWorldState, overlayCallerState, validateWorldStatePatch, defaultedFields, } from './world-state.js';
+/** Constraint keys goap_plan understands; anything else is rejected (#535). */
+const KNOWN_CONSTRAINT_KEYS = [
+    'maxCost',
+    'maxDurationMs',
+    'maxSteps',
+    'requiredAgentTypes',
+    'excludedActions',
+];
 // ============================================================================
 // Tool Implementation
 // ============================================================================
@@ -19,7 +28,13 @@ import { getSharedGOAPPlanner, DEFAULT_V3_WORLD_STATE, } from '../../../planning
  * Finds optimal action sequences to achieve QE goals using A* search.
  */
 export class GOAPPlanTool extends MCPToolBase {
+    worldStateSources;
     planner = null;
+    /** World-state sources; injectable for tests (defaults read live state). */
+    constructor(worldStateSources = {}) {
+        super();
+        this.worldStateSources = worldStateSources;
+    }
     config = {
         name: 'qe/planning/goap_plan',
         description: 'Find optimal action plan to achieve a QE goal using A* search. ' +
@@ -52,6 +67,11 @@ export class GOAPPlanTool extends MCPToolBase {
                             type: 'number',
                             description: 'Maximum total duration in milliseconds',
                         },
+                        maxSteps: {
+                            type: 'number',
+                            description: 'Maximum number of steps (actions) in the plan; positive integer',
+                            minimum: 1,
+                        },
                         requiredAgentTypes: {
                             type: 'array',
                             description: 'Only use actions that these agent types can execute',
@@ -87,12 +107,18 @@ export class GOAPPlanTool extends MCPToolBase {
     /**
      * Execute the GOAP planning
      */
-    async execute(params, context) {
+    async execute(params, _context) {
         try {
+            // Issue #535: nested constraint properties aren't covered by the base
+            // schema validation (and the MCP bridge only exposes top-level
+            // params), so validate them here instead of silently ignoring them.
+            const constraintError = this.validateConstraints(params.constraints);
+            if (constraintError) {
+                return { success: false, error: constraintError };
+            }
             const planner = await this.getPlanner();
             // Resolve goal to conditions
             let goalConditions;
-            let goalName;
             if (typeof params.goal === 'string') {
                 // Look up named goal
                 const namedGoals = await planner.getGoals();
@@ -105,20 +131,34 @@ export class GOAPPlanTool extends MCPToolBase {
                     };
                 }
                 goalConditions = found.conditions;
-                goalName = found.name;
             }
             else {
                 // Use custom goal conditions
                 goalConditions = params.goal;
-                goalName = 'custom';
             }
-            // Get current state or use default
-            const currentState = params.currentState || await this.detectCurrentState();
+            // Issue #535: start from the live/measured world state (not a static
+            // DEFAULT_V3_WORLD_STATE copy), overlaid with any caller-supplied
+            // fields, and keep track of which values are assumptions.
+            if (params.currentState !== undefined) {
+                const stateError = validateWorldStatePatch(params.currentState, [
+                    ...planner.getReferencedStateKeys(),
+                    ...Object.keys(goalConditions),
+                ]);
+                if (stateError) {
+                    return { success: false, error: `Invalid currentState: ${stateError}` };
+                }
+            }
+            const detected = params.currentState
+                ? overlayCallerState(await detectWorldState(this.worldStateSources), params.currentState)
+                : await detectWorldState(this.worldStateSources);
+            const currentState = detected.state;
+            const defaulted = defaultedFields(detected.provenance);
             // Build constraints
             const constraints = params.constraints
                 ? {
                     maxCost: params.constraints.maxCost,
                     maxDurationMs: params.constraints.maxDurationMs,
+                    maxSteps: params.constraints.maxSteps,
                     requiredAgentTypes: params.constraints.requiredAgentTypes,
                     excludedActions: params.constraints.excludedActions,
                 }
@@ -126,14 +166,23 @@ export class GOAPPlanTool extends MCPToolBase {
             // Find plan using A* search
             const plan = await planner.findPlan(currentState, goalConditions, constraints);
             if (!plan) {
+                const stepHint = constraints?.maxSteps !== undefined
+                    ? ` (maxSteps: ${constraints.maxSteps} — the goal may need more steps)`
+                    : '';
                 return {
                     success: false,
-                    error: 'No valid plan found for the given goal and constraints. ' +
+                    error: `No valid plan found for the given goal and constraints${stepHint}. ` +
                         'Try relaxing constraints or seeding more actions.',
                 };
             }
-            // Mark as real data
-            this.markAsRealData();
+            // The search is real; the start state is only 'real' if nothing in it
+            // was an assumed default.
+            if (defaulted.length === 0) {
+                this.markAsRealData();
+            }
+            else {
+                this.markAsEstimatedData();
+            }
             return {
                 success: true,
                 data: {
@@ -151,6 +200,8 @@ export class GOAPPlanTool extends MCPToolBase {
                     stepCount: plan.actions.length,
                     reusedFrom: plan.reusedFrom,
                     similarityScore: plan.similarityScore,
+                    stateProvenance: detected.provenance,
+                    defaultedFields: defaulted,
                 },
             };
         }
@@ -162,17 +213,38 @@ export class GOAPPlanTool extends MCPToolBase {
         }
     }
     /**
-     * Detect current world state
-     * In a full implementation, this would integrate with actual QE metrics
+     * Validate `constraints` (issue #535): must be an object, only known keys,
+     * numeric limits must be numbers, maxSteps a positive integer, and the
+     * list constraints string arrays.
      */
-    async detectCurrentState() {
-        // Return default state for now
-        // Real implementation would query:
-        // - Coverage metrics from coverage-analysis domain
-        // - Test results from test-execution domain
-        // - Security scores from security-compliance domain
-        // - Fleet status from coordination
-        return { ...DEFAULT_V3_WORLD_STATE };
+    validateConstraints(constraints) {
+        if (constraints === undefined || constraints === null)
+            return null;
+        if (typeof constraints !== 'object' || Array.isArray(constraints)) {
+            return 'constraints must be an object';
+        }
+        const c = constraints;
+        const unknownKeys = Object.keys(c).filter((k) => !KNOWN_CONSTRAINT_KEYS.includes(k));
+        if (unknownKeys.length > 0) {
+            return (`Unknown constraint(s): ${unknownKeys.join(', ')}. ` +
+                `Supported constraints: ${KNOWN_CONSTRAINT_KEYS.join(', ')}`);
+        }
+        for (const key of ['maxCost', 'maxDurationMs']) {
+            const v = c[key];
+            if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v) || v < 0)) {
+                return `constraints.${key} must be a non-negative number, got ${String(v)}`;
+            }
+        }
+        const stepsError = validateMaxSteps(c.maxSteps);
+        if (stepsError)
+            return stepsError;
+        for (const key of ['requiredAgentTypes', 'excludedActions']) {
+            const v = c[key];
+            if (v !== undefined && (!Array.isArray(v) || !v.every((x) => typeof x === 'string'))) {
+                return `constraints.${key} must be an array of strings`;
+            }
+        }
+        return null;
     }
 }
 //# sourceMappingURL=goap-plan.js.map

package/dist/mcp/tools/planning/goap-status.d.ts

@@ -9,6 +9,7 @@
  */
 import { MCPToolBase, MCPToolConfig, MCPToolContext } from '../base.js';
 import { ToolResult } from '../../types.js';
+import { type WorldStateProvenance, type WorldStateSources } from './world-state.js';
 /**
  * Status type to query
  */
@@ -29,28 +30,44 @@ export interface GOAPStatusParams {
     [key: string]: unknown;
 }
 /**
- * World state status result
+ * World state status result.
+ *
+ * Issue #535: values that are not observed from a live source are reported
+ * as `null` (not the planner's optimistic defaults such as securityScore
+ * 100), and `provenance` names the source of every field.
  */
 export interface WorldStateResult {
     coverage: {
-        line: number;
-        branch: number;
-        function: number;
+        line: number | null;
+        branch: number | null;
+        function: number | null;
         measured: boolean;
+        /** Coverage report the values were read from, when measured. */
+        report?: {
+            source: string;
+            measuredAt: string;
+        };
     };
     quality: {
-        testsPassing: number;
-        securityScore: number;
-        performanceScore: number;
+        testsPassing: number | null;
+        securityScore: number | null;
+        performanceScore: number | null;
     };
     fleet: {
+        /** Whether a fleet (fleet_init) is running in this MCP server process. */
+        initialized: boolean;
         activeAgents: number;
-        maxAgents: number;
+        maxAgents: number | null;
+        availableAgents: string[];
     };
     resources: {
-        timeRemaining: number;
-        parallelSlots: number;
+        timeRemaining: number | null;
+        parallelSlots: number | null;
     };
+    /** Dotted field path -> 'live' | 'measured' | 'caller' | 'default'. */
+    provenance: WorldStateProvenance;
+    /** Fields the planner would fill with DEFAULT_V3_WORLD_STATE assumptions. */
+    defaultedFields: string[];
 }
 /**
  * Goals status result
@@ -132,8 +149,11 @@ export type GOAPStatusResult = {
  * Query GOAP system status for world state, goals, actions, or plans.
  */
 export declare class GOAPStatusTool extends MCPToolBase<GOAPStatusParams, GOAPStatusResult> {
+    private readonly worldStateSources;
     private planner;
     private executor;
+    /** World-state sources; injectable for tests (defaults read live state). */
+    constructor(worldStateSources?: WorldStateSources);
     readonly config: MCPToolConfig;
     private buildSchema;
     /**
@@ -151,9 +171,14 @@ export declare class GOAPStatusTool extends MCPToolBase<GOAPStatusParams, GOAPSt
     /**
      * Execute the status query
      */
-    execute(params: GOAPStatusParams, context: MCPToolContext): Promise<ToolResult<GOAPStatusResult>>;
+    execute(params: GOAPStatusParams, _context: MCPToolContext): Promise<ToolResult<GOAPStatusResult>>;
     /**
-     * Get current world state
+     * Get current world state.
+     *
+     * Issue #535: previously returned a static DEFAULT_V3_WORLD_STATE copy
+     * (fleet.activeAgents always 0) and called markAsRealData() on it. Now
+     * reads the live fleet and any coverage report, reports unobserved values
+     * as null, and only claims 'real' when nothing was defaulted.
      */
     private getWorldState;
     /**

package/dist/mcp/tools/planning/goap-status.js

@@ -9,7 +9,8 @@
  */
 import { MCPToolBase, } from '../base.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
-import { getSharedGOAPPlanner, createMockExecutor, DEFAULT_V3_WORLD_STATE, getAllQEActions, } from '../../../planning/index.js';
+import { getSharedGOAPPlanner, createMockExecutor, getAllQEActions, } from '../../../planning/index.js';
+import { detectWorldState, defaultedFields, } from './world-state.js';
 // ============================================================================
 // Tool Implementation
 // ============================================================================
@@ -19,8 +20,14 @@ import { getSharedGOAPPlanner, createMockExecutor, DEFAULT_V3_WORLD_STATE, getAl
  * Query GOAP system status for world state, goals, actions, or plans.
  */
 export class GOAPStatusTool extends MCPToolBase {
+    worldStateSources;
     planner = null;
     executor = null;
+    /** World-state sources; injectable for tests (defaults read live state). */
+    constructor(worldStateSources = {}) {
+        super();
+        this.worldStateSources = worldStateSources;
+    }
     config = {
         name: 'qe/planning/goap_status',
         description: 'Get GOAP system status: world state, available goals, actions, or plans. ' +
@@ -93,7 +100,7 @@ export class GOAPStatusTool extends MCPToolBase {
     /**
      * Execute the status query
      */
-    async execute(params, context) {
+    async execute(params, _context) {
         try {
             switch (params.type) {
                 case 'world':
@@ -121,37 +128,60 @@ export class GOAPStatusTool extends MCPToolBase {
         }
     }
     /**
-     * Get current world state
+     * Get current world state.
+     *
+     * Issue #535: previously returned a static DEFAULT_V3_WORLD_STATE copy
+     * (fleet.activeAgents always 0) and called markAsRealData() on it. Now
+     * reads the live fleet and any coverage report, reports unobserved values
+     * as null, and only claims 'real' when nothing was defaulted.
      */
     async getWorldState() {
-        // In a full implementation, this would query actual metrics
-        // For now, return the default state with some variation
-        const state = { ...DEFAULT_V3_WORLD_STATE };
-        this.markAsRealData();
+        const detected = await detectWorldState(this.worldStateSources);
+        const { state, provenance } = detected;
+        const observed = (field) => provenance[field] !== 'default';
+        const valueIfObserved = (field, value) => observed(field) ? value : null;
+        const defaulted = defaultedFields(provenance);
+        const exposedFields = [
+            'coverage.line', 'coverage.branch', 'coverage.function',
+            'quality.testsPassing', 'quality.securityScore', 'quality.performanceScore',
+            'fleet.activeAgents', 'fleet.maxAgents',
+            'resources.timeRemaining', 'resources.parallelSlots',
+        ];
+        if (exposedFields.every(observed)) {
+            this.markAsRealData();
+        }
+        else {
+            this.markAsEstimatedData();
+        }
         return {
             success: true,
             data: {
                 type: 'world',
                 data: {
                     coverage: {
-                        line: state.coverage.line,
-                        branch: state.coverage.branch,
-                        function: state.coverage.function,
+                        line: valueIfObserved('coverage.line', state.coverage.line),
+                        branch: valueIfObserved('coverage.branch', state.coverage.branch),
+                        function: valueIfObserved('coverage.function', state.coverage.function),
                         measured: state.coverage.measured,
+                        ...(detected.coverageReport ? { report: detected.coverageReport } : {}),
                     },
                     quality: {
-                        testsPassing: state.quality.testsPassing,
-                        securityScore: state.quality.securityScore,
-                        performanceScore: state.quality.performanceScore,
+                        testsPassing: valueIfObserved('quality.testsPassing', state.quality.testsPassing),
+                        securityScore: valueIfObserved('quality.securityScore', state.quality.securityScore),
+                        performanceScore: valueIfObserved('quality.performanceScore', state.quality.performanceScore),
                     },
                     fleet: {
+                        initialized: detected.fleetInitialized,
                         activeAgents: state.fleet.activeAgents,
-                        maxAgents: state.fleet.maxAgents,
+                        maxAgents: valueIfObserved('fleet.maxAgents', state.fleet.maxAgents),
+                        availableAgents: [...state.fleet.availableAgents],
                     },
                     resources: {
-                        timeRemaining: state.resources.timeRemaining,
-                        parallelSlots: state.resources.parallelSlots,
+                        timeRemaining: valueIfObserved('resources.timeRemaining', state.resources.timeRemaining),
+                        parallelSlots: valueIfObserved('resources.parallelSlots', state.resources.parallelSlots),
                     },
+                    provenance,
+                    defaultedFields: defaulted,
                 },
             },
         };
@@ -184,7 +214,6 @@ export class GOAPStatusTool extends MCPToolBase {
      * Get available actions
      */
     async getActions(category, limit = 50) {
-        const planner = await this.getPlanner();
         // Get actions from the library
         let actions = [];
         // Get actions from the action library
@@ -224,18 +253,18 @@ export class GOAPStatusTool extends MCPToolBase {
      */
     async getPlans(status, limit = 20) {
         const planner = await this.getPlanner();
-        // Get plan reuse statistics
-        const reuseStats = await planner.getPlanReuseStats();
-        // Plans are typically stored in the database
-        // For now, return empty list with stats
+        const [{ plans, count }, reuseStats] = await Promise.all([
+            planner.listPlanSummaries(status, limit),
+            planner.getPlanReuseStats(),
+        ]);
         this.markAsRealData();
         return {
             success: true,
             data: {
                 type: 'plans',
                 data: {
-                    plans: [], // Would query from database
-                    count: 0,
+                    plans,
+                    count,
                     reuseStats: {
                         totalPlans: reuseStats.totalPlans,
                         reusedPlans: reuseStats.reusedPlans,

package/dist/mcp/tools/planning/world-state.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { type V3WorldState } from '../../../planning/index.js';
+export type WorldStateFieldSource = 'live' | 'measured' | 'caller' | 'default';
+/** Dotted world-state field path -> where its value came from. */
+export type WorldStateProvenance = Record<string, WorldStateFieldSource>;
+/** Snapshot of the in-process fleet (queen + kernel). */
+export interface FleetSnapshot {
+    /** Agents with status 'running' (same definition as queen.getHealth()). */
+    activeAgents: number;
+    /** Kernel's configured concurrent-agent cap (fleet_init maxAgents). */
+    maxAgents: number;
+    /** Distinct agent types currently idle or running. */
+    availableAgents: string[];
+}
+/** Line/branch/function coverage percentages read from a report file. */
+export interface CoverageSnapshot {
+    line: number;
+    branch: number;
+    function: number;
+    /** Report path relative to the project root, for traceability. */
+    source: string;
+    /** Report file modification time (ISO). */
+    measuredAt: string;
+}
+export interface DetectedWorldState {
+    state: V3WorldState;
+    provenance: WorldStateProvenance;
+    /** True when a fleet is initialized in this process. */
+    fleetInitialized: boolean;
+    /** Coverage report the coverage fields came from, if any. */
+    coverageReport?: {
+        source: string;
+        measuredAt: string;
+    };
+}
+/**
+ * Caller-supplied (partial) world state: any subset of each section's
+ * fields, plus planner flag keys the action library uses (e.g.
+ * `coverage.gapsIdentified`).
+ */
+export type WorldStatePatch = {
+    [S in keyof V3WorldState]?: Partial<V3WorldState[S]> & Record<string, unknown>;
+};
+export interface WorldStateSources {
+    readFleet?: () => Promise<FleetSnapshot | null>;
+    readCoverage?: () => CoverageSnapshot | null;
+}
+/**
+ * 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 declare function readLiveFleet(): Promise<FleetSnapshot | null>;
+/**
+ * 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 declare function readCoverageSummary(projectRoot?: string): CoverageSnapshot | null;
+/**
+ * Build the current world state from live/measured sources, falling back to
+ * DEFAULT_V3_WORLD_STATE per field and recording which is which.
+ */
+export declare function detectWorldState(sources?: WorldStateSources): Promise<DetectedWorldState>;
+/**
+ * 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 declare function validateWorldStatePatch(provided: unknown, extraAllowedKeys?: Iterable<string>): string | 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 declare function overlayCallerState(detected: DetectedWorldState, provided: WorldStatePatch): DetectedWorldState;
+/** Field paths whose values are assumptions rather than observations. */
+export declare function defaultedFields(provenance: WorldStateProvenance): string[];
+//# sourceMappingURL=world-state.d.ts.map