@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/cc-api-validation.js

@@ -0,0 +1,586 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const apiValidation = require('./api-validation');
+
+const CC_API_LIMITS = Object.freeze({
+  messageMaxChars: 100000,
+  documentMaxChars: 750000,
+  titleMaxChars: 512,
+  selectionMaxChars: 65536,
+  filePathMaxChars: 1024,
+  tabIdMaxChars: 96,
+  sessionIdMaxChars: 512,
+  transcriptMaxEntries: 20,
+  transcriptTextMaxChars: 65536,
+  modelMaxChars: 128,
+  projectNameMaxChars: 128,
+  watchIdMaxChars: 128,
+  metadataMaxBytes: 16384,
+  metadataMaxKeys: 32,
+  contentHashMaxChars: 64,
+  presenceUrlMaxChars: 512,
+  visibilityMaxChars: 32,
+  imageFilenameMaxChars: 255,
+  imageMaxCount: 4,
+  imageMaxDecodedBytes: 5 * 1024 * 1024,
+});
+
+const TRANSCRIPT_ROLES = Object.freeze(['user', 'assistant', 'action', 'system']);
+const TRIAGE_EFFORTS = Object.freeze(['low', 'medium', 'high']);
+const PRESENCE_VISIBILITIES = Object.freeze(['', 'visible', 'hidden', 'prerender', 'unloaded']);
+const CC_IMAGE_MIME_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+const TAB_ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const DOC_CHAT_ALLOWED_EXACT_PATHS = new Set(['notes.md', 'pinned.md', 'routing.md']);
+const DOC_CHAT_ALLOWED_PREFIXES = Object.freeze([
+  'knowledge/',
+  'meetings/',
+  'notes/',
+  'pipelines/',
+  'plans/',
+  'playbooks/',
+  'prd/',
+  'projects/',
+  'runbooks/',
+  'skills/',
+]);
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function throwConstraint(message, {
+  field,
+  path: detailPath,
+  rejectedValue,
+  expected,
+  code = 'invalid-constraint',
+  extra = {},
+} = {}) {
+  throw new apiValidation.ApiInputError(message, {
+    code,
+    field,
+    path: detailPath,
+    rejectedValue,
+    expected,
+    ...extra,
+  });
+}
+
+function validateBody(body) {
+  return apiValidation.validatePlainObject(body, {
+    field: 'body',
+    path: ['body'],
+  });
+}
+
+function validateNonBlankString(value, {
+  field,
+  path: detailPath,
+  maxLength,
+  optional = false,
+  nullable = false,
+} = {}) {
+  const validated = apiValidation.validateString(value, {
+    field,
+    path: detailPath,
+    minLength: 1,
+    maxLength,
+    optional,
+    nullable,
+  });
+  if (validated == null) return validated;
+  if (!validated.trim()) {
+    throwConstraint(`${field} must not be blank`, {
+      field,
+      path: detailPath,
+      rejectedValue: value,
+      expected: 'non-blank string',
+    });
+  }
+  return validated;
+}
+
+function validateOptionalString(value, {
+  field,
+  path: detailPath,
+  maxLength,
+  nullable = true,
+} = {}) {
+  return apiValidation.validateString(value, {
+    field,
+    path: detailPath,
+    maxLength,
+    optional: true,
+    nullable,
+  });
+}
+
+function validateMessage(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throwConstraint('message required', {
+      field: 'message',
+      path: ['body', 'message'],
+      rejectedValue: value,
+      expected: 'non-blank string',
+    });
+  }
+  return validateNonBlankString(value, {
+    field: 'message',
+    path: ['body', 'message'],
+    maxLength: CC_API_LIMITS.messageMaxChars,
+  });
+}
+
+function validateTabId(value, { required = false, path: detailPath = ['body', 'tabId'] } = {}) {
+  if (!required && (value === undefined || value === null)) return value;
+  return apiValidation.validateIdentifier(value, {
+    field: 'tabId',
+    path: detailPath,
+    maxLength: CC_API_LIMITS.tabIdMaxChars,
+    pattern: TAB_ID_PATTERN,
+  });
+}
+
+function validateSessionId(value) {
+  const sessionId = validateOptionalString(value, {
+    field: 'sessionId',
+    path: ['body', 'sessionId'],
+    maxLength: CC_API_LIMITS.sessionIdMaxChars,
+  });
+  if (sessionId != null && (!sessionId || /[\u0000-\u001f\u007f]/.test(sessionId))) {
+    throwConstraint('sessionId contains invalid characters', {
+      field: 'sessionId',
+      path: ['body', 'sessionId'],
+      rejectedValue: value,
+      expected: 'non-empty string without control characters',
+    });
+  }
+  return sessionId;
+}
+
+function validateTranscript(transcript) {
+  if (transcript === undefined || transcript === null) return transcript;
+  apiValidation.validateArray(transcript, {
+    field: 'transcript',
+    path: ['body', 'transcript'],
+    maxLength: CC_API_LIMITS.transcriptMaxEntries,
+  });
+  transcript.forEach((entry, index) => {
+    const entryPath = ['body', 'transcript', index];
+    apiValidation.validatePlainObject(entry, {
+      field: 'transcript',
+      path: entryPath,
+    });
+    apiValidation.validateEnum(entry.role, {
+      field: 'role',
+      path: [...entryPath, 'role'],
+      values: TRANSCRIPT_ROLES,
+    });
+    validateNonBlankString(entry.text, {
+      field: 'text',
+      path: [...entryPath, 'text'],
+      maxLength: CC_API_LIMITS.transcriptTextMaxChars,
+    });
+  });
+  return transcript;
+}
+
+function validateIntentMetadata(value) {
+  if (value === undefined || value === null) return value;
+  apiValidation.validatePlainObject(value, {
+    field: 'intentMetadata',
+    path: ['body', 'intentMetadata'],
+  });
+  const keys = Object.keys(value);
+  let encoded;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throwConstraint('intentMetadata must be JSON-serializable', {
+      field: 'intentMetadata',
+      path: ['body', 'intentMetadata'],
+      rejectedValue: value,
+      expected: 'JSON-serializable plain object',
+    });
+  }
+  if (keys.length > CC_API_LIMITS.metadataMaxKeys
+      || Buffer.byteLength(encoded || '', 'utf8') > CC_API_LIMITS.metadataMaxBytes) {
+    throwConstraint('intentMetadata is too large', {
+      field: 'intentMetadata',
+      path: ['body', 'intentMetadata'],
+      rejectedValue: value,
+      expected: `plain object with at most ${CC_API_LIMITS.metadataMaxKeys} keys and ${CC_API_LIMITS.metadataMaxBytes} encoded bytes`,
+      extra: { max: CC_API_LIMITS.metadataMaxBytes },
+    });
+  }
+  return value;
+}
+
+function validateProjectContext(body, projectNames) {
+  const currentProject = validateOptionalString(body.currentProject, {
+    field: 'currentProject',
+    path: ['body', 'currentProject'],
+    maxLength: CC_API_LIMITS.projectNameMaxChars,
+  });
+  const noProjectSelected = apiValidation.validateBoolean(body.noProjectSelected, {
+    field: 'noProjectSelected',
+    path: ['body', 'noProjectSelected'],
+    optional: true,
+  });
+  if (currentProject != null) {
+    const allowed = new Set(Array.isArray(projectNames) ? projectNames.filter(Boolean) : []);
+    if (!allowed.has(currentProject)) {
+      throwConstraint('currentProject is not configured', {
+        field: 'currentProject',
+        path: ['body', 'currentProject'],
+        rejectedValue: currentProject,
+        expected: 'configured project name',
+        extra: { allowedValues: [...allowed] },
+      });
+    }
+  }
+  if (currentProject && noProjectSelected === true) {
+    throwConstraint('currentProject and noProjectSelected cannot both be set', {
+      field: 'noProjectSelected',
+      path: ['body', 'noProjectSelected'],
+      rejectedValue: noProjectSelected,
+      expected: 'false or omitted when currentProject is present',
+    });
+  }
+}
+
+function validateCommandCenterRequest(body, { streaming = false, projectNames = [] } = {}) {
+  validateBody(body);
+  const reconnect = apiValidation.validateBoolean(body.reconnect, {
+    field: 'reconnect',
+    path: ['body', 'reconnect'],
+    optional: true,
+  });
+  const tabId = validateTabId(body.tabId);
+  const sessionId = validateSessionId(body.sessionId);
+
+  if (reconnect === true) {
+    if (!streaming) {
+      throwConstraint('reconnect is only supported by the streaming endpoint', {
+        field: 'reconnect',
+        path: ['body', 'reconnect'],
+        rejectedValue: reconnect,
+        expected: 'omitted for non-streaming requests',
+      });
+    }
+    if (!tabId) {
+      throwConstraint('reconnect requires tabId', {
+        field: 'reconnect',
+        path: ['body', 'reconnect'],
+        rejectedValue: reconnect,
+        expected: 'reconnect with a valid tabId',
+      });
+    }
+    const conflictingFields = [
+      'message',
+      'transcript',
+      'images',
+      'intentMetadata',
+      'currentProject',
+      'noProjectSelected',
+    ].filter(field => hasOwn(body, field) && body[field] !== undefined && body[field] !== null);
+    if (conflictingFields.length) {
+      throwConstraint('reconnect cannot include a new turn payload', {
+        field: 'reconnect',
+        path: ['body', 'reconnect'],
+        rejectedValue: reconnect,
+        expected: 'reconnect with only tabId and optional sessionId',
+      });
+    }
+    return body;
+  }
+
+  validateMessage(body.message);
+  validateTranscript(body.transcript);
+  validateIntentMetadata(body.intentMetadata);
+  validateProjectContext(body, projectNames);
+  if (sessionId && !tabId) {
+    throwConstraint('sessionId requires tabId', {
+      field: 'sessionId',
+      path: ['body', 'sessionId'],
+      rejectedValue: sessionId,
+      expected: 'sessionId paired with a valid tabId',
+    });
+  }
+  return body;
+}
+
+function validateTriageRequest(body) {
+  validateBody(body);
+  validateMessage(body.message);
+  validateOptionalString(body.watchId, {
+    field: 'watchId',
+    path: ['body', 'watchId'],
+    maxLength: CC_API_LIMITS.watchIdMaxChars,
+  });
+  apiValidation.validateEnum(body.effort, {
+    field: 'effort',
+    path: ['body', 'effort'],
+    values: TRIAGE_EFFORTS,
+    optional: true,
+  });
+  return body;
+}
+
+function validateAbortRequest(body) {
+  validateBody(body);
+  validateTabId(body.tabId);
+  return body;
+}
+
+function validateCcWarmRequest(body) {
+  validateBody(body);
+  validateTabId(body.tabId, { required: true });
+  return body;
+}
+
+function validateCcSessionPathId(id) {
+  return validateTabId(id, { required: true, path: ['path', 'id'] });
+}
+
+function realPath(targetPath) {
+  return fs.realpathSync.native ? fs.realpathSync.native(targetPath) : fs.realpathSync(targetPath);
+}
+
+function resolveRealTarget(fullPath) {
+  if (fs.existsSync(fullPath)) return realPath(fullPath);
+  let ancestor = path.dirname(fullPath);
+  while (!fs.existsSync(ancestor)) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) break;
+    ancestor = parent;
+  }
+  const realAncestor = realPath(ancestor);
+  return path.resolve(realAncestor, path.relative(ancestor, fullPath));
+}
+
+function unsafePath(filePath, message) {
+  throwConstraint(message || 'filePath is outside the allowed document sandbox', {
+    field: 'filePath',
+    path: ['body', 'filePath'],
+    rejectedValue: filePath,
+    expected: 'relative file path under the Minions directory outside protected runtime files',
+    code: 'unsafe-path',
+  });
+}
+
+function rejectSymlinkSegments(fullPath, rootPath, filePath) {
+  const root = path.resolve(rootPath);
+  let current = fullPath;
+  while (current !== root) {
+    if (fs.existsSync(current)) {
+      let stat;
+      try { stat = fs.lstatSync(current); } catch { unsafePath(filePath); }
+      if (stat.isSymbolicLink()) {
+        unsafePath(filePath, 'filePath cannot traverse symbolic links or junctions');
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) unsafePath(filePath);
+    current = parent;
+  }
+}
+
+function resolveDocChatFilePath(filePath, minionsDir) {
+  if (filePath === undefined || filePath === null) return null;
+  validateNonBlankString(filePath, {
+    field: 'filePath',
+    path: ['body', 'filePath'],
+    maxLength: CC_API_LIMITS.filePathMaxChars,
+  });
+  let fullPath;
+  try {
+    fullPath = shared.sanitizePath(filePath, minionsDir);
+  } catch {
+    unsafePath(filePath);
+  }
+  const relativePath = path.relative(path.resolve(minionsDir), fullPath).replace(/\\/g, '/');
+  if (!DOC_CHAT_ALLOWED_EXACT_PATHS.has(relativePath)
+      && !DOC_CHAT_ALLOWED_PREFIXES.some(prefix => relativePath.startsWith(prefix))) {
+    unsafePath(filePath, 'filePath is outside an allowed Minions document context');
+  }
+  rejectSymlinkSegments(fullPath, minionsDir, filePath);
+  let realRoot;
+  let realTarget;
+  try {
+    realRoot = realPath(minionsDir);
+    realTarget = resolveRealTarget(fullPath);
+  } catch {
+    unsafePath(filePath);
+  }
+  if (!shared.isPathInsideOrEqual(realTarget, realRoot)) unsafePath(filePath);
+  if (shared.isLiveCommandCenterPath(fullPath, { liveRoot: minionsDir })
+      || shared.isLiveCommandCenterPath(realTarget, { liveRoot: realRoot })) {
+    unsafePath(filePath, 'filePath targets a protected live Minions runtime file');
+  }
+  if (fs.existsSync(fullPath)) {
+    let stat;
+    try { stat = fs.statSync(fullPath); } catch { unsafePath(filePath); }
+    if (!stat.isFile()) unsafePath(filePath, 'filePath must identify a file');
+  }
+  return fullPath;
+}
+
+function contentFingerprint(value) {
+  if (!value) return '';
+  const middle = Math.floor(value.length / 2);
+  return `${value.length}:${value.charCodeAt(0)}:${value.charCodeAt(middle)}:${value.charCodeAt(value.length - 1)}`;
+}
+
+function validateContentHash(value, document) {
+  if (value === undefined || value === null) return value;
+  const contentHash = apiValidation.validateString(value, {
+    field: 'contentHash',
+    path: ['body', 'contentHash'],
+    minLength: 1,
+    maxLength: CC_API_LIMITS.contentHashMaxChars,
+  });
+  if (!/^\d+:\d+:\d+:\d+$/.test(contentHash) || contentHash !== contentFingerprint(document)) {
+    throwConstraint('contentHash does not match document', {
+      field: 'contentHash',
+      path: ['body', 'contentHash'],
+      rejectedValue: contentHash,
+      expected: 'fingerprint of body.document',
+    });
+  }
+  return contentHash;
+}
+
+function validateDocChatRequest(body, { minionsDir } = {}) {
+  validateBody(body);
+  validateMessage(body.message);
+  if (typeof body.document !== 'string' || body.document.length === 0) {
+    throwConstraint('document required', {
+      field: 'document',
+      path: ['body', 'document'],
+      rejectedValue: body.document,
+      expected: 'non-empty string',
+    });
+  }
+  const document = apiValidation.validateString(body.document, {
+    field: 'document',
+    path: ['body', 'document'],
+    minLength: 1,
+    maxLength: CC_API_LIMITS.documentMaxChars,
+  });
+  validateOptionalString(body.title, {
+    field: 'title',
+    path: ['body', 'title'],
+    maxLength: CC_API_LIMITS.titleMaxChars,
+  });
+  validateOptionalString(body.selection, {
+    field: 'selection',
+    path: ['body', 'selection'],
+    maxLength: CC_API_LIMITS.selectionMaxChars,
+  });
+  validateOptionalString(body.model, {
+    field: 'model',
+    path: ['body', 'model'],
+    maxLength: CC_API_LIMITS.modelMaxChars,
+  });
+  apiValidation.validateBoolean(body.freshSession, {
+    field: 'freshSession',
+    path: ['body', 'freshSession'],
+    optional: true,
+  });
+  validateTranscript(body.transcript);
+  validateContentHash(body.contentHash, document);
+  if (hasOwn(body, 'images') && body.images != null) {
+    throwConstraint('images are not supported by doc-chat', {
+      field: 'images',
+      path: ['body', 'images'],
+      rejectedValue: body.images,
+      expected: 'omitted',
+    });
+  }
+  return {
+    body,
+    fullPath: resolveDocChatFilePath(body.filePath, minionsDir),
+  };
+}
+
+function validateDocChatWarmRequest(body, { minionsDir } = {}) {
+  validateBody(body);
+  const title = validateOptionalString(body.title, {
+    field: 'title',
+    path: ['body', 'title'],
+    maxLength: CC_API_LIMITS.titleMaxChars,
+  });
+  // The read-only doc-chat modal sends `{ filePath: _modalFilePath || '', title }`,
+  // so an empty-string filePath means "not provided" and the `title` fallback
+  // should warm the session. Treat a blank optional filePath as absent instead
+  // of rejecting it as invalid-string.
+  const filePathInput = (typeof body.filePath === 'string' && body.filePath.trim() === '')
+    ? undefined
+    : body.filePath;
+  const fullPath = resolveDocChatFilePath(filePathInput, minionsDir);
+  if (!fullPath && !title) {
+    throwConstraint('filePath or title is required', {
+      field: 'filePath',
+      path: ['body', 'filePath'],
+      rejectedValue: body.filePath,
+      expected: 'filePath or title',
+    });
+  }
+  return { body, fullPath };
+}
+
+function validateBrowserPresenceRequest(body) {
+  validateBody(body);
+  validateTabId(body.tabId, { required: true });
+  apiValidation.validateBoolean(body.closed, {
+    field: 'closed',
+    path: ['body', 'closed'],
+    optional: true,
+  });
+  validateOptionalString(body.url, {
+    field: 'url',
+    path: ['body', 'url'],
+    maxLength: CC_API_LIMITS.presenceUrlMaxChars,
+    nullable: false,
+  });
+  apiValidation.validateEnum(body.visibility, {
+    field: 'visibility',
+    path: ['body', 'visibility'],
+    values: PRESENCE_VISIBILITIES,
+    optional: true,
+  });
+  return body;
+}
+
+function validateNoRequestBody(body) {
+  if (body === undefined) return;
+  throwConstraint('This endpoint does not accept a request body', {
+    field: 'body',
+    path: ['body'],
+    rejectedValue: body,
+    expected: 'no request body',
+  });
+}
+
+module.exports = {
+  CC_API_LIMITS,
+  TRANSCRIPT_ROLES,
+  TRIAGE_EFFORTS,
+  PRESENCE_VISIBILITIES,
+  CC_IMAGE_MIME_TYPES,
+  validateCommandCenterRequest,
+  validateTriageRequest,
+  validateAbortRequest,
+  validateCcWarmRequest,
+  validateCcSessionPathId,
+  validateDocChatRequest,
+  validateDocChatWarmRequest,
+  validateBrowserPresenceRequest,
+  validateNoRequestBody,
+  resolveDocChatFilePath,
+  contentFingerprint,
+};

package/engine/cc-worker-pool.js

@@ -286,6 +286,8 @@ async function getSession({ runtime, tabId, model, effort, mcpServers, systemPro
   return {
     sessionId: worker.sessionId,
     lifecycle,
+    runtimeName: worker.runtime.name,
+    get currentModel() { return worker.currentModel || null; },
     stream: (promptText, opts) => worker.stream(promptText, opts),
     cancel: () => worker.cancel(),
     close: () => closeTab(tabId),
@@ -328,7 +330,13 @@ async function warmTab(args = {}) {
     _warmQueue.push(async () => {
       try {
         const handle = await getSession(args);
-        resolve({ tabId: args.tabId, lifecycle: handle.lifecycle, sessionId: handle.sessionId });
+        resolve({
+          tabId: args.tabId,
+          lifecycle: handle.lifecycle,
+          sessionId: handle.sessionId,
+          runtimeName: handle.runtimeName,
+          currentModel: handle.currentModel,
+        });
       } catch (err) {
         reject(err);
       }