opencode-agent-skill 9.0.0 → 10.0.0

package/global-config/plugins/ues-router/runtime-guard.js

@@ -0,0 +1,265 @@
+import { createHash } from "node:crypto"
+
+const EXPLORATION_TOOL = /(?:^|[._-])(read|grep|glob|repo[-_.]?graph|semantic[-_.]?search|aci[-_.]?search)(?:$|[._-])/i
+const VERIFY_OR_WRITE_TOOL = /(?:^|[._-])(edit|write|patch|bash|shell|verify|test|apply)(?:$|[._-])/i
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (!value || typeof value !== "object") return value
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, canonical(value[key])]),
+  )
+}
+
+export function stableRuntimeHash(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(canonical(value))
+  return createHash("sha256").update(text || "").digest("hex")
+}
+
+export function isExplorationTool(tool) {
+  return EXPLORATION_TOOL.test(String(tool || ""))
+}
+
+export function budgetToolResult(tool, result, options = {}) {
+  const name = String(tool || "")
+  const aggressive = /grep|glob|repo[-_.]?graph|semantic[-_.]?search/i.test(name)
+  const maxChars = Math.max(2_000, Number(options.maxChars || (aggressive ? 12_000 : 24_000)))
+  const maxLines = Math.max(40, Number(options.maxLines || (aggressive ? 160 : 360)))
+
+  if (!aggressive && !/read/i.test(name)) return result
+
+  const original = typeof result === "string" ? result : String(result?.output || "")
+  const lines = original.split(/\r?\n/)
+  if (original.length <= maxChars && lines.length <= maxLines) return result
+
+  const digest = stableRuntimeHash(original)
+  const headLineCount = Math.max(1, Math.floor(maxLines * 0.7))
+  const tailLineCount = Math.max(1, maxLines - headLineCount)
+  let bounded = [
+    ...lines.slice(0, headLineCount),
+    `...[UES tool output truncated: ${lines.length} lines / ${original.length} chars, sha256=${digest.slice(0, 16)}]...`,
+    ...lines.slice(-tailLineCount),
+  ].join("\n")
+
+  if (bounded.length > maxChars) {
+    const marker = `\n...[UES char budget applied; sha256=${digest.slice(0, 16)}]...\n`
+    const room = Math.max(0, maxChars - marker.length)
+    const head = Math.floor(room * 0.7)
+    bounded = bounded.slice(0, head) + marker + bounded.slice(-(room - head))
+  }
+
+  if (typeof result === "string") return bounded
+  return {
+    ...result,
+    output: bounded,
+    metadata: {
+      ...(result?.metadata || {}),
+      uesTruncated: true,
+      uesOriginalChars: original.length,
+      uesOriginalLines: lines.length,
+      uesOutputDigest: digest,
+    },
+  }
+}
+
+export function classifyProviderFailure(error = {}) {
+  const status = Number(error?.status ?? error?.cause?.status)
+  const type = String(error?.type || error?.code || "")
+  const message = String(error?.message || error || "")
+  const value = `${type} ${message}`.toLowerCase()
+
+  if (status === 401 || status === 403 || /auth|unauthori[sz]ed|invalid api key|credential/.test(value)) return "AUTH"
+  if (/context.{0,20}(large|length|window|overflow)|too many tokens|max(?:imum)? context/.test(value)) return "CONTEXT_TOO_LARGE"
+  if (status === 429 || /rate.?limit|too many requests/.test(value)) return "RATE_LIMIT"
+  if (/quota|credit|billing|insufficient balance/.test(value)) return "QUOTA"
+  if (/no token|no output|empty response|empty completion|returned no content|no content|stalled|no-progress/.test(value)) return "NO_TOKEN"
+  if (/timeout|timed out|deadline|abort(?:ed)?/.test(value)) return "TIMEOUT"
+  if (Number.isFinite(status) && status >= 500 && status < 600) return "PROVIDER_5XX"
+  if (/provider|upstream|gateway|service unavailable/.test(value)) return "PROVIDER_5XX"
+  return "OTHER"
+}
+
+export function progressWatchdogDecision(snapshot = {}, now = Date.now(), stallMs = 60_000) {
+  const limit = Math.max(30_000, Math.min(Number(stallMs || 60_000), 5 * 60_000))
+  const lastProgressAt = Number(snapshot.lastProgressAt || 0)
+  const activeToolCalls = Math.max(0, Number(snapshot.activeToolCalls || 0))
+  const idleMs = Math.max(0, Number(now) - lastProgressAt)
+
+  if (activeToolCalls > 0) {
+    return { stalled: false, idleMs, limitMs: limit, reason: "tool-active" }
+  }
+  return {
+    stalled: idleMs >= limit,
+    idleMs,
+    limitMs: limit,
+    reason: idleMs >= limit ? "no-progress" : "within-grace",
+  }
+}
+
+export function providerRecoveryPlan(kind, physicalAttempt = 1, options = {}) {
+  const attempt = Math.max(1, Number(physicalAttempt || 1))
+  const hasEscalationModel = Boolean(options.hasEscalationModel)
+
+  if (kind === "AUTH") return { action: "fail-fast", retry: false, reason: "authentication failure requires user/config repair" }
+  if (kind === "CONTEXT_TOO_LARGE") return { action: "compact-context", retry: false, reason: "reduce/compact context instead of repeating the same request" }
+  if (kind === "QUOTA") {
+    return hasEscalationModel
+      ? { action: "fresh-session-escalated-model", retry: true, reason: "quota exhausted on current provider/model" }
+      : { action: "fail-retryable", retry: false, reason: "quota exhausted and no configured fallback model exists" }
+  }
+
+  if (["NO_TOKEN", "TIMEOUT", "RATE_LIMIT", "PROVIDER_5XX"].includes(kind)) {
+    if (attempt <= 1) {
+      return { action: "fresh-session-same-model", retry: true, reason: "retry transport/provider stall once with fresh session state" }
+    }
+    if (hasEscalationModel) {
+      return { action: "fresh-session-escalated-model", retry: true, reason: "repeated provider failure triggers configured model/provider escalation" }
+    }
+    return { action: "fail-retryable", retry: false, reason: "repeated provider failure without configured fallback" }
+  }
+
+  return { action: "fail-task", retry: false, reason: "non-provider failure should be diagnosed by the task recovery policy" }
+}
+
+function createSessionState(now = Date.now()) {
+  return {
+    signatures: new Map(),
+    lastWorkspaceSignal: null,
+    lastEvidenceKey: null,
+    noProgressCalls: 0,
+    loopBlocked: false,
+    lastProgressAt: now,
+    activeCalls: new Set(),
+    compactionAt: null,
+  }
+}
+
+export function createRuntimeGuard(options = {}) {
+  const duplicateLimit = Math.max(2, Number(options.duplicateLimit || 3))
+  const loopLimit = Math.max(4, Number(options.loopLimit || 6))
+  const sessions = new Map()
+
+  function stateFor(sessionID, at = Date.now()) {
+    const key = String(sessionID || "global")
+    if (!sessions.has(key)) sessions.set(key, createSessionState(at))
+    return sessions.get(key)
+  }
+
+  function resetForWorkspace(state, workspaceSignal) {
+    if (state.lastWorkspaceSignal === null || state.lastWorkspaceSignal === workspaceSignal) return
+    state.signatures.clear()
+    state.noProgressCalls = 0
+    state.loopBlocked = false
+    state.lastEvidenceKey = null
+  }
+
+  return {
+    before(input = {}) {
+      const at = Number(input.now || Date.now())
+      const state = stateFor(input.sessionID, at)
+      const workspaceSignal = String(input.workspaceSignal || "")
+      resetForWorkspace(state, workspaceSignal)
+      state.lastWorkspaceSignal = workspaceSignal
+
+      const tool = String(input.tool || "")
+      if (isExplorationTool(tool)) {
+        const signature = stableRuntimeHash({ tool, input: input.input || {}, cwd: input.cwd || "", workspaceSignal })
+        const seen = state.signatures.get(signature) || { count: 0, lastResultHash: null }
+        seen.count += 1
+        state.signatures.set(signature, seen)
+
+        if (state.loopBlocked) {
+          return {
+            blocked: true,
+            code: "UES_LOOP_DETECTED",
+            message: `UES loop guard blocked repeated exploration after ${state.noProgressCalls} no-progress calls. Choose a deterministic next action: edit the scoped target, run focused verification, inspect a direct caller/failing stack, change hypothesis, or escalate recovery.`,
+            signature,
+          }
+        }
+        if (seen.count > duplicateLimit) {
+          return {
+            blocked: true,
+            code: "UES_DUPLICATE_TOOL",
+            message: `UES duplicate-tool guard blocked ${tool}: equivalent arguments were already executed ${seen.count - 1} times with no workspace change. Use the previous evidence or change the query/scope before retrying.`,
+            signature,
+          }
+        }
+      }
+
+      state.lastProgressAt = at
+      if (input.callID) state.activeCalls.add(String(input.callID))
+      return { blocked: false }
+    },
+
+    after(input = {}) {
+      const at = Number(input.now || Date.now())
+      const state = stateFor(input.sessionID, at)
+      const workspaceSignal = String(input.workspaceSignal || "")
+      const tool = String(input.tool || "")
+      if (input.callID) state.activeCalls.delete(String(input.callID))
+      resetForWorkspace(state, workspaceSignal)
+
+      if (input.status === "completed" && isExplorationTool(tool)) {
+        const resultHash = stableRuntimeHash(input.result || "")
+        const evidenceKey = stableRuntimeHash({ workspaceSignal, resultHash })
+        if (state.lastEvidenceKey === evidenceKey) {
+          state.noProgressCalls += 1
+        } else {
+          state.lastEvidenceKey = evidenceKey
+          state.noProgressCalls = 0
+        }
+        if (state.noProgressCalls >= loopLimit) state.loopBlocked = true
+
+        const signature = stableRuntimeHash({ tool, input: input.input || {}, cwd: input.cwd || "", workspaceSignal })
+        const seen = state.signatures.get(signature)
+        if (seen) seen.lastResultHash = resultHash
+      } else if (
+        input.status === "completed" &&
+        (VERIFY_OR_WRITE_TOOL.test(tool) || state.lastWorkspaceSignal !== workspaceSignal)
+      ) {
+        state.noProgressCalls = 0
+        state.loopBlocked = false
+        state.lastEvidenceKey = null
+        state.signatures.clear()
+      }
+
+      state.lastWorkspaceSignal = workspaceSignal
+      state.lastProgressAt = at
+      return {
+        loopBlocked: state.loopBlocked,
+        noProgressCalls: state.noProgressCalls,
+        lastProgressAt: state.lastProgressAt,
+      }
+    },
+
+    touch(sessionID, at = Date.now()) {
+      const state = stateFor(sessionID, at)
+      state.lastProgressAt = Number(at)
+    },
+
+    compacted(sessionID, at = Date.now()) {
+      const state = stateFor(sessionID, at)
+      state.compactionAt = Number(at)
+      state.lastProgressAt = Number(at)
+      state.signatures.clear()
+      state.noProgressCalls = 0
+      state.loopBlocked = false
+      state.lastEvidenceKey = null
+    },
+
+    snapshot(sessionID) {
+      const state = stateFor(sessionID)
+      return {
+        noProgressCalls: state.noProgressCalls,
+        loopBlocked: state.loopBlocked,
+        lastProgressAt: state.lastProgressAt,
+        activeToolCalls: state.activeCalls.size,
+        compactionAt: state.compactionAt,
+      }
+    },
+
+    clear(sessionID) {
+      sessions.delete(String(sessionID || "global"))
+    },
+  }
+}

