opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/bin/ocskill.mjs

@@ -15,6 +15,7 @@ import {
 import { compareVersions } from "../lib/version.mjs"
 import { resolveLatestPublishedVersion } from "../lib/update-resolver.mjs"
 import { readRouterConfig, writeRouterConfig } from "../lib/router-config.mjs"
+import { getUesConfigDir } from "../lib/runtime-config.mjs"
 import { resolveWindowsCommand } from "../lib/windows-shim.mjs"
 import {
   detectStack,
@@ -66,8 +67,11 @@ import { createTaskSandbox, integrateTaskSandbox, listTaskSandboxes, removeTaskS
 import { analyzeEvalTraces, saveLearningAnalysis, readLearningState, acceptLearning, promoteLearning } from "../lib/learning-engine.mjs"
 import { hermesStatus, buildHermesDelegationPrompt, buildHermesWorkflowPrompt, hermesOneShotArgs, hermesSidecarPlan } from "../lib/hermes-bridge.mjs"
 import { readModelPolicy, recordModelPerformance, validateModelID, writeModelPolicy } from "../lib/model-config.mjs"
-import { evidenceStoreStatus, gcEvidenceStore, getEvidence, putEvidence } from "../lib/evidence-store.mjs"
+import { evidenceStoreStatus, gcEvidenceStore, getEvidenceSelected, putEvidence } from "../lib/evidence-store.mjs"
 import { inferTaskCapabilities } from "../lib/capability-registry.mjs"
+import { capabilityFabricStatus } from "../lib/capability-fabric.mjs"
+import { queryContextHierarchy } from "../lib/hierarchical-context.mjs"
+import { memoryStatus, proposeMemory, retrieveMemories, supersedeMemory, verifyMemory } from "../lib/memory-engine.mjs"
 import { MODEL_TASK_CLASSES } from "../lib/model-performance.mjs"
 import { browserCapability, buildBrowserVerificationPlan } from "../lib/browser-adapter.mjs"
 import { inspectBrowserPage, summarizeBrowserInspection } from "../lib/browser-runtime.mjs"
@@ -107,14 +111,12 @@ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 
 function printHelp() {
   console.log(`
-OpenCode Universal Engineering System
-
-Usage:
-  ocskill install [--force]    Install or re-sync bundled OpenCode resources
+Universal Engineering System for Pi Agent\n\nUsage (preferred CLI: ues; ocskill remains a compatibility alias):\n  ocskill install [--force]    Legacy: install/re-sync OpenCode compatibility resources
   ocskill status               Show package/resource synchronization status
-  ocskill doctor               Check Node, npm, OpenCode and installed resources
+  ocskill doctor               Legacy migration doctor for OpenCode compatibility resources
   ocskill eval                 Validate the bundled static skill-routing suite
-  ocskill eval-live [options]  Run baseline-vs-UES live behavioral evals
+  ocskill eval-live [options]  Run legacy OpenCode baseline-vs-UES behavioral evals
+  ocskill eval-pi [options]    Run Pi-native baseline-vs-UES weak-model benchmark
   ocskill eval-report [paths]  Aggregate live eval pass-rate/cost/tool telemetry
   ocskill inspect [dir]        Deterministic repository/stack/test-command map
   ocskill impact <query> [dir] Search likely impact paths and matching lines
@@ -147,6 +149,10 @@ Usage:
   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 capability-fabric <status|select> ... Health-check and select tool/provider backends
+  ocskill hierarchy <query> [dir] [--full]
+                              Progressive L0/L1 scope routing; compact by default, --full includes complete file lists
+  ocskill memory <action> ...      Verified persistent project memory and hybrid retrieval
   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
@@ -154,11 +160,7 @@ Usage:
   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> ...
-                              Configure role/tier model routing, then re-sync
-  ocskill router [status|on|off] [--max N]
-                              Configure the OpenCode v2 automatic skill router
-  ocskill update               Update the global npm package and re-sync resources
+  ues models <status|on|off|set|role> ...\n                              Configure Pi runtime role/tier model routing immediately\n  ocskill router [status|on|off] [--max N]\n                              Legacy: configure the OpenCode v2 compatibility router\n  ocskill update               Update the global npm package and re-sync resources
   ocskill remove [--force]     Remove managed resources and uninstall the npm package
   ocskill version              Show package version
   ocskill help                 Show this help
@@ -426,6 +428,16 @@ async function doctor() {
     if (code !== 0) process.exitCode = code
   }
   await status()
+  try {
+    const fabric = await capabilityFabricStatus(process.cwd())
+    console.log("Capability fabric:")
+    for (const row of fabric.rows || []) {
+      const fallbacks = row.fallbacks?.length ? " -> " + row.fallbacks.join(" -> ") : ""
+      console.log(`  ${row.capability}: ${row.selected || "UNAVAILABLE"}${fallbacks} [${row.status}]`)
+    }
+  } catch (error) {
+    console.log("Capability fabric: unavailable (" + errorMessage(error) + ")")
+  }
 }
 
 async function evaluate() {
@@ -441,6 +453,14 @@ async function evaluateLive() {
   if (code !== 0) process.exitCode = code
 }
 
+async function evaluatePi() {
+  const code = run(
+    process.execPath,
+    [path.join(packageRoot, "scripts", "eval-pi.mjs"), ...args.slice(1)],
+  )
+  if (code !== 0) process.exitCode = code
+}
+
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2))
 }
@@ -982,7 +1002,7 @@ async function modelPolicy() {
     return
   }
   const attempt = optionInt(args, "--attempt", 1)
-  const policy = await readModelPolicy(getConfigDir())
+  const policy = await readModelPolicy(getUesConfigDir())
   const normalizedAttempt = Number.isInteger(attempt) && attempt > 0 ? attempt : 1
   const taskText = optionValue(args, "--text")
   if (taskText) {
@@ -996,16 +1016,16 @@ async function modelPolicy() {
 
 async function modelsControl() {
   const action = args[1] || "status"
-  let policy = await readModelPolicy(getConfigDir())
+  let policy = await readModelPolicy(getUesConfigDir())
 
   if (action === "status") {
     printJson(policy)
     return
   }
   if (action === "on" || action === "off") {
-    policy = await writeModelPolicy(getConfigDir(), { enabled: action === "on" })
+    policy = await writeModelPolicy(getUesConfigDir(), { enabled: action === "on" })
     printJson(policy)
-    console.log("[ocskill] Run 'ocskill install' to rewrite managed agent frontmatter.")
+    console.log("[ocskill] Model routing is active immediately for Pi child-agent dispatch.")
     return
   }
   if (action === "set") {
@@ -1015,12 +1035,12 @@ async function modelsControl() {
       printCliError(Object.assign(new Error("Usage: ocskill models set <light|standard|heavy> <provider/model[#variant]>"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
-    policy = await writeModelPolicy(getConfigDir(), {
+    policy = await writeModelPolicy(getUesConfigDir(), {
       enabled: true,
       tiers: { [tier]: model },
     })
     printJson(policy)
-    console.log("[ocskill] Run 'ocskill install' to apply model mappings to managed agents.")
+    console.log("[ocskill] Model routing is active immediately for Pi child-agent dispatch.")
     return
   }
   if (action === "role") {
@@ -1030,11 +1050,11 @@ async function modelsControl() {
       printCliError(Object.assign(new Error("Usage: ocskill models role <role> <light|standard|heavy>"), { code: "UES_USAGE", exitCode: 2 }))
       return
     }
-    policy = await writeModelPolicy(getConfigDir(), {
+    policy = await writeModelPolicy(getUesConfigDir(), {
       roleTiers: { [role]: tier },
     })
     printJson(policy)
-    console.log("[ocskill] Run 'ocskill install' to apply role-tier changes.")
+    console.log("[ocskill] Role-tier routing is active immediately for Pi child-agent dispatch.")
     return
   }
 
@@ -1048,7 +1068,7 @@ async function modelsControl() {
     if (!MODEL_TASK_CLASSES.includes(taskClass)) throw new Error("--task-class must be one of: " + MODEL_TASK_CLASSES.join(", "))
     const passedRaw = String(optionValue(args, "--passed") || "").toLowerCase()
     if (!["on","off","true","false","pass","fail"].includes(passedRaw)) throw new Error("--passed must be on/off, true/false, or pass/fail")
-    policy = await recordModelPerformance(getConfigDir(), {
+    policy = await recordModelPerformance(getUesConfigDir(), {
       model, taskClass, passed: ["on","true","pass"].includes(passedRaw),
       retries: optionInt(args, "--retries", 0) || 0,
       tokens: optionInt(args, "--tokens", 0) || 0,
@@ -1078,7 +1098,7 @@ async function modelsControl() {
     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(), {
+    policy = await writeModelPolicy(getUesConfigDir(), {
       capabilities: {
         [model]: {
           ...current,
@@ -1357,7 +1377,7 @@ async function evidenceStoreControl() {
       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, {
+      printJson(await getEvidenceSelected(root, ref, {
         maxChars: optionInt(args, "--max", 24_000),
         start: optionInt(args, "--start", 0),
       }))
@@ -1386,6 +1406,122 @@ async function capabilityControl() {
   printJson(inferTaskCapabilities(text))
 }
 
+
+async function capabilityFabricControl() {
+  const action = args[1] || "status"
+  try {
+    if (action === "status") {
+      printJson(await capabilityFabricStatus(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "select") {
+      const capability = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!capability) throw new Error("Usage: ocskill capability-fabric select <capability> [dir]")
+      const status = await capabilityFabricStatus(root)
+      const selected = status.capabilities?.[capability]
+      if (!selected) throw new Error("Unknown capability: " + capability)
+      printJson(selected)
+      return
+    }
+    throw new Error("Usage: ocskill capability-fabric <status|select> ...")
+  } catch (error) {
+    printCliError(error)
+  }
+}
+
+async function hierarchyControl() {
+  const query = args[1]
+  const root = positionalArg(args, 2) || process.cwd()
+  if (!query) {
+    printCliError(Object.assign(new Error("Usage: ocskill hierarchy <query> [dir] [--max-scopes N] [--full]"), { code: "UES_USAGE", exitCode: 2 }))
+    return
+  }
+  try {
+    const result = await queryContextHierarchy(root, query, { maxScopes: optionInt(args, "--max-scopes", 6) })
+    if (args.includes("--full")) {
+      printJson(result)
+      return
+    }
+    printJson({
+      ...result,
+      compact: true,
+      scopes: (result.scopes || []).map((scope) => ({
+        path: scope.path,
+        score: scope.score,
+        reasons: scope.reasons,
+        fileCount: scope.fileCount,
+        bytes: scope.bytes,
+        l0: scope.l0,
+        l1: scope.l1,
+        topFiles: (scope.files || []).slice(0, 12),
+        topSymbols: (scope.symbols || []).slice(0, 12),
+        childCount: (scope.children || []).length,
+      })),
+    })
+  } catch (error) {
+    printCliError(error)
+  }
+}
+
+async function memoryControl() {
+  const action = args[1] || "status"
+  try {
+    if (action === "status") {
+      printJson(await memoryStatus(positionalArg(args, 2) || process.cwd()))
+      return
+    }
+    if (action === "search") {
+      const query = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!query) throw new Error("Usage: ocskill memory search <query> [dir] [--limit N] [--file <path>]")
+      const files = []
+      const file = optionValue(args, "--file")
+      if (file) files.push(file)
+      printJson(await retrieveMemories(root, query, { limit: optionInt(args, "--limit", 6), files }))
+      return
+    }
+    if (action === "propose") {
+      const content = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!content) throw new Error("Usage: ocskill memory propose <text> [dir] [--type <type>] [--scope <scope>] [--evidence <ref>] [--file <path>]")
+      const evidence = optionValue(args, "--evidence")
+      const file = optionValue(args, "--file")
+      printJson(await proposeMemory(root, {
+        content,
+        type: optionValue(args, "--type") || "episodic",
+        scope: optionValue(args, "--scope") || "project",
+        evidenceRefs: evidence ? [evidence] : [],
+        files: file ? [file] : [],
+      }))
+      return
+    }
+    if (action === "verify") {
+      const id = args[2]
+      const root = positionalArg(args, 3) || process.cwd()
+      if (!id) throw new Error("Usage: ocskill memory verify <id> [dir] --verdict PASS --verifier <name> [--evidence <ref>]")
+      const evidence = optionValue(args, "--evidence")
+      printJson(await verifyMemory(root, id, {
+        verdict: optionValue(args, "--verdict"),
+        verifier: optionValue(args, "--verifier"),
+        evidenceRefs: evidence ? [evidence] : [],
+      }))
+      return
+    }
+    if (action === "supersede") {
+      const id = args[2]
+      const replacement = args[3]
+      const root = positionalArg(args, 4) || process.cwd()
+      if (!id || !replacement) throw new Error("Usage: ocskill memory supersede <id> <replacement-id> [dir]")
+      printJson(await supersedeMemory(root, id, replacement))
+      return
+    }
+    throw new Error("Usage: ocskill memory <status|search|propose|verify|supersede> ...")
+  } catch (error) {
+    printCliError(error)
+  }
+}
+
 async function visualControl() {
   const action = args[1]
   try {
@@ -1724,6 +1860,9 @@ async function main() {
   case "eval-live":
     await evaluateLive()
     break
+  case "eval-pi":
+    await evaluatePi()
+    break
   case "eval-report":
     await evaluateReport()
     break
@@ -1787,6 +1926,15 @@ async function main() {
   case "capabilities":
     await capabilityControl()
     break
+  case "capability-fabric":
+    await capabilityFabricControl()
+    break
+  case "hierarchy":
+    await hierarchyControl()
+    break
+  case "memory":
+    await memoryControl()
+    break
   case "visual":
     await visualControl()
     break
@@ -1856,4 +2004,4 @@ try {
   await main()
 } catch (error) {
   printCliError(error)
-}
+}

package/docs/OPENCODE-COMPAT.md

@@ -1,124 +1,61 @@
-# OpenCode compatibility
+# Legacy OpenCode compatibility
 
-V13 ships one npm package for OpenCode 1.x and 2.x. CLI/state/verification features remain available on both lines, while V2-native fresh-session and parallel runtime features are enabled only when the required V2 capabilities are detected.
+> Deprecated compatibility surface. The supported runtime in this repository is **Pi Agent**.
 
-## Detection
+UES no longer depends on the OpenCode router for its core task policy, model routing, context construction, specialist dispatch, scheduling, verification, or benchmark path. The canonical runtime lives under `pi/` and `lib/`.
 
-During resource sync, UES reads:
+## Why these files still exist
 
-```text
-opencode --version
-```
-
-Tests may override with:
-
-```text
-UES_OPENCODE_MAJOR=1
-UES_OPENCODE_MAJOR=2
-```
-
-The detected major is recorded in the managed state.
-
-## OpenCode 1.x
-
-UES installs:
+A small compatibility layer is retained temporarily so older installations can be inspected or migrated without silently deleting user-managed resources. It is not loaded by the Pi package manifest and should not be used for new development.
 
-- 48 namespaced skills
-- 11 namespaced commands
-- 12 namespaced subagents using compatible V1 `permission` frontmatter
-- managed global `AGENTS.md` block
-
-The V2 runtime plugin is not installed.
-
-Durable CLI state, task DAG, plan/integration gates, Windows UTF text recovery and model-policy configuration remain available. `ues.dispatch_task` and `ues.dispatch_parallel` are unavailable because those tools live in the V2 router plugin.
-
-## OpenCode 2.x
-
-UES converts managed agent permission frontmatter to V2 ordered `permissions` and installs:
-
-```text
-<global-config>/plugins/ues-router/
-```
+Legacy-only surfaces include:
 
-V13 also installs the 11 UES slash-command templates inside the managed router as V2 **prompt aliases** instead of registering them as native global custom commands. Typing `/ues-run ...`, `/ues-fix ...`, and the other `/ues-*` aliases therefore travels through `session.prompt`; the router expands the same bundled command contract before routing skills. This is a compatibility workaround for V2 custom-command transport failures such as `UnsupportedContentType` from the `session.command` path. Re-syncing with `ocskill install` removes stale UES-managed native command files from older installs.
+- `global-config/commands/`;
+- `global-config/plugins/ues-router/`;
+- OpenCode installer/router compatibility code in `lib/installer.mjs`, `lib/opencode-compat.mjs`, and `lib/router-config.mjs`;
+- `scripts/eval-live.mjs`, which exists only for historical OpenCode benchmark comparison.
 
-For `/ues-run`, V13.0.0-beta.2 adds adaptive admission before the prompt is sent to the model. The router classifies the real user arguments, not the expanded command template. FAST and STANDARD work receive compact envelopes, while only DEEP/long-horizon/high-risk work keeps the full durable workflow. `/ues-resume` stays explicitly durable. This prevents a trivial or bounded request from being turned into a long-running repository workflow simply because the user typed `/ues-run`.
+The old router policy file is now a compatibility shim that re-exports the canonical Pi-native `lib/task-policy.mjs`, preventing policy drift.
 
-The plugin provides:
+## Current Pi equivalents
 
-- prompt-admission skill routing
-- long-task context guardrails
-- permission safety evaluation when that hook exists
-- durable-state/task-graph/context-pack tools
-- `ues.dispatch_task` bounded fresh executor runtime
-- `ues.cancel_task` and `ues.recover_task` when session interruption is supported
-- `ues.dispatch_parallel` when the full fresh-dispatch surface is present; it runs independent approved tasks in isolated same-model sessions, verifies each task independently, and serializes integration
+| Legacy surface | Pi-native replacement |
+|---|---|
+| OpenCode router task admission | `lib/task-policy.mjs` + `ues_execute` |
+| OpenCode dispatch | `ues_execute` / `ues_dispatch` |
+| OpenCode model routing | `lib/model-policy.mjs` consumed directly by Pi dispatch |
+| OpenCode prompt aliases | `pi/prompts/*.md` |
+| OpenCode live eval | `ues eval-pi ...` / `scripts/eval-pi.mjs` |
+| Manual writer worktree preparation | structured-plan safe-wave scheduler in `ues_execute` |
 
-`ues.dispatch_task` uses V2 session APIs to create a fresh session rooted at the selected execution directory, bind its session ID to the task lease, select `ues-executor`, optionally switch model tier, prompt one approved task, heartbeat while waiting, and interrupt on timeout. Concurrent writing tasks can be isolated in Git worktrees.
+## Migration guidance
 
-## Router control
+New installs should use Pi:
 
 ```cmd
-ocskill router status
-ocskill router on
-ocskill router on --max 3
-ocskill router off
+npm install -g @earendil-works/pi-coding-agent
+pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi
 ```
 
-Default maximum is 4 selected skills; supported range is 1–6.
-
-## Model routing
+Use the UES-native CLI alias for deterministic operations:
 
 ```cmd
-ocskill models status
-ocskill models on
-ocskill models set standard provider/model
-ocskill models set heavy provider/strong-model
+ues task-policy "fix a payment callback race" --json
+ues models status --json
+ues eval-pi --model provider/model --mode both
 ```
 
-Re-run `ocskill install` after changing static managed-agent model frontmatter. Runtime `ues.dispatch_task` also reads the current model policy for attempt-based executor escalation.
-
-## Upgrading OpenCode
+`ocskill` remains an alias during the migration window so existing scripts do not break immediately.
 
-After moving between V1/V2 lines:
+For an existing OpenCode installation that still needs the deprecated compatibility resources, synchronization is now explicit rather than an npm lifecycle side effect:
 
 ```cmd
 ocskill install
-ocskill status
 ```
 
-Only UES-managed resources are rewritten/removed. Unrelated user plugins/resources are preserved.
-
-## Primary references
-
-- https://opencode.ai/v2/docs/build/plugins
-- https://opencode.ai/v2/docs/build/plugins/migrate-v1
-- https://opencode.ai/v2/docs/permissions
-- https://opencode.ai/v2/docs/plugins
-- https://opencode.ai/v2/docs/skills
-
-
-## V8 capability probing
-
-Version detection remains useful for install-time compatibility, but V8 runtime dispatch does not assume that a major version proves the availability of every session API.
-
-The managed V2 plugin probes for:
-
-- session creation
-- prompting
-- waiting
-- interruption
-- context retrieval
-- agent switching
-- model switching
-- session hooks
-- permission hooks
-
-`ues.capabilities` exposes the observed surface. Fresh dispatch fails closed when the minimum create/prompt/wait/interrupt/context/switch-agent surface is unavailable. Optional context/prompt/permission hooks degrade safely instead of preventing the plugin from loading.
-
-
-## V13 parallel compatibility
+The npm package intentionally has no `postinstall` or `preuninstall` compatibility hooks. Installing UES for Pi must not silently mutate OpenCode configuration.
 
-`ues.dispatch_parallel` is capability-gated, not version-string-gated. It requires the complete fresh-dispatch surface reported by `ues.capabilities`: session create, prompt, wait, interrupt, context retrieval and agent switching. If any required API is missing, V13 fails closed and the durable CLI workflow remains usable in serial mode.
+## Removal rule
 
-OpenCode 1.x users can still use V13 CLI hardening, durable `.ues-work/<slug>/` state, receipts, task graphs and Windows text normalization. To use native multi-session parallel execution, use a runtime that exposes the V2 fresh-session APIs.
+Do not add new features to the legacy OpenCode compatibility surface. New runtime features must land in Pi/`lib` first. Legacy files may be removed once migration coverage proves that no supported Pi command imports or packages them.