dsh-omni-router 2.3.0 → 2.4.0

package/README.md

@@ -79,6 +79,7 @@
 - **2.1 收敛增强**：Mission Resume（`omni_mission_resume` 跨 session 继续 DAG，`runDagLoop` 支持 `onProgress` 周期保存）、Harness evidence extraction（`extractHarnessEvidence` 从 commands/tests/toolCalls/EVIDENCE_JSON 提取机器可验证证据）、context token budget（`maxContextTokens` 真正限制检索输出）、semantic failure retrieval + evidence-backed skill distillation、OmniBench v2 real runner。
 - **2.2 Capability Auto-Provisioning（优化7）**：Capability Auditor（baseline/task-time audit）、Gap Detection、Plugin/Skill Quality Scoring、Minimal Capability Set Solver、Discovery Adapters（marketplace/hub/static registry）、Trusted Auto Provisioning（recommend/auto-trusted/manual）、Post-install probe、Install rollback transaction、Capability performance learning / redundancy detection。
 - **2.3 Progressive Intelligence（优化8）**：L0 Direct / L1 Assisted / L2 Orchestrated / L3 Guarded 四级渐进智能；Context Capsule（最小相关上下文 + 动态 needs）；Strategy Shift（相同失败策略自动换策略，不再盲目 retry）；`omni_explain` / `omni_doctor` 用户入口。
+- **2.4 Reliability Kernel（优化9）**：TaskContract 统一任务契约；Intervention Gate（默认 NOOP，按 Expected Utility 决定是否介入）；OmniEvent / Host Interface（宿主无关事件与能力协商）；Evidence Trust（T0-T4）与 Invalidation；Context Freshness（workspace fingerprint）；Recovery Policy（retry/repair/expand/replan/escalate/stop）。
 - **TaskDecision**：`createTaskDecision` 生成唯一决策对象，Policy/Runtime 统一消费，避免重复 classify 分叉。
 - **Evidence Protocol**：`src/evidence.mjs` 用结构化 command/file/test/finding 证据判定 PASS/FAIL；`isQaPass` 已支持从 QA 输出解析 JSON evidence，不再只信文本。
 - **Task Compiler**：`compileTask` 生成 objective / constraints / non-goals / acceptance / hidden assumptions / ambiguities / invariants / risk / artifacts；`compileTaskWithLLM` 可用 LLM 增强。

package/README.zh-CN.md

@@ -79,6 +79,7 @@
 - **2.1 收敛增强**：Mission Resume（`omni_mission_resume` 跨 session 继续 DAG，`runDagLoop` 支持 `onProgress` 周期保存）、Harness evidence extraction（`extractHarnessEvidence` 从 commands/tests/toolCalls/EVIDENCE_JSON 提取机器可验证证据）、context token budget（`maxContextTokens` 真正限制检索输出）、semantic failure retrieval + evidence-backed skill distillation、OmniBench v2 real runner。
 - **2.2 Capability Auto-Provisioning（优化7）**：Capability Auditor（baseline/task-time audit）、Gap Detection、Plugin/Skill Quality Scoring、Minimal Capability Set Solver、Discovery Adapters（marketplace/hub/static registry）、Trusted Auto Provisioning（recommend/auto-trusted/manual）、Post-install probe、Install rollback transaction、Capability performance learning / redundancy detection。
 - **2.3 Progressive Intelligence（优化8）**：L0 Direct / L1 Assisted / L2 Orchestrated / L3 Guarded 四级渐进智能；Context Capsule（最小相关上下文 + 动态 needs）；Strategy Shift（相同失败策略自动换策略，不再盲目 retry）；`omni_explain` / `omni_doctor` 用户入口。
