@piagent/platform 1.0.0

package/docs/memory-policy.md

@@ -0,0 +1,164 @@
+# Memory policy cho Pi Agent Platform
+
+## Tóm tắt quyết định
+
+Áp dụng memory theo hướng **explicit-only, project-scoped, markdown-first**.
+
+Nghĩa là:
+
+- project có `.pi/memory/memory_summary.md` và `.pi/memory/MEMORY.md`;
+- agent chỉ ghi memory khi user yêu cầu rõ kiểu “remember this” hoặc workflow yêu cầu explicit;
+- memory là hint để giảm scout lại, không phải source of truth;
+- không bật background session extraction/consolidation mặc định trong public platform;
+- nếu team muốn native/third-party Pi memory package thì install riêng sau khi review source.
+
+## Vì sao không bật auto background memory ngay
+
+Bài “How Pi remembers” mô tả hệ thống đầy đủ gồm:
+
+- read path trước turn: nạp summary vào prompt;
+- write path nền: đọc session cũ, trích raw memory, consolidate thành notebook;
+- SQLite catalog để quản lý job/lease/usage;
+- git snapshot để đọc bản memory sạch;
+- `/memory` control panel.
+
+Đó là kiến trúc tốt, nhưng với repo public dùng cho nhiều team, bật mặc định có 3 rủi ro:
+
+1. **Token/cost khó đo:** background extraction có thể gọi model sau session.
+2. **Ghi nhớ sai:** transcript cũ có thể chứa kết luận chưa verify nếu extractor không đủ chặt.
+3. **Secret/privacy:** memory tự động phải có redaction + audit mạnh trước khi rollout.
+
+Do đó bản platform hiện tại lấy phần chắc chắn nhất:
+
+- memory file markdown dễ đọc/sửa, nhưng mặc định là private local state;
+- write explicit-only;
+- search/read bằng tool;
+- context index chỉ lưu pointer/citation ngắn để định tuyến context, không lưu transcript thô;
+- profile knobs để sau này bật external package hoặc assisted mode.
+
+## File layout
+
+Trong project được init:
+
+```text
+.pi/memory/
+├─ memory_summary.md   compact index, bắt đầu bằng v1, ignored by default
+├─ MEMORY.md           durable project memory handbook, ignored by default
+└─ local/              private local notes, ignored by git
+```
+
+Memory markdown mặc định không commit vì nội dung có thể đến từ model/user free-text. Nếu team muốn shared handbook, hãy review/redact thủ công rồi opt-in bằng cách bỏ rule ignore ở `.pi/.gitignore`.
+
+Runtime/experimental files không commit:
+
+```text
+.pi/memory/MEMORY.md
+.pi/memory/memory_summary.md
+.pi/memory/state.sqlite
+.pi/memory/raw_memories.md
+.pi/memory/rollout_summaries/
+.pi/memory/extensions/ad_hoc/
+.pi/memory/local/
+.pi/memory/.git/
+```
+
+## Profile config
+
+Mỗi `.pi/piagent-profile.json` có block:
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "mode": "manual",
+    "scope": "project",
+    "summaryFile": ".pi/memory/memory_summary.md",
+    "handbookFile": ".pi/memory/MEMORY.md",
+    "localDir": ".pi/memory/local",
+    "readBeforeTask": true,
+    "writePolicy": "explicit-only",
+    "maxInjectedChars": 4000,
+    "externalPackages": []
+  }
+}
+```
+
+Mode hiện tại:
+
+| Mode | Ý nghĩa |
+|---|---|
+| `off` | Không dùng project memory. |
+| `manual` | Mặc định. Tool đọc/search/write explicit-only. |
+| `assisted` | Dành cho tương lai: agent có thể đề xuất memory note nhưng vẫn cần user approve. |
+| `external-package` | Project/team dùng thêm package memory riêng như `pi-memory`. |
+
+## Tools trong platform
+
+| Tool | Mục đích |
+|---|---|
+| `piagent_memory_status` | Xem memory config/files/rules. |
+| `piagent_memory_note` | Ghi durable note khi user explicit ask. Có redaction cho token/key/connection-string phổ biến. |
+| `piagent_memory_search` | Keyword-search memory markdown. |
+| `piagent_memory_citation_record` | Ghi memory file đã ảnh hưởng task contract. |
+| `piagent_context_index_status` | Kiểm tra `.pi/context-index.json` có tồn tại/fresh/có citation không. |
+| `piagent_context_index_search` | Tìm node/edge/citation trong context index trước khi scout rộng. |
+| `piagent_context_index_record` | Ghi compact context graph sau onboarding hoặc approved handoff; không ghi transcript thô. |
+
+## Workflow khuyến nghị
+
+### First run
+
+```text
+/login
+/onboard-project
+/memory-policy
+```
+
+### Ghi nhớ explicit
+
+```text
+Remember: this repo uses pnpm, never npm.
+```
+
+Agent nên gọi `piagent_memory_note` với category `preference`.
+
+### Trước implementation
+
+1. `piagent_context`
+2. `piagent_context_index_status` hoặc `/context-index` để lấy điểm vào repo nếu đã onboard
+3. `piagent_memory_status`
+4. `piagent_memory_search` nếu task có keyword liên quan
+5. đọc repo files hiện tại để verify
+6. implement
+
+Memory và context index giúp giảm token scout lại, nhưng không thay thế việc đọc source hiện tại. Không paste secret vào memory hoặc context index; redaction là lớp phòng tai nạn, không phải bảo đảm dữ liệu nhạy cảm có thể được lưu an toàn.
+
+## Khi muốn dùng package memory ngoài
+
+Pi package chạy code và ảnh hưởng hành vi agent, nên phải review source trước khi install.
+
+Candidate phổ biến:
+
+```bash
+pi install npm:pi-memory@0.4.0
+```
+
+Package này lưu markdown ở local memory dir, có tools `memory_write`, `memory_read`, `scratchpad`, `memory_status`; search nâng cao cần qmd.
+
+Nếu dùng external package, set profile:
+
+```json
+{
+  "memory": {
+    "mode": "external-package",
+    "externalPackages": ["npm:pi-memory@0.4.0"]
+  }
+}
+```
+
+## Tài liệu chính
+
+- Pi memory explainer: https://tuyenhx.com/docs/memory-explainer.html
+- Pi extensions docs: https://pi.dev/docs/latest/extensions
+- Pi settings/project trust docs: https://pi.dev/docs/latest/settings
+- Pi package `pi-memory`: https://pi.dev/packages/pi-memory

package/docs/model-options.md

@@ -0,0 +1,165 @@
+# Model selector and scope
+
+Pi Agent Platform không khóa vào một provider. OpenAI Codex và Claude/Anthropic đều là first-class option.
+
+Quan trọng: flow chính là user chọn model bằng native Pi selector, không phải hỏi agent recommend.
+
+## Flow chuẩn sau OAuth
+
+Trong Pi:
+
+```text
+/login
+/model          # hoặc Ctrl+L
+/scoped-models  # optional, edit danh sách Ctrl+P cycle
+```
+
+Hotkeys:
+
+```text
+Ctrl+L          # mở model selector
+Ctrl+P          # cycle model trong enabledModels
+Shift+Ctrl+P    # cycle ngược
+Shift+Tab       # cycle thinking level
+```
+
+Global setup của repo sẽ seed `enabledModels` vào `~/.pi/agent/settings.json`, nên sau OAuth anh chọn/đổi model bằng option selector của Pi.
+
+## Kiểm tra model hiện có
+
+Trong Pi:
+
+```text
+/login
+/model
+/settings
+/scoped-models
+```
+
+Từ terminal:
+
+```bash
+pi --list-models
+pi --list-models openai-codex
+pi --list-models claude
+pi --list-models anthropic
+piagent-models
+piagent-models --provider openai-codex
+piagent-models --provider anthropic
+```
+
+Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, Claude có thể chưa hiện dù model catalog local có metadata.
+
+## Thinking levels
+
+Pi hỗ trợ:
+
+```text
+off, minimal, low, medium, high, xhigh, max
+```
+
+Không phải model nào cũng hỗ trợ mọi level. Pi sẽ clamp theo capability của model. Cách chọn:
+
+```bash
+pi --model openai-codex/gpt-5.5:high
+pi --model anthropic/claude-sonnet-5:xhigh
+pi --thinking medium
+```
+
+## Current latest-family catalog
+
+Đừng giới hạn vào vài ví dụ. Sau `pi update --models`, kiểm tra catalog local bằng `piagent-models`. Ở release hiện tại, các family/presets chính cần nhớ:
+
+### OpenAI Codex
+
+| Model | Role gợi ý | Khi dùng |
+|---|---|---|
+| `openai-codex/gpt-5.3-codex-spark` | fast scout | hỏi nhanh, thao tác nhỏ, chi phí thấp |
+| `openai-codex/gpt-5.4-mini` | fast/cheap | scout nhẹ, docs, simple fix |
+| `openai-codex/gpt-5.4` | balanced | task bình thường |
+| `openai-codex/gpt-5.5` | balanced/hard default | default mạnh cho implement |
+| `openai-codex/gpt-5.6-luna` | focused hard | debug/review/test khó, cần reasoning sâu nhưng scope hẹp |
+| `openai-codex/gpt-5.6-sol` | strategic/deep | architecture, large refactor, planning lớn |
+| `openai-codex/gpt-5.6-terra` | huge-context scout | đọc nhiều docs/source, tổng hợp repo lớn |
+
+### Claude / Anthropic
+
+| Model | Role gợi ý | Khi dùng |
+|---|---|---|
+| `anthropic/claude-haiku-4-5` | fast/cheap | hỏi nhanh, docs/scout nhẹ |
+| `anthropic/claude-sonnet-4-5` | balanced | task source bình thường |
+| `anthropic/claude-sonnet-4-6` | balanced/deep | source task lớn hơn, max-capable |
+| `anthropic/claude-sonnet-5` | balanced/hard default | Claude default mạnh cho implement |
+| `anthropic/claude-opus-4-5` | deep | review/refactor lớn |
+| `anthropic/claude-opus-4-6` | deep/max | architecture/reasoning nặng |
+| `anthropic/claude-opus-4-7` | deep/xhigh/max | high-risk/debug/architecture |
+| `anthropic/claude-opus-4-8` | deep/xhigh/max | deep default nếu có quyền dùng |
+| `anthropic/claude-fable-5` | huge-context/deep | repo/docs rất lớn, synthesis dài |
+
+Pi catalog có thể có thêm dated variants như `*-2025xxxx`. Dùng alias latest-family ở trên cho team flow, dùng dated version khi cần reproducibility.
+
+## Recommended presets
+
+Preset dưới đây là cách mình seed `enabledModels`, không phải giới hạn hard. User vẫn có thể mở `/model` để chọn bất kỳ model available nào trong provider catalog.
+
+| Preset | OpenAI Codex example | Claude/Anthropic example | Khi dùng |
+|---|---|---|---|
+| Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | đọc nhanh, hỏi đáp, grep/scout nhẹ |
+| Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | task source bình thường |
+| Hard implement | `openai-codex/gpt-5.6-luna:xhigh` hoặc `openai-codex/gpt-5.5:xhigh` | `anthropic/claude-sonnet-5:xhigh` | task nhiều file, contract mapping, debug khó |
+| Strategic/deep | `openai-codex/gpt-5.6-sol:xhigh` | `anthropic/claude-opus-4-7:max` hoặc `anthropic/claude-opus-4-8:max` | architecture, large refactor, high-risk review |
+| Huge-context scout | `openai-codex/gpt-5.6-terra:xhigh` | `anthropic/claude-fable-5:max` | đọc nhiều docs/context, tổng hợp repo lớn |
+
+Tên model có thể đổi theo Pi model catalog. Khi không chắc, ưu tiên `/model` hoặc `pi --list-models`.
+
+## Practical routing
+
+Global setup mặc định:
+
+```bash
+piagent-model-scope --preset full --default-model openai-codex/gpt-5.5:xhigh
+```
+
+Scope này ghi vào settings:
+
+```bash
+~/.pi/agent/settings.json
+```
+
+Sau đó dùng selector:
+
+```text
+/model
+/scoped-models
+Ctrl+P
+Shift+Tab
+```
+
+Nếu muốn đặt default khác:
+
+```bash
+piagent-model-scope --preset full --default-model openai-codex/gpt-5.6-sol:xhigh
+piagent-model-scope --preset full --default-model anthropic/claude-sonnet-5:xhigh
+```
+
+## Benchmark rule
+
+Không claim “Pi + provider X tiết kiệm hơn provider Y” bằng cảm giác. Chạy cùng scenario rồi ghi bằng:
+
+```bash
+piagent-usage /path/to/project
+bash scripts/quality-benchmark.sh /path/to/project --record \
+  --scenario bounded-source-fix \
+  --surface pi \
+  --result pass \
+  --tokens <total> \
+  --cost <cost> \
+  --verify "<verify-command>" \
+  --notes "provider/model/thinking=<provider/model:thinking>"
+```
+
+So sánh tối thiểu:
+
+- Pi + Codex fast/balanced/deep;
+- Pi + Claude fast/balanced/deep;
+- any other approved setup nếu team muốn so sánh bằng số liệu.

package/docs/oauth-providers.md

@@ -0,0 +1,53 @@
+# OAuth providers trong Pi
+
+## Mục tiêu
+
+Dùng provider/model được Pi hỗ trợ mà không đưa token hoặc local auth file vào repository.
+
+## Setup
+
+```bash
+pi
+/login
+```
+
+Chọn provider theo danh sách Pi hiển thị. Sau đó kiểm tra:
+
+```text
+/model
+/model-options
+```
+
+Hoặc:
+
+```bash
+pi --list-models
+```
+
+## Credential boundary
+
+Không đưa những file này vào source:
+
+- `~/.pi/agent/auth.json`
+- custom agent dir `auth.json`
+- `.env`
+- API keys
+- session dumps có token
+
+## Team usage
+
+Mỗi dev login OAuth bằng account được công ty cho phép. Repo platform chỉ chứa:
+
+- hướng dẫn login
+- package source
+- profile/policy
+- template config không có secret
+
+## CI/automation
+
+Không dùng OAuth local cho CI. Nếu sau này cần headless automation, dùng secret manager riêng và policy riêng.
+
+## Tài liệu chính
+
+- Pi providers/OAuth: https://pi.dev/docs/latest/providers
+- Pi settings/trust: https://pi.dev/docs/latest/settings