opencode-agent-skill 9.0.0 → 11.0.0

package/bin/ocskill.mjs

@@ -54,16 +54,27 @@ import {
   createPlanVerificationReceipt,
   createIntegrationVerificationReceipt,
   runtimeEvents,
+  checkpointWork,
+  markCheckpointResumed,
 } from "../lib/task-engine.mjs"
 import { reviewScope } from "../lib/review-scope.mjs"
 import { buildVerificationPlan } from "../lib/verification-plan.mjs"
-import { resolveAdaptiveModel, resolveModel } from "../lib/model-policy.mjs"
+import { resolveAdaptiveModel, resolveCapabilityModel, resolveModel } from "../lib/model-policy.mjs"
 import { createVerificationReceipt } from "../lib/evidence-receipt.mjs"
 import { classifyEngineeringTask } from "../lib/orchestrator-policy.mjs"
 import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskSandbox } from "../lib/worktree-sandbox.mjs"
 import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
-import { hermesStatus, buildHermesDelegationPrompt, hermesOneShotArgs } from "../lib/hermes-bridge.mjs"
+import { hermesStatus, buildHermesDelegationPrompt, buildHermesWorkflowPrompt, hermesOneShotArgs, hermesSidecarPlan } from "../lib/hermes-bridge.mjs"
 import { readModelPolicy, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
+import { evidenceStoreStatus, gcEvidenceStore, getEvidence, putEvidence } from "../lib/evidence-store.mjs"
+import { inferTaskCapabilities } from "../lib/capability-registry.mjs"
+import { browserCapability, buildBrowserVerificationPlan } from "../lib/browser-adapter.mjs"
+import { inspectBrowserPage, summarizeBrowserInspection } from "../lib/browser-runtime.mjs"
+import { comparePngFiles, cropPngFile } from "../lib/png-diff.mjs"
+import { createGeometryReceipt, responsiveViewportMatrix, validateVisualSpec } from "../lib/visual-spec.mjs"
+import { planDynamicWorkflow } from "../lib/dynamic-workflow.mjs"
+import { lintSkillCatalog } from "../lib/skill-quality.mjs"
+import { designTokenEvidence, extractDesignTokens, inspectResponsiveLayout } from "../lib/ui-inspector.mjs"
 import {
   clipOutput,
   errorMessage,
@@ -115,7 +126,14 @@ Usage:
   ocskill sandbox <action> ...  Create, integrate and clean isolated Git worktree sandboxes
                               Also supports capability/exec for fail-closed container verification
   ocskill learn <action> ...    Analyze eval traces and promote benchmark-validated lessons
-  ocskill hermes <action> ...   Optional Hermes adapter/status
+  ocskill hermes <action> ...   Optional Hermes sidecar/status/task/workflow planning
+  ocskill store <status|put|get|gc> ... Content-addressed evidence storage and bounded retrieval
+  ocskill capabilities <text>     Infer required execution/model capabilities
+  ocskill visual <action> ...     Geometry receipts, PNG diff/crop and viewport matrix
+  ocskill browser <action> ...    Browser capability, plan and bounded Playwright inspection
+  ocskill ui <tokens|layout> ...  Extract design tokens or verify responsive geometry
+  ocskill workflow-plan <plan>    Cost-aware deterministic/LLM/vision wave schedule
+  ocskill skills lint [dir]       Lint skill size, metadata and routing-description collisions
   ocskill dashboard [dir] [--serve] [--port N]
                               Generate/serve the local UES Control Center
   ocskill models <status|on|off|set|role> ...
@@ -152,6 +170,7 @@ Usage:
     ocskill models on|off
     ocskill models set <light|standard|heavy> <provider/model[#variant]>
     ocskill models role <role> <light|standard|heavy>
+    ocskill models capability <provider/model> [--vision on|off] [--browser on|off] [--reasoning on|off] [--long-context on|off] [--cost low|medium|high] [--latency fast|medium|slow] [--quality 0..1]
 
   --force backs up and replaces/removes state owned by another package.
 `)
@@ -589,6 +608,28 @@ async function workControl() {
       }))
       return
     }
+    if (action === "checkpoint") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work checkpoint <slug> <task-id> [dir] --run-id <id> [--reason <text>]")
+      printJson(await checkpointWork(root, slug, {
+        taskID,
+        runId: optionValue(args, "--run-id"),
+        reason: optionValue(args, "--reason") || "pre-compaction",
+      }))
+      return
+    }
+    if (action === "checkpoint-resumed") {
+      const taskID = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!taskID) throw new Error("Usage: ocskill work checkpoint-resumed <slug> <task-id> [dir] --run-id <id> [--reason <text>]")
+      printJson(await markCheckpointResumed(root, slug, {
+        taskID,
+        runId: optionValue(args, "--run-id"),
+        reason: optionValue(args, "--reason"),
+      }))
+      return
+    }
     if (action === "events") {
       const root = positionalArg(args, 3) || process.cwd()
       const limit = optionInt(args, "--limit", 200)
@@ -717,7 +758,8 @@ async function modelPolicy() {
   const normalizedAttempt = Number.isInteger(attempt) && attempt > 0 ? attempt : 1
   const taskText = optionValue(args, "--text")
   if (taskText) {
-    printJson(resolveAdaptiveModel(role, normalizedAttempt, classifyEngineeringTask(taskText), policy))
+    const taskPolicy = classifyEngineeringTask(taskText)
+    printJson(resolveCapabilityModel(role, normalizedAttempt, taskText, taskPolicy, policy))
     return
   }
   printJson(resolveModel(role, normalizedAttempt, policy))
@@ -770,6 +812,48 @@ async function modelsControl() {
     return
   }
 
+  if (action === "capability") {
+    const model = args[2]
+    if (!validateModelID(model)) {
+      console.error("Usage: ocskill models capability <provider/model> [capability flags]")
+      process.exitCode = 2
+      return
+    }
+    const current = policy.capabilities?.[model] || {}
+    const boolFlag = (name, prior) => {
+      const value = optionValue(args, name)
+      if (value == null) return prior
+      if (!["on", "off", "true", "false"].includes(String(value).toLowerCase())) throw new Error(name + " must be on/off")
+      return ["on", "true"].includes(String(value).toLowerCase())
+    }
+    const qualityRaw = optionValue(args, "--quality")
+    const quality = qualityRaw == null ? current.quality : Number(qualityRaw)
+    if (qualityRaw != null && (!Number.isFinite(quality) || quality < 0 || quality > 1)) throw new Error("--quality must be from 0 to 1")
+    const cost = optionValue(args, "--cost") || current.costClass
+    const latency = optionValue(args, "--latency") || current.latencyClass
+    if (cost && !["low", "medium", "high"].includes(cost)) throw new Error("--cost must be low|medium|high")
+    if (latency && !["fast", "medium", "slow"].includes(latency)) throw new Error("--latency must be fast|medium|slow")
+    policy = await writeModelPolicy(getConfigDir(), {
+      capabilities: {
+        [model]: {
+          ...current,
+          coding: boolFlag("--coding", current.coding),
+          reasoning: boolFlag("--reasoning", current.reasoning),
+          toolCalling: boolFlag("--tool-calling", current.toolCalling),
+          vision: boolFlag("--vision", current.vision),
+          browser: boolFlag("--browser", current.browser),
+          filesystem: boolFlag("--filesystem", current.filesystem),
+          longContext: boolFlag("--long-context", current.longContext),
+          ...(cost ? { costClass: cost } : {}),
+          ...(latency ? { latencyClass: latency } : {}),
+          ...(quality != null ? { quality } : {}),
+        },
+      },
+    })
+    printJson(policy)
+    return
+  }
+
   console.error("Usage: ocskill models <status|on|off|set|role> ...")
   process.exitCode = 2
 }
@@ -932,6 +1016,40 @@ async function hermesControl() {
     printJson(hermesStatus())
     return
   }
+  if (action === "workflow" || action === "exec-workflow") {
+    const slug = args[2]
+    const root = positionalArg(args, 3) || process.cwd()
+    if (!slug) {
+      console.error("Usage: ocskill hermes <workflow|exec-workflow> <slug> [dir] [--max-concurrent N]")
+      process.exitCode = 2
+      return
+    }
+    const planFile = path.join(path.resolve(root), ".ues-work", slug, "PLAN.json")
+    const plan = readJsonFile(planFile)
+    const schedule = planDynamicWorkflow(plan.tasks || [], {
+      maxConcurrent: optionInt(args, "--max-concurrent", 4),
+    })
+    const sidecar = hermesSidecarPlan({ mode: "dynamic-workflow", maxConcurrent: schedule.maxConcurrent })
+    const prompt = buildHermesWorkflowPrompt({ slug, goal: plan.goal || null, plan }, schedule)
+    if (action === "workflow") {
+      printJson({ sidecar, schedule, prompt })
+      return
+    }
+    const status = hermesStatus()
+    if (!status.available) {
+      console.error(status.error || "Hermes CLI is unavailable")
+      process.exitCode = 1
+      return
+    }
+    const result = runCapture("hermes", hermesOneShotArgs(prompt), {
+      cwd: path.resolve(root),
+      maxBuffer: 8 * 1024 * 1024,
+    })
+    if (result.stdout) process.stdout.write(result.stdout)
+    if (result.stderr) process.stderr.write(result.stderr)
+    if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
+    return
+  }
   if (action === "prompt" || action === "exec") {
     const slug = args[2]
     const taskID = args[3]
@@ -962,10 +1080,220 @@ async function hermesControl() {
     if ((result.status ?? 1) !== 0) process.exitCode = result.status ?? 1
     return
   }
-  console.error("Usage: ocskill hermes <status|prompt|exec> ...")
+  console.error("Usage: ocskill hermes <status|prompt|exec|workflow|exec-workflow> ...")
   process.exitCode = 2
 }
 
+async function evidenceStoreControl() {
+  const action = args[1] || "status"
+  try {
+    if (action === "status") {
+      printJson(await evidenceStoreStatus(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "put") {
+      const file = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!file) throw new Error("Usage: ocskill store put <file> [dir] [--kind <kind>] [--summary <text>]")
+      const content = readTextFile(file)
+      printJson(await putEvidence(root, content, {
+        kind: optionValue(args, "--kind") || "file",
+        source: path.resolve(file),
+        summary: optionValue(args, "--summary"),
+      }))
+      return
+    }
+    if (action === "get") {
+      const ref = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!ref) throw new Error("Usage: ocskill store get <evidence-ref> [dir] [--max N] [--start N]")
+      printJson(await getEvidence(root, ref, {
+        maxChars: optionInt(args, "--max", 24_000),
+        start: optionInt(args, "--start", 0),
+      }))
+      return
+    }
+    if (action === "gc") {
+      const root = positionalArg(args, 2) || process.cwd()
+      printJson(await gcEvidenceStore(root, {
+        maxEntries: optionInt(args, "--max-entries", 2000),
+        maxAgeDays: optionInt(args, "--max-age-days", 30),
+      }))
+      return
+    }
+    throw new Error("Usage: ocskill store <status|put|get|gc> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function capabilityControl() {
+  const text = args.slice(1).join(" ").trim()
+  if (!text) {
+    console.error("Usage: ocskill capabilities <task text>")
+    process.exitCode = 2
+    return
+  }
+  printJson(inferTaskCapabilities(text))
+}
+
+async function visualControl() {
+  const action = args[1]
+  try {
+    if (action === "spec") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill visual spec <VISUAL_SPEC.json>")
+      printJson(validateVisualSpec(readJsonFile(file)))
+      return
+    }
+    if (action === "geometry") {
+      const specFile = args[2]
+      const actualFile = args[3]
+      if (!specFile || !actualFile) throw new Error("Usage: ocskill visual geometry <VISUAL_SPEC.json> <actual-boxes.json>")
+      printJson(createGeometryReceipt(readJsonFile(specFile), readJsonFile(actualFile)))
+      return
+    }
+    if (action === "compare") {
+      const expected = args[2]
+      const actual = args[3]
+      if (!expected || !actual) throw new Error("Usage: ocskill visual compare <expected.png> <actual.png> [--threshold N] [--max-diff-ratio N]")
+      const threshold = Number(optionValue(args, "--threshold") ?? 16)
+      const maxDiffRatio = Number(optionValue(args, "--max-diff-ratio") ?? 0)
+      printJson(await comparePngFiles(expected, actual, { threshold, maxDiffRatio }))
+      return
+    }
+    if (action === "crop") {
+      const input = args[2]
+      const output = args[3]
+      if (!input || !output) throw new Error("Usage: ocskill visual crop <input.png> <output.png> --x N --y N --width N --height N")
+      printJson(await cropPngFile(input, output, {
+        x: optionInt(args, "--x", 0),
+        y: optionInt(args, "--y", 0),
+        width: optionInt(args, "--width", 1),
+        height: optionInt(args, "--height", 1),
+      }))
+      return
+    }
+    if (action === "viewports") {
+      printJson(responsiveViewportMatrix())
+      return
+    }
+    throw new Error("Usage: ocskill visual <spec|geometry|compare|crop|viewports> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function browserControl() {
+  const action = args[1] || "capability"
+  try {
+    if (action === "capability") {
+      printJson(await browserCapability(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "plan") {
+      const url = args[2] || null
+      printJson(buildBrowserVerificationPlan({
+        url,
+        target: optionValue(args, "--target"),
+      }))
+      return
+    }
+    if (action === "inspect") {
+      const url = args[2]
+      if (!url) throw new Error("Usage: ocskill browser inspect <url> [dir] [--selector <css>] [--screenshot <path>] [--width N] [--height N] [--max-elements N]")
+      const root = positionalArg(args, 3) || process.cwd()
+      const report = await inspectBrowserPage(root, url, {
+        selector: optionValue(args, "--selector"),
+        screenshot: optionValue(args, "--screenshot"),
+        width: optionInt(args, "--width", 1440),
+        height: optionInt(args, "--height", 900),
+        maxElements: optionInt(args, "--max-elements", 80),
+        timeoutMs: optionInt(args, "--timeout-ms", 30000),
+        waitMs: optionInt(args, "--wait-ms", 0),
+        fullPage: !args.includes("--viewport-only"),
+      })
+      printJson(args.includes("--full") ? report : summarizeBrowserInspection(report, { limit: optionInt(args, "--limit", 20) }))
+      return
+    }
+    throw new Error("Usage: ocskill browser <capability|plan|inspect> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function uiControl() {
+  const action = args[1]
+  try {
+    if (action === "tokens") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill ui tokens <styles.css>")
+      const tokens = extractDesignTokens(readTextFile(file))
+      printJson({ tokens, evidence: designTokenEvidence(tokens) })
+      return
+    }
+    if (action === "layout") {
+      const file = args[2]
+      if (!file) throw new Error("Usage: ocskill ui layout <boxes.json> --width N --height N [--min-touch N] [--overlap-ratio N]")
+      const payload = readJsonFile(file)
+      const items = Array.isArray(payload) ? payload : payload.elements || payload.boxes || []
+      printJson(inspectResponsiveLayout(items, {
+        width: optionInt(args, "--width", Number(payload.viewport?.width || 0)),
+        height: optionInt(args, "--height", Number(payload.viewport?.height || 0)),
+      }, {
+        minTouchTarget: optionInt(args, "--min-touch", 44),
+        overlapRatio: Number(optionValue(args, "--overlap-ratio") ?? 0.15),
+      }))
+      return
+    }
+    throw new Error("Usage: ocskill ui <tokens|layout> ...")
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function workflowPlanControl() {
+  const file = args[1]
+  if (!file) {
+    console.error("Usage: ocskill workflow-plan <PLAN.json> [--max-concurrent N]")
+    process.exitCode = 2
+    return
+  }
+  try {
+    const plan = readJsonFile(file)
+    printJson(planDynamicWorkflow(plan.tasks || [], {
+      maxConcurrent: optionInt(args, "--max-concurrent", 4),
+      maxLLMConcurrent: optionInt(args, "--max-llm-concurrent", optionInt(args, "--max-concurrent", 4)),
+      maxVisionConcurrent: optionInt(args, "--max-vision-concurrent", 2),
+      maxWaveCost: optionInt(args, "--max-wave-cost", 24),
+      minAgentCost: optionInt(args, "--min-agent-cost", 5),
+      minVisionAgentCost: optionInt(args, "--min-vision-agent-cost", 4),
+    }))
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
+async function skillsControl() {
+  const action = args[1] || "lint"
+  if (action !== "lint") {
+    console.error("Usage: ocskill skills lint [dir]")
+    process.exitCode = 2
+    return
+  }
+  try {
+    printJson(await lintSkillCatalog(positionalArg(args, 2) || packageRoot))
+  } catch (error) {
+    console.error(errorMessage(error))
+    process.exitCode = 1
+  }
+}
+
 async function dashboardControl() {
   const forwarded = args.slice(1)
   const code = run(process.execPath, [path.join(packageRoot, "scripts", "control-center.mjs"), ...forwarded])
@@ -1138,6 +1466,27 @@ switch (command) {
   case "hermes":
     await hermesControl()
     break
+  case "store":
+    await evidenceStoreControl()
+    break
+  case "capabilities":
+    await capabilityControl()
+    break
+  case "visual":
+    await visualControl()
+    break
+  case "browser":
+    await browserControl()
+    break
+  case "workflow-plan":
+    await workflowPlanControl()
+    break
+  case "ui":
+    await uiControl()
+    break
+  case "skills":
+    await skillsControl()
+    break
   case "dashboard":
     await dashboardControl()
     break

package/docs/V11-PERCEPTION-ADAPTIVE-EXECUTION.md

@@ -0,0 +1,75 @@
+# V11 Perception & Adaptive Execution
+
+## Goal
+
+V11 minimizes context and model cost without deleting evidence needed for correctness. It adds perception-aware UI/browser verification so the system can reason about **what an element is, where it is and how it looks** using different evidence channels.
+
+## Runtime layers
+
+```text
+Task
+  -> intent/risk
+  -> capability requirements
+  -> adaptive evidence budget
+  -> semantic/index evidence
+  -> content-addressed evidence pointers
+  -> focused skills
+  -> capability-aware model
+  -> fresh executor
+  -> deterministic verification
+  -> visual/browser verifier when required
+  -> diagnosis + evidence expansion only on failure
+```
+
+## Evidence Store
+
+Large raw tool output, durable specs and dependency reports are stored under:
+
+```text
+.ues-cache/evidence-v1/<hash-prefix>/<sha256>.blob
+.ues-cache/evidence-v1/<hash-prefix>/<sha256>.json
+```
+
+A prompt receives a bounded excerpt and a reference such as `evidence:sha256:<hash>`. Use `ocskill store get` to retrieve only the needed slice. `.ues-cache` is runtime state and is excluded from workspace verification fingerprints.
+
+## Adaptive evidence budget
+
+FAST/STANDARD/DEEP remain outer safety ceilings. Inside that ceiling V11 allocates characters by evidence role instead of treating all context as equally valuable. Debugging shifts budget toward tests/history; high-risk work shifts toward tests/references; browser/visual work shifts toward deterministic tool evidence.
+
+Failure expands evidence through the existing initial -> diagnose -> deep-recovery stages instead of loading maximum context on the first attempt.
+
+## Prompt cache shape
+
+Stable material is separated conceptually from dynamic task/evidence. The runtime records stable/dynamic hashes and cacheable ratio. This is telemetry, not a promise that every provider supports prompt caching.
+
+## Capability-aware routing
+
+Model profiles may declare coding, reasoning, toolCalling, vision, browser, filesystem, longContext, cost/latency class and a quality hint. UES never invents an unavailable capability. If no configured candidate satisfies a requirement it exposes capability fallback instead of silently claiming that a text-only model can see screenshots.
+
+## Visual fidelity
+
+Visual verification uses three complementary layers: semantic DOM/accessibility identity, geometry/bounding boxes, and screenshot pixels. VISUAL_SPEC describes important anchors and tolerances. Geometry receipts prove position/size claims. PNG diff finds changed pixels and their bounding region. A failed region can be cropped so vision only sees the area that needs judgment.
+
+Screenshot equality does not prove accessibility or interaction; DOM equality does not prove appearance.
+
+## Browser QA and security
+
+Browser workflows prefer bounded deterministic scripts/CLI for ordinary verification. Remote webpage content is untrusted and cannot change UES/tool permissions, request secrets, expand the approved task or authorize external side effects.
+
+## Dynamic workflows
+
+The scheduler classifies units as deterministic, LLM judgment or vision judgment. Deterministic work does not spawn agents. Independent tasks may share a wave only when dependencies are ready and file ownership does not conflict. Each wave is integrated and verified before later waves rely on it.
+
+## Skill system
+
+V11 keeps progressive disclosure: description metadata for routing, short SKILL.md entrypoint, references only when the selected mode needs them, and deterministic logic in runtime/scripts rather than repeated prompt text.
+
+`ocskill skills lint` flags oversized entrypoints and highly overlapping descriptions.
+
+## Hermes sidecar
+
+Hermes remains optional. UES owns durable `.ues-work` state, evidence references, task leases/runId fencing, verification receipts and safety/permission boundaries. Hermes may execute a bounded task/workflow when explicitly available but does not become the source of truth.
+
+## Release evidence
+
+V11 must pass syntax/resource/router/V11 contract tests, all Node tests, package/install smokes, no-regression live suites, capability-routing tests, visual geometry/pixel fixtures, browser security/targeted-evidence fixtures and token/cache/evidence telemetry benchmarks before stable promotion.