+- **2.4 Reliability Kernel（优化9）**：TaskContract 统一任务契约；Intervention Gate（默认 NOOP，按 Expected Utility 决定是否介入）；OmniEvent / Host Interface（宿主无关事件与能力协商）；Evidence Trust（T0-T4）与 Invalidation；Context Freshness（workspace fingerprint）；Recovery Policy（retry/repair/expand/replan/escalate/stop）。
 - **TaskDecision**：`createTaskDecision` 生成唯一决策对象，Policy/Runtime 统一消费，避免重复 classify 分叉。
 - **Evidence Protocol**：`src/evidence.mjs` 用结构化 command/file/test/finding 证据判定 PASS/FAIL；`isQaPass` 已支持从 QA 输出解析 JSON evidence，不再只信文本。
 - **Task Compiler**：`compileTask` 生成 objective / constraints / non-goals / acceptance / hidden assumptions / ambiguities / invariants / risk / artifacts；`compileTaskWithLLM` 可用 LLM 增强。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-omni-router",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Omni - a reliability and orchestration control plane for DeepSeek Harness, designed to turn fast models into dependable long-horizon software-engineering agents.",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,7 +41,7 @@
     }
   },
   "scripts": {
-    "test": "node test/omni-router.test.mjs && node test/agent-chain.test.mjs && node test/skill-suggest.test.mjs && node test/methodology.test.mjs && node test/compat.test.mjs && node test/project-brain.test.mjs && node test/mission-planner.test.mjs && node test/agent-runtime.test.mjs && node test/judge.test.mjs && node test/memory.test.mjs && node test/memory-v3.test.mjs && node test/memory-engine.test.mjs && node test/mission-resume.test.mjs && node test/engineering-benchmark.test.mjs && node test/benchmark-runner.test.mjs && node test/benchmark-results.test.mjs && node test/continuous-eval.test.mjs && node --no-warnings test/project-brain-v2.test.mjs && node --no-warnings test/project-brain-v3.test.mjs && node test/visual-qa.test.mjs && node test/evidence.test.mjs && node test/evidence-store.test.mjs && node test/evidence-engine.test.mjs && node test/task-decision.test.mjs && node test/task-compiler.test.mjs && node test/capability-brain.test.mjs && node test/capability-manifest.test.mjs && node test/capability-sandbox.test.mjs && node test/capability-auditor.test.mjs && node test/capability-quality.test.mjs && node test/capability-solver.test.mjs && node test/capability-provisioner.test.mjs && node test/capability-performance.test.mjs && node test/progressive-intelligence.test.mjs && node test/context-capsule.test.mjs && node test/strategy-shift.test.mjs && node test/planner-dag.test.mjs && node test/dynamic-context.test.mjs && node test/mission-dag.test.mjs && node test/failure-taxonomy.test.mjs && node test/context-expansion.test.mjs && node test/hybrid-retrieval.test.mjs && node test/dependency-graph.test.mjs && node test/ast-provider.test.mjs && node test/experience-router.test.mjs && node test/benchmark-tasks.test.mjs && node test/bundle-installer.test.mjs && node test/omnibench-runner.test.mjs",
+    "test": "node test/omni-router.test.mjs && node test/agent-chain.test.mjs && node test/skill-suggest.test.mjs && node test/methodology.test.mjs && node test/compat.test.mjs && node test/project-brain.test.mjs && node test/mission-planner.test.mjs && node test/agent-runtime.test.mjs && node test/judge.test.mjs && node test/memory.test.mjs && node test/memory-v3.test.mjs && node test/memory-engine.test.mjs && node test/mission-resume.test.mjs && node test/engineering-benchmark.test.mjs && node test/benchmark-runner.test.mjs && node test/benchmark-results.test.mjs && node test/continuous-eval.test.mjs && node --no-warnings test/project-brain-v2.test.mjs && node --no-warnings test/project-brain-v3.test.mjs && node test/visual-qa.test.mjs && node test/evidence.test.mjs && node test/evidence-store.test.mjs && node test/evidence-engine.test.mjs && node test/task-decision.test.mjs && node test/task-compiler.test.mjs && node test/capability-brain.test.mjs && node test/capability-manifest.test.mjs && node test/capability-sandbox.test.mjs && node test/capability-auditor.test.mjs && node test/capability-quality.test.mjs && node test/capability-solver.test.mjs && node test/capability-provisioner.test.mjs && node test/capability-performance.test.mjs && node test/progressive-intelligence.test.mjs && node test/context-capsule.test.mjs && node test/strategy-shift.test.mjs && node test/task-contract.test.mjs && node test/intervention-gate.test.mjs && node test/omni-event.test.mjs && node test/host-interface.test.mjs && node test/evidence-trust.test.mjs && node test/context-freshness.test.mjs && node test/recovery-policy.test.mjs && node test/planner-dag.test.mjs && node test/dynamic-context.test.mjs && node test/mission-dag.test.mjs && node test/failure-taxonomy.test.mjs && node test/context-expansion.test.mjs && node test/hybrid-retrieval.test.mjs && node test/dependency-graph.test.mjs && node test/ast-provider.test.mjs && node test/experience-router.test.mjs && node test/benchmark-tasks.test.mjs && node test/bundle-installer.test.mjs && node test/omnibench-runner.test.mjs",
     "benchmark": "node benchmark/run.mjs",
     "benchmark:engineering": "node benchmark/engineering-run.mjs",
     "benchmark:compare": "node benchmark/compare.mjs",

package/src/context-freshness.mjs

@@ -0,0 +1,37 @@
+/**
+ * Context Freshness.
+ *
+ * Context Capsules and evidence records must be bound to a workspace
+ * fingerprint. After files change, old context/evidence is stale and cannot be
+ * used as reliable input.
+ */
+
+import crypto from 'node:crypto'
+
+export function fingerprintText(text) {
+  return crypto.createHash('sha1').update(String(text || '')).digest('hex').slice(0, 16)
+}
+
+export function fingerprintFiles(files = {}) {
+  const hash = crypto.createHash('sha1')
+  for (const [name, content] of Object.entries(files)) {
+    hash.update(name)
+    hash.update('\0')
+    hash.update(String(content || ''))
+    hash.update('\0')
+  }
+  return hash.digest('hex').slice(0, 24)
+}
+
+export function fingerprintWorkspace({ commit = '', files = {} } = {}) {
+  return fingerprintText(`${commit || ''}|${fingerprintFiles(files)}`)
+}
+
+export function attachFingerprint(context = {}, fingerprint = '') {
+  return { ...context, workspaceFingerprint: fingerprint }
+}
+
+export function isContextStale(context = {}, currentFingerprint = '') {
+  if (!currentFingerprint) return false
+  return Boolean(context.workspaceFingerprint && context.workspaceFingerprint !== currentFingerprint)
+}

package/src/evidence-trust.mjs

@@ -0,0 +1,63 @@
+/**
+ * Evidence Trust & Invalidation.
+ *
+ * Assigns every evidence record a trust level and a workspace fingerprint.
+ * If the workspace changes after evidence was produced, that evidence becomes
+ * stale and must not count toward completion.
+ */
+
+export const TRUST_LEVELS = {
+  T0: 0, // model claim
+  T1: 1, // agent observation
+  T2: 2, // host/tool output
+  T3: 3, // deterministic execution
+  T4: 4, // independent/hidden verifier
+}
+
+export function createEvidenceRecord({
+  id = `E-${Date.now().toString(36)}`,
+  criterionId = '',
+  workspaceFingerprint = '',
+  producer = 'unknown',
+  trustLevel = 'T0',
+  createdAt = new Date().toISOString(),
+  payload = {},
+} = {}) {
+  return {
+    evidenceId: id,
+    criterionId,
+    workspaceFingerprint,
+    producer,
+    trustLevel,
+    trustValue: TRUST_LEVELS[trustLevel] ?? 0,
+    createdAt,
+    payload,
+  }
+}
+
+export function isEvidenceStale(record = {}, currentFingerprint = '') {
+  if (!currentFingerprint) return false
+  return Boolean(record.workspaceFingerprint && record.workspaceFingerprint !== currentFingerprint)
+}
+
+export function invalidateEvidence(records = [], currentFingerprint = '') {
+  return records.map((record) => ({
+    ...record,
+    stale: isEvidenceStale(record, currentFingerprint),
+  }))
+}
+
+export function requiredTrustForRisk(risk = 'low') {
+  if (risk === 'high' || risk === 'critical') return { minimum: 'T3', independent: true, label: 'T3 + independent T4' }
+  if (risk === 'medium') return { minimum: 'T3', independent: false, label: 'T3' }
+  return { minimum: 'T1', independent: false, label: 'T1/T2' }
+}
+
+export function evidenceMeetsTrust(record = {}, requiredLevel = 'T0') {
+  const required = TRUST_LEVELS[requiredLevel] ?? 0
+  return (record.trustValue ?? 0) >= required
+}
+
+export function formatEvidenceTrust(record = {}) {
+  return `E${record.evidenceId || '?'} T${record.trustLevel || '0'} ${record.stale ? 'STALE' : 'fresh'} criterion=${record.criterionId || '-'}`
+}

package/src/host-interface.mjs

@@ -0,0 +1,62 @@
+/**
+ * OmniHost Interface.
+ *
+ * The small contract a host (DSH, Codex, Claude, ...) implements so Omni's
+ * kernel stays host-independent. Omni never executes; it decides, prepares,
+ * and verifies through this boundary.
+ */
+
+export const HOST_FEATURES = [
+  'workflow',
+  'approvals',
+  'skills',
+  'plugins',
+  'subagents',
+  'toolEvents',
+  'testEvents',
+  'fileEvents',
+]
+
+export function createHostAdapter(host = {}) {
+  const missing = []
+  for (const method of ['describeHost']) {
+    if (typeof host[method] !== 'function') missing.push(method)
+  }
+  return {
+    ...host,
+    missing,
+    valid: missing.length === 0,
+  }
+}
+
+export function describeHostCapabilities(capabilities = {}) {
+  const result = {}
+  for (const feature of HOST_FEATURES) {
+    result[feature] = capabilities[feature] === true
+  }
+  return result
+}
+
+export function negotiateHost(hostCapabilities = {}, required = HOST_FEATURES) {
+  const caps = describeHostCapabilities(hostCapabilities)
+  const supported = []
+  const degraded = []
+  for (const feature of required) {
+    if (caps[feature]) supported.push(feature)
+    else degraded.push(feature)
+  }
+  return {
+    supported,
+    degraded,
+    capabilities: caps,
+    mode: degraded.length ? 'degraded' : 'full',
+  }
+}
+
+export function formatHostNegotiation(result = {}) {
+  return [
+    `Host mode: ${result.mode}`,
+    `Supported: ${result.supported.join(', ') || '(none)'}`,
+    `Degraded: ${result.degraded.join(', ') || '(none)'}`,
+  ].join('\n')
+}

package/src/intervention-gate.mjs

@@ -0,0 +1,84 @@
+/**
+ * Intervention Gate.
+ *
+ * Decides whether Omni should intervene at all. The default answer is NOOP:
+ * if the host can already do the job without extra tokens/latency/context
+ * pollution, Omni stays out of the way.
+ */
+
+export function expectedInterventionUtility({
+  successGain = 0,
+  tokenOverhead = 0,
+  latency = 0,
+  contextPollution = 0,
+  overlap = 0,
+  failureSurface = 0,
+  taskFrequency = 1,
+} = {}) {
+  const utility = (
+    successGain * 1.0 -
+    tokenOverhead * 0.5 -
+    latency * 0.3 -
+    contextPollution * 0.5 -
+    overlap * 0.4 -
+    failureSurface * 0.4
+  ) * Math.max(0.1, taskFrequency)
+  return Math.round(utility * 1000) / 1000
+}
+
+export function shouldIntervene(utility = 0, threshold = 0.1) {
+  return utility > threshold
+}
+
+export function decideIntervention({
+  successGain,
+  tokenOverhead,
+  latency,
+  contextPollution,
+  overlap,
+  failureSurface,
+  taskFrequency,
+  threshold = 0.1,
+} = {}) {
+  const utility = expectedInterventionUtility({
+    successGain,
+    tokenOverhead,
+    latency,
+    contextPollution,
+    overlap,
+    failureSurface,
+    taskFrequency,
+  })
+  return {
+    utility,
+    threshold,
+    intervene: shouldIntervene(utility, threshold),
+    mode: shouldIntervene(utility, threshold) ? 'intervene' : 'noop',
+  }
+}
+
+export function noOpPrecision(decisions = []) {
+  // decision: { predictedNoop: boolean, actuallyNeeded: boolean }
+  let predictedNoop = 0
+  let correctNoop = 0
+  for (const d of decisions) {
+    if (!d.predictedNoop) continue
+    predictedNoop += 1
+    if (!d.actuallyNeeded) correctNoop += 1
+  }
+  return predictedNoop ? Math.round((correctNoop / predictedNoop) * 1000) / 1000 : 1
+}
+
+export function interventionEfficiency({ rawSuccess = 0, omniSuccess = 0, tokenOverhead = 0 }) {
+  const gain = omniSuccess - rawSuccess
+  const overhead = Math.max(0.01, tokenOverhead)
+  return {
+    gain: Math.round(gain * 1000) / 1000,
+    tokenOverhead,
+    efficiency: Math.round((gain / overhead) * 1000) / 1000,
+  }
+}
+
+export function formatInterventionGate(result = {}) {
+  return `${result.intervene ? 'INTERVENE' : 'NOOP'} (utility=${result.utility}, threshold=${result.threshold})`
+}

package/src/omni-event.mjs

@@ -0,0 +1,70 @@
+/**
+ * OmniEvent.
+ *
+ * Host-independent event model. DSH, Codex, Claude, etc. normalize their own
+ * events into OmniEvent so the Evidence/Recovery/Memory kernels never depend on
+ * a specific host.
+ */
+
+export const OMNI_EVENT_TYPES = [
+  'model.started',
+  'model.completed',
+  'tool.started',
+  'tool.completed',
+  'command.completed',
+  'test.completed',
+  'file.changed',
+  'approval.requested',
+  'approval.completed',
+  'agent.started',
+  'agent.completed',
+]
+
+export function createOmniEvent({
+  type,
+  host = 'unknown',
+  sessionId = '',
+  taskId = '',
+  workspaceFingerprint = '',
+  payload = {},
+} = {}) {
+  if (!type) throw new Error('OmniEvent type is required')
+  return {
+    type,
+    host,
+    sessionId,
+    taskId,
+    workspaceFingerprint,
+    timestamp: new Date().toISOString(),
+    payload,
+  }
+}
+
+export function normalizeHostEvent(hostEvent = {}, host = 'unknown', context = {}) {
+  const rawType = String(hostEvent.type || hostEvent.event || hostEvent.name || 'unknown')
+  const type = mapHostEventType(rawType, host)
+  return createOmniEvent({
+    type,
+    host: hostEvent.host || host,
+    sessionId: hostEvent.sessionId || context.sessionId || '',
+    taskId: hostEvent.taskId || context.taskId || '',
+    workspaceFingerprint: hostEvent.workspaceFingerprint || context.workspaceFingerprint || '',
+    payload: hostEvent.payload || hostEvent.data || hostEvent,
+  })
+}
+
+function mapHostEventType(raw, host) {
+  const value = String(raw).toLowerCase()
+  if (host === 'dsh') {
+    if (/tool|command/.test(value) && /start/.test(value)) return 'tool.started'
+    if (/tool|command/.test(value) && /end|done|complete/.test(value)) return 'tool.completed'
+    if (/test/.test(value)) return 'test.completed'
+    if (/file|change/.test(value)) return 'file.changed'
+    if (/approval/.test(value)) return 'approval.requested'
+    if (/agent|subagent/.test(value) && /start/.test(value)) return 'agent.started'
+    if (/agent|subagent/.test(value) && /end|done|complete/.test(value)) return 'agent.completed'
+  }
+  if (/start|begin/.test(value)) return 'model.started'
+  if (/end|done|complete|finish/.test(value)) return 'model.completed'
+  return OMNI_EVENT_TYPES.includes(raw) ? raw : 'model.completed'
+}

package/src/omni-router.mjs

@@ -39,6 +39,10 @@ import { baselineAudit, formatCapabilityAudit, taskTimeAudit } from './capabilit
 import { createStaticRegistryAdapter, discoverCandidates, evaluateProvisionPlan, formatProvisionResult, probeCapability, provisionCapabilities } from './capability-provisioner.mjs'
 import { evaluateProviderValue, formatPerformanceRegistry, loadPerformanceRegistry, recommendDemotion, recordProvisionOutcome, savePerformanceRegistry } from './capability-performance.mjs'
 import { decideIntelligenceLevel, formatIntelligenceLevel } from './progressive-intelligence.mjs'
+import { buildTaskContract, formatTaskContract } from './task-contract.mjs'
+import { decideIntervention, formatInterventionGate } from './intervention-gate.mjs'
+import { negotiateHost, formatHostNegotiation } from './host-interface.mjs'
+import { requiredTrustForRisk } from './evidence-trust.mjs'
 import { buildProgressiveContext } from './context-expansion.mjs'
 import { buildDynamicContext } from './dynamic-context.mjs'
 import { classifyFailure } from './failure-taxonomy.mjs'
@@ -1020,12 +1024,18 @@ export function apply(ctx, config = {}) {
         thinkingMode: state.thinkingMode || 'balanced',
       })
       const intelligence = decideIntelligenceLevel(taskDecision)
