opencode-agent-skill 9.0.0 → 11.0.0

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/browser-adapter.mjs

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+
+function depHas(pkg, name) {
+  return Boolean(pkg?.dependencies?.[name] || pkg?.devDependencies?.[name] || pkg?.optionalDependencies?.[name])
+}
+
+export async function browserCapability(root = process.cwd()) {
+  root = path.resolve(root)
+  let pkg = {}
+  try { pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) } catch {}
+  const localBin = process.platform === "win32"
+    ? path.join(root, "node_modules", ".bin", "playwright.cmd")
+    : path.join(root, "node_modules", ".bin", "playwright")
+  const packageDeclared = depHas(pkg, "@playwright/test") || depHas(pkg, "playwright")
+  const storybookDeclared = Object.keys({
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+    ...(pkg.optionalDependencies || {}),
+  }).some((name) => name === "storybook" || name.startsWith("@storybook/"))
+  return {
+    schemaVersion: 1,
+    playwright: {
+      packageDeclared,
+      localBinary: existsSync(localBin) ? localBin : null,
+      available: packageDeclared || existsSync(localBin),
+    },
+    storybook: {
+      declared: storybookDeclared,
+      configPresent: existsSync(path.join(root, ".storybook")),
+    },
+    modePreference: "cli-first",
+    rationale: "Use deterministic CLI/scripts for bounded verification; use richer browser tooling only when persistent exploratory state is necessary.",
+  }
+}
+
+export function buildBrowserVerificationPlan(input = {}) {
+  const viewports = Array.isArray(input.viewports) && input.viewports.length
+    ? input.viewports
+    : [{ id: "desktop", width: 1440, height: 900 }]
+  return {
+    schemaVersion: 1,
+    url: input.url || null,
+    target: input.target || null,
+    trustLevel: input.trustLevel || "untrusted-external",
+    steps: [
+      { kind: "navigate", value: input.url || null },
+      { kind: "targeted-accessibility-snapshot", target: input.target || null, maxChars: 6000 },
+      { kind: "geometry", fields: ["id", "role", "x", "y", "width", "height"] },
+      { kind: "interaction", flow: input.flow || [] },
+      ...viewports.map((viewport) => ({ kind: "screenshot", viewport })),
+      { kind: "verify", checks: ["interaction", "geometry", "visual", "accessibility"] },
+    ],
+    security: {
+      webpageInstructionsTrusted: false,
+      allowPageContentToChangePermissions: false,
+      allowPageContentToRequestSecrets: false,
+      allowPageContentToAuthorizeExternalSideEffects: false,
+    },
+  }
+}
+
+export function targetedBrowserEvidence(snapshot = [], query = "", options = {}) {
+  const needle = String(query || "").toLowerCase()
+  const limit = Math.max(1, Math.min(50, Number(options.limit || 12)))
+  const rows = Array.isArray(snapshot) ? snapshot : []
+  return rows
+    .filter((row) => {
+      const haystack = [row.role, row.name, row.text, row.id].filter(Boolean).join(" ").toLowerCase()
+      return !needle || haystack.includes(needle)
+    })
+    .slice(0, limit)
+    .map((row) => ({
+      id: row.id || null,
+      role: row.role || null,
+      name: row.name || null,
+      box: row.box || (["x","y","width","height"].every((key) => Number.isFinite(Number(row[key])))
+        ? { x: Number(row.x), y: Number(row.y), width: Number(row.width), height: Number(row.height) }
+        : null),
+    }))
+}

