UES for Pi Agent

Universal Engineering System (UES) là một engineering runtime dành cho Pi Agent, tập trung vào việc giúp model coding nhỏ/yếu làm việc có cấu trúc hơn trên repository thật: lấy đúng context, chia task, giữ trạng thái dài hạn, cô lập thay đổi, thu evidence và chỉ kết luận khi có verification.

Package: opencode-agent-skill
Host chính: Pi Agent
Phiên bản package hiện tại: 14.4.0
Release hiện tại: V14.4 Stable Weak-Model Intelligence Runtime
Runtime: Node.js 22.19+
License: MIT

UES không biến một model nhỏ thành model lớn theo nghĩa năng lực nền tảng. UES cố gắng giảm phần suy luận hạ tầng mà model phải tự gánh bằng deterministic tooling, bounded context, specialist roles, durable state và evidence-gated verification.

Mục lục

UES giải quyết vấn đề gì?
Kiến trúc tổng thể
Luồng /ues-run end-to-end
Task Policy: FAST / STANDARD / DEEP
12 specialist agents
48 skills
11 slash prompts
Context Engine L0/L1/L2
Semantic index, repo graph và ACI
Model routing và recovery
Task graph, Dynamic Workflow và parallel runtime
Worktree sandbox
Evidence Store, receipts và verification gates
V14.1 reversible output compaction
V14.2 Turbo Weak-Model Runtime
Verified Persistent Memory
Capability Fabric
Playwright / Browser MCP on-demand
Trajectory và observability
Learning engine và benchmark confidence
Durable long-horizon work
Control Center
Safety model
Cài đặt
Cập nhật
Đóng gói npm
Các CLI quan trọng
Benchmark model yếu
Cấu trúc repository
Triết lý thiết kế
Giới hạn có chủ đích

UES giải quyết vấn đề gì?

Một coding model yếu thường gặp các vấn đề sau khi làm việc trên repository thật:

Vấn đề	Nếu để model tự xử lý	UES xử lý thế nào
Repository lớn	đọc quá nhiều file, mất context	semantic index + hierarchy L0/L1/L2 + bounded context
Task dài	quên mục tiêu, lặp lại việc	durable work state + PLAN/STATE/EVENTS
Nhiều thay đổi song song	đụng file, ghi đè nhau	task graph + safe waves + worktree sandbox
Không biết test gì	chạy full CI hoặc đoán	detect-tests + verification plan + declared verification commands
Model báo xong quá sớm	false PASS	verifier + integration-verifier + receipts
Retry mù	vá chồng vá	diagnosis-first recovery policy
Log quá lớn	token phình	reversible model-visible compaction
Tool quá nhiều	model chọn sai tool	role allowlist + capability-based routing
UI/browser	đoán thay vì quan sát	Playwright/Browser MCP lane + visual verifier
Kinh nghiệm cũ	nhớ sai hoặc nhiễm	verified persistent memory
Tối ưu không có bằng chứng	nhanh hơn nhưng yếu đi	baseline-vs-UES eval + promotion confidence

Kiến trúc tổng thể

flowchart TD
    U[User task] --> P[Pi Agent]
    P --> X[UES extension]

    X --> TP[Task Policy]
    TP --> C[Context Engine]
    TP --> M[Model Policy]
    TP --> W[Workflow Policy]

    C --> H[Hierarchy L0 L1 L2]
    C --> SI[Semantic Index]
    C --> MEM[Verified Memory]
    C --> CAP[Capability Fabric]
    C --> EV[Evidence Store]

    W --> A[Specialist Agents]
    W --> TG[Task Graph]
    W --> DW[Dynamic Workflow]
    W --> SB[Worktree Sandbox]

    A --> EX[Executor]
    A --> VE[Verifier]
    A --> IV[Integration Verifier]
    A --> VV[Visual Verifier]

    EX --> CHECK[Project-native checks]
    VE --> CHECK
    IV --> CHECK
    VV --> BROWSER[Playwright Browser evidence]

    CHECK --> R[Fresh Evidence]
    BROWSER --> R
    R --> G{Verification gates}
    G -->|PASS| DONE[Verified completion]
    G -->|FAIL| REC[Diagnosis and bounded retry]
    REC --> C

Các lớp chính

1. Pi host layer

Pi chịu trách nhiệm session, model provider, thinking level, built-in tools và extension runtime.

2. UES Pi extension

File chính: pi/extensions/ues.ts.

Extension đăng ký ba tool orchestration:

Tool	Vai trò
`ues_execute`	Chạy task engineering end-to-end
`ues_cli`	Gọi deterministic UES CLI không qua shell interpolation
`ues_dispatch`	Gọi specialist child agents theo single / chain / bounded parallel

3. Deterministic engine

Thư mục lib/ chứa các engine cho:

task/risk classification;
semantic index;
repo graph;
context manifest;
evidence storage;
receipts;
work state;
task graph;
safe-wave scheduling;
model routing;
memory;
capability selection;
browser evidence;
benchmark/learning;
safety;
Windows compatibility.

4. Specialist layer

UES không dùng một prompt khổng lồ cho mọi việc. Nó có 12 specialist roles với tool boundary khác nhau.

5. Verification layer

Hoàn thành không đồng nghĩa model nói “done”. UES cố gắng ràng buộc completion với fresh evidence, receipt và verifier độc lập.

Luồng /ues-run end-to-end

/ues-run là entry point khuyến nghị cho engineering task.