+      const contract = buildTaskContract({ taskText: state.firstText || '', decision: taskDecision })
+      const intervention = decideIntervention({
+        successGain: intelligence.level === 'L0' ? 0 : 0.15,
+        tokenOverhead: intelligence.level === 'L0' ? 0.05 : 0.2,
+      })
       return [
         `omni-router: ${state.kind || 'unclassified'}`,
         `taskType=${state.taskType || 'unknown'}`,
         `thinkingMode=${state.thinkingMode || 'balanced'}`,
         `riskLevel=${state.riskLevel || 'unknown'}`,
         `intelligenceLevel=${formatIntelligenceLevel(intelligence)}`,
+        `intervention=${formatInterventionGate(intervention)}`,
         `planRequested=${state.planRequested}`,
         `directOverride=${state.directOverride}`,
         `routerStandard=${routerStandard ? 'delegated' : 'not-detected'}`,
@@ -1054,6 +1064,8 @@ export function apply(ctx, config = {}) {
         thinkingMode: state.thinkingMode || 'balanced',
       })
       const intelligence = decideIntelligenceLevel(decision)
+      const contract = buildTaskContract({ taskText: state.firstText || '', decision })
+      const trust = requiredTrustForRisk(decision.risk)
       const topic = String(args?.topic || '').toLowerCase()
       const lines = [
         `Mode: ${intelligence.level} ${intelligence.label}`,
@@ -1061,8 +1073,9 @@ export function apply(ctx, config = {}) {
         `Reasoning effort: ${intelligence.reasoningEffort}`,
         `Verification: ${intelligence.verification}`,
         `Approval required: ${intelligence.approvalRequired ? 'yes' : 'no'}`,
-        `Capabilities needed: ${(decision.evidenceRequirements || []).join(', ') || 'native tools'}`,
-        `Completion requires: ${decision.evidenceRequirements?.length ? 'harness evidence for ' + decision.evidenceRequirements.join(', ') : 'light verification'}`,
+        `Capabilities needed: ${(contract.requiredCapabilities || []).join(', ') || 'native tools'}`,
+        `Evidence trust required: ${trust.label}`,
+        `Completion requires: ${contract.acceptance?.join('; ') || 'light verification'}`,
       ]
       if (topic === 'mode' || topic === 'capabilities' || topic === 'verification' || topic === 'completion') {
         const idx = lines.findIndex((l) => l.toLowerCase().startsWith(topic))
@@ -1084,6 +1097,17 @@ export function apply(ctx, config = {}) {
       brain = loadCapabilityManifests(brain, config.capabilityManifests || [])
       const baseline = baselineAudit(brain)
       const fs = ctx.get('fs') || ctx.fs
+      const hostCaps = {
+        workflow: !!(ctx.get('workflow') || ctx.workflow),
+        approvals: !!(ctx.get('approvals') || ctx.approvals),
+        skills: !!(ctx.get('skills') || ctx.skills),
+        plugins: !!(ctx.get('plugins') || ctx.plugins),
+        subagents: !!(ctx.get('subagents') || ctx.subagents),
+        toolEvents: !!(ctx.get('events') || ctx.events),
+        testEvents: false,
+        fileEvents: !!fs,
+      }
+      const host = negotiateHost(hostCaps)
       const lines = [
         `DSH session: ${session ? 'ok' : 'missing'}`,
         `Tools registered: ${toolNames.length}`,
@@ -1091,6 +1115,7 @@ export function apply(ctx, config = {}) {
         `Missing baseline: ${baseline.missing.join(', ') || '(none)'}`,
         `ProjectIndex: ${fs ? 'available' : 'unavailable'}`,
         `Evidence hooks: ${ctx.get('evidence') || ctx.evidence ? 'available' : 'not-detected'}`,
+        `Host negotiation: ${host.mode} (degraded: ${host.degraded.join(', ') || 'none'})`,
       ]
       return lines.join('\n')
     },

package/src/recovery-policy.mjs

@@ -0,0 +1,34 @@
+/**
+ * Recovery Policy.
+ *
+ * A single small decision procedure for failures: retry, repair, expand
+ * context, change hypothesis, replan, escalate, or stop. No new "Recovery
+ * Brain"; just one policy.
+ */
+
+export function decideRecovery({
+  failure = {},
+  attemptCount = 1,
+  sameFailureCount = 0,
+  hasContextGap = false,
+  maxAttempts = 3,
+  budgetRemaining = true,
+} = {}) {
+  if (!budgetRemaining) return { action: 'stop', reason: 'budget exhausted' }
+  if (attemptCount >= maxAttempts) return { action: 'escalate', reason: `max attempts (${maxAttempts}) reached` }
+  if (sameFailureCount >= 2) {
+    return {
+      action: hasContextGap ? 'expand_context' : 'change_hypothesis',
+      reason: `same failure repeated ${sameFailureCount} times`,
+    }
+  }
+  if (hasContextGap) return { action: 'expand_context', reason: 'missing context for root cause' }
+  if (failure.category === 'test_failure' || failure.category === 'build_failure') {
+    return { action: 'repair', reason: 'diagnose and repair with evidence' }
+  }
+  return { action: 'retry', reason: 'transient or unknown failure, retry once' }
+}
+
+export function formatRecoveryDecision(decision = {}) {
+  return `${decision.action} — ${decision.reason || ''}`
+}

package/src/task-contract.mjs

@@ -0,0 +1,51 @@
+/**
+ * TaskContract.
+ *
+ * The single immutable contract that all Omni modules consume after Decide.
+ * It replaces ad-hoc re-classification across Planner/Runtime/Verifier.
+ */
+
+import { decideIntelligenceLevel } from './progressive-intelligence.mjs'
+
+export function buildTaskContract({
+  taskText = '',
+  decision = {},
+  acceptance = [],
+  constraints = [],
+  nonGoals = [],
+  requiredCapabilities = [],
+} = {}) {
+  const intelligence = decideIntelligenceLevel(decision)
+  return {
+    objective: taskText,
+    constraints: Array.isArray(constraints) ? constraints : [],
+    nonGoals: Array.isArray(nonGoals) ? nonGoals : [],
+    acceptance: Array.isArray(acceptance) && acceptance.length ? acceptance : [`${taskText} is complete`],
+    risk: decision.risk || 'low',
+    uncertainty: decision.uncertainty ?? 0.1,
+    intelligenceLevel: intelligence.level,
+    contextBudget: decision.contextBudget || 20000,
+    verificationPolicy: {
+      level: intelligence.verification,
+      independentVerify: intelligence.independentVerify,
+      approvalRequired: intelligence.approvalRequired,
+    },
+    requiredCapabilities: Array.isArray(requiredCapabilities) && requiredCapabilities.length
+      ? requiredCapabilities
+      : (decision.evidenceRequirements || []),
+    reasoningEffort: intelligence.reasoningEffort,
+  }
+}
+
+export function formatTaskContract(contract = {}) {
+  const lines = [
+    `Objective: ${contract.objective || ''}`,
+    `Risk: ${contract.risk} | Uncertainty: ${contract.uncertainty}`,
+    `Intelligence: ${contract.intelligenceLevel}`,
+    `Verification: ${contract.verificationPolicy?.level}${contract.verificationPolicy?.independentVerify ? ' + independent' : ''}${contract.verificationPolicy?.approvalRequired ? ' + approval' : ''}`,
+    `Context budget: ${contract.contextBudget}`,
+  ]
+  if (contract.acceptance?.length) lines.push(`Acceptance:\n${contract.acceptance.map((c) => `- ${c}`).join('\n')}`)
+  if (contract.requiredCapabilities?.length) lines.push(`Required capabilities: ${contract.requiredCapabilities.join(', ')}`)
+  return lines.join('\n')
+}

package/test/context-freshness.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  attachFingerprint,
+  fingerprintFiles,
+  fingerprintText,
+  fingerprintWorkspace,
+  isContextStale,
+} from '../src/context-freshness.mjs'
+
+test('fingerprintText is deterministic', () => {
+  assert.equal(fingerprintText('abc'), fingerprintText('abc'))
+  assert.notEqual(fingerprintText('abc'), fingerprintText('abd'))
+})
+
+test('fingerprintFiles changes when content changes', () => {
+  const a = fingerprintFiles({ 'a.ts': 'x' })
+  const b = fingerprintFiles({ 'a.ts': 'y' })
+  assert.notEqual(a, b)
+})
+
+test('fingerprintWorkspace combines commit and files', () => {
+  const fp = fingerprintWorkspace({ commit: 'abc', files: { 'a.ts': 'x' } })
+  assert.ok(fp.length > 0)
+})
+
+test('attachFingerprint and isContextStale', () => {
+  const context = attachFingerprint({ files: [] }, 'fp1')
+  assert.equal(context.workspaceFingerprint, 'fp1')
+  assert.equal(isContextStale(context, 'fp1'), false)
+  assert.equal(isContextStale(context, 'fp2'), true)
+})

package/test/evidence-trust.test.mjs

@@ -0,0 +1,52 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  TRUST_LEVELS,
+  createEvidenceRecord,
+  evidenceMeetsTrust,
+  formatEvidenceTrust,
+  invalidateEvidence,
+  isEvidenceStale,
+  requiredTrustForRisk,
+} from '../src/evidence-trust.mjs'
+
+test('TRUST_LEVELS are ordered', () => {
+  assert.ok(TRUST_LEVELS.T3 > TRUST_LEVELS.T1)
+  assert.equal(TRUST_LEVELS.T4, 4)
+})
+
+test('createEvidenceRecord includes fingerprint and trust', () => {
+  const record = createEvidenceRecord({ criterionId: 'c1', workspaceFingerprint: 'fp1', trustLevel: 'T3' })
+  assert.equal(record.trustValue, 3)
+  assert.equal(record.criterionId, 'c1')
+})
+
+test('isEvidenceStale detects fingerprint mismatch', () => {
+  const record = createEvidenceRecord({ workspaceFingerprint: 'fp1' })
+  assert.equal(isEvidenceStale(record, 'fp1'), false)
+  assert.equal(isEvidenceStale(record, 'fp2'), true)
+})
+
+test('invalidateEvidence marks stale records', () => {
+  const records = [
+    createEvidenceRecord({ workspaceFingerprint: 'fp1' }),
+    createEvidenceRecord({ workspaceFingerprint: 'fp2' }),
+  ]
+  const invalidated = invalidateEvidence(records, 'fp2')
+  assert.equal(invalidated[0].stale, true)
+  assert.equal(invalidated[1].stale, false)
+})
+
+test('requiredTrustForRisk escalates for high risk', () => {
+  assert.equal(requiredTrustForRisk('low').minimum, 'T1')
+  assert.equal(requiredTrustForRisk('high').minimum, 'T3')
+  assert.equal(requiredTrustForRisk('high').independent, true)
+})
+
+test('evidenceMeetsTrust compares trust values', () => {
+  const record = createEvidenceRecord({ trustLevel: 'T3' })
+  assert.equal(evidenceMeetsTrust(record, 'T2'), true)
+  assert.equal(evidenceMeetsTrust(record, 'T4'), false)
+  assert.match(formatEvidenceTrust(record), /T3/)
+})

package/test/host-interface.test.mjs

@@ -0,0 +1,31 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  createHostAdapter,
+  describeHostCapabilities,
+  formatHostNegotiation,
+  negotiateHost,
+} from '../src/host-interface.mjs'
+
+test('createHostAdapter validates describeHost', () => {
+  const valid = createHostAdapter({ describeHost: async () => ({}) })
+  assert.equal(valid.valid, true)
+  const invalid = createHostAdapter({})
+  assert.equal(invalid.valid, false)
+  assert.ok(invalid.missing.includes('describeHost'))
+})
+
+test('describeHostCapabilities defaults to false', () => {
+  const caps = describeHostCapabilities({ workflow: true })
+  assert.equal(caps.workflow, true)
+  assert.equal(caps.skills, false)
+})
+
+test('negotiateHost reports supported and degraded features', () => {
+  const result = negotiateHost({ workflow: true, approvals: true, skills: false, plugins: false })
+  assert.ok(result.supported.includes('workflow'))
+  assert.ok(result.degraded.includes('skills'))
+  assert.equal(result.mode, 'degraded')
+  assert.match(formatHostNegotiation(result), /Host mode: degraded/)
+})

