Composition
piagent-guard.ts chỉ giữ wiring, registration order và shared runtime state. File này không được tiếp tục chứa feature algorithm.
Kiến trúc repo
Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được.
Chiều dependency được enforce bằng code.
architecture/layers.json là rule máy đọc; npm run architecture:check chặn dependency ngược và file vượt budget.
Runtime adapters
packages/piagent-core/runtime quản lý Pi hook, command, tool, session UI, usage, log compaction và workflow input routing.
Core services
Policy, task, context và state trả về structured decision. Core service không import runtime adapter hay Pi composition root.
Integrations
mcp/, capabilities/ và security/ có ownership riêng; không nhúng task workflow vào integration.
Entrypoints
scripts/ parse CLI argument rồi gọi use case. Metric, policy và state transition không được duplicate trong CLI.
Product assets
prompts/, skills/, subagents/, adapters/, packs/ và schemas/ là declarative assets.
Adaptive runtime
Piagent tách runtime decision khỏi Pi wiring
Harness giữ nguyên model người dùng chọn, nhưng mỗi task có context plan nhỏ hơn, có citation, có task journal bền vững và recovery decision rõ ràng.
Context planner
runtime/context/adaptive-planner.ts chọn budget, retrieval lane, code inclusion và plan receipt theo phase, context pressure, model capability và thinking level.
Task journal
extensions/task-journal.js ghi checkpoint cho start, progress, mutation, verifier và completion. Resume tin task contract trước; retention compaction giữ hash anchor.
Repository memory
extensions/repository-memory.js chỉ lưu fact có citation và expiry; từ chối raw prompt/output, OAuth material, API key và secret. Hint chỉ dùng token budget còn dư.
Model capability
runtime/model/capabilities.ts đọc model family, context window và thinking level làm tín hiệu budget, không đổi provider và không cần API key.
Verification intelligence
extensions/verification-intelligence.js phân loại lỗi và chọn verify group theo task scope; scope chạm cả frontend/backend dùng full source verifier.
Execution backend
extensions/execution-backend.js giữ Pi OAuth local làm owner; mutation bị block nếu experimental adapter được yêu cầu nhưng chưa có.
Ownership
Một state chỉ có một source of truth
Project profile và lock có thể commit. Task evidence, telemetry, trace, capture và session history là local state. Derived index phải có policy digest và rebuild được.
| State | Owner | Vị trí | Commit |
|---|---|---|---|
| Project profile + lock | Project | .pi/piagent-profile*.json | Có |
| Task, trace, telemetry, capture | Runtime | .pi/piagent-state/ | Không |
| Task journal + checkpoint | Runtime | .pi/piagent-state/task-journal/ | Không |
| Repository memory fact | Runtime | .pi/piagent-state/repository-memory/ | Không |
| Session history | Pi | Pi session store | Không |
| Shared instructions | Project | AGENTS.md, project docs | Có |