@ran-sh/dsh-crew 0.5.5 → 0.5.7

package/src/local-request-guard.mjs

@@ -0,0 +1,60 @@
+// Shared local-request trust primitives for the two loopback surfaces:
+// the isolated 3210 hub API (src/hub/index.mjs) and the 3080→3210
+// official-web bridge (src/official-web-bridge.mjs). One implementation keeps
+// the two guards from drifting apart again.
+//
+// Trust model (see docs/ui-surfaces.md): both surfaces are loopback-only and
+// have no bearer token by design — every process running as the local user is
+// inside the trust boundary. The guards exist to keep off-machine browsers,
+// DNS-rebinding pages, and cross-machine proxies out, not to authenticate
+// local users. `localRequestCore` proves the peer is this machine (loopback
+// socket, local Host header, browser fetch-metadata pass); each surface then
+// layers its own Origin policy on top — the hub accepts any loopback origin
+// because the 3080 panel calls it cross-port, while the bridge requires an
+// exact authority match because it only serves its own same-origin client.
+
+function isIpv4Loopback(a) { return /^127(\.\d{1,3}){3}$/.test(a); }
+
+export function isLoopbackAddress(address) {
+  if (!address) return false;
+  const n = address.toLowerCase().split('%', 1)[0];
+  if (n === '::1' || isIpv4Loopback(n)) return true;
+  if (!n.startsWith('::ffff:')) return false;
+  return isIpv4Loopback(n.slice(7));
+}
+
+export function isLocalHostname(hostname) {
+  return hostname === 'localhost' || hostname === '::1' || hostname === '[::1]' || isIpv4Loopback(hostname);
+}
+
+/**
+ * Core of both guards: loopback peer, loopback Host header, and (when the
+ * client is a browser) a same-origin/none fetch-metadata request. Returns
+ * false for anything that cannot be proven local.
+ */
+export function localRequestCore(req) {
+  if (!isLoopbackAddress(req?.socket?.remoteAddress)) return false;
+  const host = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
+  if (!host) return false;
+  let authority;
+  try { authority = new URL(`http://${host}`); } catch { return false; }
+  if (!isLocalHostname(authority.hostname.toLowerCase())) return false;
+  const fetchSite = String(req?.headers?.['sec-fetch-site'] ?? '').toLowerCase();
+  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false;
+  return true;
+}
+
+/** Hub Origin policy: an Origin, when present, must name a loopback host. */
+export function originLoopback(originHeader) {
+  if (typeof originHeader !== 'string') return false;
+  let parsed;
+  try { parsed = new URL(originHeader); } catch { return false; }
+  return isLocalHostname(parsed.hostname.toLowerCase());
+}
+
+/** Bridge Origin policy: the Origin authority must equal the request authority. */
+export function originAuthorityMatches(originHeader, host) {
+  if (!originLoopback(originHeader)) return false;
+  const parsed = new URL(originHeader);
+  return parsed.host.toLowerCase() === String(host).trim().toLowerCase();
+}

package/src/mcp-runtime.mjs

@@ -69,8 +69,9 @@ export function attemptFromView(view, spec) {
     modelClassHint: spec.model_class_hint ?? null,
     strategy: source ?? 'transport-selection',
     candidateSet: logicalAttempt > 0 ? 'escalation' : 'primary',
-    provider: view?.provider ?? null,
-    model: view?.model ?? null,
+    provider: view?.provider ?? null,
+    model: view?.model ?? null,
+    execution_context: view?.execution_context ?? null,
     source: source ?? 'transport-selection',
     escalationReason: spec.escalation_reason ?? null,
   });
