@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/api-contracts/cc-ops.js

@@ -0,0 +1,219 @@
+'use strict';
+
+const {
+  CC_API_LIMITS,
+  CC_IMAGE_MIME_TYPES,
+  TRANSCRIPT_ROLES,
+  TRIAGE_EFFORTS,
+} = require('../cc-api-validation');
+
+const transcriptField = () => ({
+  name: 'transcript',
+  type: 'array',
+  required: false,
+  maxItems: CC_API_LIMITS.transcriptMaxEntries,
+  itemType: {
+    type: 'object',
+    fields: [
+      { name: 'role', type: 'string', required: true, allowedValues: TRANSCRIPT_ROLES },
+      { name: 'text', type: 'string', required: true, maxLength: CC_API_LIMITS.transcriptTextMaxChars },
+    ],
+  },
+});
+
+const commandCenterFields = (messageRequired = false) => [
+  { name: 'message', type: 'string', required: messageRequired, maxLength: CC_API_LIMITS.messageMaxChars },
+  { name: 'tabId', type: 'string', required: false, maxLength: CC_API_LIMITS.tabIdMaxChars },
+  { name: 'sessionId', type: 'string', required: false, maxLength: CC_API_LIMITS.sessionIdMaxChars },
+  transcriptField(),
+  {
+    name: 'images',
+    type: 'array',
+    required: false,
+    maxItems: CC_API_LIMITS.imageMaxCount,
+    itemType: {
+      type: 'object',
+      fields: [
+        { name: 'mimeType', type: 'string', required: true, allowedValues: CC_IMAGE_MIME_TYPES },
+        { name: 'dataBase64', type: 'string', required: true },
+        { name: 'filename', type: 'string', required: false, maxLength: CC_API_LIMITS.imageFilenameMaxChars },
+      ],
+    },
+  },
+  { name: 'reconnect', type: 'boolean', required: false },
+  {
+    name: 'currentProject',
+    type: 'string',
+    required: false,
+    maxLength: CC_API_LIMITS.projectNameMaxChars,
+    allowedValuesSource: 'config.projects[].name',
+  },
+  { name: 'noProjectSelected', type: 'boolean', required: false },
+  { name: 'intentMetadata', type: 'object', required: false, maxBytes: CC_API_LIMITS.metadataMaxBytes },
+];
+
+const docChatFields = () => [
+  { name: 'message', type: 'string', required: true, maxLength: CC_API_LIMITS.messageMaxChars },
+  { name: 'document', type: 'string', required: true, maxLength: CC_API_LIMITS.documentMaxChars },
+  { name: 'title', type: 'string', required: false, maxLength: CC_API_LIMITS.titleMaxChars },
+  { name: 'filePath', type: 'path', required: false, maxLength: CC_API_LIMITS.filePathMaxChars },
+  { name: 'selection', type: 'string', required: false, maxLength: CC_API_LIMITS.selectionMaxChars },
+  { name: 'contentHash', type: 'string', required: false, maxLength: CC_API_LIMITS.contentHashMaxChars },
+  transcriptField(),
+  { name: 'model', type: 'string', required: false, maxLength: CC_API_LIMITS.modelMaxChars },
+  { name: 'freshSession', type: 'boolean', required: false },
+];
+
+const ccHeaders = {
+  policy: 'optional',
+  fields: [
+    { name: 'X-CC-Turn-Id', type: 'string', required: false, maxLength: 80 },
+  ],
+};
+
+const commonNegativeTests = [
+  { strategy: 'omit-required-field', expectedStatus: 400 },
+  { strategy: 'use-wrong-field-type', expectedStatus: 400 },
+  { strategy: 'exceed-field-or-array-limit', expectedStatus: 400 },
+  { strategy: 'violate-cross-field-constraint', expectedStatus: 400 },
+];
+
+const docConstraints = [
+  { kind: 'sandboxed-path', field: 'filePath', root: 'MINIONS_DIR', rejectProtectedLivePaths: true },
+  { kind: 'fingerprint-of', field: 'contentHash', sourceField: 'document' },
+  { kind: 'unsupported-field', field: 'images' },
+];
+
+module.exports = {
+  owner: 'cc-ops',
+  routes: [
+    'POST /api/doc-chat',
+    'POST /api/doc-chat/stream',
+    'POST /api/doc-chat/warm',
+    'POST /api/command-center/new-session',
+    'POST /api/command-center/abort',
+    'POST /api/command-center',
+    'POST /api/command-center/triage',
+    'POST /api/command-center/stream',
+    'GET /api/cc-sessions',
+    'POST /api/cc-sessions/warm',
+    'DELETE /api/cc-sessions/<id>',
+  ],
+  bodyless: [
+    'POST /api/command-center/new-session',
+    'DELETE /api/cc-sessions/<id>',
+  ],
+  overrides: {
+    'GET /api/cc-sessions': { noInput: true },
+    'POST /api/doc-chat': {
+      audit: 'audited',
+      body: { policy: 'required', fields: docChatFields() },
+      headers: ccHeaders,
+      constraints: docConstraints,
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/doc-chat/stream': {
+      audit: 'audited',
+      body: { policy: 'required', fields: docChatFields() },
+      headers: ccHeaders,
+      constraints: docConstraints,
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/doc-chat/warm': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'filePath', type: 'path', required: false, maxLength: CC_API_LIMITS.filePathMaxChars },
+          { name: 'title', type: 'string', required: false, maxLength: CC_API_LIMITS.titleMaxChars },
+        ],
+      },
+      constraints: [
+        { kind: 'at-least-one', fields: ['filePath', 'title'] },
+        docConstraints[0],
+      ],
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/command-center/abort': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'tabId', type: 'string', required: false, maxLength: CC_API_LIMITS.tabIdMaxChars },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'use-invalid-tab-id', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/command-center/new-session': {
+      audit: 'audited',
+      negativeTests: [
+        { strategy: 'send-unexpected-body', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/command-center': {
+      audit: 'audited',
+      body: { policy: 'required', fields: commandCenterFields(true).filter(field => field.name !== 'reconnect') },
+      headers: ccHeaders,
+      constraints: [
+        { kind: 'requires', field: 'sessionId', requiredField: 'tabId' },
+        { kind: 'mutually-exclusive', fields: ['currentProject', 'noProjectSelected:true'] },
+      ],
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/command-center/triage': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'message', type: 'string', required: true, maxLength: CC_API_LIMITS.messageMaxChars },
+          { name: 'watchId', type: 'string', required: false, maxLength: CC_API_LIMITS.watchIdMaxChars },
+          { name: 'effort', type: 'string', required: false, allowedValues: TRIAGE_EFFORTS },
+        ],
+      },
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/command-center/stream': {
+      audit: 'audited',
+      body: { policy: 'required', fields: commandCenterFields() },
+      headers: ccHeaders,
+      constraints: [
+        { kind: 'message-unless', unless: 'reconnect:true' },
+        { kind: 'requires', field: 'sessionId', requiredField: 'tabId' },
+        { kind: 'requires', field: 'reconnect:true', requiredField: 'tabId' },
+        {
+          kind: 'mutually-exclusive',
+          fields: ['reconnect:true', 'message|transcript|images|intentMetadata|currentProject|noProjectSelected'],
+        },
+        { kind: 'mutually-exclusive', fields: ['currentProject', 'noProjectSelected:true'] },
+      ],
+      negativeTests: commonNegativeTests,
+    },
+    'POST /api/cc-sessions/warm': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'tabId', type: 'string', required: true, maxLength: CC_API_LIMITS.tabIdMaxChars },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'omit-or-malform-tab-id', expectedStatus: 400 },
+      ],
+    },
+    'DELETE /api/cc-sessions/<id>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'string', required: true, maxLength: CC_API_LIMITS.tabIdMaxChars },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'use-oversized-path-id', expectedStatus: 400 },
+        { strategy: 'send-unexpected-body', expectedStatus: 400 },
+      ],
+    },
+  },
+};

