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

package/docs/PI-COMPAT.md

@@ -0,0 +1,188 @@
+# Pi Agent runtime
+
+Repository này hiện đóng gói UES cho **Pi Agent**.
+
+## Requirements
+
+- Node.js 22.19+
+- Git
+- `@earendil-works/pi-coding-agent`
+
+## Install
+
+```cmd
+npm install -g @earendil-works/pi-coding-agent
+pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi list
+pi
+```
+
+Project-local:
+
+```cmd
+pi install git:github.com/laivannha0202/opencode-agent-skill- -l
+```
+
+Hoặc từ checkout local:
+
+```cmd
+pi install .
+```
+
+## Resources loaded by Pi
+
+`package.json` exposes:
+
+- extension: `./pi/extensions/ues.ts`
+- skills: `./global-config/skills`
+- prompts: `./pi/prompts/*.md`
+
+The packaged runtime also contains `global-config/agents/`, `bin/ocskill.mjs`, and `lib/` because the Pi extension uses them for specialist child-agent execution and deterministic UES operations.
+
+## Tools
+
+### ues_cli
+
+Runs bundled `ocskill` functionality directly, without requiring a separate global `ocskill` installation.
+
+Typical uses:
+
+- task policy;
+- repository inspection;
+- dependency/task graph;
+- durable `.ues-work/` state;
+- evidence and receipts;
+- verification and recovery;
+- worktree isolation.
+
+### ues_execute
+
+Runs the high-level deterministic controller for end-to-end engineering work.
+
+The controller applies task policy, adaptive context, model-tier routing, optional diagnosis/plan gating, implementation, verifier/integration-verifier gates, bounded retries, and model-performance telemetry. This is the preferred entry point for weak models because the parent model no longer has to remember the orchestration protocol.
+
+For a valid multi-task structured plan, the controller also computes dependency-safe waves, creates isolated Git worktrees for writing tasks, verifies each task independently, rejects writes outside the declared file scope, integrates successful work serially, and rolls back already-integrated work if a later integration in the same wave fails.
+
+### ues_dispatch
+
+
+Runs bundled specialist roles in isolated child Pi processes. Each child receives routed model selection plus a bounded adaptive context pack before execution.
+
+Supported execution patterns:
+
+- single;
+- chain;
+- bounded parallel.
+
+Parallel writer agents require distinct explicit cwd/worktrees. Read-only agents may share the same repository.
+
+Child Pi processes keep extension discovery enabled so custom model providers remain available, while skills, prompt templates and context files are disabled and each specialist receives a strict tool allowlist. Enriched task/context input is piped through stdin instead of argv for Windows command-line safety.
+
+Each child also has bounded runtime supervision: a 30-minute hard timeout, a 5-minute idle timeout and a 15-second heartbeat by default. These can be tuned with `UES_CHILD_HARD_TIMEOUT_MS`, `UES_CHILD_IDLE_TIMEOUT_MS` and `UES_CHILD_HEARTBEAT_MS`.
+
+
+## V14.2 Turbo Weak-Model Runtime
+
+V14.2 keeps the Pi-native controller and specialist roles but changes the hot path to reduce repeated startup, context and verification work.
+
+- `UES_CHILD_RUNTIME=auto` prefers persistent Pi RPC workers and falls back to one-shot CLI children.
+- A fresh Pi session is started between specialist runs even when the worker process stays warm.
+- Interactive steering is forwarded to the single active RPC child; stop/cancel/dừng/hủy abort active children. RPC steer/abort control waits are bounded to 3 seconds by default before abort escalates to process-tree termination.
+- `pi/extensions/ues-child-runtime.ts` is loaded explicitly in child sessions for output compaction, evidence recovery, shell safety and verification receipts.
+- Test/lint/typecheck/build commands receive bounded default timeouts when the model omitted one.
+- Pi's `details.fullOutputPath` is used when available so Evidence Store can preserve the full shell output instead of only the visible truncated tail.
+- Low/medium-risk verifier roles may reuse an exact fresh PASS receipt when the workspace fingerprint is unchanged; high-risk verification does not receive this optimization.
+- Context uses adaptive role budgets, bounded micro-skills, cached dependency graphs and affected-test hints.
+- DEEP/long-horizon structured runs auto-create `.ues-work/<slug>` and require plan/task/integration receipts before finalization.
+
+Useful switches:
+
+```text
+UES_CHILD_RUNTIME=auto
+UES_RPC_MAX_WORKERS=8
+UES_RPC_CONTROL_TIMEOUT_MS=3000
+UES_ADAPTIVE_CONTEXT=1
+UES_MICRO_SKILLS=1
+UES_AFFECTED_TEST_HINTS=1
+UES_CHILD_TOOL_COMPACTION=1
+```
+
+See `docs/V14.2-TURBO-WEAK-MODEL-RUNTIME.md`.
+
+## Prompts
+
+```text
+/ues-run
+/ues-plan
+/ues-feature
+/ues-fix
+/ues-debug
+/ues-review
+/ues-verify
+/ues-audit
+/ues-research
+/ues-critique
+/ues-resume
+```
+
+## Safety
+
+The extension intercepts risky `bash`/`powershell` calls and applies the UES destructive-command guard. Interactive Pi can ask for confirmation; non-interactive risky execution fails closed.
+
+## Validation
+
+Run from the repository:
+
+```cmd
+npm ci --ignore-scripts
+npm test
+npm run syntax
+npm run smoke:pi
+npm run smoke:package
+npm pack --dry-run
+```
+
+The npm package manifest is Pi-only: it does not run lifecycle setup for another coding-agent host.
+
+
+## Weak-model benchmark
+
+Use the Pi-native benchmark to compare the same model with and without UES:
+
+```cmd
+ues eval-pi --model provider/model --thinking low --suite live --trials 3 --mode both
+```
+
+Each run uses an isolated workspace and an external grader. Extension discovery is disabled for fairness, then the model-provider extension is loaded explicitly in both baseline and UES modes; only UES mode additionally loads the UES extension. For `kilo/...` models the benchmark reuses the installed Kilo Pi provider when available and otherwise uses `git:github.com/Kilo-Org/kilo-pi-provider`. Other custom providers can be supplied with repeatable `--provider-extension <source>`. UES mode uses an isolated `UES_CONFIG_DIR` so role routing cannot silently substitute a stronger configured model. Telemetry includes parent and child-agent token/tool usage.
+
+When `--mode both` is used, V14.2 also emits paired benchmark confidence. The turbo promotion view requires quality non-regression, isolated baseline arms, no controller false-PASS, bounded overhead and at least one measured efficiency improvement.
+
+## Model routing
+
+Runtime model routing is configured with `ocskill models ...` and is consumed directly by Pi child-agent dispatch. Set `UES_CONFIG_DIR` to override the UES config root. If a native UES policy does not exist, the runtime can read an existing legacy OpenCode model policy for migration compatibility.
+
+## Package closure
+
+`npm run smoke:package` inspects the actual npm pack file list, verifies required Pi/runtime files are present, checks relative module imports do not point outside the published package, and smoke-runs the deterministic task policy. This guards against the previous class of errors where Git installs worked but npm publication omitted a core dependency.
+
+
+## V14 context and memory fabric
+
+Pi child-agent dispatch keeps the existing specialist set. V14 strengthens the context supplied to those agents instead of adding more roles:
+
+- L0/L1 hierarchy scopes are selected before broad L2 excerpts;
+- only evidence-verified, non-superseded project memories are injected;
+- capability providers expose deterministic health and fallback state.
+
+Useful deterministic commands:
+
+```cmd
+ues capability-fabric status .
+ues hierarchy "task query" .
+ues memory status .
+ues memory search "task query" .
+```
+
+`ues_execute` may persist a verified episodic memory only after an independent verifier has returned PASS. The memory record is backed by a content-addressed evidence receipt and is stored under ignored local `.ues-memory/` state.
+
+See `docs/V14-CONTEXT-MEMORY-FABRIC.md`.