sequenceDiagram
    participant U as User
    participant P as Pi
    participant UES as UES Controller
    participant CTX as Context Engine
    participant EX as Executor
    participant V as Verifier
    participant IV as Integration Verifier
    participant VV as Visual Verifier

    U->>P: /ues-run task
    P->>UES: ues_execute(task)
    UES->>UES: classify task/risk/profile
    UES->>CTX: build bounded context
    CTX-->>UES: hierarchy + evidence + memory + capability hints

    alt long/high risk
        UES->>UES: architect + structured plan
        UES->>UES: plan-checker gate
    end

    UES->>EX: fresh specialist execution
    EX-->>UES: implementation handoff

    UES->>V: independent verification
    V-->>UES: PASS / FAIL / PARTIAL

    alt integration required
        UES->>IV: cross-task/final repository verification
        IV-->>UES: PASS / FAIL / PARTIAL
    end

    alt visual/browser evidence required
        UES->>VV: rendered-state verification
        VV-->>UES: PASS / FAIL / PARTIAL
    end

    alt all required gates PASS
        UES-->>P: verified completion
        P-->>U: final result
    else failure
        UES->>UES: diagnosis / recovery / bounded retry
    end

UES không làm gì ở luồng này?

không tự push;
không tự publish npm;
không tự deploy production;
không coi executor report là bằng chứng hoàn thành;
không bỏ verifier chỉ vì compile pass;
không lưu hidden chain-of-thought.

Task Policy: FAST / STANDARD / DEEP

Task Policy nằm trong lib/task-policy.mjs và phân loại task theo tín hiệu có thể quan sát.

flowchart LR
    T[Task text + repo facts] --> S[Risk and complexity signals]

    S --> F{Classification}
    F -->|low + bounded| FAST[FAST]
    F -->|medium| STD[STANDARD]
    F -->|long horizon or high risk| DEEP[DEEP]

    FAST --> F1[8k context budget]
    FAST --> F2[max 2 skills]
    FAST --> F3[targeted verification]

    STD --> S1[20k context budget]
    STD --> S2[max 4 skills]
    STD --> S3[targeted + affected verification]

    DEEP --> D1[48k context budget]
    DEEP --> D2[max 5 skills]
    DEEP --> D3[plan + integration + durable state]

FAST

Dành cho task nhỏ, low-risk, bounded.

Đặc điểm:

context budget mặc định khoảng 8k;
tối đa 2 skills;
direct skill loading;
không bắt durable work;
verification targeted;
không bật full CI mặc định.

STANDARD

Dành cho task vừa, có debugging/change scope đáng kể.

Đặc điểm:

context budget khoảng 20k;
tối đa 4 skills;
selective skill loading;
affected verification;
worktree khi có conflict.

DEEP

Dành cho long-horizon/high-risk.

Đặc điểm:

context budget đến khoảng 48k;
tối đa 5 skills;
structured plan;
durable state;
plan checker;
worktree cho writers;
integration verification;
full CI policy;
critic ở high-risk/final paths.

High-risk signals

UES phân biệt “chỉ nhắc tới database/security” với “thực sự thay đổi database/security”.

Những thay đổi như sau có thể nâng risk:

auth/permission/security mutation;
payment flow;
database/schema migration;
production deploy;
secret/credential rotation;
breaking public API;
destructive Git/database action.

12 specialist agents

Thư mục: global-config/agents/.

Agent	Nhiệm vụ	Có ghi file?	Khi dùng
architect	thiết kế plan/contract/dependency	không	task phức tạp, long-horizon
codebase-mapper	đọc repo và map scope	không	repo lớn/không rõ vị trí
critic	phản biện plan/solution	không	high-risk hoặc recovery sâu
debugger	tìm nguyên nhân gốc từ evidence	không	bug/failure/retry
executor	thực thi thay đổi nhỏ nhất hợp lý	có	implementation
integration-verifier	kiểm tra final cross-task state	không	standard/deep/high-risk
merge-arbiter	xử lý integration/merge boundary	có	conflict/merge workflow
plan-checker	kiểm tra plan có grounded không	không	trước long/high-risk execution
researcher	nghiên cứu bằng chứng	không	uncertainty/external facts
reviewer	review thay đổi	không	code review/audit
verifier	fresh independent verification	không	completion gate
visual-verifier	verify rendered UI/browser state	không	visual/browser task

Quan hệ giữa các agent

flowchart TD
    MAP[codebase-mapper] --> ARCH[architect]
    ARCH --> PC[plan-checker]
    PC --> EX[executor]

    EX --> V[verifier]
    V -->|PASS| IV[integration-verifier]
    V -->|FAIL| D[debugger]

    D --> EX
    D --> C[critic]
    C --> ARCH

    IV -->|visual task| VV[visual-verifier]
    IV -->|non visual| DONE[complete]
    VV --> DONE

    R[researcher] -. evidence .-> ARCH
    R -. evidence .-> D
    REV[reviewer] -. review .-> V

48 skills

UES hiện có 48 skill directories trong global-config/skills/. Skills không phải 48 agent độc lập; chúng là bounded domain instructions để UES chỉ nạp đúng chuyên môn cần thiết.

Nhóm orchestration và reasoning

engineering-orchestrator
dynamic-workflow
task-planner
software-architect
context-engineering
change-impact-analysis
repo-explorer
research-verification
long-task-state
implementation-engineer
bug-diagnosis
code-review
skill-authoring
skill-evaluation

Nhóm verification và testing

test-driven-development
test-verification
accessibility
responsive-verification
component-visual-testing
visual-fidelity
browser-qa
browser-security
web-security-review
performance-engineering

Nhóm backend / API / data

api-contract
rest-api-design
auth-security
database-engineering
payment-engineering
ecommerce-engineering
file-upload-engineering
dependency-management
devops-engineering
documentation-engineering
git-safety

Nhóm framework / language