package/engine/api-contracts/config-runtime.js

@@ -0,0 +1,419 @@
+'use strict';
+
+module.exports = {
+  owner: 'config-runtime',
+  routes: [
+    'GET /api/resolve-area',
+    'POST /api/projects/browse',
+    'POST /api/projects/scan',
+    'POST /api/projects/confirm-token',
+    'POST /api/projects/add',
+    'POST /api/projects/remove',
+    'GET /api/runtimes',
+    'POST /api/runtimes/<runtime>/models/refresh',
+    'GET /api/runtimes/<runtime>/models',
+    'GET /api/settings',
+    'POST /api/settings',
+    'POST /api/settings/routing',
+    'POST /api/settings/reset',
+    'GET /api/features',
+    'POST /api/features/toggle',
+    'GET /api/welcome',
+    'POST /api/welcome/ack',
+    'POST /api/diagnostics/refresh',
+    'GET /api/diagnostics/ado-throttle',
+    'GET /api/diagnostics/ado-token',
+    'GET /api/diagnostics/memory',
+    'GET /api/diagnostics/memory/history',
+    'POST /api/diagnostics/heap-snapshot',
+  ],
+  bodyless: [
+    'POST /api/projects/confirm-token',
+    'POST /api/runtimes/<runtime>/models/refresh',
+    'POST /api/settings/reset',
+    'POST /api/diagnostics/heap-snapshot',
+    'POST /api/welcome/ack',
+  ],
+  overrides: {
+    'POST /api/projects/browse': {
+      audit: 'audited',
+      body: {
+        policy: 'optional',
+        fields: [
+          { name: 'modernPicker', type: 'boolean', required: false, default: false },
+          { name: 'initialPath', type: 'path', required: false, maxLength: 4096 },
+        ],
+      },
+      constraints: [
+        {
+          kind: 'conditional-use',
+          field: 'initialPath',
+          when: { field: 'modernPicker', equals: true },
+        },
+      ],
+      negativeTests: [
+        { strategy: 'invalid-picker-flag-before-os-dialog', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/projects/scan': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'path', type: 'path', required: false, maxLength: 4096, defaultSource: 'os.homedir()' },
+          { name: 'depth', type: 'integer', required: false, default: 3, min: 1, max: 6 },
+        ],
+      },
+      constraints: [
+        { kind: 'existing-directory', field: 'path', location: 'body' },
+        { kind: 'validate-before-discovery', fields: ['path', 'depth'] },
+      ],
+      negativeTests: [
+        { strategy: 'out-of-range-depth-before-scan', expectedStatus: 400 },
+        { strategy: 'non-directory-path', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/projects/confirm-token': {
+      audit: 'audited',
+      noInputReason: 'Mints a short-lived single-use token and accepts no caller input.',
+      constraints: [
+        { kind: 'single-use-token', ttlMs: 300000, consumer: 'POST /api/projects/add' },
+      ],
+    },
+    'POST /api/projects/add': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'path', type: 'path', required: true, maxLength: 4096 },
+          { name: 'name', type: 'string', required: false, maxLength: 64, pattern: '^[A-Za-z0-9_-]+$' },
+          { name: 'allowNonRepo', type: 'boolean', required: false, default: false },
+          { name: 'confirmToken', type: 'identifier', required: false, maxLength: 36 },
+          { name: 'checkoutMode', type: 'string', required: false, allowedValuesSource: 'shared.CHECKOUT_MODES' },
+          { name: 'worktreeMode', type: 'string', required: false, allowedValuesSource: 'shared.validateCheckoutMode legacy aliases' },
+          { name: 'observeAuthors', type: 'array<string>', required: false, maxLength: 100 },
+        ],
+      },
+      aliases: [
+        { name: 'worktreeMode', canonical: 'checkoutMode' },
+      ],
+      constraints: [
+        { kind: 'existing-directory', field: 'path', location: 'body' },
+        { kind: 'conditional-requires', field: 'allowNonRepo', equals: true, requires: 'confirmToken' },
+        { kind: 'single-use-token', field: 'confirmToken', location: 'body' },
+        { kind: 'validate-before-discovery', fields: ['name', 'allowNonRepo', 'confirmToken', 'checkoutMode', 'worktreeMode', 'observeAuthors'] },
+      ],
+      negativeTests: [
+        { strategy: 'invalid-name-before-discovery', expectedStatus: 400 },
+        { strategy: 'invalid-boolean-before-discovery', expectedStatus: 400 },
+        { strategy: 'invalid-checkout-mode-before-discovery', expectedStatus: 400 },
+        { strategy: 'reused-confirmation-token', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/projects/remove': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'name', type: 'string', required: false, maxLength: 64, allowedValuesSource: 'config.projects[].name' },
+          { name: 'path', type: 'path', required: false, maxLength: 4096, allowedValuesSource: 'config.projects[].localPath' },
+          { name: 'keepData', type: 'boolean', required: false, default: false },
+          { name: 'purge', type: 'boolean', required: false, default: false },
+        ],
+      },
+      constraints: [
+        { kind: 'exactly-one-of', fields: ['name', 'path'] },
+        { kind: 'mutually-exclusive', fields: ['keepData', 'purge'], whenTruthy: true },
+        { kind: 'validate-before-project-removal', fields: ['name', 'path', 'keepData', 'purge'] },
+      ],
+      negativeTests: [
+        { strategy: 'conflicting-project-selector', expectedStatus: 400 },
+        { strategy: 'conflicting-removal-flags', expectedStatus: 400 },
+        { strategy: 'unknown-project', expectedStatus: 404 },
+      ],
+    },
+    'GET /api/runtimes': {
+      audit: 'audited',
+      noInputReason: 'Lists the canonical runtime registry and accepts no caller input.',
+    },
+    'POST /api/runtimes/<runtime>/models/refresh': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'runtime',
+            type: 'identifier',
+            required: true,
+            maxLength: 128,
+            allowedValuesSource: 'runtimes.listRuntimes()',
+          },
+        ],
+      },
+      constraints: [
+        { kind: 'decoded-before-cache-mutation', field: 'runtime', location: 'path' },
+      ],
+      negativeTests: [
+        { strategy: 'unknown-runtime-before-cache-invalidation', expectedStatus: 404 },
+        { strategy: 'encoded-path-separator', expectedStatus: 400 },
+      ],
+    },
+    'GET /api/runtimes/<runtime>/models': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'runtime',
+            type: 'identifier',
+            required: true,
+            maxLength: 128,
+            allowedValuesSource: 'runtimes.listRuntimes()',
+          },
+        ],
+      },
+      constraints: [
+        { kind: 'decoded-before-model-read', field: 'runtime', location: 'path' },
+      ],
+      negativeTests: [
+        { strategy: 'unknown-runtime', expectedStatus: 404 },
+        { strategy: 'encoded-path-separator', expectedStatus: 400 },
+      ],
+    },
+    'GET /api/features': {
+      audit: 'audited',
+      noInputReason: 'Lists the canonical feature registry and accepts no caller input.',
+    },
+    'GET /api/welcome': {
+      audit: 'audited',
+      noInputReason: 'Reads the internal-distribution welcome state from the installed package manifest and SQL small-state; accepts no caller-supplied body, path, query, or header input.',
+    },
+    'POST /api/welcome/ack': {
+      audit: 'audited',
+      noInputReason: 'Acknowledges the internal welcome popup for the current runtime installation; the installation id is server-resolved, so the request carries no caller input.',
+    },
+    'GET /api/settings': {
+      audit: 'audited',
+    },
+    'POST /api/settings': {
+      audit: 'audited',
+      body: {
+        policy: 'optional',
+        fields: [
+          {
+            name: 'engine',
+            type: 'object',
+            required: false,
+            shapeSource: 'ENGINE_DEFAULTS and settings validation rules',
+            allowedValuesSource: 'runtime registry names and capabilities',
+          },
+          {
+            name: 'claude',
+            type: 'object',
+            required: false,
+            shapeSource: 'DEFAULT_CLAUDE compatibility fields',
+          },
+          {
+            name: 'agents',
+            type: 'object',
+            required: false,
+            allowedValuesSource: 'config.agents keys',
+            shapeSource: 'agent settings and workspace manifest validators',
+          },
+          {
+            name: 'projects',
+            type: 'array',
+            required: false,
+            allowedValuesSource: 'config.projects[].name',
+            shapeSource: 'project settings validators',
+          },
+          {
+            name: 'features',
+            type: 'object',
+            required: false,
+            allowedValuesSource: 'features registry',
+          },
+        ],
+      },
+      aliases: [
+        { name: 'agents.*.skills', canonical: 'agents.*.expertise', deprecated: true },
+        { name: 'projects[].worktreeMode', canonical: 'projects[].checkoutMode', deprecated: true },
+      ],
+      constraints: [
+        {
+          kind: 'atomic-candidate',
+          description: 'The complete candidate is validated before config or in-memory state changes.',
+        },
+        {
+          kind: 'clear-sentinel',
+          values: ['', null],
+          description: 'Optional runtime, model, agent, and project overrides accept established clear sentinels.',
+        },
+        {
+          kind: 'dynamic-registry',
+          sources: ['runtime registry', 'features registry', 'configured agents', 'configured projects'],
+        },
+      ],
+      negativeTests: [
+        { strategy: 'mixed-valid-invalid-atomic-rejection', expectedStatus: 422 },
+        { strategy: 'runtime-model-discovery-unavailable', expectedStatus: 503 },
+      ],
+    },
+    'POST /api/settings/routing': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'content', type: 'string', required: true },
+        ],
+      },
+      constraints: [
+        { kind: 'atomic-text-replacement', field: 'content' },
+      ],
+      negativeTests: [
+        { strategy: 'reject-non-string-routing-content', expectedStatus: 422 },
+      ],
+    },
+    'POST /api/settings/reset': {
+      audit: 'audited',
+      noInputReason: 'Reset derives a complete candidate from ENGINE_DEFAULTS and DEFAULT_AGENTS and accepts no caller input.',
+    },
+    'GET /api/resolve-area': {
+      audit: 'audited',
+      query: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'project',
+            type: 'string',
+            required: true,
+            allowedValuesSource: 'config.projects[].name',
+          },
+          { name: 'token', type: 'string', required: true },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'omit-required-query-field', expectedStatus: 400 },
+        { strategy: 'use-unknown-project', expectedStatus: 404 },
+      ],
+    },
+    'GET /api/diagnostics/ado-throttle': {
+      audit: 'audited',
+      noInputReason: 'Snapshots the in-memory per-org ADO throttle tracker; accepts no caller-supplied body, path, query, or header input.',
+    },
+    'GET /api/diagnostics/ado-token': {
+      audit: 'audited',
+      noInputReason: 'Reads the ADO token-acquisition health snapshot; accepts no caller-supplied body, path, query, or header input.',
+    },
+    'GET /api/diagnostics/memory': {
+      audit: 'audited',
+      noInputReason: 'Reads the latest dashboard and engine memory samples; accepts no caller-supplied body, path, query, or header input.',
+    },
+    'POST /api/features/toggle': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true, maxLength: 128, allowedValuesSource: 'features.FEATURES keys' },
+          { name: 'enabled', type: 'boolean', required: true },
+        ],
+      },
+      constraints: [
+        { kind: 'validate-before-config-mutation', fields: ['id', 'enabled'] },
+      ],
+      negativeTests: [
+        { strategy: 'unknown-feature', expectedStatus: 404 },
+        { strategy: 'non-boolean-enabled', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/diagnostics/refresh': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'entries',
+            type: 'array',
+            required: true,
+            maxLength: 500,
+            items: {
+              type: 'object',
+              fields: [
+                { name: 'ts', type: 'integer', required: false, min: 0 },
+                {
+                  name: 'kind',
+                  type: 'identifier',
+                  required: false,
+                  allowedValues: ['refresh', 'visibility'],
+                },
+              ],
+            },
+          },
+        ],
+      },
+      headers: {
+        policy: 'optional',
+        fields: [
+          {
+            name: 'X-Minions-Dashboard-Tab',
+            type: 'identifier',
+            required: false,
+            maxLength: 80,
+          },
+          { name: 'X-Minions-Dashboard-Url', type: 'string', required: false, maxLength: 200 },
+          { name: 'User-Agent', type: 'string', required: false, maxLength: 200 },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'omit-entries', expectedStatus: 400 },
+        { strategy: 'send-non-array-entries', expectedStatus: 400 },
+        { strategy: 'exceed-entry-count-cap', expectedStatus: 400 },
+        { strategy: 'send-non-object-entry', expectedStatus: 400 },
+        { strategy: 'send-invalid-diagnostic-identifier', expectedStatus: 400 },
+      ],
+    },
+    'GET /api/diagnostics/memory/history': {
+      audit: 'audited',
+      query: {
+        policy: 'required',
+        fields: [
+          { name: 'process', type: 'string', required: true, allowedValues: ['engine', 'dashboard'] },
+          { name: 'limit', type: 'integer', required: false, min: 1, max: 1440 },
+        ],
+      },
+      negativeTests: [
+        { strategy: 'omit-process', expectedStatus: 400 },
+        { strategy: 'use-unknown-process', expectedStatus: 400 },
+        { strategy: 'use-non-integer-limit', expectedStatus: 400 },
+        { strategy: 'use-out-of-range-limit', expectedStatus: 400 },
+      ],
+    },
+    'POST /api/diagnostics/heap-snapshot': {
+      audit: 'audited',
+      query: {
+        policy: 'required',
+        fields: [
+          {
+            name: 'confirm',
+            type: 'string',
+            required: true,
+            allowedValues: ['YES_I_UNDERSTAND_THIS_STALLS_THE_ENGINE'],
+          },
+        ],
+      },
+      constraints: [
+        {
+          kind: 'literal-confirmation',
+          field: 'confirm',
+          location: 'query',
+        },
+      ],
+      negativeTests: [
+        { strategy: 'omit-confirmation', expectedStatus: 400 },
+        { strategy: 'use-wrong-confirmation', expectedStatus: 400 },
+        { strategy: 'send-confirmation-in-body', expectedStatus: 400 },
+        { strategy: 'send-empty-object-body', expectedStatus: 400 },
+      ],
+    },
+  },
+};