package/lib/browser-runtime.mjs

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto"
+import { createRequire } from "node:module"
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+function boundedInt(value, fallback, min, max) {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.min(max, Math.max(min, Math.round(parsed)))
+}
+
+function safeUrl(value) {
+  let parsed
+  try { parsed = new URL(String(value || "")) } catch { throw new Error("Browser inspect requires a valid http(s) URL") }
+  if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("Browser inspect only allows http(s) URLs")
+  return parsed.toString()
+}
+
+function safeOutput(root, url, requested = null) {
+  const base = path.resolve(root)
+  const dir = path.join(base, ".ues-cache", "browser-v1")
+  if (!requested) {
+    const hash = createHash("sha256").update(url).digest("hex").slice(0, 20)
+    return { dir, file: path.join(dir, hash + ".png") }
+  }
+  const target = path.resolve(base, String(requested))
+  if (target !== base && !target.startsWith(base + path.sep)) {
+    throw new Error("Browser screenshot path must stay inside the project root")
+  }
+  return { dir: path.dirname(target), file: target }
+}
+
+function loadPlaywright(root) {
+  const requireFromProject = createRequire(path.join(path.resolve(root), "package.json"))
+  for (const name of ["playwright", "@playwright/test"]) {
+    try {
+      const mod = requireFromProject(name)
+      if (mod?.chromium) return mod
+      if (mod?.default?.chromium) return mod.default
+    } catch {}
+  }
+  throw new Error("Playwright is unavailable in this project. Add playwright or @playwright/test before browser inspection.")
+}
+
+function roleForElement(el) {
+  const explicit = el.getAttribute("role")
+  if (explicit) return explicit
+  const tag = el.tagName.toLowerCase()
+  const type = (el.getAttribute("type") || "").toLowerCase()
+  if (tag === "button") return "button"
+  if (tag === "a" && el.hasAttribute("href")) return "link"
+  if (tag === "img") return "img"
+  if (/^h[1-6]$/.test(tag)) return "heading"
+  if (tag === "input") {
+    if (["button","submit","reset"].includes(type)) return "button"
+    if (type === "checkbox") return "checkbox"
+    if (type === "radio") return "radio"
+    return "textbox"
+  }
+  if (tag === "textarea") return "textbox"
+  if (tag === "select") return "combobox"
+  return tag
+}
+
+export async function inspectBrowserPage(root = process.cwd(), url, options = {}) {
+  root = path.resolve(root)
+  const targetUrl = safeUrl(url)
+  const maxElements = boundedInt(options.maxElements, 80, 1, 250)
+  const timeoutMs = boundedInt(options.timeoutMs, 30_000, 1_000, 120_000)
+  const viewport = {
+    width: boundedInt(options.width, 1440, 240, 7680),
+    height: boundedInt(options.height, 900, 240, 4320),
+  }
+  const output = safeOutput(root, targetUrl, options.screenshot)
+  await mkdir(output.dir, { recursive: true })
+
+  const playwright = loadPlaywright(root)
+  const browser = await playwright.chromium.launch({ headless: true })
+  let page
+  try {
+    page = await browser.newPage({ viewport })
+    await page.goto(targetUrl, { waitUntil: options.waitUntil || "domcontentloaded", timeout: timeoutMs })
+    if (options.waitMs) await page.waitForTimeout(boundedInt(options.waitMs, 0, 0, 15_000))
+
+    const selector = options.selector ? String(options.selector) : null
+    const raw = await page.evaluate(({ maxElements, selector }) => {
+      const clean = (value, max = 180) => String(value || "").replace(/\s+/g, " ").trim().slice(0, max)
+      const candidateSelector = selector || [
+        "button","a[href]","input","textarea","select","img",
+        "h1","h2","h3","h4","h5","h6",
+        "[role]","[tabindex]","[data-testid]"
+      ].join(",")
+      let nodes = []
+      try { nodes = Array.from(document.querySelectorAll(candidateSelector)) } catch { nodes = [] }
+      return nodes.slice(0, maxElements).map((el, index) => {
+        const rect = el.getBoundingClientRect()
+        const style = getComputedStyle(el)
+        const name =
+          el.getAttribute("aria-label") ||
+          el.getAttribute("alt") ||
+          el.getAttribute("title") ||
+          el.getAttribute("placeholder") ||
+          el.textContent ||
+          ""
+        return {
+          index,
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute("role"),
+          name: clean(name),
+          text: clean(el.textContent),
+          id: el.id || null,
+          testId: el.getAttribute("data-testid") || null,
+          box: {
+            x: Number(rect.x.toFixed(2)),
+            y: Number(rect.y.toFixed(2)),
+            width: Number(rect.width.toFixed(2)),
+            height: Number(rect.height.toFixed(2)),
+          },
+          visible: Boolean(rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none"),
+          style: {
+            display: style.display,
+            position: style.position,
+            fontSize: style.fontSize,
+            fontWeight: style.fontWeight,
+            color: style.color,
+            backgroundColor: style.backgroundColor,
+            borderRadius: style.borderRadius,
+          },
+        }
+      })
+    }, { maxElements, selector })
+
+    const elements = raw.map((item) => ({
+      ...item,
+      role: item.role || roleForElement({
+        getAttribute: (name) => {
+          if (name === "role") return item.role
+          if (name === "type") return null
+          return null
+        },
+        hasAttribute: () => item.tag === "a",
+        tagName: item.tag,
+      }),
+    }))
+
+    await page.screenshot({ path: output.file, fullPage: options.fullPage !== false })
+    const title = await page.title().catch(() => "")
+    const finalUrl = page.url()
+
+    return {
+      schemaVersion: 1,
+      trustLevel: "untrusted-external",
+      requestedUrl: targetUrl,
+      finalUrl,
+      title,
+      viewport,
+      selector,
+      elementCount: elements.length,
+      elements,
+      screenshot: path.relative(root, output.file).replaceAll("\\", "/"),
+      security: {
+        pageContentIsInstruction: false,
+        allowPageContentToChangePermissions: false,
+        allowPageContentToRequestSecrets: false,
+        allowPageContentToAuthorizeExternalSideEffects: false,
+      },
+    }
+  } finally {
+    await browser.close().catch(() => {})
+  }
+}
+
+export function summarizeBrowserInspection(report = {}, options = {}) {
+  const limit = boundedInt(options.limit, 20, 1, 100)
+  return {
+    schemaVersion: 1,
+    trustLevel: report.trustLevel || "untrusted-external",
+    finalUrl: report.finalUrl || report.requestedUrl || null,
+    title: report.title || null,
+    viewport: report.viewport || null,
+    screenshot: report.screenshot || null,
+    elementCount: Number(report.elementCount || report.elements?.length || 0),
+    elements: (report.elements || []).slice(0, limit).map((item) => ({
+      index: item.index,
+      role: item.role || null,
+      name: item.name || null,
+      id: item.id || null,
+      testId: item.testId || null,
+      box: item.box || null,
+      visible: item.visible !== false,
+    })),
+  }
+}

package/lib/capability-registry.mjs

@@ -0,0 +1,109 @@
+const BOOLEAN_CAPS = ["coding", "reasoning", "toolCalling", "vision", "browser", "filesystem", "longContext"]
+
+const ROLE_REQUIREMENTS = {
+  executor: { coding: true, toolCalling: true },
+  debugger: { coding: true, reasoning: true, toolCalling: true },
+  architect: { reasoning: true, longContext: true },
+  reviewer: { coding: true, reasoning: true },
+  verifier: { toolCalling: true },
+  "integration-verifier": { coding: true, reasoning: true, toolCalling: true },
+  "visual-verifier": { vision: true },
+  "merge-arbiter": { coding: true, reasoning: true, toolCalling: true },
+}
+
+function uniq(values) {
+  return [...new Set(values.filter(Boolean))]
+}
+
+export function inferTaskCapabilities(text, facts = {}) {
+  const value = String(text || "").toLowerCase()
+  const required = {
+    coding: facts.coding !== false,
+    reasoning: facts.reasoning === true || /(architect|design decision|root cause|complex|high-risk|kiến trúc|nguyên nhân gốc)/.test(value),
+    toolCalling: facts.toolCalling !== false,
+    vision: facts.vision === true || /(screenshot|image reference|figma|visual fidelity|pixel|ảnh mẫu|hình ảnh|giao diện giống)/.test(value),
+    browser: facts.browser === true || /(playwright|browser|e2e|web page|click|form flow|trình duyệt)/.test(value),
+    filesystem: facts.filesystem !== false,
+    longContext: facts.longContext === true || /(whole repo|entire project|large refactor|long-horizon|toàn bộ dự án|tác vụ dài)/.test(value),
+  }
+  const tags = []
+  if (required.vision) tags.push("vision")
+  if (required.browser) tags.push("browser")
+  if (/(figma|design token|design source|ảnh mẫu)/.test(value)) tags.push("design-source")
+  if (/(responsive|breakpoint|mobile|tablet|viewport)/.test(value)) tags.push("responsive")
+  if (/(storybook|visual regression|snapshot)/.test(value)) tags.push("component-visual-testing")
+  if (/(untrusted page|prompt injection|web content injection)/.test(value)) tags.push("browser-security")
+  return { schemaVersion: 1, required, tags: uniq(tags) }
+}
+
+export function normalizeCapabilityProfile(profile = {}) {
+  const normalized = {}
+  for (const key of BOOLEAN_CAPS) normalized[key] = profile[key] === true
+  return {
+    ...normalized,
+    latencyClass: ["fast", "medium", "slow"].includes(profile.latencyClass) ? profile.latencyClass : "medium",
+    costClass: ["low", "medium", "high"].includes(profile.costClass) ? profile.costClass : "medium",
+    quality: Number.isFinite(Number(profile.quality)) ? Math.max(0, Math.min(1, Number(profile.quality))) : 0.5,
+  }
+}
+
+function classPenalty(value, order) {
+  const index = order.indexOf(value)
+  return index < 0 ? 1 : index
+}
+
+function tierPenalty(tier, preferredTier) {
+  const order = ["light", "standard", "heavy"]
+  const current = Math.max(0, order.indexOf(tier))
+  const preferred = Math.max(0, order.indexOf(preferredTier))
+  return Math.max(0, current - preferred)
+}
+
+export function selectCapabilityCandidate(requirements = {}, candidates = [], options = {}) {
+  const required = { ...(ROLE_REQUIREMENTS[options.role] || {}), ...(requirements.required || requirements) }
+  const rows = candidates.map((candidate) => {
+    const profile = normalizeCapabilityProfile(candidate.capabilities || {})
+    const missing = Object.entries(required)
+      .filter(([key, needed]) => needed === true && BOOLEAN_CAPS.includes(key) && !profile[key])
+      .map(([key]) => key)
+    const score =
+      profile.quality * 100 -
+      classPenalty(profile.costClass, ["low", "medium", "high"]) * 8 -
+      classPenalty(profile.latencyClass, ["fast", "medium", "slow"]) * 5 -
+      tierPenalty(candidate.tier, options.preferredTier || candidate.tier) * 25
+    return { ...candidate, capabilities: profile, missing, eligible: missing.length === 0, score }
+  })
+  const eligible = rows.filter((item) => item.eligible).sort((a, b) => b.score - a.score)
+  return {
+    selected: eligible[0] || null,
+    candidates: rows,
+    required,
+    fallbackNeeded: eligible.length === 0,
+  }
+}
+
+export function modelCandidatesFromPolicy(policy = {}) {
+  const seen = new Set()
+  const output = []
+  for (const tier of ["light", "standard", "heavy"]) {
+    const model = policy.tiers?.[tier]
+    if (!model || seen.has(model)) continue
+    seen.add(model)
+    output.push({
+      id: model,
+      tier,
+      capabilities: policy.capabilities?.[model] || {
+        coding: true,
+        reasoning: tier !== "light",
+        toolCalling: true,
+        filesystem: true,
+        longContext: tier === "heavy",
+      },
+    })
+  }
+  return output
+}
+
+export function roleCapabilityRequirements(role) {
+  return { ...(ROLE_REQUIREMENTS[role] || {}) }
+}

package/lib/context-engine-v11.mjs

@@ -0,0 +1,146 @@
+import { buildContextManifest } from "./context-manifest.mjs"
+import { planEvidenceBudget, evidenceValueScore } from "./evidence-budget.mjs"
+import { putEvidence } from "./evidence-store.mjs"
+import { inferTaskCapabilities } from "./capability-registry.mjs"
+import { buildPromptEnvelope, comparePromptEnvelopes } from "./prompt-cache.mjs"
+
+function taskText(task = {}) {
+  return [
+    task.title,
+    task.summary,
+    ...(task.acceptance || []),
+    ...(task.verification || []),
+  ].filter(Boolean).join(" ")
+}
+
+function rankExcerpt(item = {}, task = {}) {
+  const text = taskText(task).toLowerCase()
+  const pathValue = String(item.path || "").toLowerCase()
+  const declared = item.role === "declared" ? 1 : 0
+  const test = item.role === "test" ? 0.9 : 0
+  const instruction = item.role === "instruction" ? 0.85 : 0
+  const pathMatch = text && pathValue
+    ? text.split(/[^a-z0-9_$.-]+/i).filter((term) => term.length >= 4 && pathValue.includes(term.toLowerCase())).length
+    : 0
+  const relevance = Math.min(1, declared + test + instruction + pathMatch * 0.15)
+  return evidenceValueScore({
+    relevance,
+    freshness: 1,
+    confidence: item.role === "reference" ? 0.7 : 1,
+    chars: String(item.text || "").length || 1,
+  })
+}
+
+export async function externalizeContextExcerpts(root, manifest, options = {}) {
+  if (!manifest) return { manifest: null, externalized: [], externalizedBytes: 0 }
+  const threshold = Math.max(512, Number(options.threshold || 2_500))
+  const keepInline = Math.max(256, Number(options.inlineChars || 1_200))
+  const externalized = []
+  let externalizedBytes = 0
+  const excerpts = []
+
+  for (const item of manifest.excerpts || []) {
+    const text = String(item.text || "")
+    if (text.length <= threshold) {
+      excerpts.push(item)
+      continue
+    }
+
+    const stored = await putEvidence(root, text, {
+      kind: "context-excerpt",
+      source: item.path || null,
+      summary: `Externalized ${item.role || "reference"} context excerpt for ${item.path || "unknown"}`,
+    })
+    externalized.push({
+      ref: stored.ref,
+      path: item.path || null,
+      role: item.role || null,
+      bytes: stored.bytes,
+      score: Number(rankExcerpt(item, options.task).toFixed(8)),
+    })
+    externalizedBytes += stored.bytes
+    excerpts.push({
+      ...item,
+      text: text.slice(0, keepInline) + "\n...[externalized: " + stored.ref + "]",
+      evidenceRef: stored.ref,
+      originalChars: text.length,
+      externalized: true,
+    })
+  }
+
+  return {
+    manifest: {
+      ...manifest,
+      schemaVersion: Math.max(5, Number(manifest.schemaVersion || 0)),
+      excerpts,
+      evidencePointers: externalized,
+    },
+    externalized,
+    externalizedBytes,
+  }
+}
+
+export async function buildAdaptiveTaskContext(root, task, options = {}) {
+  const policy = options.policy || {}
+  const capabilities = options.capabilities || inferTaskCapabilities(taskText(task), options.facts || {})
+  const evidenceBudget = options.evidenceBudget || planEvidenceBudget(policy, task, capabilities.required)
+  const manifest = await buildContextManifest(root, task, {
+    budget: evidenceBudget.total,
+    evidenceBudget,
+    strategy: options.strategy || policy?.profile?.contextStrategy || "incremental-semantic+git",
+    semanticMaxFiles: options.semanticMaxFiles,
+    maxFiles: options.maxFiles,
+  })
+
+  const externalized = await externalizeContextExcerpts(root, manifest, {
+    task,
+    threshold: options.externalizeThreshold,
+    inlineChars: options.inlineChars,
+  })
+
+  const promptEnvelope = buildPromptEnvelope({
+    invariants: options.invariants || "evidence-first; scoped edits; fresh verification; no unsupported completion claims",
+    role: options.role || "executor",
+    skills: options.skills || policy.domains || [],
+    projectFacts: {
+      strategy: externalized.manifest?.strategy || null,
+      instructions: externalized.manifest?.instructions || [],
+      ...(options.projectFacts || {}),
+    },
+    task,
+    evidence: [
+      ...(externalized.externalized || []).map((item) => item.ref),
+      ...(externalized.manifest?.rankedReferences || []).slice(0, 12).map((item) => item.path),
+      ...(options.evidence || []),
+    ],
+    recentFailure: options.recentFailure || null,
+    nextAction: options.nextAction || null,
+    recentMessages: options.recentMessages || [],
+  })
+
+  const cache = options.previousPromptEnvelope
+    ? comparePromptEnvelopes(options.previousPromptEnvelope, promptEnvelope)
+    : null
+
+  return {
+    schemaVersion: 1,
+    contextSchemaVersion: 6,
+    capabilities,
+    evidenceBudget,
+    contextManifest: externalized.manifest,
+    evidenceStore: {
+      refs: externalized.externalized.length,
+      externalizedBytes: externalized.externalizedBytes,
+      entries: externalized.externalized,
+    },
+    promptEnvelope,
+    promptCache: {
+      stablePrefixHash: promptEnvelope.stablePrefixHash,
+      dynamicHash: promptEnvelope.dynamicHash,
+      stableChars: promptEnvelope.stableChars,
+      dynamicChars: promptEnvelope.dynamicChars,
+      cacheableRatio: promptEnvelope.cacheableRatio,
+      ...(cache || {}),
+    },
+  }
+}

package/lib/context-manifest.mjs

@@ -243,7 +243,8 @@ async function rankedReferences(root, nodes, terms, declared, changed, limit = 2
 
 export async function buildContextManifest(root, task, options = {}) {
   root = path.resolve(root)
-  const budget = Math.max(4_000, Number(options.budget ?? 24_000))
+  const budget = Math.max(4_000, Number(options.evidenceBudget?.total ?? options.budget ?? 24_000))
+  const evidenceBudget = options.evidenceBudget || null
   const declared = taskFiles(task)
   const terms = taskTerms(task)
   const changed = gitChangedFiles(root)
@@ -331,20 +332,30 @@ export async function buildContextManifest(root, task, options = {}) {
   }
 
   let remaining = budget
+  const categoryRemaining = {
+    declared: evidenceBudget?.buckets?.declared ?? Math.round(budget * 0.42),
+    test: evidenceBudget?.buckets?.tests ?? Math.round(budget * 0.20),
+    instruction: evidenceBudget?.buckets?.instructions ?? Math.round(budget * 0.12),
+    reference: evidenceBudget?.buckets?.references ?? Math.round(budget * 0.26),
+  }
   const excerpts = []
   for (const file of priority) {
     if (remaining <= 0) break
     const isDeclared = declared.includes(file)
     const isTest = tests.includes(file)
     const isInstruction = instructions.includes(file)
+    const role = isDeclared ? "declared" : isTest ? "test" : isInstruction ? "instruction" : "reference"
     const desired = isDeclared ? 6_000 : isTest ? 4_000 : isInstruction ? 3_000 : 2_500
-    const perFile = Math.min(desired, remaining)
+    const category = Math.max(0, Number(categoryRemaining[role] || 0))
+    if (category <= 0) continue
+    const perFile = Math.min(desired, remaining, category)
     const item = await excerpt(root, file, perFile, terms)
     if (!item) continue
     remaining -= item.text.length
+    categoryRemaining[role] = Math.max(0, categoryRemaining[role] - item.text.length)
     excerpts.push({
       ...item,
-      role: isDeclared ? "declared" : isTest ? "test" : isInstruction ? "instruction" : "reference",
+      role,
     })
   }
 
@@ -373,6 +384,8 @@ export async function buildContextManifest(root, task, options = {}) {
       hotspots: graph.hotspots.slice(0, 12),
     },
     budget,
+    evidenceBudget,
+    categoryRemaining,
     used: budget - remaining,
   }
 }