nodejs-engineering
nextjs-engineering
react-engineering
react-native-engineering
nestjs-engineering
fastapi-engineering
django-engineering
python-engineering
java-spring-engineering
dotnet-engineering
flutter-engineering

Nhóm UI/design

ui-ux-engineering
design-source

Mục tiêu của skill routing là progressive disclosure: model không phải đọc tất cả 48 skills cho một task.

11 slash prompts

Pi package cung cấp 11 slash prompts:

Command	Ý nghĩa
`/ues-run`	controller end-to-end
`/ues-plan`	lập kế hoạch
`/ues-feature`	triển khai feature
`/ues-fix`	sửa bug
`/ues-debug`	điều tra failure
`/ues-review`	review code/scope
`/ues-verify`	xác minh claim
`/ues-audit`	audit scope
`/ues-research`	research
`/ues-critique`	phản biện proposal
`/ues-resume`	tiếp tục durable work

flowchart LR
    CMD[Slash command] --> ROUTE[UES router/controller]
    ROUTE --> POLICY[Task policy]
    POLICY --> AGENT[Relevant specialist path]
    AGENT --> EVIDENCE[Fresh evidence]
    EVIDENCE --> RESULT[Result]

Context Engine L0/L1/L2

Một trong các mục tiêu lớn của UES là nạp ít context hơn nhưng đúng hơn.

flowchart TD
    Q[Task query] --> TERM[Extract bounded terms]
    TERM --> IDX[Semantic index]
    IDX --> H0[L0 routing abstract]
    H0 --> H1[L1 subtree overview]
    H1 --> H2[L2 exact excerpts on demand]

    GIT[Git changed files] --> RANK[Ranking]
    DECL[Declared files] --> RANK
    TEST[Likely tests] --> RANK
    SYM[Symbol hits] --> RANK
    MEM[Verified memory] --> RANK

    H2 --> RANK
    RANK --> PACK[Bounded context pack]
    PACK --> CHILD[Fresh child agent]

L0

Routing abstract rất ngắn:

khu vực nào có vẻ liên quan;
key symbols;
child areas.

L1

Scope overview:

file count;
extension mix;
symbols;
bounded file names;
subtree relation.

L2

Exact excerpts chỉ load khi cần.

Context pack có thể bao gồm

declared files;
import neighbors;
likely tests;
nearby instructions;
Git-changed files;
semantic references;
symbol hits;
evidence refs;
verified memories;
provider hints;
recent failure.

Semantic index, repo graph và ACI

UES có ba lớp khác nhau; chúng không phải một thứ.

Semantic Index

lib/semantic-index.mjs

Dùng để tạo persistent incremental index phục vụ retrieval.

flowchart LR
    SRC[Source files] --> PARSE[Bounded parse]
    PARSE --> SYMBOLS[Symbols]
    PARSE --> TERMS[Terms]
    SYMBOLS --> INDEX[Persistent semantic index]
    TERMS --> INDEX
    INDEX --> QUERY[Task query]
    QUERY --> RANK[Ranked references]

CLI:

ues index status .
ues index build .
ues index rebuild .

Repo Graph

lib/repo-graph.mjs

Tạo bounded import/dependency graph:

local edges;
external imports;
coupling hotspots.

Nó không tự nhận là full language-server call graph.

flowchart LR
    FILES[Source files] --> IMPORTS[Import extraction]
    IMPORTS --> LOCAL[Local dependency edges]
    IMPORTS --> EXT[External import frequency]
    LOCAL --> HOT[Coupling hotspots]
    EXT --> HOT

CLI:

ues repo-graph .
ues repo-graph . --compact

ACI

lib/aci.mjs

Evidence-first code interface cho:

search;
references;
view;
bounded text search.

CLI:

ues aci search ...
ues aci refs ...
ues aci view ...
ues aci text ...

Model routing và recovery

UES không hard-code tên model “mạnh nhất”. Model IDs do người dùng cấu hình.

Tier

light
standard
heavy

Role có default tier, và attempt có thể escalate trong giới hạn cấu hình.

flowchart TD
    TASK[Task] --> CLASS[Task class + risk]
    CLASS --> BASE[Base tier]
    BASE --> CAPS[Required capabilities]
    CAPS --> PERF[Historical model performance]
    PERF --> SELECT[Select configured model]

    SELECT --> RUN[Attempt]
    RUN -->|PASS| DONE[Done]
    RUN -->|FAIL attempt 1| DIAG[Diagnosis]
    DIAG --> RETRY[Attempt 2]
    RETRY -->|FAIL| DEEP[Deep recovery + critic]
    DEEP --> STRONGER[Eligible stronger tier]

Recovery policy

Attempt 1

normal bounded context;
smallest coherent implementation.

Attempt 2

dedicated diagnosis;
mở rộng context vừa phải;
caller/test/failure-adjacent evidence;
không vá speculative chồng lên patch cũ.

Attempt 3

deep recovery;
semantic + graph + Git context;
critic;
re-investigate failed hypothesis;
architecture/coupling review khi cần.

Task graph, Dynamic Workflow và parallel runtime

Structured plan dùng JSON schema version 1.

Mỗi task có thể khai báo:

id;
title;
summary;
dependsOn;
files create/modify/test/delete/read;
acceptance;
verification;
optional verificationCommands;
risk.

Dependency validation

UES kiểm tra:

duplicate IDs;
missing dependency;
self dependency;
cycles;
path escape;
acceptance/verification thiếu;
invalid risk.

Safe waves