package/test/intervention-gate.test.mjs

@@ -0,0 +1,44 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  decideIntervention,
+  expectedInterventionUtility,
+  formatInterventionGate,
+  interventionEfficiency,
+  noOpPrecision,
+  shouldIntervene,
+} from '../src/intervention-gate.mjs'
+
+test('expectedInterventionUtility favors high gain low overhead', () => {
+  const high = expectedInterventionUtility({ successGain: 0.2, tokenOverhead: 0.05 })
+  const low = expectedInterventionUtility({ successGain: 0.01, tokenOverhead: 0.8 })
+  assert.ok(high > low)
+})
+
+test('shouldIntervene respects threshold', () => {
+  assert.equal(shouldIntervene(0.2, 0.1), true)
+  assert.equal(shouldIntervene(0.05, 0.1), false)
+})
+
+test('decideIntervention returns NOOP by default for low utility', () => {
+  const result = decideIntervention({ successGain: 0, tokenOverhead: 0.5 })
+  assert.equal(result.intervene, false)
+  assert.equal(result.mode, 'noop')
+  assert.match(formatInterventionGate(result), /NOOP/)
+})
+
+test('noOpPrecision measures correct no-op calls', () => {
+  const precision = noOpPrecision([
+    { predictedNoop: true, actuallyNeeded: false },
+    { predictedNoop: true, actuallyNeeded: true },
+    { predictedNoop: false, actuallyNeeded: false },
+  ])
+  assert.equal(precision, 0.5)
+})
+
+test('interventionEfficiency computes gain per overhead', () => {
+  const result = interventionEfficiency({ rawSuccess: 0.6, omniSuccess: 0.78, tokenOverhead: 0.3 })
+  assert.equal(result.gain, 0.18)
+  assert.equal(result.efficiency, 0.6)
+})

