@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/agent-api-validation.js

@@ -0,0 +1,571 @@
+'use strict';
+
+const apiValidation = require('./api-validation');
+const steeringConstraints = require('./steering-constraints');
+const steeringStore = require('./steering-store');
+
+const AGENT_ID_MAX_LENGTH = 128;
+const DISPATCH_ID_MAX_LENGTH = 128;
+const AGENT_CHARTER_MAX_LENGTH = 256 * 1024;
+const STEERING_MESSAGE_MAX_LENGTH = 64 * 1024;
+const CANCEL_TASK_MAX_LENGTH = 512;
+const LIVE_TAIL_MAX_BYTES = 64 * 1024;
+const LIVE_RANGE_MAX_BYTES = 512 * 1024;
+const STEERING_LIST_MAX_LIMIT = 200;
+const OUTPUT_FILE_MAX_LENGTH = 512;
+
+const AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const DISPATCH_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+const STATIC_OUTPUT_FILENAMES = new Set([
+  'output.log',
+  'live-output.log',
+  'live-output-prev.log',
+]);
+const OUTPUT_FILENAMES = Object.freeze([
+  ...STATIC_OUTPUT_FILENAMES,
+  'output-<dispatch-id>.log',
+]);
+
+function inputError(message, options) {
+  throw new apiValidation.ApiInputError(message, options);
+}
+
+function validateAgentId(value, options = {}) {
+  return apiValidation.validateIdentifier(value, {
+    field: options.field || 'id',
+    path: options.path || options.field || 'id',
+    pattern: AGENT_ID_PATTERN,
+    maxLength: AGENT_ID_MAX_LENGTH,
+    code: options.code || 'invalid-agent-id',
+    trim: options.trim === true,
+  });
+}
+
+function validateDispatchId(value, options = {}) {
+  return apiValidation.validateIdentifier(value, {
+    field: options.field || 'id',
+    path: options.path || options.field || 'id',
+    pattern: DISPATCH_ID_PATTERN,
+    maxLength: DISPATCH_ID_MAX_LENGTH,
+    code: options.code || 'invalid-dispatch-id',
+  });
+}
+
+function validateSteeringId(value, options = {}) {
+  return apiValidation.validateIdentifier(value, {
+    field: options.field || 'id',
+    path: options.path || options.field || 'id',
+    pattern: steeringConstraints.STEER_ID_PATTERN,
+    maxLength: 16,
+    code: options.code || 'invalid-steering-id',
+  });
+}
+
+function knownAgentIds({ config = {}, dispatch = {}, defaultAgents = {} } = {}) {
+  const configured = config.agents && Object.keys(config.agents).length > 0
+    ? config.agents
+    : defaultAgents;
+  const ids = new Set(Object.keys(configured || {}));
+  for (const entry of Array.isArray(dispatch.active) ? dispatch.active : []) {
+    if (typeof entry?.agent === 'string'
+        && entry.agent.startsWith('temp-')
+        && AGENT_ID_PATTERN.test(entry.agent)
+        && entry.agent.length <= AGENT_ID_MAX_LENGTH) {
+      ids.add(entry.agent);
+    }
+  }
+  return ids;
+}
+
+function validateKnownAgent(value, context, options = {}) {
+  const field = options.field || 'agent';
+  const path = options.path || field;
+  const agentId = validateAgentId(value, {
+    field,
+    path,
+    trim: options.trim !== false,
+  });
+  if (!knownAgentIds(context).has(agentId)) {
+    inputError(`Unknown agent: ${agentId}`, {
+      statusCode: 404,
+      code: 'unknown-agent',
+      field,
+      path,
+      rejectedValue: agentId,
+      expected: 'configured agent or active temp agent',
+    });
+  }
+  return agentId;
+}
+
+// Read-only historical-agent set. Mutating routes (charter/steer/kill) are
+// limited to configured or active agents via knownAgentIds, but output/detail
+// reads must remain available for agents whose dispatch has already completed —
+// e.g. a temp-* agent that errored: the completed-dispatch table still offers an
+// "error details" button that reads its persisted output.log. Restricting reads
+// to the active set would 404 that historical output the moment the dispatch
+// moves active -> completed. Includes any well-formed agent id observed in the
+// completed-dispatch history so those persisted logs stay reachable.
+function readableAgentIds(context = {}) {
+  const ids = knownAgentIds(context);
+  const dispatch = context.dispatch || {};
+  for (const entry of Array.isArray(dispatch.completed) ? dispatch.completed : []) {
+    if (typeof entry?.agent === 'string'
+        && AGENT_ID_PATTERN.test(entry.agent)
+        && entry.agent.length <= AGENT_ID_MAX_LENGTH) {
+      ids.add(entry.agent);
+    }
+  }
+  return ids;
+}
+
+// Validation seam for read-only output/detail access. Accepts a safe, well-formed
+// agent identity that is configured, currently active, present in completed
+// dispatch history, OR whose output artifacts still persist on disk (context may
+// supply an `isPersistedAgent` predicate so pruned completed entries whose
+// agents/<id>/ directory survives remain readable). The agent id is always
+// shape-validated first (no traversal), so a rejected value never reaches the
+// filesystem. Mutations must keep using validateKnownAgent.
+function validateReadableAgent(value, context, options = {}) {
+  const field = options.field || 'agent';
+  const path = options.path || field;
+  const agentId = validateAgentId(value, {
+    field,
+    path,
+    trim: options.trim !== false,
+  });
+  if (readableAgentIds(context).has(agentId)) return agentId;
+  if (typeof context?.isPersistedAgent === 'function'
+      && context.isPersistedAgent(agentId) === true) {
+    return agentId;
+  }
+  inputError(`Unknown agent: ${agentId}`, {
+    statusCode: 404,
+    code: 'unknown-agent',
+    field,
+    path,
+    rejectedValue: agentId,
+    expected: 'configured, active, or historical agent with persisted output',
+  });
+}
+
+function validateCharterRequest(body, context) {
+  apiValidation.validatePlainObject(body, { field: 'body', path: 'body' });
+  const agent = validateKnownAgent(body.agent, context, {
+    field: 'agent',
+    path: 'body.agent',
+  });
+  const content = apiValidation.validateString(body.content, {
+    field: 'content',
+    path: 'body.content',
+    maxLength: AGENT_CHARTER_MAX_LENGTH,
+    code: 'invalid-charter-content',
+  });
+  return { agent, content };
+}
+
+function validateSteeringRequest(body, context) {
+  apiValidation.validatePlainObject(body, { field: 'body', path: 'body' });
+  const agent = validateKnownAgent(body.agent, context, {
+    field: 'agent',
+    path: 'body.agent',
+  });
+  const message = apiValidation.validateString(body.message, {
+    field: 'message',
+    path: 'body.message',
+    trim: true,
+    allowEmpty: false,
+    maxLength: STEERING_MESSAGE_MAX_LENGTH,
+    code: 'invalid-steering-message',
+  });
+
+  let scope = steeringConstraints.SCOPE.AGENT;
+  if (body.scope !== undefined) {
+    scope = apiValidation.validateString(body.scope, {
+      field: 'scope',
+      path: 'body.scope',
+      trim: true,
+      allowEmpty: false,
+      maxLength: 32,
+      code: 'invalid-steering-scope',
+    }).toLowerCase();
+    apiValidation.validateEnum(scope, {
+      field: 'scope',
+      path: 'body.scope',
+      values: Object.values(steeringConstraints.SCOPE),
+      code: 'invalid-steering-scope',
+    });
+  }
+
+  let supersede = '';
+  if (body.supersede !== undefined && body.supersede !== null && body.supersede !== '') {
+    supersede = apiValidation.validateString(body.supersede, {
+      field: 'supersede',
+      path: 'body.supersede',
+      trim: true,
+      allowEmpty: false,
+      maxLength: 32,
+      code: 'invalid-steering-supersede',
+    });
+    if (!steeringConstraints.isSupersedeValue(supersede)) {
+      inputError('supersede must be all, unacked, or a steering id', {
+        code: 'invalid-steering-supersede',
+        field: 'supersede',
+        path: 'body.supersede',
+        rejectedValue: supersede,
+        expected: 'all | unacked | steer-<10 hex characters>',
+      });
+    }
+  }
+
+  return { agent, message, scope, supersede };
+}
+
+function presentAliasValues(body, names) {
+  return names
+    .filter(name => Object.prototype.hasOwnProperty.call(body, name)
+      && body[name] !== undefined
+      && body[name] !== null)
+    .map(name => ({ name, value: body[name] }));
+}
+
+function conflictingAliases(entries, normalizedValues, canonicalField) {
+  if (new Set(normalizedValues).size <= 1) return;
+  const conflicting = entries[entries.length - 1];
+  inputError(`Conflicting aliases for ${canonicalField}`, {
+    code: 'conflicting-aliases',
+    field: conflicting.name,
+    path: `body.${conflicting.name}`,
+    rejectedValue: conflicting.value,
+    expected: `same value as body.${entries[0].name}`,
+  });
+}
+
+function validateCancelRequest(body) {
+  apiValidation.validatePlainObject(body, { field: 'body', path: 'body' });
+  const agentEntries = presentAliasValues(body, ['agent', 'agentId']);
+  const taskEntries = presentAliasValues(body, ['task', 'cancelTask']);
+
+  if (agentEntries.length === 0 && taskEntries.length === 0) {
+    inputError('Exactly one agent or task target is required', {
+      code: 'missing-target',
+      details: [
+        {
+          code: 'missing-target',
+          field: 'agent',
+          path: 'body.agent',
+          message: 'agent or task is required',
+          expected: 'agent identifier or task substring',
+        },
+        {
+          code: 'missing-target',
+          field: 'task',
+          path: 'body.task',
+          message: 'agent or task is required',
+          expected: 'agent identifier or task substring',
+        },
+      ],
+    });
+  }
+  if (agentEntries.length > 0 && taskEntries.length > 0) {
+    inputError('Provide exactly one agent or task target', {
+      code: 'ambiguous-target',
+      details: [
+        {
+          code: 'ambiguous-target',
+          field: 'agent',
+          path: `body.${agentEntries[0].name}`,
+          message: 'agent and task cannot both be supplied',
+          rejectedValue: agentEntries[0].value,
+          expected: 'exactly one target selector',
+        },
+        {
+          code: 'ambiguous-target',
+          field: 'task',
+          path: `body.${taskEntries[0].name}`,
+          message: 'agent and task cannot both be supplied',
+          rejectedValue: taskEntries[0].value,
+          expected: 'exactly one target selector',
+        },
+      ],
+    });
+  }
+
+  if (agentEntries.length > 0) {
+    const normalized = agentEntries.map(entry => validateAgentId(entry.value, {
+      field: entry.name,
+      path: `body.${entry.name}`,
+      trim: true,
+    }));
+    conflictingAliases(agentEntries, normalized, 'agent');
+    return { kind: 'agent', field: agentEntries[0].name, value: normalized[0] };
+  }
+
+  const normalized = taskEntries.map(entry => apiValidation.validateString(entry.value, {
+    field: entry.name,
+    path: `body.${entry.name}`,
+    trim: true,
+    allowEmpty: false,
+    maxLength: CANCEL_TASK_MAX_LENGTH,
+    code: 'invalid-task-selector',
+  }));
+  conflictingAliases(taskEntries, normalized, 'task');
+  return { kind: 'task', field: taskEntries[0].name, value: normalized[0] };
+}
+
+function resolveSingleCancelTarget(selector, activeEntries) {
+  const active = Array.isArray(activeEntries) ? activeEntries : [];
+  const matches = selector.kind === 'agent'
+    ? active.filter(entry => entry.agent === selector.value)
+    : active.filter(entry => String(entry.task || '').toLowerCase()
+      .includes(selector.value.toLowerCase()));
+  const path = `body.${selector.field}`;
+  if (matches.length === 0) {
+    inputError(`No active dispatch matches ${selector.kind} target`, {
+      statusCode: 404,
+      code: 'target-not-found',
+      field: selector.field,
+      path,
+      rejectedValue: selector.value,
+      expected: `one active dispatch matched by ${selector.kind}`,
+    });
+  }
+  if (matches.length > 1) {
+    inputError(`${selector.kind} target matches multiple active dispatches`, {
+      statusCode: 409,
+      code: 'ambiguous-target',
+      field: selector.field,
+      path,
+      rejectedValue: selector.value,
+      expected: 'selector matching exactly one active dispatch',
+    });
+  }
+  return matches[0];
+}
+
+function queryValues(params, name) {
+  const values = params.getAll(name);
+  if (values.length > 1) {
+    inputError(`${name} may be supplied only once`, {
+      code: 'invalid-query',
+      field: name,
+      path: `query.${name}`,
+      rejectedValue: values,
+      expected: 'single query parameter',
+    });
+  }
+  return values.length === 1 ? values[0] : undefined;
+}
+
+function queryInteger(params, name, options = {}) {
+  const raw = queryValues(params, name);
+  if (raw === undefined) return options.defaultValue;
+  if (!/^(?:0|[1-9]\d*)$/.test(raw)) {
+    inputError(`${name} must be a non-negative integer`, {
+      code: options.code || 'invalid-query',
+      field: name,
+      path: `query.${name}`,
+      rejectedValue: raw,
+      expected: 'non-negative integer',
+    });
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value)
+      || (Number.isFinite(options.min) && value < options.min)
+      || (Number.isFinite(options.max) && value > options.max)) {
+    inputError(`${name} is outside the allowed range`, {
+      code: options.code || 'invalid-query',
+      field: name,
+      path: `query.${name}`,
+      rejectedValue: raw,
+      expected: 'integer in range',
+      ...(Number.isFinite(options.min) ? { min: options.min } : {}),
+      ...(Number.isFinite(options.max) ? { max: options.max } : {}),
+    });
+  }
+  return value;
+}
+
+function validateLiveStreamQuery(url) {
+  const params = new URL(url, 'http://localhost').searchParams;
+  return {
+    tail: queryInteger(params, 'tail', {
+      defaultValue: LIVE_TAIL_MAX_BYTES,
+      min: 0,
+      max: LIVE_TAIL_MAX_BYTES,
+    }),
+  };
+}
+
+function validateLiveOutputQuery(url) {
+  const params = new URL(url, 'http://localhost').searchParams;
+  const rawTail = queryValues(params, 'tail');
+  const rawFrom = queryValues(params, 'from');
+  const rawTo = queryValues(params, 'to');
+  const rawPrev = queryValues(params, 'prev');
+  const hasRange = rawFrom !== undefined || rawTo !== undefined;
+
+  if (hasRange && rawTail !== undefined) {
+    inputError('tail cannot be combined with from/to', {
+      code: 'ambiguous-query',
+      field: 'tail',
+      path: 'query.tail',
+      rejectedValue: rawTail,
+      expected: 'tail mode or range mode, not both',
+    });
+  }
+  if (hasRange && (rawFrom === undefined || rawTo === undefined)) {
+    const field = rawFrom === undefined ? 'from' : 'to';
+    inputError('from and to must both be provided for a range read', {
+      code: 'missing-range-bound',
+      field,
+      path: `query.${field}`,
+      expected: 'paired from and to values',
+    });
+  }
+  if (rawPrev !== undefined && rawPrev !== '0' && rawPrev !== '1') {
+    inputError('prev must be 0 or 1', {
+      code: 'invalid-query',
+      field: 'prev',
+      path: 'query.prev',
+      rejectedValue: rawPrev,
+      allowedValues: ['0', '1'],
+    });
+  }
+  if (!hasRange && rawPrev === '1') {
+    inputError('prev=1 requires a from/to range', {
+      code: 'ambiguous-query',
+      field: 'prev',
+      path: 'query.prev',
+      rejectedValue: rawPrev,
+      expected: 'prev is only valid in range mode',
+    });
+  }
+
+  if (!hasRange) {
+    return {
+      mode: 'tail',
+      tail: queryInteger(params, 'tail', {
+        defaultValue: 8192,
+        min: 1,
+        max: LIVE_TAIL_MAX_BYTES,
+      }),
+      prev: false,
+    };
+  }
+
+  const from = queryInteger(params, 'from', { min: 0 });
+  const to = queryInteger(params, 'to', { min: 1 });
+  if (from >= to) {
+    inputError('from must be less than to', {
+      code: 'invalid-range',
+      field: 'from',
+      path: 'query.from',
+      rejectedValue: rawFrom,
+      expected: 'integer less than query.to',
+    });
+  }
+  if (to - from > LIVE_RANGE_MAX_BYTES) {
+    inputError(`range exceeds maximum of ${LIVE_RANGE_MAX_BYTES} bytes`, {
+      code: 'range-too-large',
+      field: 'to',
+      path: 'query.to',
+      rejectedValue: rawTo,
+      expected: `range no larger than ${LIVE_RANGE_MAX_BYTES} bytes`,
+      max: LIVE_RANGE_MAX_BYTES,
+    });
+  }
+  return {
+    mode: 'range',
+    from,
+    to,
+    prev: rawPrev === '1',
+  };
+}
+
+function validateSteeringListQuery(url) {
+  const params = new URL(url, 'http://localhost').searchParams;
+  const limit = queryInteger(params, 'limit', {
+    defaultValue: 50,
+    min: 1,
+    max: STEERING_LIST_MAX_LIMIT,
+  });
+  const status = queryValues(params, 'status');
+  if (status !== undefined && !steeringStore.VALID_STATUSES.has(status)) {
+    inputError('status must be a valid steering delivery status', {
+      code: 'invalid-steering-status',
+      field: 'status',
+      path: 'query.status',
+      rejectedValue: status,
+      allowedValues: [...steeringStore.VALID_STATUSES],
+    });
+  }
+  return { limit, status };
+}
+
+function validateOutputFile(value, context) {
+  const file = apiValidation.validateString(value, {
+    field: 'file',
+    path: 'query.file',
+    trim: true,
+    allowEmpty: false,
+    maxLength: OUTPUT_FILE_MAX_LENGTH,
+    code: 'invalid-output-file',
+  });
+  const parts = file.replace(/\\/g, '/').split('/');
+  const archiveMatch = /^output-(.+)\.log$/.exec(parts[2] || '');
+  const supportedFilename = STATIC_OUTPUT_FILENAMES.has(parts[2])
+    || (archiveMatch
+      && archiveMatch[1].length <= DISPATCH_ID_MAX_LENGTH
+      && DISPATCH_ID_PATTERN.test(archiveMatch[1]));
+  if (parts.length !== 3
+      || parts[0] !== 'agents'
+      || !AGENT_ID_PATTERN.test(parts[1])
+      || parts[1].length > AGENT_ID_MAX_LENGTH
+      || !supportedFilename) {
+    inputError('file must name a supported agent output file', {
+      code: 'invalid-output-file',
+      field: 'file',
+      path: 'query.file',
+      rejectedValue: file,
+      expected: 'agents/<agent-id>/<supported-output-filename>',
+      allowedValues: OUTPUT_FILENAMES,
+    });
+  }
+  if (context) {
+    validateReadableAgent(parts[1], context, {
+      field: 'file',
+      path: 'query.file',
+      trim: false,
+    });
+  }
+  return file;
+}
+
+module.exports = {
+  AGENT_ID_MAX_LENGTH,
+  DISPATCH_ID_MAX_LENGTH,
+  AGENT_CHARTER_MAX_LENGTH,
+  STEERING_MESSAGE_MAX_LENGTH,
+  CANCEL_TASK_MAX_LENGTH,
+  LIVE_TAIL_MAX_BYTES,
+  LIVE_RANGE_MAX_BYTES,
+  STEERING_LIST_MAX_LIMIT,
+  OUTPUT_FILE_MAX_LENGTH,
+  OUTPUT_FILENAMES,
+  validateAgentId,
+  validateDispatchId,
+  validateSteeringId,
+  knownAgentIds,
+  validateKnownAgent,
+  readableAgentIds,
+  validateReadableAgent,
+  validateCharterRequest,
+  validateSteeringRequest,
+  validateCancelRequest,
+  resolveSingleCancelTarget,
+  validateLiveStreamQuery,
+  validateLiveOutputQuery,
+  validateSteeringListQuery,
+  validateOutputFile,
+};