flowchart TD
    PLAN[PLAN tasks] --> DAG[Dependency DAG]
    DAG --> READY[Ready tasks]
    READY --> FILES[Read/write file scope]
    FILES --> CONFLICT{Conflict?}

    CONFLICT -->|No| SAME[Same safe wave]
    CONFLICT -->|Yes| SERIAL[Serialize]

    SAME --> PAR[Bounded parallel execution]
    SERIAL --> NEXT[Later wave]

Read/read overlap có thể chạy cùng wave. Writer xung đột với reader/writer sẽ bị serialize nếu scope overlap hoặc không đủ rõ.

Dynamic Workflow

lib/dynamic-workflow.mjs phân task thành:

deterministic;
inline;
agent;
vision-related work.

flowchart LR
    T[Task] --> K{Kind}
    K -->|test lint typecheck compile| DET[Deterministic]
    K -->|small bounded reasoning| INLINE[Inline]
    K -->|independent substantial work| AG[Agent]
    K -->|visual judgment| VISION[Vision agent]

    DET --> SAVE[No unnecessary executor slot]
    INLINE --> SAVE
    AG --> SLOT[LLM slot]
    VISION --> VSLOT[Vision slot]

V14.1 có fast path: deterministic read-only task có thể bỏ executor nhưng verifier vẫn phải PASS.

Worktree sandbox

Parallel writers không được cùng sửa một checkout.

sequenceDiagram
    participant R as Root repo
    participant U as UES Scheduler
    participant W1 as Worktree T1
    participant W2 as Worktree T2

    U->>R: inspect dirty state
    U->>W1: create isolated worktree
    U->>W2: create isolated worktree

    W1->>W1: execute + verify T1
    W2->>W2: execute + verify T2

    U->>W1: inspect changed files
    U->>W2: inspect changed files
    U->>R: conflict check

    alt safe integration
        U->>R: apply T1 patch
        U->>R: apply T2 patch
    else conflict/failure
        U->>R: refuse or rollback integrated wave
    end

Safety của worktree

root dirty mặc định bị chặn nếu không dùng explicit inheritance;
dirty root có thể được snapshot vào sandbox theo policy;
integration kiểm tra overlap với thay đổi root;
branch cleanup chỉ xóa branch namespace UES;
rollback dùng reverse patch;
không force-push.

Evidence Store, receipts và verification gates

Evidence Store

UES có content-addressed Evidence Store.

flowchart LR
    RAW[Raw output / artifact] --> HASH[SHA-256]
    HASH --> STORE[Evidence Store]
    STORE --> REF[evidence:sha256:...]
    REF --> RECEIPT[Verification / memory / gate receipt]
    REF --> GET[Bounded retrieval]

CLI:

ues store status .
ues store put ...
ues store get evidence:sha256:<hash>
ues store gc .

Verification receipts

Receipt có thể bind:

command result;
output digest;
before/after workspace fingerprint;
verifier;
verdict;
active run/task.

Mục tiêu là tránh tình trạng:

test từng PASS ở trạng thái A
→ code thay đổi sang trạng thái B
→ model vẫn dùng PASS cũ để tuyên bố hoàn thành

Gate model

flowchart TD
    PLAN[Plan] --> PG[Plan checker]
    PG --> PR[Plan receipt]
    PR --> EXEC[Execution]

    EXEC --> TV[Task verifier]
    TV --> TR[Task verification receipt]

    TR --> INT[Integration verifier]
    INT --> IR[Integration receipt]

    IR --> FP{Workspace fingerprint unchanged?}
    FP -->|Yes| FINAL[Finalize]
    FP -->|No| INVALID[Receipt stale - reverify]

V14.1 reversible output compaction

Mục tiêu của V14.1 là giảm model-visible noise mà không bỏ raw evidence.

flowchart TD
    OUT[Large CLI/tool output] --> SIZE{Over limit?}
    SIZE -->|No| RAW[Return unchanged]
    SIZE -->|Yes| SAVE[Store exact raw bytes in Evidence Store]
    SAVE --> PREVIEW[Build head + high-signal + tail preview]
    PREVIEW --> MODEL[Send bounded preview to model]
    MODEL --> NEED{Need more?}
    NEED -->|Yes| REF[Retrieve exact slices by evidence ref]
    NEED -->|No| CONT[Continue]

Default model-visible limit hiện khoảng 64 KiB.

High-signal lines ưu tiên các pattern như:

error;
failed;
exception;
warning;
timeout;
traceback;
mismatch;
conflict;
passed;
tests;
exit code;
changed.

Quan trọng

thinking level không bị hạ bởi compaction;
raw output được lưu trước khi compact;
small output giữ nguyên;
failure của compaction fail-open về raw output.

V14.2 Turbo Weak-Model Runtime

V14.2 tối ưu hot path cho model yếu/siêu yếu mà không hạ thinking hoặc bỏ verification gate.

flowchart TD
    T[Task] --> P[Task Policy]
    P --> C[Adaptive context]
    C --> G[Semantic + dependency graph rank]
    G --> S[Bounded micro-skills]
    S --> W[Warm Pi RPC worker]

    W --> E[Executor]
    E --> R[Tool-boundary verification receipts]
    R --> V[Verifier]

    V -->|fresh receipt fully covers check| REUSE[Reuse exact PASS receipt]
    V -->|missing/stale/high-risk| RUN[Run fresh check]

    REUSE --> IV[Integration verification when required]
    RUN --> IV

    E --> O[Large tool output]
    O --> COMP[Command-aware compaction]
    COMP --> RAW[Raw bytes in Evidence Store]
    RAW --> REC[Selective recovery on demand]

Các thay đổi chính:

warm Pi RPC worker pool với fresh session giữa specialist runs;
interactive steering/abort khi một child đang active;
unified process-tree supervisor + bounded I/O drain;
rolling Jest/open-handle detection;
adaptive role-aware context budgets;
runtime context + dependency-graph cache theo workspace fingerprint;
bounded micro-skill compiler thay vì load toàn bộ skill catalog;
affected-test hints;
verification receipt reuse chỉ khi fingerprint còn nguyên;
high-risk verifier không dùng receipt reuse optimization;
child test/lint/typecheck/build có timeout theo profile;
full shell output được recover từ Pi fullOutputPath khi có;
command-aware reversible compaction ngay ở child tool-result boundary;
JSON evidence selector để lấy đúng subtree;
personalized dependency graph ranking;
task-specific Browser MCP subset;
confidence-bound weak-model routing;
DEEP task auto-promote sang .ues-work durable workflow;
paired benchmark có turbo promotion gate: quality non-regression + efficiency gain + zero controller false-PASS.

Các optimization quan trọng có thể rollback riêng:

UES_CHILD_RUNTIME=cli
UES_ADAPTIVE_CONTEXT=0
UES_MICRO_SKILLS=0
UES_AFFECTED_TEST_HINTS=0
UES_CHILD_TOOL_COMPACTION=0

Chi tiết: docs/V14.2-TURBO-WEAK-MODEL-RUNTIME.md.

Verified Persistent Memory

Memory của UES không phải “chat memory tự do”. Retrieval chỉ dùng memory đủ điều kiện.

flowchart TD
    EXPERIENCE[Task outcome] --> CAND[Memory candidate]
    CAND --> EVID{Has durable evidence?}
    EVID -->|No| DROP[Not retrievable]
    EVID -->|Yes| VER{Verifier PASS?}
    VER -->|No| DROP
    VER -->|Yes| VM[Verified memory]

    VM --> RANK[Hybrid retrieval]
    RANK --> LEX[Lexical relevance]
    RANK --> VEC[Deterministic vector similarity]
    RANK --> FILE[File affinity]
    RANK --> REC[Recency/confidence]
    RANK --> TASK[Task-class affinity]

    LEX --> TOP[Bounded top memories]
    VEC --> TOP
    FILE --> TOP
    REC --> TOP
    TASK --> TOP

Memory hỗ trợ:

candidate / verified / superseded lifecycle;
confidence;
expiry;
task-class affinity;
usage accounting;
evidence references;
supersession.

CLI:

ues memory status .
ues memory retrieve ...
ues memory propose ...
ues memory verify ...
ues memory supersede ...

Capability Fabric

Capability Fabric giúp model không phải tự đoán backend/tool nào đang khỏe.

Built-in capability groups

Source hiện có các nhóm như:

code.search;
memory;
evidence;
output.compaction;
filesystem;
git;
agent.host;
github;
browser.

flowchart TD
    NEED[Required capability] --> REG[Provider registry]
    REG --> PROBE[Health probe]
    PROBE --> SCORE[Score]

    OBS[Persisted success/failure/latency] --> SCORE
    QUALITY[Quality] --> SCORE
    COST[Cost class] --> SCORE
    LAT[Latency class] --> SCORE

    SCORE --> PRIMARY[Selected provider]
    SCORE --> FALLBACK[Fallback providers]

Provider score xét:

configured priority;
quality;
current health;
historical success/failure;
cost class;
latency class.

Output compaction providers

V14.1 có registry cho:

built-in ues-reversible-compactor — mặc định;
RTK CLI — optional;
Caveman CLI — optional experimental;
Headroom CLI — optional experimental.

Detection không có nghĩa auto-enable external provider.

Playwright / Browser MCP on-demand

UES có browser adapter/runtime riêng và thêm routing cho Playwright/Browser MCP đang có trong Pi host.

Mục tiêu: browser tools chỉ xuất hiện khi task thực sự cần browser/visual evidence.

flowchart TD
    TASK[Task] --> NEED{Needs browser or visual evidence?}

    NEED -->|No| NORMAL[Normal agent tool allowlist]
    NEED -->|Yes| DISCOVER[Inspect host Pi tool registry]

    DISCOVER --> SELECT[Select Playwright/browser tools]
    SELECT --> CHILD[Add selected names to child --tools]

    CHILD --> SNAP[Semantic/accessibility snapshot]
    CHILD --> INT[Targeted interaction]
    CHILD --> LOG[Console/network evidence]
    CHILD --> SHOT[Screenshot when visual proof needed]

    SNAP --> VV[Visual verifier]
    INT --> VV
    LOG --> VV
    SHOT --> VV

    VV -->|PASS| DONE[Visual claim verified]
    VV -->|FAIL / no evidence| STOP[No browser-visible PASS claim]

Routing behavior

Backend task

Ví dụ:

/ues-run sửa transaction inventory backend và chạy test

Playwright không cần được thêm vào child agent.

Browser E2E task

Ví dụ:

/ues-run kiểm tra checkout form bằng browser, click flow và console error

Browser MCP lane được yêu cầu.

Visual task

Ví dụ:

/ues-run sửa giao diện theo ảnh mẫu và kiểm tra responsive

Sau code verifier/integration verifier, UES có thể chạy thêm ues-visual-verifier.

Evidence order

UES ưu tiên:

semantic/accessibility snapshot;
DOM/target state;
targeted interaction;
console/network evidence;
viewport checks;
screenshot khi cần visual proof.

Browser security

Webpage text, accessibility content, console output và network payload được coi là untrusted external evidence.

Page content không được:

thay đổi permissions;
yêu cầu secret;
override system/task instructions;
tự cấp quyền external/destructive side effect.

Optional overrides

Nếu Browser MCP dùng tên tool lạ:

