@ran-sh/dsh-crew 0.3.0

package/src/adaptive-routing.mjs

@@ -0,0 +1,260 @@
+// Opt-in adaptive model routing primitives.
+//
+// This module is deliberately pure/process-local: it never reads credentials,
+// provider quota, billing data, persistent files, or DSH profile state. The
+// caller may record only outcomes Crew already observed, and routing decisions
+// expose bounded evidence suitable for model-selection trace metadata.
+
+export const ADAPTIVE_ROUTING_VERSION = 1;
+export const ADAPTIVE_ROUTING_DEFAULTS = Object.freeze({
+  enabled: false,
+  window_size: 8,
+  min_samples: 2,
+});
+
+export const ADAPTIVE_ROUTING_REASON_CODES = Object.freeze({
+  DISABLED: 'DISABLED',
+  EXPLICIT_PRIORITY: 'EXPLICIT_PRIORITY',
+  NO_ELIGIBLE_CANDIDATES: 'NO_ELIGIBLE_CANDIDATES',
+  SINGLE_CANDIDATE: 'SINGLE_CANDIDATE',
+  INSUFFICIENT_HISTORY: 'INSUFFICIENT_HISTORY',
+  HEALTH_NEUTRAL: 'HEALTH_NEUTRAL',
+  HEALTH_REORDERED: 'HEALTH_REORDERED',
+  HEALTH_ORDER_UNCHANGED: 'HEALTH_ORDER_UNCHANGED',
+});
+
+function clampInteger(value, fallback, min, max) {
+  const n = Number(value);
+  if (!Number.isInteger(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+export function normalizeAdaptiveRouting(raw = {}) {
+  const windowSize = clampInteger(raw?.window_size, ADAPTIVE_ROUTING_DEFAULTS.window_size, 1, 32);
+  return {
+    enabled: raw?.enabled === true,
+    window_size: windowSize,
+    min_samples: clampInteger(raw?.min_samples, ADAPTIVE_ROUTING_DEFAULTS.min_samples, 1, windowSize),
+  };
+}
+
+function normalizeRef(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const provider = typeof raw.provider === 'string' ? raw.provider.trim() : '';
+  const model = typeof raw.model === 'string' ? raw.model.trim() : '';
+  return provider && model ? { provider, model } : null;
+}
+
+function refKey(ref, role = 'worker') {
+  const normalized = normalizeRef(ref);
+  return normalized ? `${role === 'reviewer' ? 'reviewer' : 'worker'}\0${normalized.provider}\0${normalized.model}` : '';
+}
+
+function normalizeLatencyMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return null;
+  // Bound pathological values; adaptive routing only needs a coarse signal.
+  return Math.min(Math.round(n), 3_600_000);
+}
+
+function latencyBucket(samples) {
+  const values = samples.map((sample) => sample.latency_ms).filter(Number.isFinite);
+  if (values.length === 0) return 'unknown';
+  const average = values.reduce((sum, value) => sum + value, 0) / values.length;
+  if (average <= 30_000) return 'fast';
+  if (average <= 120_000) return 'medium';
+  return 'slow';
+}
+
+function outcomeKind(observation = {}) {
+  const stopReason = String(observation.stopReason ?? observation.stop_reason ?? '').toLowerCase();
+  if (observation.timed_out === true || stopReason === 'timeout' || stopReason === 'timed_out') return 'timeout';
+  const status = String(observation.status ?? '').toLowerCase();
+  if (status === 'done' || status === 'success' || status === 'completed') return 'success';
+  if (status === 'failed' || status === 'failure' || status === 'error') return 'failure';
+  return null;
+}
+
+function healthScore(summary) {
+  let score = summary.successes * 4 - summary.failures * 3 - summary.timeouts * 6;
+  if (summary.latency_bucket === 'medium') score -= 1;
+  else if (summary.latency_bucket === 'slow') score -= 2;
+  return score;
+}
+
+export function createAdaptiveHealthStore({ maxSamples = 32 } = {}) {
+  const limit = clampInteger(maxSamples, 32, 1, 32);
+  const history = new Map();
+
+  return {
+    record(ref, observation = {}) {
+      const key = refKey(ref, observation.role);
+      const outcome = outcomeKind(observation);
+      if (!key || !outcome) return false;
+      const samples = history.get(key) ?? [];
+      samples.push({
+        outcome,
+        latency_ms: normalizeLatencyMs(observation.latencyMs ?? observation.latency_ms),
+      });
+      if (samples.length > limit) samples.splice(0, samples.length - limit);
+      history.set(key, samples);
+      return true;
+    },
+
+    snapshot(ref, { role = 'worker', windowSize = ADAPTIVE_ROUTING_DEFAULTS.window_size } = {}) {
+      const key = refKey(ref, role);
+      const window = clampInteger(windowSize, ADAPTIVE_ROUTING_DEFAULTS.window_size, 1, 32);
+      const samples = key ? (history.get(key) ?? []).slice(-window) : [];
+      const summary = {
+        samples: samples.length,
+        successes: samples.filter((sample) => sample.outcome === 'success').length,
+        failures: samples.filter((sample) => sample.outcome === 'failure').length,
+        timeouts: samples.filter((sample) => sample.outcome === 'timeout').length,
+        latency_bucket: latencyBucket(samples),
+      };
+      return { ...summary, score: healthScore(summary) };
+    },
+
+    clear() {
+      history.clear();
+    },
+  };
+}
+
+// One bounded store per Node.js process. Hub routing and its entry wrapper share
+// this module instance, so a completed opt-in Hub attempt can influence a later
+// opt-in Hub selection without writing any persistent state. Process restart is
+// intentionally the reset boundary.
+const PROCESS_ADAPTIVE_HEALTH = createAdaptiveHealthStore();
+
+export function getProcessAdaptiveHealthStore() {
+  return PROCESS_ADAPTIVE_HEALTH;
+}
+
+function uniqueCandidates(candidates) {
+  const seen = new Set();
+  const out = [];
+  for (const candidate of Array.isArray(candidates) ? candidates : []) {
+    const ref = normalizeRef(candidate);
+    if (!ref) continue;
+    const key = `${ref.provider}\0${ref.model}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(ref);
+  }
+  return out;
+}
+
+function traceBase(config, reason, candidates = []) {
+  return {
+    version: ADAPTIVE_ROUTING_VERSION,
+    enabled: config.enabled,
+    decision_supported: false,
+    applied: false,
+    reason,
+    window_size: config.window_size,
+    min_samples: config.min_samples,
+    candidates,
+  };
+}
+
+/**
+ * Stable health-based ordering for automatically derived candidates.
+ *
+ * Explicit user priority is a hard bypass: health never changes its order.
+ * Candidates below min_samples are scored as neutral (0), allowing a mature
+ * unhealthy candidate to yield to an unknown one without overreacting to a
+ * single sample. Ties always retain baseline order.
+ */
+export function rankAdaptiveCandidates(candidates, {
+  config: rawConfig,
+  healthStore = PROCESS_ADAPTIVE_HEALTH,
+  role = 'worker',
+  explicitPriority = false,
+} = {}) {
+  const config = normalizeAdaptiveRouting(rawConfig);
+  const baseline = uniqueCandidates(candidates);
+
+  if (!config.enabled) {
+    return { candidates: baseline, trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.DISABLED) };
+  }
+  if (explicitPriority) {
+    return { candidates: baseline, trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.EXPLICIT_PRIORITY) };
+  }
+  if (baseline.length === 0) {
+    return { candidates: baseline, trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.NO_ELIGIBLE_CANDIDATES) };
+  }
+  if (baseline.length === 1) {
+    return { candidates: baseline, trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.SINGLE_CANDIDATE) };
+  }
+
+  const scored = baseline.map((candidate, baselineRank) => {
+    const summary = healthStore?.snapshot?.(candidate, { role, windowSize: config.window_size }) ?? {
+      samples: 0, successes: 0, failures: 0, timeouts: 0, latency_bucket: 'unknown', score: 0,
+    };
+    const mature = summary.samples >= config.min_samples;
+    return {
+      candidate,
+      baselineRank,
+      mature,
+      effectiveScore: mature ? summary.score : 0,
+      summary,
+    };
+  });
+
+  const mature = scored.filter((entry) => entry.mature);
+  if (mature.length === 0) {
+    const candidatesTrace = scored.map((entry) => ({
+      ...entry.candidate,
+      baseline_rank: entry.baselineRank,
+      adaptive_rank: entry.baselineRank,
+      health_state: 'warming',
+      samples: entry.summary.samples,
+      successes: entry.summary.successes,
+      failures: entry.summary.failures,
+      timeouts: entry.summary.timeouts,
+      latency_bucket: entry.summary.latency_bucket,
+      score: null,
+    }));
+    return {
+      candidates: baseline,
+      trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.INSUFFICIENT_HISTORY, candidatesTrace),
+    };
+  }
+
+  const hasSignal = mature.some((entry) => entry.effectiveScore !== 0);
+  const ranked = [...scored].sort((a, b) => {
+    if (a.effectiveScore !== b.effectiveScore) return b.effectiveScore - a.effectiveScore;
+    return a.baselineRank - b.baselineRank;
+  });
+  const orderChanged = ranked.some((entry, index) => entry.baselineRank !== index);
+  const rankByKey = new Map(ranked.map((entry, index) => [`${entry.candidate.provider}\0${entry.candidate.model}`, index]));
+  const candidatesTrace = scored.map((entry) => ({
+    ...entry.candidate,
+    baseline_rank: entry.baselineRank,
+    adaptive_rank: rankByKey.get(`${entry.candidate.provider}\0${entry.candidate.model}`),
+    health_state: entry.mature ? 'mature' : 'warming',
+    samples: entry.summary.samples,
+    successes: entry.summary.successes,
+    failures: entry.summary.failures,
+    timeouts: entry.summary.timeouts,
+    latency_bucket: entry.summary.latency_bucket,
+    score: entry.mature ? entry.effectiveScore : null,
+  }));
+
+  if (!hasSignal) {
+    return {
+      candidates: baseline,
+      trace: traceBase(config, ADAPTIVE_ROUTING_REASON_CODES.HEALTH_NEUTRAL, candidatesTrace),
+    };
+  }
+
+  const trace = traceBase(
+    config,
+    orderChanged ? ADAPTIVE_ROUTING_REASON_CODES.HEALTH_REORDERED : ADAPTIVE_ROUTING_REASON_CODES.HEALTH_ORDER_UNCHANGED,
+    candidatesTrace,
+  );
+  trace.decision_supported = true;
+  trace.applied = orderChanged;
+  return { candidates: ranked.map((entry) => entry.candidate), trace };
+}

package/src/client/activation-summary.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+
+type Boundary = 'live' | 'next-workflow' | 'next-session' | 'restart-required';
+type ActivationEntry = { global?: Boundary; session?: Boundary | null; note?: string };
+
+const ORDER: Boundary[] = ['live', 'next-workflow', 'next-session', 'restart-required'];
+
+const LABELS = {
+  zh: {
+    title: '配置生效边界',
+    hint: '这里显示全局 Settings 保存后的实际生效时机；会话内 dsh_worker_config 覆盖可能更早生效。',
+    boundary: {
+      live: 'Live · 当前运行时',
+      'next-workflow': 'Next workflow · 下一个任务',
+      'next-session': 'Next session · 新 CC / Codex 会话',
+      'restart-required': 'Restart required · 重启 DSH / MCP',
+    } as Record<Boundary, string>,
+  },
+  en: {
+    title: 'Configuration activation boundaries',
+    hint: 'Shows when persisted Settings changes actually take effect. Session-level dsh_worker_config overrides may activate earlier.',
+    boundary: {
+      live: 'Live · current runtime',
+      'next-workflow': 'Next workflow',
+      'next-session': 'Next session · new CC / Codex session',
+      'restart-required': 'Restart required · restart DSH / MCP',
+    } as Record<Boundary, string>,
+  },
+};
+
+export function groupActivationBoundaries(activation: Record<string, ActivationEntry> = {}) {
+  const grouped = Object.fromEntries(ORDER.map((boundary) => [boundary, [] as string[]])) as Record<Boundary, string[]>;
+  for (const [key, entry] of Object.entries(activation)) {
+    if (entry?.global && grouped[entry.global]) grouped[entry.global].push(key);
+  }
+  for (const boundary of ORDER) grouped[boundary].sort();
+  return grouped;
+}
+
+export function ActivationSummary({ activation, locale }: {
+  activation?: Record<string, ActivationEntry>;
+  locale?: string;
+}) {
+  if (!activation || Object.keys(activation).length === 0) return null;
+  const lang = locale === 'zh' ? 'zh' : 'en';
+  const copy = LABELS[lang];
+  const grouped = groupActivationBoundaries(activation);
+  return (
+    <div style={{ border: '1px solid rgba(128,128,128,0.22)', borderRadius: 8, padding: '9px 12px', display: 'flex', flexDirection: 'column', gap: 5 }}>
+      <div style={{ fontWeight: 600, fontSize: 12.5 }}>{copy.title}</div>
+      <div style={{ fontSize: 11, opacity: 0.6 }}>{copy.hint}</div>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: '5px 12px' }}>
+        {ORDER.map((boundary) => (
+          <div key={boundary} style={{ minWidth: 0 }}>
+            <div style={{ fontSize: 10.5, opacity: 0.7, fontWeight: 600 }}>{copy.boundary[boundary]}</div>
+            <div style={{ fontSize: 10.5, opacity: 0.55, wordBreak: 'break-word' }}>
+              {grouped[boundary].length ? grouped[boundary].join(' · ') : '—'}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/client/entry.tsx

@@ -0,0 +1,236 @@
+import React, { useEffect, useState, useSyncExternalStore } from 'react';
+import { apply as applyCrew, inject as crewInject } from './index';
+import { ActivationSummary } from './activation-summary';
+
+export const inject = crewInject;
+const API = '/_dsh/dsh-crew';
+
+type AdaptiveConfig = {
+  enabled: boolean;
+  window_size: number;
+  min_samples: number;
+};
+
+const DEFAULT_ADAPTIVE: AdaptiveConfig = { enabled: false, window_size: 8, min_samples: 2 };
+
+function clampInt(value: unknown, fallback: number, min: number, max: number) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) return fallback;
+  return Math.max(min, Math.min(max, parsed));
+}
+
+function normalizeAdaptive(value: any): AdaptiveConfig {
+  const windowSize = clampInt(value?.window_size, DEFAULT_ADAPTIVE.window_size, 1, 32);
+  return {
+    enabled: value?.enabled === true,
+    window_size: windowSize,
+    min_samples: clampInt(value?.min_samples, DEFAULT_ADAPTIVE.min_samples, 1, windowSize),
+  };
+}
+
+function useLocale(ctx: any) {
+  return useSyncExternalStore(
+    (notify: () => void) => ctx.on('locale/change', notify),
+    () => ctx.locale.getLocale().active,
+    () => ctx.locale.getLocale().active,
+  );
+}
+
+function AdaptiveRoutingPanel({ ctx }: { ctx: any }) {
+  const locale = useLocale(ctx);
+  const zh = locale === 'zh';
+  const [adaptive, setAdaptive] = useState<AdaptiveConfig>(DEFAULT_ADAPTIVE);
+  const [loaded, setLoaded] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useState('');
+
+  const copy = zh ? {
+    title: '自适应模型路由（实验）',
+    hint: '默认关闭。仅对系统自动产生的候选做健康排序；显式 Provider / Model 优先级永远保持原序。信号只来自本进程内 Crew 已观察到的成功、失败、超时与粗粒度延迟，不读取额度、价格或凭据。重启 Hub 会清空健康历史。',
+    enabled: '启用自适应路由',
+    window: '健康窗口',
+    minSamples: '最少样本',
+    windowHint: '每个 role/provider/model 最多参考最近 1–32 次结果。',
+    minHint: '达到该样本数后才允许健康分数影响自动候选顺序。',
+    boundary: '生效边界：下一工作流',
+    saved: '已保存',
+    loading: '加载中…',
+  } : {
+    title: 'Adaptive Model Routing (experimental)',
+    hint: 'Off by default. Health ordering applies only to automatically derived candidates; explicit Provider / Model priorities always keep their order. Signals are limited to Crew-observed success, failure, timeout, and coarse latency in this process—never quota, pricing, or credentials. Restarting the Hub clears the history.',
+    enabled: 'Enable adaptive routing',
+    window: 'Health window',
+    minSamples: 'Minimum samples',
+    windowHint: 'Use at most the most recent 1–32 outcomes per role/provider/model.',
+    minHint: 'Health may affect automatic candidate order only after this many samples.',
+    boundary: 'Activation boundary: next workflow',
+    saved: 'Saved',
+    loading: 'Loading…',
+  };
+
+  useEffect(() => {
+    let cancelled = false;
+    const load = async () => {
+      try {
+        const lang = zh ? 'zh' : 'en';
+        const res = await fetch(`${API}/config?lang=${lang}`, { cache: 'no-store' });
+        const body = await res.json();
+        if (!res.ok || body?.ok === false) throw new Error(body?.error ?? `HTTP ${res.status}`);
+        if (!cancelled) {
+          setAdaptive(normalizeAdaptive(body?.config?.worker?.model_policy?.adaptive));
+          setMessage('');
+          setLoaded(true);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setMessage(err?.message ?? String(err));
+          setLoaded(true);
+        }
+      }
+    };
+    void load();
+    return () => { cancelled = true; };
+  }, [zh]);
+
+  const save = async (candidate: AdaptiveConfig) => {
+    const next = normalizeAdaptive(candidate);
+    setAdaptive(next);
+    setSaving(true);
+    try {
+      const lang = zh ? 'zh' : 'en';
+      const res = await fetch(`${API}/config?lang=${lang}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ worker: { model_policy: { adaptive: next } } }),
+      });
+      const body = await res.json();
+      if (!res.ok || body?.ok === false) throw new Error(body?.error ?? `HTTP ${res.status}`);
+      setAdaptive(normalizeAdaptive(body?.config?.worker?.model_policy?.adaptive));
+      setMessage(copy.saved);
+      setTimeout(() => setMessage(''), 1500);
+    } catch (err: any) {
+      setMessage(err?.message ?? String(err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (!loaded) return <div style={{ fontSize: 12, opacity: 0.6 }}>{copy.loading}</div>;
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 10, fontSize: 13, lineHeight: 1.55 }}>
+      <div>
+        <div style={{ fontWeight: 600, fontSize: 14 }}>{copy.title}</div>
+        <div style={{ opacity: 0.68, fontSize: 12, marginTop: 2 }}>{copy.hint}</div>
+      </div>
+      <label style={{ display: 'flex', alignItems: 'center', gap: 7 }}>
+        <input
+          type="checkbox"
+          checked={adaptive.enabled}
+          disabled={saving}
+          onChange={(event) => { void save({ ...adaptive, enabled: event.target.checked }); }}
+        />
+        <span>{copy.enabled}</span>
+      </label>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: 10 }}>
+        <label style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <span style={{ fontSize: 12, fontWeight: 500 }}>{copy.window}</span>
+          <input
+            type="number"
+            min={1}
+            max={32}
+            value={adaptive.window_size}
+            disabled={saving}
+            onChange={(event) => {
+              const windowSize = clampInt(event.target.value, adaptive.window_size, 1, 32);
+              setAdaptive((current) => ({
+                ...current,
+                window_size: windowSize,
+                min_samples: Math.min(current.min_samples, windowSize),
+              }));
+            }}
+            onBlur={() => { void save(adaptive); }}
+            style={{ padding: '5px 7px', borderRadius: 5, border: '1px solid rgba(128,128,128,0.35)', background: 'transparent', color: 'inherit' }}
+          />
+          <span style={{ fontSize: 10.5, opacity: 0.55 }}>{copy.windowHint}</span>
+        </label>
+        <label style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <span style={{ fontSize: 12, fontWeight: 500 }}>{copy.minSamples}</span>
+          <input
+            type="number"
+            min={1}
+            max={adaptive.window_size}
+            value={adaptive.min_samples}
+            disabled={saving}
+            onChange={(event) => setAdaptive((current) => ({
+              ...current,
+              min_samples: clampInt(event.target.value, current.min_samples, 1, current.window_size),
+            }))}
+            onBlur={() => { void save(adaptive); }}
+            style={{ padding: '5px 7px', borderRadius: 5, border: '1px solid rgba(128,128,128,0.35)', background: 'transparent', color: 'inherit' }}
+          />
+          <span style={{ fontSize: 10.5, opacity: 0.55 }}>{copy.minHint}</span>
+        </label>
+      </div>
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center', fontSize: 11.5, opacity: 0.62 }}>
+        <span>{copy.boundary}</span>
+        {message && <span>· {message}</span>}
+      </div>
+    </div>
+  );
+}
+
+function ActivationBoundaryPanel({ ctx }: { ctx: any }) {
+  const locale = useLocale(ctx);
+  const [activation, setActivation] = useState<any>(null);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    let cancelled = false;
+    const load = async () => {
+      try {
+        const lang = locale === 'zh' ? 'zh' : 'en';
+        const res = await fetch(`${API}/config?lang=${lang}`, { cache: 'no-store' });
+        const body = await res.json();
+        if (!cancelled) {
+          if (!res.ok || body?.ok === false) throw new Error(body?.error ?? `HTTP ${res.status}`);
+          setActivation(body?.config?.config_activation ?? null);
+          setError('');
+        }
+      } catch (err: any) {
+        if (!cancelled) setError(err?.message ?? String(err));
+      }
+    };
+    void load();
+    return () => { cancelled = true; };
+  }, [locale]);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, fontSize: 13, lineHeight: 1.55 }}>
+      {error && <div style={{ fontSize: 11.5, opacity: 0.6 }}>{error}</div>}
+      <ActivationSummary activation={activation ?? undefined} locale={locale} />
+    </div>
+  );
+}
+
+export function apply(ctx: any): void {
+  applyCrew(ctx);
+  ctx.slots.inject('settings.section', () => ctx.slots.register(
+    {
+      name: 'settings.section',
+      id: 'dsh-crew-adaptive-routing',
+      order: 65,
+      label: () => ctx.locale.getLocale().active === 'zh' ? 'DSH Crew · 自适应路由' : 'DSH Crew · Adaptive Routing',
+    },
+    () => <AdaptiveRoutingPanel ctx={ctx} />,
+  ));
+  ctx.slots.inject('settings.section', () => ctx.slots.register(
+    {
+      name: 'settings.section',
+      id: 'dsh-crew-runtime-controls',
+      order: 66,
+      label: () => ctx.locale.getLocale().active === 'zh' ? 'DSH Crew · 生效边界' : 'DSH Crew · Activation',
+    },
+    () => <ActivationBoundaryPanel ctx={ctx} />,
+  ));
+}