package/lib/benchmark-confidence.mjs

@@ -24,6 +24,14 @@ function mean(values) {
   return usable.length ? usable.reduce((sum, value) => sum + value, 0) / usable.length : null
 }
 
+function positiveMean(values) {
+  return mean(values.map(Number).filter((value) => Number.isFinite(value) && value > 0))
+}
+
+function ratio(candidate, reference) {
+  return reference && candidate ? candidate / reference : null
+}
+
 export function pairedBenchmarkConfidence(results, options = {}) {
   const byKey = new Map()
   for (const item of results || []) {
@@ -71,25 +79,41 @@ export function pairedBenchmarkConfidence(results, options = {}) {
     item.delta = item.uesPassRate - item.baselinePassRate
   }
 
-  const baselineDurations = pairs.map((pair) => Number(pair.baseline.durationMs))
-  const uesDurations = pairs.map((pair) => Number(pair.ues.durationMs))
-  const baselineDuration = mean(baselineDurations)
-  const uesDuration = mean(uesDurations)
-  const durationRatio = baselineDuration && uesDuration ? uesDuration / baselineDuration : null
+  const baselineDuration = mean(pairs.map((pair) => Number(pair.baseline.durationMs)))
+  const uesDuration = mean(pairs.map((pair) => Number(pair.ues.durationMs)))
+  const durationRatio = ratio(uesDuration, baselineDuration)
 
-  const baselineCosts = pairs.map((pair) => Number(pair.baseline.telemetry?.cost)).filter((value) => value > 0)
-  const uesCosts = pairs.map((pair) => Number(pair.ues.telemetry?.cost)).filter((value) => value > 0)
-  const baselineCost = mean(baselineCosts)
-  const uesCost = mean(uesCosts)
-  const costRatio = baselineCost && uesCost ? uesCost / baselineCost : null
+  const baselineCost = positiveMean(pairs.map((pair) => pair.baseline.telemetry?.cost))
+  const uesCost = positiveMean(pairs.map((pair) => pair.ues.telemetry?.cost))
+  const costRatio = ratio(uesCost, baselineCost)
+
+  const baselineInitialInput = positiveMean(
+    pairs.map((pair) => pair.baseline.telemetry?.firstUsage?.input),
+  )
+  const uesInitialInput = positiveMean(
+    pairs.map((pair) => pair.ues.telemetry?.firstUsage?.input),
+  )
+  const initialInputRatio = ratio(uesInitialInput, baselineInitialInput)
+
+  const baselineTokens = positiveMean(
+    pairs.map((pair) => pair.baseline.telemetry?.tokens?.total),
+  )
+  const uesTokens = positiveMean(
+    pairs.map((pair) => pair.ues.telemetry?.tokens?.total),
+  )
+  const tokenRatio = ratio(uesTokens, baselineTokens)
 
   const minPairs = Math.max(1, Number(options.minPairs || 20))
   const alpha = Math.min(0.5, Math.max(0.0001, Number(options.alpha || 0.05)))
   const minDelta = Math.max(0, Number(options.minDelta || 0))
   const suiteRegressionTolerance = Math.max(0, Number(options.suiteRegressionTolerance || 0))
   const maxDurationRatio = Math.max(1, Number(options.maxDurationRatio || 1.75))
+  const maxInitialInputRatio = Math.max(1, Number(options.maxInitialInputRatio || 1.5))
+  const maxTokenRatio = Math.max(1, Number(options.maxTokenRatio || 1.75))
   const noSuiteRegression = Object.values(suites).every((item) => item.delta >= -suiteRegressionTolerance)
   const speedAcceptable = durationRatio == null || durationRatio <= maxDurationRatio
+  const initialInputAcceptable = initialInputRatio == null || initialInputRatio <= maxInitialInputRatio
+  const tokensAcceptable = tokenRatio == null || tokenRatio <= maxTokenRatio
 
   const checks = {
     pairedCoverage: total >= minPairs,
@@ -98,9 +122,11 @@ export function pairedBenchmarkConfidence(results, options = {}) {
     statisticallySupported: pValue <= alpha,
     noSuiteRegression,
     speedAcceptable,
+    initialInputAcceptable,
+    tokensAcceptable,
   }
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     kind: "ues-paired-benchmark-confidence",
     pairs: total,
     bothPass,
@@ -123,6 +149,18 @@ export function pairedBenchmarkConfidence(results, options = {}) {
       ratio: durationRatio,
       maxRatio: maxDurationRatio,
     },
+    initialInput: {
+      baselineMeanTokens: baselineInitialInput,
+      uesMeanTokens: uesInitialInput,
+      ratio: initialInputRatio,
+      maxRatio: maxInitialInputRatio,
+    },
+    tokens: {
+      baselineMean: baselineTokens,
+      uesMean: uesTokens,
+      ratio: tokenRatio,
+      maxRatio: maxTokenRatio,
+    },
     cost: {
       baselineMean: baselineCost,
       uesMean: uesCost,

package/lib/eval-ablation.mjs

@@ -0,0 +1,104 @@
+function finite(value) {
+  if (value === null || value === undefined || value === "") return null
+  const number = Number(value)
+  return Number.isFinite(number) ? number : null
+}
+
+function modeSummary(value) {
+  return value?.summary?.modes?.ues || value?.modes?.ues || null
+}
+
+function ratio(candidate, reference) {
+  return candidate != null && reference != null && reference > 0
+    ? candidate / reference
+    : null
+}
+
+function delta(candidate, reference) {
+  return candidate != null && reference != null ? candidate - reference : null
+}
+
+export function compareEvalSummaries(reference, candidate, options = {}) {
+  const ref = modeSummary(reference)
+  const next = modeSummary(candidate)
+  if (!ref || !next) throw new Error("reference and candidate must contain a UES mode summary")
+
+  const passRateTolerance = Math.max(0, Number(options.passRateTolerance || 0))
+  const minInitialInputReduction = Math.max(0, Number(options.minInitialInputReduction ?? 0.10))
+  const maxTotalTokenRatio = Math.max(0.01, Number(options.maxTotalTokenRatio || 1.05))
+  const maxDurationRatio = Math.max(0.01, Number(options.maxDurationRatio || 1.10))
+
+  const referencePassRate = finite(ref.passRate)
+  const candidatePassRate = finite(next.passRate)
+  const referenceInitialInput = finite(ref.avgInitialInputTokens)
+  const candidateInitialInput = finite(next.avgInitialInputTokens)
+  const referenceTokens = finite(ref.avgTokens)
+  const candidateTokens = finite(next.avgTokens)
+  const referenceDuration = finite(ref.avgDurationMs)
+  const candidateDuration = finite(next.avgDurationMs)
+
+  const initialInputRatio = ratio(candidateInitialInput, referenceInitialInput)
+  const tokenRatio = ratio(candidateTokens, referenceTokens)
+  const durationRatio = ratio(candidateDuration, referenceDuration)
+
+  const checks = {
+    passRatePreserved:
+      referencePassRate != null &&
+      candidatePassRate != null &&
+      candidatePassRate >= referencePassRate - passRateTolerance,
+    initialInputReduced:
+      initialInputRatio == null
+        ? null
+        : initialInputRatio <= 1 - minInitialInputReduction,
+    totalTokensBounded:
+      tokenRatio == null ? null : tokenRatio <= maxTotalTokenRatio,
+    durationBounded:
+      durationRatio == null ? null : durationRatio <= maxDurationRatio,
+  }
+
+  const efficiencyEvidence = [
+    checks.initialInputReduced,
+    checks.totalTokensBounded,
+    checks.durationBounded,
+  ].filter((value) => value !== null)
+
+  return {
+    schemaVersion: 1,
+    kind: "ues-eval-ablation",
+    thresholds: {
+      passRateTolerance,
+      minInitialInputReduction,
+      maxTotalTokenRatio,
+      maxDurationRatio,
+    },
+    reference: {
+      passRate: referencePassRate,
+      avgInitialInputTokens: referenceInitialInput,
+      avgTokens: referenceTokens,
+      avgDurationMs: referenceDuration,
+    },
+    candidate: {
+      passRate: candidatePassRate,
+      avgInitialInputTokens: candidateInitialInput,
+      avgTokens: candidateTokens,
+      avgDurationMs: candidateDuration,
+    },
+    delta: {
+      passRate: delta(candidatePassRate, referencePassRate),
+      avgInitialInputTokens: delta(candidateInitialInput, referenceInitialInput),
+      avgTokens: delta(candidateTokens, referenceTokens),
+      avgDurationMs: delta(candidateDuration, referenceDuration),
+    },
+    ratios: {
+      initialInput: initialInputRatio,
+      totalTokens: tokenRatio,
+      duration: durationRatio,
+    },
+    checks,
+    telemetrySufficient: checks.initialInputReduced !== null,
+    gateEligible:
+      checks.passRatePreserved === true &&
+      checks.initialInputReduced === true &&
+      efficiencyEvidence.every((value) => value === true),
+  }
+}

package/lib/eval-report.mjs

@@ -10,6 +10,8 @@ export function summarizeEvalResults(results) {
       toolSamples: 0,
       tokens: 0,
       tokenSamples: 0,
+      initialInputTokens: 0,
+      initialInputSamples: 0,
       cost: 0,
       costSamples: 0,
     }
@@ -25,6 +27,11 @@ export function summarizeEvalResults(results) {
       bucket.tokens += Number(item.telemetry?.tokens?.total) || 0
       bucket.tokenSamples += 1
     }
+    const initialInput = Number(item.telemetry?.firstUsage?.input)
+    if (Number.isFinite(initialInput)) {
+      bucket.initialInputTokens += initialInput
+      bucket.initialInputSamples += 1
+    }
     if ((item.telemetry?.costSamples || 0) > 0) {
       bucket.cost += Number(item.telemetry?.cost) || 0
       bucket.costSamples += 1
@@ -36,10 +43,12 @@ export function summarizeEvalResults(results) {
     bucket.avgDurationMs = bucket.total ? bucket.durationMs / bucket.total : 0
     bucket.avgToolCalls = bucket.toolSamples ? bucket.toolCalls / bucket.toolSamples : null
     bucket.avgTokens = bucket.tokenSamples ? bucket.tokens / bucket.tokenSamples : null
+    bucket.avgInitialInputTokens = bucket.initialInputSamples ? bucket.initialInputTokens / bucket.initialInputSamples : null
     bucket.avgCost = bucket.costSamples ? bucket.cost / bucket.costSamples : null
     bucket.telemetryCoverage = {
       tools: bucket.total ? bucket.toolSamples / bucket.total : 0,
       tokens: bucket.total ? bucket.tokenSamples / bucket.total : 0,
+      initialInputTokens: bucket.total ? bucket.initialInputSamples / bucket.total : 0,
       cost: bucket.total ? bucket.costSamples / bucket.total : 0,
     }
     delete bucket.durationMs
@@ -47,6 +56,8 @@ export function summarizeEvalResults(results) {
     delete bucket.toolSamples
     delete bucket.tokens
     delete bucket.tokenSamples
+    delete bucket.initialInputTokens
+    delete bucket.initialInputSamples
     delete bucket.cost
     delete bucket.costSamples
   }

package/lib/eval-telemetry.mjs

@@ -92,6 +92,7 @@ export function parseOpenCodeTelemetry(stdout) {
   let cost = 0
   let usageSamples = 0
   let costSamples = 0
+  let firstUsage = null
 
   parsed.forEach((event, eventIndex) => {
     let eventUsage = null
@@ -130,6 +131,7 @@ export function parseOpenCodeTelemetry(stdout) {
     })
 
     if (eventUsage) {
+      if (!firstUsage && eventUsage.input > 0) firstUsage = { ...eventUsage }
       usageSamples += 1
       tokens.input += eventUsage.input
       tokens.output += eventUsage.output
@@ -151,6 +153,7 @@ export function parseOpenCodeTelemetry(stdout) {
     skillsLoaded: [...skills].sort(),
     subagents: [...subagents].sort(),
     tokens,
+    firstUsage,
     usageSamples,
     cost,
     costSamples,

package/lib/model-policy.mjs

@@ -58,11 +58,17 @@ export function resolveAdaptiveModel(role, attempt, taskPolicy = {}, config = {}
     ...config,
     roleTiers: { ...(config.roleTiers || {}), [role]: baseTier },
   })
+  const normalizedAttempt = Math.max(1, Number(attempt || 1))
   return {
     ...resolved,
+    recoveryStage:
+      normalizedAttempt <= 1 ? "initial" :
+      normalizedAttempt === 2 ? "diagnose" :
+      "deep-recovery",
     policy: {
       mode: taskPolicy.mode || null,
       risk: taskPolicy.risk || null,
+      executionProfile: taskPolicy.executionProfile || null,
       score: Number(taskPolicy.score || 0),
       maxAttempts: Number(taskPolicy.maxAttempts || 0) || null,
       contextBudget: Number(taskPolicy.contextBudget || 0) || null,