set UES_BROWSER_MCP_TOOL_NAMES=browser_navigate,browser_snapshot,browser_screenshot,browser_click
set UES_BROWSER_MCP_TOOL_LIMIT=14

Trajectory và observability

lib/trajectory.mjs lưu operational events, không lưu hidden chain-of-thought.

flowchart LR
    RUN[Agent run] --> EVT[Observable event]
    EVT --> SCRUB[Secret redaction]
    SCRUB --> LIMIT[Bound event size]
    LIMIT --> JSONL[.ues-traces trace.jsonl]

    JSONL --> SHOW[trace show]
    JSONL --> DEBUG[Debug/replay analysis]

Trajectory scrub các dạng dữ liệu như:

Authorization Bearer;
OpenAI-style API keys;
GitHub tokens;
npm tokens;
generic api_key/token/secret/password/credential fields.

Large event payload được bounded và có SHA-256 digest.

CLI:

ues trace append ...
ues trace show ...

Learning engine và benchmark confidence

Learning của UES được thiết kế theo hướng proposal → shadow evidence → promotion, không phải “agent fail một lần rồi tự sửa rule vĩnh viễn”.

flowchart TD
    EVAL[Eval artifacts] --> ANALYZE[Analyze recurring failures]
    ANALYZE --> PROP[Learning proposal]
    PROP --> ACCEPT[Manual acceptance]
    ACCEPT --> SHADOW[Shadow benchmark required]

    SHADOW --> PAIR[Paired baseline vs UES]
    PAIR --> CONF[Statistical confidence checks]

    CONF -->|Eligible| PROMOTE[Promote learning]
    CONF -->|Not eligible| HOLD[Keep unpromoted]

Failure patterns được phân tích

Ví dụ:

hard-timeout;
idle-timeout;
agent-exit;
grader-failure;
orchestration-failure;
telemetry parse errors.

Promotion confidence

lib/benchmark-confidence.mjs so sánh paired baseline/UES:

total paired samples;
both pass;
both fail;
baseline-only win;
UES-only win;
pass-rate delta;
exact sign-test p-value;
per-suite regression;
duration ratio;
initial input ratio;
token ratio;
cost summary.

Promotion yêu cầu nhiều điều kiện cùng đạt, không chỉ “UES thắng một vài task”.

Durable long-horizon work

Task dài có thể dùng .ues-work/<slug>/ làm source of truth.

.ues-work/<slug>/
  SPEC.md
  PLAN.json
  STATE.json
  EVIDENCE.json
  EVENTS.jsonl
  ACTIVE_PLAN.json
  tasks/
  reports/
  plans/

State machine khái quát

stateDiagram-v2
    [*] --> Initialized
    Initialized --> Planned
    Planned --> PlanApproved
    PlanApproved --> Running
    Running --> Running: next task
    Running --> Blocked
    Blocked --> Running
    Running --> IntegrationVerification
    IntegrationVerification --> Finalized: PASS + fresh fingerprint
    IntegrationVerification --> Running: FAIL / rework
    Running --> Recovering: stale lease / interruption
    Recovering --> Running

Locking

State/evidence mutation dùng:

per-work lock;
heartbeat;
stale lock recovery;
atomic file replacement.

Runtime events

EVENTS.jsonl append-only cho operational observability.

Control Center

UES có local Control Center qua:

ues dashboard .
ues dashboard . --serve

Control Center tổng hợp các loại dữ liệu như:

durable work;
task state;
blockers;
receipts;
recent events;
eval summaries;
learning state;
evidence store;
verified memory;
capability fabric health.

flowchart LR
    WORK[.ues-work] --> CC[Control Center]
    EVENTS[EVENTS.jsonl] --> CC
    EV[Evidence Store] --> CC
    MEM[Memory] --> CC
    CAP[Capability Fabric] --> CC
    LEARN[Learning] --> CC
    EVAL[Eval artifacts] --> CC

Control Center là observer/controller cục bộ; nó không bypass verification/safety gates.

Safety model

UES cố gắng đưa safety vào code thay vì chỉ nhắc model.

Shell safety

Có detection/gate cho các thao tác rủi ro như:

force push;
history rewrite;
reset hard;
recursive destructive deletion;
destructive database commands;
deploy/apply;
publish.

Scope safety

Structured task phải khai báo file scope. Scheduler kiểm tra actual changed files so với declared write scope.

Parallel safety

Writer agents chạy parallel phải ở distinct worktree/cwd.

Evidence safety

Old PASS không tự được coi là hợp lệ nếu workspace đã thay đổi.

Browser safety

External page content là untrusted.

Memory safety

Candidate hoặc superseded memory không được retrieval như verified memory.

Learning safety

Proposal không tự promote nếu chưa có benchmark evidence phù hợp.

Cài đặt

Yêu cầu

Node.js 22.19+
Git
Pi Agent

Cài Pi:

npm install -g @earendil-works/pi-coding-agent
pi --version

Cài UES stable từ npm (khuyến nghị):

pi install npm:opencode-agent-skill
pi list
pi

Hoặc cài CLI toàn cục:

npm install -g opencode-agent-skill@latest
ues version

Cài trực tiếp từ GitHub main nếu muốn dùng source mới nhất:

pi install git:github.com/laivannha0202/opencode-agent-skill-
pi list
pi

Nếu đã clone repo local:

cd /d E:\Code\opencode-agent-skill-
npm install
pi install .

Cập nhật

Nếu cài từ clone local:

cd /d E:\Code\opencode-agent-skill-
git status
git pull --ff-only origin main
pi install .

Nếu local có thay đổi chưa commit, hãy backup/stash hoặc xử lý diff trước khi pull. Không nên reset/clean mù quáng.