package/docs/V14-CONTEXT-MEMORY-FABRIC.md

@@ -0,0 +1,70 @@
+# V14 Context & Memory Fabric
+
+Status: beta prerelease (`14.0.0-beta.1`).
+
+## Goal
+
+V14 improves weak-model reliability without adding more specialist agents. It moves repository understanding, persistent memory, and tool/provider selection into deterministic runtime layers so the model receives less irrelevant context and makes fewer infrastructure choices itself.
+
+## Architecture
+
+### Hierarchical context
+
+UES builds deterministic repository summaries on top of the incremental semantic index:
+
+- **L0**: bounded routing abstract for a directory/subtree;
+- **L1**: bounded overview with child areas, important symbols, extensions and files;
+- **L2**: existing task-context source/test/instruction excerpts loaded only after scope selection.
+
+`buildContextManifest` still preserves declared files, tests, Git changes and graph evidence, but semantic references inside selected hierarchy scopes receive a deterministic boost. The compact Pi child context includes only the highest-ranked L0/L1 scopes. A diversity fence prevents a single parent/child directory chain from consuming the complete scope budget. Durable `.ues-work` task packs use the same hierarchy, verified-memory recall and bounded capability-provider hints as inline Pi execution.
+
+### Verified persistent memory
+
+Project memory lives in ignored local state under `.ues-memory/MEMORY.json`.
+
+Memory lifecycle:
+
+```text
+candidate -> durable evidence -> independent PASS -> verified -> retrieval
+                                                \-> superseded
+```
+
+A memory cannot become retrievable merely because an agent emitted text. Verification requires at least one content-addressed Evidence Store reference and a named verifier. Successful `ues_execute` runs record a bounded evidence receipt and promote an episodic memory only after task or integration verification passes. Durable work finalization does the same after a recorded integration PASS, using declared plan files rather than unrelated dirty workspace files.
+
+Retrieval combines deterministic lexical BM25-style relevance, hashed-vector similarity, file-path affinity, task-class affinity, scope, recency and confidence using reciprocal-rank fusion. Candidate, superseded and expired memories are excluded. Recalled memories track `lastUsedAt` and `useCount` for future policy tuning.
+
+### Capability fabric
+
+`lib/capability-fabric.mjs` adds a provider layer above individual tools. Each capability may expose primary and fallback providers with health, priority, quality, latency and cost hints. Built-in UES services are health-checked without external network calls; optional command/package providers may be unavailable without making unrelated tasks fail. Bounded success/failure/latency observations are persisted in ignored `.ues-learning/CAPABILITY-OBSERVATIONS.json`; observation weight ramps up over repeated samples so one transient failure cannot immediately poison routing.
+
+Project overrides may be placed in `.ues-capabilities.json` or supplied through `UES_CAPABILITY_CONFIG`.
+
+## CLI
+
+```text
+ues capability-fabric status [dir]
+ues capability-fabric select <capability> [dir]
+
+ues hierarchy "<query>" [dir]
+
+ues memory status [dir]
+ues memory search "<query>" [dir] [--limit N]
+ues memory propose "<text>" [dir] --evidence <evidence:sha256:...>
+ues memory verify <id> [dir] --verdict PASS --verifier <name> [--evidence <ref>]
+ues memory supersede <id> <replacement-id> [dir]
+```
+
+`ues doctor` also prints the currently selected capability providers and fallbacks.
+
+## Safety properties
+
+- no new autonomous specialist role is introduced;
+- memory is fail-closed on missing evidence;
+- supersession requires the replacement memory to be verified first;
+- provider health is deterministic and optional providers do not silently masquerade as healthy;
+- hierarchy and memory are bounded before being injected into child Pi context;
+- memory recording failures never turn a verified engineering task into a failed task.
+
+## Evaluation
+
+V14 adds deterministic unit/CLI regression coverage plus `evals/v14/tasks.json` for hierarchy routing, verified recall, supersession, provider failover and context contamination. The existing weak-model baseline-vs-UES Pi benchmark remains the release-quality measure; V14 does not claim that orchestration makes a weak base model equivalent to a stronger model.

