opencode-agent-skill 13.0.0-beta.1 → 14.2.0-beta.1

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,122 +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
+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.
 
-UES installs:
+Legacy-only surfaces include:
 
-- 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/
-```
+- `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.
 
-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.
+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.