@@ -86,9 +87,10 @@ export function attemptFromView(view, spec) {
     // `view.attempt` may be an adapter routing-attempt (see below); the
     // workflow's logical attempt number is always the spec value.
     attempt: logicalAttempt,
-    provider: view?.provider ?? null,
-    model: view?.model ?? null,
-    selection_source: source,
+    provider: view?.provider ?? null,
+    model: view?.model ?? null,
+    execution_context: view?.execution_context ?? null,
+    selection_source: source,
     selection_trace: selectionTrace,
     status: view?.status ?? 'failed',
     result: view?.result ?? null,

package/src/model-routing.mjs

@@ -26,13 +26,36 @@ export const MODEL_SELECTION_REASON_CODES = Object.freeze({
   PROVIDER_UNAVAILABLE: 'PROVIDER_UNAVAILABLE',
   PREFERRED_MODEL_UNAVAILABLE: 'PREFERRED_MODEL_UNAVAILABLE',
   PREFERRED_MODEL_AMBIGUOUS: 'PREFERRED_MODEL_AMBIGUOUS',
-  ADAPTIVE_DEPRIORITIZED: 'ADAPTIVE_DEPRIORITIZED',
-  HARNESS_DEFAULT_INVALID: 'HARNESS_DEFAULT_INVALID',
+  ADAPTIVE_DEPRIORITIZED: 'ADAPTIVE_DEPRIORITIZED',
+  PROVIDER_TOMBSTONED: 'PROVIDER_TOMBSTONED',
+  CREDENTIAL_MISSING: 'CREDENTIAL_MISSING',
+  QUOTA_EXHAUSTED: 'QUOTA_EXHAUSTED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  PROBE_TIMEOUT: 'PROBE_TIMEOUT',
+  PROVIDER_INTERNAL_ERROR: 'PROVIDER_INTERNAL_ERROR',
+  HARNESS_DEFAULT_INVALID: 'HARNESS_DEFAULT_INVALID',
   HARNESS_DEFAULT_PROVIDER_UNAVAILABLE: 'HARNESS_DEFAULT_PROVIDER_UNAVAILABLE',
   PRIMARY_CANDIDATES_EXHAUSTED: 'PRIMARY_CANDIDATES_EXHAUSTED',
   ESCALATION_CANDIDATES_EXHAUSTED: 'ESCALATION_CANDIDATES_EXHAUSTED',
-  NO_AVAILABLE_MODEL: 'NO_AVAILABLE_MODEL',
-});
+  NO_AVAILABLE_MODEL: 'NO_AVAILABLE_MODEL',
+});
+
+const HEALTH_BLOCK_REASONS = Object.freeze({
+  'credential-missing': MODEL_SELECTION_REASON_CODES.CREDENTIAL_MISSING,
+  'quota-exhausted': MODEL_SELECTION_REASON_CODES.QUOTA_EXHAUSTED,
+  'rate-limited': MODEL_SELECTION_REASON_CODES.RATE_LIMITED,
+  timeout: MODEL_SELECTION_REASON_CODES.PROBE_TIMEOUT,
+  'internal-error': MODEL_SELECTION_REASON_CODES.PROVIDER_INTERNAL_ERROR,
+});
+
+const BLOCKED_MODEL_CODES = Object.freeze({
+  [MODEL_SELECTION_REASON_CODES.CREDENTIAL_MISSING]: 'MODEL_BLOCKED_CREDENTIAL',
+  [MODEL_SELECTION_REASON_CODES.QUOTA_EXHAUSTED]: 'MODEL_BLOCKED_QUOTA',
+  [MODEL_SELECTION_REASON_CODES.RATE_LIMITED]: 'MODEL_BLOCKED_RATE_LIMIT',
+  [MODEL_SELECTION_REASON_CODES.PROBE_TIMEOUT]: 'MODEL_BLOCKED_TIMEOUT',
+  [MODEL_SELECTION_REASON_CODES.PROVIDER_INTERNAL_ERROR]: 'MODEL_BLOCKED_PROVIDER',
+  [MODEL_SELECTION_REASON_CODES.PROVIDER_TOMBSTONED]: 'MODEL_BLOCKED_TOMBSTONED',
+});
 
 export function normalizeModelRef(raw) {
   if (!raw || typeof raw !== 'object') return null;
@@ -101,7 +124,7 @@ function traceBase({
   };
 }
 
-function candidateDecision(ref, source, status, { reasonCode, advertised } = {}) {
+function candidateDecision(ref, source, status, { reasonCode, advertised } = {}) {
   return {
     provider: ref?.provider ?? null,
     model: ref?.model ?? null,
@@ -110,7 +133,25 @@ function candidateDecision(ref, source, status, { reasonCode, advertised } = {})
     ...(reasonCode ? { reason_code: reasonCode } : {}),
     ...(advertised === false ? { advertised: false } : {}),
   };
-}
+}
+
+function healthAdmissionReason(ref, { healthStore, healthGate, tombstones } = {}) {
+  if (tombstones?.[ref?.provider] === 'absent') return MODEL_SELECTION_REASON_CODES.PROVIDER_TOMBSTONED;
+  if (healthGate !== 'hard-failures' || typeof healthStore?.get !== 'function') return null;
+  const observation = healthStore.get(ref?.provider, ref?.model);
+  if (observation?.fresh !== true) return null;
+  return HEALTH_BLOCK_REASONS[observation.state] ?? null;
+}
+
+function blockedSelection(trace, ref, source, reasonCode) {
+  trace.fallback_reason = reasonCode;
+  return {
+    ok: false,
+    code: BLOCKED_MODEL_CODES[reasonCode] ?? 'MODEL_BLOCKED_PROVIDER',
+    message: `Model ${ref?.provider ?? 'unknown'}/${ref?.model ?? 'unknown'} is blocked by ${reasonCode}.`,
+    selection_trace: trace,
+  };
+}
 
 function selectTrace(trace, ref, source, { advertised, fallbackReason } = {}) {
   trace.ordered_candidates.push(candidateDecision(ref, source, 'selected', { advertised }));
@@ -198,7 +239,7 @@ export function enrichSelectionTrace(trace, {
   return base;
 }
 
-export function resolveWorkerModel({
+export function resolveWorkerModel({
   tier,
   priority,
   priorityConfigured = false,
@@ -207,9 +248,13 @@ export function resolveWorkerModel({
   fallback = 'harness-default',
   preferredModelId = DEFAULT_TIER_MODEL_PREFERENCES[tier],
   traceContext = {},
-  adaptive,
-  adaptiveHealth,
-} = {}) {
+  adaptive,
+  adaptiveHealth,
+  healthStore,
+  healthGate,
+  allowFallback = true,
+  tombstones,
+} = {}) {
   const providers = providerMap(catalog);
   const normalizedPriority = normalizeModelPriority(priority);
   const prioritySource = typeof traceContext.prioritySource === 'string' && traceContext.prioritySource
@@ -230,17 +275,25 @@ export function resolveWorkerModel({
     rankForTrace(trace, normalizedPriority, { adaptive, adaptiveHealth, explicitPriority: true });
   }
 
-  for (let index = 0; index < normalizedPriority.length; index++) {
-    const ref = normalizedPriority[index];
-    const provider = providers.get(ref.provider);
+  for (let index = 0; index < normalizedPriority.length; index++) {
+    const ref = normalizedPriority[index];
+    const provider = providers.get(ref.provider);
     if (!provider) {
       trace.ordered_candidates.push(candidateDecision(ref, prioritySource, 'skipped', {
         reasonCode: MODEL_SELECTION_REASON_CODES.PROVIDER_UNAVAILABLE,
-      }));
-      continue;
-    }
-    const advertised = (provider.models ?? []).some((model) => model?.id === ref.model);
-    selectTrace(trace, ref, prioritySource, { advertised });
+      }));
+      continue;
+    }
+    const advertised = (provider.models ?? []).some((model) => model?.id === ref.model);
+    const healthReason = healthAdmissionReason(ref, { healthStore, healthGate, tombstones });
+    if (healthReason) {
+      trace.ordered_candidates.push(candidateDecision(ref, prioritySource, 'skipped', {
+        reasonCode: healthReason, advertised,
+      }));
+      if (allowFallback === false) return blockedSelection(trace, ref, prioritySource, healthReason);
+      continue;
+    }
+    selectTrace(trace, ref, prioritySource, { advertised });
     return {
       ok: true,
       ...ref,
@@ -259,24 +312,47 @@ export function resolveWorkerModel({
       if ((provider.models ?? []).some((model) => model?.id === preferredModelId)) {
         matches.push({ provider: provider.id, model: preferredModelId });
       }
-    }
-    if (matches.length === 1) {
-      rankForTrace(trace, matches, { adaptive, adaptiveHealth });
-      selectTrace(trace, matches[0], 'preferred-default');
-      return { ok: true, ...matches[0], source: 'preferred-default', selection_trace: trace };
-    }
-    if (matches.length > 1) {
-      const preferredProvider = normalizeModelRef(harnessDefault)?.provider;
-      const deterministicMatch = matches.find((candidate) => candidate.provider === preferredProvider) ?? null;
-      const baseline = deterministicMatch
-        ? [deterministicMatch, ...matches.filter((candidate) => candidate.provider !== deterministicMatch.provider)]
-        : matches;
-      const ranked = rankForTrace(trace, baseline, { adaptive, adaptiveHealth });
-      const adaptiveChoice = ranked.trace.decision_supported ? ranked.candidates[0] : null;
-      const match = adaptiveChoice ?? deterministicMatch;
-      if (match) {
-        const decisionOrder = adaptiveChoice ? ranked.candidates : matches;
-        for (const candidate of decisionOrder) {
+    }
+    if (matches.length === 1) {
+      const preferred = matches[0];
+      const healthReason = healthAdmissionReason(preferred, { healthStore, healthGate, tombstones });
+      if (healthReason) {
+        trace.ordered_candidates.push(candidateDecision(preferred, 'preferred-default', 'skipped', {
+          reasonCode: healthReason,
+        }));
+        if (allowFallback === false) return blockedSelection(trace, preferred, 'preferred-default', healthReason);
+      } else {
+        rankForTrace(trace, matches, { adaptive, adaptiveHealth });
+        selectTrace(trace, preferred, 'preferred-default');
+        return { ok: true, ...preferred, source: 'preferred-default', selection_trace: trace };
+      }
+    }
+    if (matches.length > 1) {
+      const availableMatches = matches.filter((candidate) => {
+        const healthReason = healthAdmissionReason(candidate, { healthStore, healthGate, tombstones });
+        if (!healthReason) return true;
+        trace.ordered_candidates.push(candidateDecision(candidate, 'preferred-default', 'skipped', {
+          reasonCode: healthReason,
+        }));
+        return false;
+      });
+      if (availableMatches.length === 0) {
+        const blocked = matches.find((candidate) => healthAdmissionReason(candidate, { healthStore, healthGate, tombstones }));
+        if (blocked && allowFallback === false) {
+          return blockedSelection(trace, blocked, 'preferred-default', healthAdmissionReason(blocked, { healthStore, healthGate, tombstones }));
+        }
+      }
+      const preferredProvider = normalizeModelRef(harnessDefault)?.provider;
+      const deterministicMatch = availableMatches.find((candidate) => candidate.provider === preferredProvider) ?? null;
+      const baseline = deterministicMatch
+        ? [deterministicMatch, ...availableMatches.filter((candidate) => candidate.provider !== deterministicMatch.provider)]
+        : availableMatches;
+      const ranked = rankForTrace(trace, baseline, { adaptive, adaptiveHealth });
+      const adaptiveChoice = ranked.trace.decision_supported ? ranked.candidates[0] : null;
+      const match = adaptiveChoice ?? deterministicMatch;
+      if (match) {
+        const decisionOrder = adaptiveChoice ? ranked.candidates : availableMatches;
+        for (const candidate of decisionOrder) {
           if (candidate.provider === match.provider && candidate.model === match.model) continue;
           trace.ordered_candidates.push(candidateDecision(candidate, 'preferred-default', 'skipped', {
             reasonCode: adaptiveChoice
@@ -318,20 +394,28 @@ export function resolveWorkerModel({
         reasonCode: MODEL_SELECTION_REASON_CODES.HARNESS_DEFAULT_PROVIDER_UNAVAILABLE,
       }));
     } else {
-      const fallbackReason = traceContext.candidateSet === 'escalation'
-        ? MODEL_SELECTION_REASON_CODES.ESCALATION_CANDIDATES_EXHAUSTED
-        : MODEL_SELECTION_REASON_CODES.PRIMARY_CANDIDATES_EXHAUSTED;
-      selectTrace(trace, defaultRef, 'harness-default', { fallbackReason });
-      return {
+      const fallbackReason = traceContext.candidateSet === 'escalation'
+        ? MODEL_SELECTION_REASON_CODES.ESCALATION_CANDIDATES_EXHAUSTED
+        : MODEL_SELECTION_REASON_CODES.PRIMARY_CANDIDATES_EXHAUSTED;
+      const healthReason = healthAdmissionReason(defaultRef, { healthStore, healthGate, tombstones });
+      if (healthReason) {
+        trace.ordered_candidates.push(candidateDecision(defaultRef, 'harness-default', 'skipped', {
+          reasonCode: healthReason,
+        }));
+        if (allowFallback === false) return blockedSelection(trace, defaultRef, 'harness-default', healthReason);
+      } else {
+      selectTrace(trace, defaultRef, 'harness-default', { fallbackReason });
+      return {
         ok: true,
         ...defaultRef,
         source: 'harness-default',
         ...(typeof harnessDefault.reasoningEffort === 'string' && harnessDefault.reasoningEffort
           ? { reasoningEffort: harnessDefault.reasoningEffort }
           : {}),
-        selection_trace: trace,
-      };
-    }
+        selection_trace: trace,
+      };
+      }
+    }
   }
   trace.fallback_reason = MODEL_SELECTION_REASON_CODES.NO_AVAILABLE_MODEL;
   return {
@@ -351,14 +435,18 @@ export function resolveWorkerModel({
  * The output shape matches resolveWorkerModel (provider/model/source/...) plus
  * role + attempt so selection provenance lands in job metadata.
  */
-export function resolveModel({
+export function resolveModel({
   role = 'worker',
   attempt = 0,
   policy,
   catalog,
   harnessDefault,
-  adaptiveHealth,
-} = {}) {
+  adaptiveHealth,
+  healthStore,
+  healthGate,
+  allowFallback = true,
+  tombstones,
+} = {}) {
   const p = policy && typeof policy === 'object' ? policy : {};
   const escalated = Number.isInteger(attempt) && attempt > 0;
   const candidates = escalated ? p.escalation_priority : p.priority;
@@ -376,8 +464,12 @@ export function resolveModel({
     harnessDefault,
     fallback: p.fallback === 'harness-default' ? 'harness-default' : 'harness-default',
     preferredModelId,
-    adaptive: p.adaptive,
-    adaptiveHealth,
+    adaptive: p.adaptive,
+    adaptiveHealth,
+    healthStore,
+    healthGate,
+    allowFallback,
+    tombstones,
     traceContext: {
       role,
       logicalAttempt: attempt,