package/docs/V14.1-QUALITY-PERFORMANCE-FABRIC.md

@@ -0,0 +1,114 @@
+# V14.1 Quality-Preserving Performance Fabric
+
+Status: incremental V14.1 work on top of `14.0.0-beta.1`.
+
+## Goal
+
+Increase throughput for weak models without lowering reasoning effort or weakening UES completion gates. V14.1 removes model-visible noise before it removes reasoning, verification, or evidence.
+
+## Non-regression invariants
+
+The default path keeps these properties unchanged:
+
+- inherited Pi thinking level is preserved;
+- executor work still requires independent verification;
+- high-risk and long-horizon work keeps plan, scope, sandbox, retry, fresh-evidence and integration-verification gates;
+- raw evidence remains recoverable;
+- no external optimizer is installed, enabled, or wrapped around Pi automatically;
+- optimization failure is fail-open: UES returns raw output rather than hiding evidence.
+
+## Reversible model-visible output
+
+`lib/performance-fabric.mjs` bounds oversized UES deterministic CLI output using a head / high-signal lines / tail preview. Before any reduction, the exact original is written to the content-addressed Evidence Store.
+
+The compact result includes an `evidence:sha256:...` handle. The original can be recovered with:
+
+```text
+ues store get evidence:sha256:<hash>
+```
+
+Small outputs are returned unchanged. `UES_MODEL_VISIBLE_OUTPUT_LIMIT` controls the Pi adapter threshold and defaults to 64 KiB.
+
+This layer does not rewrite model prompts, source files, verifier reports, or the model's thinking configuration.
+
+## Compact hierarchy
+
+`ues hierarchy` now returns bounded routing data by default: L0/L1 summaries, scores, reasons, counts, top files and top symbols. Complete file arrays remain available explicitly:
+
+```text
+ues hierarchy "<query>" . --full
+```
+
+The adaptive child context was already bounded separately; this change protects direct `ues_cli` use from accidentally injecting very large scope payloads.
+
+## Deterministic read-only fast path
+
+Structured tasks classified by Dynamic Workflow as `deterministic` skip the executor only when `taskWriteFiles()` is empty. The read-only `ues-verifier` still runs with the inherited thinking level and must return PASS. Any task with create/modify/test/delete scope keeps the existing executor → verifier path.
+
+This makes verification-only plan steps such as test, typecheck, lint, compile or explicit verify-command tasks consume one specialist model call instead of two without removing the independent evidence gate.
+
+## Minimal-solution executor policy
+
+The executor now prefers the first maintainable solution that fully satisfies the task:
+
+1. reuse an existing codebase primitive;
+2. use the standard library or native platform capability;
+3. use an already-installed dependency;
+4. write the smallest necessary new implementation.
+
+This is inspired by Ponytail's minimal-solution approach, but UES explicitly forbids using brevity as a reason to weaken validation, error handling, security, data integrity, accessibility, compatibility, tests, observability, or explicit requirements. The rule is scoped to implementation; independent verifiers remain independent.
+
+## External providers
+
+Capability Fabric exposes an `output.compaction` capability with these providers:
+
+- `ues-reversible-compactor`: built-in, default, reversible, non-lossy raw recovery;
+- `rtk-cli`: optional detected command provider for shell-output compaction;
+- `caveman-cli`: optional experimental provider;
+- `headroom-cli`: optional experimental provider.
+
+Detection is not activation. The built-in provider has the highest default score, so installing an external command does not silently alter UES behavior.
+
+RTK is kept outside the Pi hook chain to avoid competing command-rewrite hooks. Caveman remains external because its engine-linked runtime directories are BSL-1.1; UES does not vendor those components into the MIT core. Headroom remains experimental and its output-effort shaping is not enabled by UES.
+
+## On-demand Playwright / Browser MCP lane
+
+UES keeps browser automation out of ordinary coding tasks. At `ues_execute` / `ues_dispatch` time, the Pi extension inspects the host tool registry and selects only tools that identify as Playwright/browser automation. Those names are added to the child `--tools` allowlist only when deterministic task capability inference says browser or visual evidence is needed.
+
+Visual tasks keep the normal executor → verifier → optional integration-verifier path, then add one final `ues-visual-verifier` gate against the rendered state. This does not replace code verification.
+
+The browser lane is evidence-first:
+
+- prefer accessibility/semantic snapshots, console/network evidence and targeted interactions;
+- use screenshots when visual proof is required;
+- treat webpage text, accessibility content, console output and network payloads as untrusted external data;
+- if browser evidence is required but no browser MCP tool is discovered, the child is instructed not to claim browser-visible behavior as verified.
+
+Optional environment overrides:
+
+```text
+UES_BROWSER_MCP_TOOL_NAMES=tool_a,tool_b,...
+UES_BROWSER_MCP_TOOL_LIMIT=14
+```
+
+## Promotion gate
+
+An external provider should become a default only after a paired baseline-vs-provider evaluation on the same model and task set shows all of the following:
+
+```text
+pass rate >= baseline
+false PASS rate <= baseline
+safety/required gates >= baseline
+and latency or token usage materially improves
+```
+
+Until that evidence exists, external compressors remain optional capabilities rather than default execution policy.
+
+## Upstream inspirations
+
+- Ponytail — DietrichGebert/ponytail (MIT)
+- RTK — rtk-ai/rtk (Apache-2.0)
+- Headroom — headroomlabs-ai/headroom (Apache-2.0)
+- Caveman — JuliusBrussee/caveman (MIT skill/CLI areas plus BSL-1.1 engine-linked runtime areas)
+
+UES uses architectural ideas and external provider detection; it does not vendor upstream runtime code in this change.