Đóng gói npm

Kiểm tra đầy đủ trước khi pack:

npm install
npm run ci
npm pack --dry-run
npm pack

Package stable hiện tại trong package.json là:

14.4.0

V14.4 gom V14/V14.1/V14.2 cùng code intelligence, hash-anchored editing, completion auditor, stable memory snapshots, reversible context/document ingestion và MCP health-aware routing thành release stable.

Test file packed với Pi:

pi install .\opencode-agent-skill-14.4.0.tgz
pi list

Publish thật chỉ nên thực hiện sau khi CI và package smoke tests PASS.

Các CLI quan trọng

CLI ưu tiên là ues; ocskill vẫn là compatibility alias.

Repository intelligence

ues inspect .
ues impact <query> .
ues evidence .
ues working-tree .
ues repo-graph .
ues index status .
ues index build .
ues aci search ...

Task và verification

ues task-policy "<task>"
ues verification-plan .
ues task-graph PLAN.json
ues workflow-plan PLAN.json
ues review-scope main .

Durable work

ues work init <slug> . --goal "..."
ues work plan <slug> PLAN.json .
ues work approve-plan <slug> . --evidence "..."
ues work start <slug> <task-id> .
ues work verify-command <slug> <task-id> . --run-id <id> -- npm test
ues work complete <slug> <task-id> . --run-id <id> --evidence "..."
ues work verify-integration <slug> . --verdict PASS --evidence "..."
ues work finalize <slug> . --evidence "..."
ues work events <slug> .
ues work resume <slug> .

Sandbox

ues sandbox list .
ues sandbox create ...
ues sandbox integrate ...
ues sandbox rollback ...
ues sandbox remove ...

Context / memory / capability

ues hierarchy "<query>" .
ues hierarchy "<query>" . --full
ues memory status .
ues capability-fabric status .
ues capabilities "<task>"

Evidence / trace

ues store status .
ues store get evidence:sha256:<hash>
ues trace show ...

Browser / visual

ues browser capability .
ues browser plan ...
ues browser inspect ...
ues visual ...
ues ui tokens ...
ues ui layout ...

Models

ues models status
ues models on
ues models set light <provider/model>
ues models set standard <provider/model>
ues models set heavy <provider/model>
ues models role verifier standard

Learning / eval

ues eval-pi --model provider/model --thinking low --suite live --trials 3 --mode both
ues learn analyze . --eval-dir .ues-evals

Benchmark model yếu

UES có Pi-native baseline-vs-UES benchmark.

flowchart LR
    TASKS[Same benchmark tasks] --> B[Baseline Pi]
    TASKS --> U[Pi + UES]

    B --> BG[External grader]
    U --> UG[External grader]

    B --> BT[Tokens/cost/tool telemetry]
    U --> UT[Tokens/cost/tool telemetry]

    BG --> PAIR[Paired comparison]
    UG --> PAIR
    BT --> PAIR
    UT --> PAIR

    PAIR --> CONF[Confidence / regression checks]

Ví dụ:

ues eval-pi --model provider/model --thinking low --suite live --trials 3 --mode both

Eval script thu thập:

pass/fail;
duration;
parent tool calls;
child tool calls;
input/output/cache token telemetry;
reported cost;
controller usage;
workspace changes;
external grader result.

Eval suites trong repo

Hiện có các nhóm như:

live;
long;
polyglot;
repo-scale;
v11;
v14;
routing/router trigger suites.

Cấu trúc repository

opencode-agent-skill-/
├─ bin/
│  └─ ocskill.mjs
│
├─ lib/
│  ├─ task-policy.mjs
│  ├─ task-engine.mjs
│  ├─ task-graph.mjs
│  ├─ dynamic-workflow.mjs
│  ├─ context-engine-v11.mjs
│  ├─ hierarchical-context.mjs
│  ├─ semantic-index.mjs
│  ├─ repo-graph.mjs
│  ├─ aci.mjs
│  ├─ evidence-store.mjs
│  ├─ evidence-receipt.mjs
│  ├─ gate-receipt.mjs
│  ├─ memory-engine.mjs
│  ├─ capability-fabric.mjs
│  ├─ model-policy.mjs
│  ├─ model-performance.mjs
│  ├─ worktree-sandbox.mjs
│  ├─ container-sandbox.mjs
│  ├─ performance-fabric.mjs
│  ├─ trajectory.mjs
│  ├─ learning-engine.mjs
│  ├─ benchmark-confidence.mjs
│  ├─ browser-adapter.mjs
│  ├─ browser-runtime.mjs
│  ├─ browser-mcp-routing.mjs
│  └─ ...
│
├─ pi/
│  ├─ extensions/
│  │  └─ ues.ts
│  └─ prompts/
│     └─ 11 UES slash prompts
│
├─ global-config/
│  ├─ agents/
│  │  └─ 12 specialist agents
│  └─ skills/
│     └─ 48 domain/workflow skills
│
├─ evals/
│  ├─ live/
│  ├─ long/
│  ├─ polyglot/
│  ├─ repo-scale/
│  ├─ v11/
│  └─ v14/
│
├─ scripts/
│  └─ eval, validation, smoke, install helpers
│
├─ test/
│  └─ deterministic/runtime/regression tests
│
└─ docs/
   ├─ ENGINEERING-DESIGN.md
   ├─ DETERMINISTIC-TOOLS.md
   ├─ V11-PERCEPTION-ADAPTIVE-EXECUTION.md
   ├─ V12-WEAK-MODEL-INTELLIGENCE.md
   ├─ V13-PARALLEL-WEAK-MODEL-RUNTIME.md
   ├─ V14-CONTEXT-MEMORY-FABRIC.md
   └─ V14.1-QUALITY-PERFORMANCE-FABRIC.md

