[Qiao-yq]

Please provide a description of this PR:

Draft. This PR is blocked by and must be merged after #1609 and its prerequisites #1596 and #1608. Merge order: #1596 → #1608 → #1609 → this PR. Complete the Phase 1 prerequisites and G1 acceptance before merging this production integration.

Implement Phase 2 foundations / Core MVP PR 1: unified context contracts, versioned templates, complete-request budgets, and canonical tool interactions for #1539. This follows the Phase 1 security, Session lifecycle, authentication, and usage/audit foundations; it provides the compilation path needed by later conversation-summary and cross-session-memory work.

Previously, ReAct assembled prompts separately and stored tool results without a complete recoverable request/result association. This PR compiles each Act and Answer request through one bounded path, and retains canonical tool records that can be restored after failed or cancelled attempts.

• add server-registered Source/Item/Decision contracts with identity, provenance, role, and content-kind checks; keep recent-history continuity local to each Source so oversized extension evidence does not discard fitting history
• support constrained template placeholders, immutable version references, atomic Session template pinning, and archived versions; resolve variables against the selected version while preserving its required/length checks
• budget system/phase policies, messages, tool schemas, output reserve, and safety margin together; adapt the compiled request to the SDK without separate hidden prompt bindings
• separate raw collection limits (max_collect_bytes) from rendered request limits (max_context_bytes); sanitize and bound tool-result views before final selection, keeping call IDs, arguments, statuses, and native request/result pairing intact
• persist pending tool batches before execution, then update results through version CAS and active-Turn fencing; implement Memory/GORM quotas, cleanup, and bounded recovery independently of deleted failed Turns
• restore successful results and pending/interrupted uncertainty in subsequent requests, including same-key retries and GORM restarts; retain a mandatory uncertainty notice when recovery details are omitted, without automatically replaying tools
• report estimated input usage separately from provider-reported usage, expose explicit context/template errors, bound the existing history tool, and retain the Compiler-backed tool-free minimal rollback mode

Compatibility: production Agent construction now requires NewReActAgentWithStore and a CompilationStore; the old constructor without storage returns an explicit migration error. GORM migration adds the tool ledger, Session template reference, and context-estimate metadata. Legacy tool results remain labeled evidence; missing requests or call IDs are not invented. Stored canonical records are not rewritten by model-input sanitization or result trimming.

This is the first Core MVP PR, not completion of the entire Phase 2 scope or #1539. Summary persistence, cross-session Memory, frontend controls, and a dynamic plugin platform are deferred. The three local planning documents are not included in these commits.

While the dependencies are open, GitHub's comparison against ai includes their changes. Review this PR's six functional commits on top of the Phase 1 baseline here.

Validation from ai/ (test cache disabled):

• go test -count=1 ./...
• go test -race -count=1 ./component/context ./component/agent/react ./component/agent/react/test ./store/...
• git diff --check 8459ec4..HEAD

Regression tests inspect actual OpenAI-compatible HTTP Provider requests for multi-tool pairing, partial success followed by cancellation, retries and restarts, archived-template variable changes, and approximately 100 KB tool results fitting a 16 KB request budget after trimming. They also check retained canonical payloads, uncertainty, sanitization, Source isolation, and explicit mandatory-budget failures.

Provider tests use a local HTTP fixture and GORM tests use SQLite. Real-model behavior and production MySQL/PostgreSQL acceptance remain unverified; these checks do not establish the Phase 1 G1 gate.

Part of #1539. Blocked by #1596, #1608, and #1609.

To help us figure out who should review this PR, please put an X in all the areas that this PR affects.

• Docs
• Installation
• User Experience
• Dubboctl
• Console
• Core Component

Please check any characteristics that apply to this pull request.

• Includes tests
• Changes security-sensitive behavior
• Adds database tables and migration
• Changes Agent construction compatibility

[Qiao-yq]

Updated head to 5e5cc5c addressing the review feedback.

Dependency sync — merged the latest #1609 (8266dfd, 10 commits) in 35116df. The only conflict was ai/store/gorm/store_test.go; both the compilation-contract test and the new retry/replay tests were kept. go test ./... passes locally in ai/.

Session owner vs. acting subject (P2, larry-zy) — fixed in 923916a:

• CollectRequest now carries the canonical SessionTenantID / SessionOwnerID from the trusted Session/Turn snapshot.
• Item and tool-batch provenance are validated against that owner, and the caller is checked with AccessContext.CanAccessOwner — same-tenant ai:sessions:admin is allowed, cross-tenant stays denied.
• Canonical tool batches are recorded with the Session owner instead of the acting subject (react/tool_records.go).
• Regressions added in c79e671 and 923916a: administrator context compilation, ledger/snapshot/recovery access, canonical tool execution through the full ReAct path, and administrator-owned/mismatched batch rejection. Ordinary-owner and unauthorized-caller paths are covered alongside.

JSON fail-open (P2, AlexStocks) — JSON() is now fail-closed (panics on marshal error) in 923916a, with TestJSONFailsClosedOnMarshalError.

P3 follow-ups — in 923916a / 5e5cc5c:

• invalid budget configuration (output reserve plus safety margin exceeding the context window) now returns ErrInvalidBudget instead of ErrMandatoryBudget;
• tool call inputs are bounded with the same limitValue limits as outputs;
• limitValue returns the original container when nothing was truncated;
• CompilationReport.InputTokens is documented as a UTF-8 JSON byte upper bound, not provider-reported usage.

Re-review welcome.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud