@yemi33/minions 0.1.2446 → 0.1.2447

package/dashboard.js

@@ -101,6 +101,7 @@ const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getProjectGitStatus, timeSince,
   MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, PRD_DIR } = queries;
 const apiContracts = require('./engine/api-contracts');
+const listPaging = require('./engine/api-contracts/paging');
 
 // Dev vs binary differentiation. When two dashboards run side-by-side (npm
 // install on 7331, local checkout on 7332), the favicon and title need to
@@ -3384,7 +3385,11 @@ async function _maxInputMtimeMs(inputs) {
 // cross-scope display order is post-enrichment (central + every project by
 // rowid), which per-scope SQL LIMIT/OFFSET cannot compose, and (c) slicing the
 // deterministic cached array is O(page) to serialize — the real transfer win.
-const _LIST_PAGE_MAX = 1000;
+// The bounds come from engine/api-contracts/paging.js — the SAME constants the
+// route catalog publishes on GET /api/routes, so the clamp and the advertised
+// contract can never drift (review of PR #1062).
+const _LIST_PAGE_MAX = listPaging.LIST_PAGE_MAX_LIMIT;
+const _LIST_PAGE_DEFAULT_LIMIT = listPaging.LIST_PAGE_DEFAULT_LIMIT;
 function _parsePageParams(req) {
   const params = new URL((req && req.url) || '/', 'http://localhost').searchParams;
   const hasLimit = params.has('limit');
@@ -3394,7 +3399,7 @@ function _parsePageParams(req) {
   const rawOffset = Number(params.get('offset'));
   const limit = hasLimit && Number.isFinite(rawLimit)
     ? Math.max(1, Math.min(_LIST_PAGE_MAX, Math.floor(rawLimit)))
-    : 50;
+    : _LIST_PAGE_DEFAULT_LIMIT;
   const offset = hasOffset && Number.isFinite(rawOffset) ? Math.max(0, Math.floor(rawOffset)) : 0;
   return { limit, offset };
 }
@@ -9164,14 +9169,23 @@ const server = http.createServer(async (req, res) => {
   }
 
   async function handlePlansList(req, res) {
+    let page;
     try {
-      planPrdValidation.validateNoQuery(req);
+      // Only the optional limit/offset paging params are accepted; every other
+      // query param is still rejected with the canonical 400, and the error
+      // blames the REJECTED param rather than the accepted paging one
+      // (W-ms3ovk83000rb60f). _parsePageParams returns null on the legacy
+      // no-param path so the response stays byte-identical to legacy then.
+      planPrdValidation.validateNoQuery(req, { allow: listPaging.LIST_PAGING_PARAMS });
+      page = _parsePageParams(req);
     } catch (e) {
       return apiErrorReply(res, e, req);
     }
     const now = Date.now();
     if (_plansCache && (now - _plansCacheTs) < PLANS_CACHE_TTL_MS) {
-      return jsonReply(res, 200, _plansCache);
+      // Keep caching the full array and slice per-request AFTER the cache read
+      // so paging never corrupts the cache and `total` reflects the full set.
+      return jsonReply(res, 200, page ? _paginateList(_plansCache, page) : _plansCache);
     }
     const fsp = fs.promises;
     // W-mrffmjaf002f08f0 — PRD JSON is SQL-authoritative (engine/prd-store.js);
@@ -9325,7 +9339,7 @@ const server = http.createServer(async (req, res) => {
     plans.sort((a, b) => (b.generatedAt || '').localeCompare(a.generatedAt || ''));
     _plansCache = plans;
     _plansCacheTs = Date.now();
-    return jsonReply(res, 200, plans);
+    return jsonReply(res, 200, page ? _paginateList(plans, page) : plans);
   }
 
   async function handlePlansArchiveRead(req, res, match) {
@@ -12551,7 +12565,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   // ── Watches API Handlers ─────────────────────────────────────────────────
 
   async function handleWatchesList(req, res) {
-    return jsonReply(res, 200, { watches: watchesMod.getWatches() });
+    const all = watchesMod.getWatches();
+    // Optional progressive-load paging (W-ms3ovk83000rb60f). With no paging
+    // params the response is byte-identical to the legacy `{ watches: [...] }`
+    // shape; when a param is present we slice the SAME array and keep the
+    // `watches` key (mapped from _paginateList's `items`) so existing consumers
+    // keep working, adding total/hasMore/offset/limit alongside it.
+    const page = _parsePageParams(req);
+    if (!page) return jsonReply(res, 200, { watches: all });
+    const { items, total, offset, limit, hasMore } = _paginateList(all, page);
+    return jsonReply(res, 200, { watches: items, total, hasMore, offset, limit });
   }
 
   async function handleWatchesTargetTypes(req, res) {
@@ -14829,10 +14852,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
       });
     }},
-    { method: 'GET', path: '/api/schedules', desc: 'Schedule definitions merged with SQL schedule-run state (_lastRun/_lastResult/_lastCompletedAt)', handler: (req, res) => {
+    { method: 'GET', path: '/api/schedules', desc: 'Schedule definitions merged with SQL schedule-run state (_lastRun/_lastResult/_lastCompletedAt). Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: (req, res) => {
+      const page = _parsePageParams(req);
       return serveFreshJson(req, res, {
         tag: 'schedules',
         inputs: [CONFIG_PATH],
+        variant: page ? ('p' + page.offset + '.' + page.limit) : '',
+        transform: page ? (list) => _paginateList(list, page) : null,
         builder: () => {
           // Read config.json directly via queries.getConfig() rather than
           // calling reloadConfig() — the latter cascades into
@@ -14857,12 +14883,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
       });
     }},
-    { method: 'GET', path: '/api/pipelines', desc: 'Pipeline definitions merged with last-5 SQL-backed runs', handler: (req, res) => {
+    { method: 'GET', path: '/api/pipelines', desc: 'Pipeline definitions merged with last-5 SQL-backed runs. Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: (req, res) => {
+      const page = _parsePageParams(req);
       return serveFreshJson(req, res, {
         tag: 'pipelines',
         inputs: [
           path.join(MINIONS_DIR, 'pipelines'),
         ],
+        variant: page ? ('p' + page.offset + '.' + page.limit) : '',
+        transform: page ? (list) => _paginateList(list, page) : null,
         builder: () => {
           try {
             const pl = require('./engine/pipeline');
@@ -15100,7 +15129,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Plans
     { method: 'POST', path: '/api/plan', desc: 'Create a plan work item that chains to PRD on completion', params: `title, description?, ${WORK_ITEM_PRIORITY_PARAM_HINT}, project? (string OR array for cross-repo plans), agent?, branch_strategy? or branchStrategy?`, handler: handlePlanCreate },
-    { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs)', handler: handlePlansList },
+    { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs). Optional ?limit=&offset= returns a { items, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the full array is byte-identical to legacy.', handler: handlePlansList },
     { method: 'POST', path: '/api/plans/trigger-verify', desc: 'Manually trigger verification for a completed plan', params: 'file', handler: handlePlansTriggerVerify },
     { method: 'POST', path: '/api/plans/approve', desc: 'Approve a plan for execution', params: 'file, approvedBy?, forceRegen?, skipRegen?', handler: handlePlansApprove },
     { method: 'POST', path: '/api/plans/pause', desc: 'Pause a plan (stops materialization + resets active items)', params: 'file', handler: handlePlansPause },
@@ -15996,7 +16025,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/schedules/run-now', desc: 'Manually enqueue the work item for a schedule', params: 'id', handler: handleSchedulesRunNow },
 
     // Watches
-    { method: 'GET', path: '/api/watches', desc: 'List all watches', handler: handleWatchesList },
+    { method: 'GET', path: '/api/watches', desc: 'List all watches. Optional ?limit=&offset= returns a wrapped { watches, total, hasMore, offset, limit } page (progressive load, W-ms3bbzry000i6612); with no paging params the response is byte-identical to legacy { watches: [...] }.', handler: handleWatchesList },
     { method: 'GET', path: '/api/watches/target-types', desc: 'List registered watch target types and their valid conditions', handler: handleWatchesTargetTypes },
     { method: 'GET', path: '/api/watches/action-types', desc: 'List registered follow-up action types (notify, dispatch-work-item, webhook, ...)', handler: handleWatchesActionTypes },
     { method: 'GET', path: /^\/api\/watches\/([\w-]+)\/history$/, template: '/api/watches/:id/history', desc: 'Read the persisted evaluation history (last 25 checks) for a watch', handler: handleWatchHistory },

package/engine/api-contracts/orchestration.js

@@ -4,6 +4,23 @@ const keepProcesses = require('../keep-process-sweep');
 const managedSpawn = require('../managed-spawn');
 const managedSpecNameMax = managedSpawn.validateManagedSpecName('x').maxLength;
 const agentApiValidation = require('../agent-api-validation');
+const paging = require('./paging');
+
+// The optional progressive-load paging window is the ONLY caller-supplied input
+// these list endpoints read; unknown params are ignored (not rejected) because
+// they never reach a validator.
+function pagedListContract() {
+  return {
+    audit: 'audited',
+    query: paging.listPagingQuery(
+      'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+    ),
+    constraints: [
+      ...paging.listPagingClampConstraints(),
+      { kind: 'ignores-unknown-query-params', location: 'query' },
+    ],
+  };
+}
 
 function absentOrEmptyOperatorBody() {
   return {
@@ -74,9 +91,12 @@ module.exports = {
   ],
   overrides: {
     'GET /api/keep-processes': { noInput: true },
-    'GET /api/schedules': { noInput: true },
-    'GET /api/pipelines': { noInput: true },
-    'GET /api/watches': { noInput: true },
+    // These three consume the optional ?limit=&offset= paging window
+    // (W-ms3ovk83000rb60f) — they are NOT input-less, so the catalog must publish
+    // the real parameters instead of certifying them noInput.
+    'GET /api/schedules': pagedListContract(),
+    'GET /api/pipelines': pagedListContract(),
+    'GET /api/watches': pagedListContract(),
     'GET /api/watches/target-types': { noInput: true },
     'GET /api/watches/action-types': { noInput: true },
     'GET /api/watches/<id>/history': {

package/engine/api-contracts/paging.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Single source of truth for the OPTIONAL progressive-load paging query surface
+// (`?limit=&offset=`) shared by the large list endpoints.
+//
+// dashboard.js's `_parsePageParams` clamps incoming values with these bounds and
+// the api-contract owner modules publish the same bounds on `GET /api/routes`,
+// so the runtime behavior and the advertised contract cannot drift. Adding
+// paging to another list endpoint means declaring `listPagingQuery()` on its
+// contract — otherwise the route keeps certifying itself input-less while
+// silently consuming caller input (review of PR #1062).
+
+const LIST_PAGE_MAX_LIMIT = 1000;
+const LIST_PAGE_DEFAULT_LIMIT = 50;
+const LIST_PAGING_PARAMS = Object.freeze(['limit', 'offset']);
+
+function listPagingQueryFields() {
+  return [
+    {
+      name: 'limit',
+      type: 'integer',
+      required: false,
+      min: 1,
+      max: LIST_PAGE_MAX_LIMIT,
+      default: LIST_PAGE_DEFAULT_LIMIT,
+    },
+    {
+      name: 'offset',
+      type: 'integer',
+      required: false,
+      min: 0,
+      default: 0,
+    },
+  ];
+}
+
+// `rationale` documents the per-route behavior for the params this contract does
+// NOT list (rejected on /api/plans, ignored on the serveFreshJson endpoints).
+function listPagingQuery(rationale) {
+  const query = { policy: 'optional', fields: listPagingQueryFields() };
+  if (rationale) query.rationale = String(rationale);
+  return query;
+}
+
+// Out-of-range/non-numeric paging values are clamped to the published bounds
+// rather than rejected, so the clamp is part of the contract, not a 400 path.
+function listPagingClampConstraints() {
+  return [
+    {
+      kind: 'clamped-limit',
+      field: 'limit',
+      location: 'query',
+      min: 1,
+      max: LIST_PAGE_MAX_LIMIT,
+      default: LIST_PAGE_DEFAULT_LIMIT,
+    },
+    {
+      kind: 'clamped-offset',
+      field: 'offset',
+      location: 'query',
+      min: 0,
+      default: 0,
+    },
+  ];
+}
+
+module.exports = {
+  LIST_PAGE_MAX_LIMIT,
+  LIST_PAGE_DEFAULT_LIMIT,
+  LIST_PAGING_PARAMS,
+  listPagingQueryFields,
+  listPagingQuery,
+  listPagingClampConstraints,
+};

package/engine/api-contracts/pull-requests.js

@@ -3,6 +3,7 @@
 const { PR_ACTIONS } = require('../pr-action');
 const { EXECUTION_TARGET_IDS } = require('../pr-fix-target');
 const { PR_FIX_CAUSE } = require('../shared');
+const paging = require('./paging');
 
 const PR_REFERENCE_FORMATS = Object.freeze([
   'GitHub PR URL',
@@ -52,6 +53,15 @@ module.exports = {
   overrides: {
     'GET /api/pull-requests': {
       audit: 'audited',
+      // Consumes the optional ?limit=&offset= paging window (W-ms3bbzry000i6612),
+      // clamped rather than rejected — declared so the catalog publishes it.
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        { kind: 'ignores-unknown-query-params', location: 'query' },
+      ],
     },
     'GET /api/prs/<id>': {
       audit: 'audited',

package/engine/api-contracts/work-plan-prd.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const paging = require('./paging');
+
 const AUDITED_NEGATIVE_TESTS = Object.freeze([{
   strategy: 'isolated-http-invalid-input-state-snapshot',
   expectedStatus: '400-or-409',
@@ -57,7 +59,24 @@ module.exports = {
       query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
     },
     'GET /api/plans': {
-      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+      audit: 'audited',
+      // Accepts the optional ?limit=&offset= paging window (W-ms3ovk83000rb60f);
+      // every OTHER query parameter is still rejected with the canonical 400 via
+      // planPrdValidation.validateNoQuery(req, { allow: LIST_PAGING_PARAMS }).
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is rejected (planPrdValidation.validateNoQuery).',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        {
+          kind: 'reject-unknown-query-params',
+          location: 'query',
+          allowed: [...paging.LIST_PAGING_PARAMS],
+        },
+      ],
+      negativeTests: [
+        { strategy: 'reject-unknown-query-param-blaming-the-rejected-name', expectedStatus: 400 },
+      ],
     },
     'POST /api/work-items': {
       audit: 'audited',
@@ -248,10 +267,18 @@ module.exports = {
       },
     },
     'GET /api/work-items': {
-      // Polled list endpoint: reads no query/body — returns the full slimmed
-      // work-item collection. Affirmed input-less so it is audited rather than
-      // defaulting to pending-audit by omission (review PR #966).
-      noInput: true,
+      // Polled list endpoint. Reads no body/headers; the only caller-supplied
+      // input is the optional ?limit=&offset= paging window (W-ms3bbzry000i6612),
+      // which is clamped rather than rejected. Declared explicitly so the catalog
+      // publishes the real parameters instead of certifying the route input-less.
+      audit: 'audited',
+      query: paging.listPagingQuery(
+        'Optional progressive-load paging window; any other query parameter is ignored, not rejected.',
+      ),
+      constraints: [
+        ...paging.listPagingClampConstraints(),
+        { kind: 'ignores-unknown-query-params', location: 'query' },
+      ],
     },
     'GET /api/work-items/archive': {
       // Archived-item listing: reads no query/body. Affirmed input-less.

package/engine/plan-prd-validation.js

@@ -65,11 +65,20 @@ function validateBody(body) {
   });
 }
 
-function validateNoQuery(req) {
+// Reject caller-supplied query params. `options.allow` lists the params the
+// endpoint genuinely accepts (e.g. the optional `limit`/`offset` paging window);
+// those are filtered out BEFORE the offending name is chosen, so the message and
+// the machine-readable `field`/`path` always blame a rejected param rather than
+// an accepted one (review of PR #1062).
+function validateNoQuery(req, options = {}) {
+  const allowed = new Set(Array.isArray(options.allow) ? options.allow : []);
   const parsed = new URL(req?.url || '/', 'http://localhost');
-  const names = [...new Set(parsed.searchParams.keys())];
+  const names = [...new Set(parsed.searchParams.keys())].filter(name => !allowed.has(name));
   if (names.length > 0) {
-    inputError(`This endpoint does not accept query parameters: ${names.join(', ')}`, {
+    const message = allowed.size > 0
+      ? `This endpoint only accepts the query parameters ${[...allowed].join(', ')}: ${names.join(', ')}`
+      : `This endpoint does not accept query parameters: ${names.join(', ')}`;
+    inputError(message, {
       code: 'unexpected-query',
       field: names[0],
       path: `query.${names[0]}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2446",
+  "version": "0.1.2447",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"