@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/cloud/index.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * engine/cloud/index.js — Cloud dispatch provider registry.
+ *
+ * Single resolution point for everything specific to a REMOTE coding agent
+ * (Agency, GitHub Copilot cloud, ADO work-item assignment). Engine code MUST
+ * go through `resolveCloudProvider()` — never `require('./providers/<id>')`
+ * — and MUST gate behavior on `provider.capabilities.*`, never on a provider
+ * id comparison. Same discipline as the runtime registry, different contract:
+ * see the header of `contract.js` for why cloud is not a runtime.
+ *
+ * Adding a provider:
+ *   1. Implement API version 1 from contract.js.
+ *   2. `registerCloudProvider('<id>', require('./providers/<id>'));`
+ *   3. Nothing else — resolution, config gating, and the dashboard listing
+ *      pick it up from the registry.
+ *
+ * NOTE: no providers are registered yet. The registry ships empty on purpose
+ * so the surface, validation, and fail-closed gating land (and are tested)
+ * before any provider can dispatch real work anywhere.
+ */
+
+const contract = require('./contract');
+
+const registry = new Map();
+
+/**
+ * Register a cloud provider. Always strict — unlike runtimes there is no
+ * legacy adapter generation to stay compatible with, so a provider either
+ * satisfies API version 1 or does not register at all.
+ */
+function registerCloudProvider(id, provider) {
+  const normalized = contract.normalizeCloudProvider(id, provider);
+  registry.set(id, normalized);
+  return normalized;
+}
+
+/**
+ * Names of every registered provider, sorted. Used by the dashboard and by
+ * error messages so an operator sees the real option list.
+ */
+function listCloudProviders() {
+  return Array.from(registry.keys()).sort();
+}
+
+/**
+ * Look up a provider by id. Throws (never falls back to a default) so a typo
+ * or an unbuilt provider surfaces immediately at dispatch time instead of
+ * silently routing work somewhere unintended.
+ *
+ * @throws {Error} with `code: 'CLOUD_PROVIDER_UNKNOWN'`
+ */
+function resolveCloudProvider(id) {
+  const key = typeof id === 'string' ? id.trim() : '';
+  const provider = key ? registry.get(key) : null;
+  if (!provider) {
+    const known = listCloudProviders();
+    const err = new Error(
+      `Unknown cloud provider "${key || String(id)}". `
+      + (known.length
+        ? `Registered providers: ${known.join(', ')}.`
+        : `No cloud providers are registered.`)
+    );
+    err.code = 'CLOUD_PROVIDER_UNKNOWN';
+    throw err;
+  }
+  return provider;
+}
+
+/**
+ * Resolve the provider id declared for a dispatch, most specific first:
+ *   1. `item.meta.cloudProvider` — per work item
+ *   2. `project.cloudProvider`   — per project
+ *   3. `engine.cloudProvider`    — fleet default
+ * Returns null when nothing is declared (the caller then fails the dispatch
+ * with CLOUD_PROVIDER_UNAVAILABLE rather than guessing a provider).
+ */
+function resolveCloudProviderId(item, project, engine) {
+  const fromItem = item && typeof item === 'object' && item.meta && typeof item.meta === 'object'
+    ? item.meta.cloudProvider
+    : undefined;
+  const candidates = [fromItem, project?.cloudProvider, engine?.cloudProvider];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+/**
+ * Fail-closed pre-dispatch gate. Answers "can this work item actually be sent
+ * to a cloud provider right now?" without any network call.
+ *
+ * Every negative answer is STRUCTURAL — an unregistered id, no declared
+ * provider, or a provider that reports itself unconfigured for this project.
+ * Retrying reproduces it identically, which is why the caller maps this to the
+ * non-retryable FAILURE_CLASS.CLOUD_PROVIDER_UNAVAILABLE instead of burning
+ * the retry budget.
+ *
+ * A provider whose isConfigured() THROWS is treated as unavailable rather than
+ * allowed through: a provider that cannot answer the cheap question is not one
+ * we should hand a work item to.
+ *
+ * @returns {{ok: true, provider: object, id: string}
+ *          |{ok: false, reason: string, id: string|null}}
+ */
+function resolveCloudDispatchTarget({ item, project, engine, config } = {}) {
+  const id = resolveCloudProviderId(item, project, engine);
+  if (!id) {
+    return {
+      ok: false,
+      id: null,
+      reason: 'no cloud provider is declared — set `meta.cloudProvider` on the work item, '
+        + '`cloudProvider` on the project, or `engine.cloudProvider` as the fleet default',
+    };
+  }
+  let provider;
+  try {
+    provider = resolveCloudProvider(id);
+  } catch (err) {
+    return { ok: false, id, reason: err.message };
+  }
+  let configured = false;
+  try {
+    configured = provider.isConfigured({ config, project }) === true;
+  } catch (err) {
+    return {
+      ok: false,
+      id,
+      reason: `cloud provider "${id}" could not report its configuration state: ${err.message}`,
+    };
+  }
+  if (!configured) {
+    return {
+      ok: false,
+      id,
+      reason: `cloud provider "${id}" is not configured for project `
+        + `"${project?.name || '(none)'}" (missing credentials, repo binding, or disabled in config)`,
+    };
+  }
+  return { ok: true, provider, id };
+}
+
+module.exports = {
+  CLOUD_PROVIDER_API_VERSION: contract.CLOUD_PROVIDER_API_VERSION,
+  CLOUD_SESSION_STATE: contract.CLOUD_SESSION_STATE,
+  CLOUD_SESSION_STATE_VALUES: contract.CLOUD_SESSION_STATE_VALUES,
+  isTerminalCloudSessionState: contract.isTerminalCloudSessionState,
+  normalizeSessionStatus: contract.normalizeSessionStatus,
+  normalizeCreatedSession: contract.normalizeCreatedSession,
+  validateCloudProvider: contract.normalizeCloudProvider,
+  registerCloudProvider,
+  resolveCloudProvider,
+  resolveCloudProviderId,
+  resolveCloudDispatchTarget,
+  listCloudProviders,
+  // Exposed for tests — engine code MUST go through resolveCloudProvider.
+  _registry: registry,
+};

package/engine/{execution-model.js → core/execution-model.js}

@@ -71,7 +71,7 @@ function runtimeDefaultModelLabel(runtime) {
 /**
  * A model id we can show verbatim. `auto` is a request for the runtime to pick,
  * not a concrete model — mirrors buildRuntimeModelEvidence's treatment in
- * engine/queries.js.
+ * engine/core/queries.js.
  */
 function concreteExecutionModel(value) {
   const model = normalizeExecutionModel(value);

package/engine/{features.js → core/features.js}

@@ -1,5 +1,5 @@
 /**
- * engine/features.js — Feature flag registry. Recipe in CLAUDE.md → "Feature Flags".
+ * engine/core/features.js — Feature flag registry. Recipe in CLAUDE.md → "Feature Flags".
  */
 
 // Entry shape: id → { description, default: bool, addedIn?: version, expires?: ISO-date, requiredCcRuntime?: string }
@@ -45,7 +45,7 @@ const FEATURES = {
     expires: '2026-11-01',
   },
   // ccUseWorkerPool — sub-tasks B/C/D of W-mp2w003600196c51 (CC perf).
-  // Routes Command Center / doc-chat through engine/cc-worker-pool.js
+  // Routes Command Center / doc-chat through engine/agents/cc-worker-pool.js
   // (persistent `copilot --acp` per CC tab) instead of spawning a fresh CLI
   // per turn. Saves ~14 s of cold-start cost.
   //
@@ -59,7 +59,7 @@ const FEATURES = {
   // which now refuses the override when CC runtime is not copilot
   // (W-mphlriic00095f69).
   //
-  // Resolution: `shared.resolveCcUseWorkerPool(engine)` (engine/shared.js)
+  // Resolution: `shared.resolveCcUseWorkerPool(engine)` (engine/core/shared.js)
   // is the canonical predicate every dashboard.js call site uses. Explicit
   // `engine.ccUseWorkerPool` true/false in config wins ONLY when CC runtime
   // is copilot; otherwise the helper forces `false`. PR #2492 flipped the
@@ -122,7 +122,7 @@ function readEnvOverride(id) {
 
 function isFeatureOn(id, config, registry = FEATURES) {
   if (!Object.prototype.hasOwnProperty.call(registry, id)) {
-    throw new Error(`Unknown feature flag: "${id}". Register it in engine/features.js.`);
+    throw new Error(`Unknown feature flag: "${id}". Register it in engine/core/features.js.`);
   }
   const env = readEnvOverride(id);
   if (env !== undefined) return env;

package/engine/{operator-identity.js → core/operator-identity.js}

@@ -1,4 +1,4 @@
-// engine/operator-identity.js — W-mpejf0fq000e84d6
+// engine/core/operator-identity.js — W-mpejf0fq000e84d6
 //
 // Resolve the human operator's platform login for branch naming and other
 // dispatch-time identity needs. The convention is documented in CLAUDE.md