package/test/omni-event.test.mjs

@@ -0,0 +1,35 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  OMNI_EVENT_TYPES,
+  createOmniEvent,
+  normalizeHostEvent,
+} from '../src/omni-event.mjs'
+
+test('createOmniEvent builds host-independent event', () => {
+  const event = createOmniEvent({ type: 'test.completed', host: 'dsh', sessionId: 's1', taskId: 't1', workspaceFingerprint: 'fp', payload: { passed: 10 } })
+  assert.equal(event.type, 'test.completed')
+  assert.equal(event.host, 'dsh')
+  assert.equal(event.workspaceFingerprint, 'fp')
+  assert.ok(event.timestamp)
+})
+
+test('normalizeHostEvent maps DSH tool events', () => {
+  const event = normalizeHostEvent({ type: 'tool.started', name: 'edit', data: { file: 'a.ts' } }, 'dsh', { sessionId: 's', taskId: 't' })
+  assert.equal(event.type, 'tool.started')
+  assert.equal(event.sessionId, 's')
+  assert.equal(event.payload.file, 'a.ts')
+})
+
+test('normalizeHostEvent maps generic start/end to model events', () => {
+  const started = normalizeHostEvent({ type: 'start' }, 'codex')
+  const ended = normalizeHostEvent({ type: 'finished' }, 'codex')
+  assert.equal(started.type, 'model.started')
+  assert.equal(ended.type, 'model.completed')
+})
+
+test('OMNI_EVENT_TYPES is stable', () => {
+  assert.ok(OMNI_EVENT_TYPES.includes('file.changed'))
+  assert.ok(OMNI_EVENT_TYPES.includes('approval.completed'))
+})