package/engine/agent-worker-pool.js

@@ -26,19 +26,20 @@
  *                                               // it died during the lease)
  *       }
  *   pool.setPoolSize(n) / getPoolSize()
+ *   pool.setEnabled(bool)            // close idle workers when disabled
  *   pool.shutdown()                  // close every worker, reject the queue
  *
  * Assignment strategy (acquireWorker), per the P-7a1c2e4f spike's findings:
  *
- *   1. A FREE worker whose MCP config, process environment, and process cwd
- *      match the request wins
- *      first — reused via a fresh `session/new` (worker.newSession), no
- *      respawn, no wasted initialize handshake.
+ *   1. A FREE worker whose MCP and process-launch context already match the
+ *      request wins first. Persisted sessions prefer their current owning
+ *      worker and continue in place; otherwise the worker uses `session/load`
+ *      or a fresh `session/new`.
  *   2. Otherwise any OTHER free worker is evicted (closed) and a replacement
  *      is spawned fresh with the requested mcpServers/cwd — MCP servers are
  *      resolved at `copilot --acp` process boot (via $COPILOT_HOME), so a
- *      changed local/stdio server set or process cwd requires a full respawn,
- *      not just a new session (spike (c)).
+ *      changed local/stdio server set, process cwd, or process-scoped ACP CLI
+ *      policy requires a full respawn, not just a new session (spike (c)).
  *   3. Otherwise, if the pool has room (fewer than `poolSize` workers
  *      allocated across free+busy+in-flight-spawn), spawn a brand new
  *      worker.