Một ví dụ đầy đủ

Task:

/ues-run sửa checkout inventory reservation, chạy test liên quan và xác minh UI checkout

Luồng có thể diễn ra:

flowchart TD
    T[User task] --> P[Task Policy STANDARD/DEEP]
    P --> C[Context selection]
    C --> R[Repo graph + semantic refs + likely tests]
    R --> E[Executor]
    E --> TEST[Targeted backend tests]
    TEST --> V[Verifier]

    V -->|PASS| I[Integration verifier]
    V -->|FAIL| D[Debugger]
    D --> E

    I --> B{Visual/browser required?}
    B -->|No| DONE[Verified completion]
    B -->|Yes| MCP[Playwright MCP lane]
    MCP --> VV[Visual verifier]
    VV -->|PASS| DONE
    VV -->|FAIL| D

Điểm khác với “một model tự làm tất cả” là:

context được bounded;
implementation và verification tách vai;
browser evidence chỉ nạp khi cần;
retry có diagnosis;
long task có state;
parallel writers có isolation;
completion bị ràng buộc bởi evidence.

Triết lý thiết kế

Deterministic facts trước probabilistic reasoning

Những việc có thể tính bằng code thì ưu tiên tính bằng code:

Git state;
dependency graph;
changed files;
plan cycle;
file overlap;
command exit status;
workspace fingerprint;
provider health;
token/cost telemetry.

Model tập trung vào phần cần semantic judgment.

Progressive disclosure

Không nạp:

toàn repo;
toàn bộ 48 skills;
mọi MCP tool;
mọi memory;
mọi log.

Chỉ nạp bounded evidence phù hợp.

Fresh specialists

Child specialist được tạo với prompt/tool boundary hẹp hơn để giảm contamination từ conversation dài.

Evidence-first completion

“Agent nói đã xong” không phải completion gate.

Reversible optimization

Tối ưu output/context phải giữ đường lấy raw evidence trở lại.

Benchmark-gated learning

Không promote rule/tool/provider chỉ vì cảm giác “có vẻ nhanh”.

Giới hạn có chủ đích

UES cố ý không:

tạo hàng trăm agents;
load mọi skill cho mọi task;
auto push;
auto publish;
auto deploy;
ghi hidden chain-of-thought;
coi keyword routing là semantic truth tuyệt đối;
coi import scan là full compiler/LSP semantic graph;
coi một benchmark là bằng chứng model-equivalence;
bỏ verifier chỉ để tăng tốc;
dùng browser tool cho backend task không cần browser.

Quick start

npm install -g @earendil-works/pi-coding-agent
pi install npm:opencode-agent-skill
pi

Trong Pi:

/ues-run kiểm tra project, tìm lỗi, sửa lỗi cần thiết và chạy test xác minh

Kiểm tra deterministic runtime:

ues task-policy "fix checkout bug" --json
ues capability-fabric status .
ues hierarchy "checkout inventory" .
ues memory status .

Tài liệu sâu hơn

docs/ENGINEERING-DESIGN.md — engineering architecture.
docs/DETERMINISTIC-TOOLS.md — deterministic CLI/evidence tools.
docs/V11-PERCEPTION-ADAPTIVE-EXECUTION.md — perception/adaptive execution.
docs/V12-WEAK-MODEL-INTELLIGENCE.md — weak-model intelligence.
docs/V13-PARALLEL-WEAK-MODEL-RUNTIME.md — parallel runtime.
docs/V14-CONTEXT-MEMORY-FABRIC.md — context, memory, capability fabric.
docs/V14.1-QUALITY-PERFORMANCE-FABRIC.md — quality-preserving performance.
docs/EVALS.md — evaluation.
docs/PI-COMPAT.md — Pi compatibility.
docs/NPM-PUBLISH.md — npm publishing.

License

MIT

Signals

Download trend

README

UES for Pi Agent

Mục lục

UES giải quyết vấn đề gì?

Kiến trúc tổng thể

Các lớp chính

1. Pi host layer

2. UES Pi extension

3. Deterministic engine

4. Specialist layer

5. Verification layer

Luồng /ues-run end-to-end

UES không làm gì ở luồng này?

Task Policy: FAST / STANDARD / DEEP

FAST

STANDARD

DEEP

High-risk signals

12 specialist agents

Quan hệ giữa các agent

48 skills

Nhóm orchestration và reasoning

Nhóm verification và testing

Nhóm backend / API / data

Nhóm framework / language

Nhóm UI/design

11 slash prompts

Context Engine L0/L1/L2

L0

L1

L2

Context pack có thể bao gồm

Semantic index, repo graph và ACI

Semantic Index

Repo Graph

ACI

Model routing và recovery

Tier

Recovery policy

Attempt 1

Attempt 2

Attempt 3

Task graph, Dynamic Workflow và parallel runtime

Dependency validation

Safe waves

Dynamic Workflow

Worktree sandbox

Safety của worktree

Evidence Store, receipts và verification gates

Evidence Store

Verification receipts

Gate model

V14.1 reversible output compaction

Quan trọng

V14.2 Turbo Weak-Model Runtime

Verified Persistent Memory

Capability Fabric

Built-in capability groups

Output compaction providers

Playwright / Browser MCP on-demand

Routing behavior

Backend task

Browser E2E task

Visual task

Evidence order

Browser security

Optional overrides

Trajectory và observability

Learning engine và benchmark confidence

Failure patterns được phân tích

Promotion confidence

Durable long-horizon work

State machine khái quát

Locking

Runtime events

Control Center

Safety model

Shell safety