package/test/recovery-policy.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  decideRecovery,
+  formatRecoveryDecision,
+} from '../src/recovery-policy.mjs'
+
+test('decideRecovery repairs test/build failures', () => {
+  const decision = decideRecovery({ failure: { category: 'test_failure' }, attemptCount: 1 })
+  assert.equal(decision.action, 'repair')
+})
+
+test('decideRecovery expands context when gap exists', () => {
+  const decision = decideRecovery({ failure: {}, hasContextGap: true })
+  assert.equal(decision.action, 'expand_context')
+})
+
+test('decideRecovery changes hypothesis after repeated same failure', () => {
+  const decision = decideRecovery({ failure: { category: 'test_failure' }, sameFailureCount: 2, hasContextGap: false })
+  assert.equal(decision.action, 'change_hypothesis')
+})
+
+test('decideRecovery escalates after max attempts', () => {
+  const decision = decideRecovery({ attemptCount: 4, maxAttempts: 3 })
+  assert.equal(decision.action, 'escalate')
+})
+
+test('decideRecovery stops when budget exhausted', () => {
+  const decision = decideRecovery({ budgetRemaining: false })
+  assert.equal(decision.action, 'stop')
+  assert.match(formatRecoveryDecision(decision), /stop/)
+})

package/test/task-contract.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  buildTaskContract,
+  formatTaskContract,
+} from '../src/task-contract.mjs'
+
+test('buildTaskContract produces a single unified contract', () => {
+  const contract = buildTaskContract({
+    taskText: 'Fix payment race',
+    decision: { complexity: 'plan', risk: 'high', type: 'bugfix' },
+    acceptance: ['no double charge', 'tests pass'],
+    requiredCapabilities: ['debugging', 'verification'],
+  })
+  assert.equal(contract.objective, 'Fix payment race')
+  assert.equal(contract.intelligenceLevel, 'L3')
+  assert.equal(contract.verificationPolicy.independentVerify, true)
+  assert.deepEqual(contract.acceptance, ['no double charge', 'tests pass'])
+  assert.ok(contract.requiredCapabilities.includes('verification'))
+})
+
+test('buildTaskContract fills default acceptance', () => {
+  const contract = buildTaskContract({ taskText: 'Fix typo' })
+  assert.equal(contract.acceptance.length, 1)
+  assert.match(contract.acceptance[0], /Fix typo/)
+})
+
+test('formatTaskContract renders readable summary', () => {
+  const text = formatTaskContract(buildTaskContract({ taskText: 'x' }))
+  assert.match(text, /Objective: x/)
+  assert.match(text, /Intelligence: L0/)
+})