Docs/pi agent integration

[chaojixinren]

Summary

Adds an end-to-end Pi Agent integration for #698: a bilingual guide plus a
runnable example project, following the layout and quality bar of the existing
integration examples.

What Changed

• Runnable example at examples/pi-agent-integration/:
  • Dockerfile — Node.js 24 + @earendil-works/pi-coding-agent on top of
    ghcr.io/tencentcloud/cubesandbox-base:2026.16; envd already listens on :49983.
  • run_pi_agent.py — headless one-shot run (pi --version preflight → seed
    project → pi --print --mode json → stream stdout, key injected per-command via envs=).
  • resume_pi_agent.py — pause/resume across two turns; verifies /workspace
    and Pi's state dir (/root/.pi/agent) survive the snapshot. Manual
    try/finally lifecycle (no context manager) so the pause is not undone.
  • network_policy.py — default-deny egress + CubeEgress inject so the
    provider key rides the wire and never enters the VM.
  • env_utils.py, bilingual README.md / README_zh.md, .env.example,
    .gitignore, requirements.txt.
• Integration guide in both languages, on the _template.md frontmatter,
  linked from both index tables:
  • docs/guide/integrations/pi-agent.md
  • docs/zh/guide/integrations/pi-agent.md

Acceptance Criteria (#698)

1. End-to-end guide — template build, deps, API key injection, network/egress
   policy, snapshot-based session persistence. ✅
2. Runnable example under examples/ with template definition + reproducible
   flow + bilingual README. ✅
3. Use cases & best practices (isolated dev, run agent-generated code, snapshot
   checkpoint/resume). ✅
4. FAQ / troubleshooting aligned with existing egress / auth / template mechanics. ✅
5. Docs placed under docs/guide/integrations following the existing template. ✅

Test Plan

• python3 -m py_compile examples/pi-agent-integration/*.py
• env_utils helper checks (LLM host resolution, credential inject shape, vault env excludes secrets)
• run/resume/network_policy --help parse cleanly
• cd docs && npm run docs:build
• git diff --check clean
• docker build --platform linux/amd64 succeeds (~76s; image 551 MB)
• envd /health returns 204 (probe passes); envd 0.5.13; pi 0.80.3; node 24.18; git/python3/rg/jq present

Live CubeSandbox cluster run

Ran against a live single-node CubeSandbox cluster (a registered pi-agent-cube
template, pi 0.80.3). The LLM provider was an Anthropic-compatible gateway
registered as a custom Pi provider (model glm-5.2), because no native
Anthropic key was available in the test environment.

• run_pi_agent.py — sandbox created, pi --version preflight, seeded
  project, one-shot task drove bash/write tool calls and wrote
  /workspace/result.md; exit 0. The runner's parsed transcript (assistant
  text + tool calls) renders cleanly; --raw still dumps the JSONL stream.
• resume_pi_agent.py — turn 1 wrote /workspace/plan.md; sandbox.pause()
  then Sandbox.connect() resumed; /workspace/plan.md and Pi's state dir
  (/root/.pi/agent) survived the snapshot; turn 2 read the plan and continued
  (wrote current_time.py + progress.md, plan.md left intact); exit 0.
• network_policy.py — default-deny egress verified on-cluster: a non-LLM
  host (example.com) is blocked, and printenv inside the sandbox shows the
  provider key unset/placeholder (the real key never enters the VM).
• network_policy.py full LLM call via CubeEgress inject — verified end-to-end
  on-cluster. A bare request (no auth header) is authenticated by the injected
  key and the LLM returns HTTP 200, while the VM only ever holds a placeholder.
  Pi (Node) additionally needs NODE_EXTRA_CA_CERTS to trust the CubeEgress
  interception CA (now set by the script).

Closes #698

[cubesandboxbot]

Pi Agent Integration — Code Review Summary

Overall, this is a well-structured, thoroughly tested PR. The code is clean, the security model is thoughtfully documented, the docs are accurate and bilingual, and the example scripts are practical. Below are the findings worth flagging before merge.

Security (1 issue, moderate)

Self-modifying-instruction risk in resume_pi_agent.py
pi_command() defaults to approve=True, trusting CLAUDE.md/AGENTS.md in the workspace. Turn 1's Pi agent can write a malicious CLAUDE.md to /workspace, which Turn 2 then blindly trusts via --approve after the pause/resume. The resume script has no files that need trusting pre-turn-2, so passing approve=False closes this gap. (Inline comment on line 199)

Code quality / maintainability (1 issue)

Fragile exception-message matching in _pi_common.py
The TypeError retry guard checks "envs" not in str(exc) — exception messages are implementation-defined and not part of Python's spec. This may silently mask bugs across Python versions or SDK changes. (Inline comment on line 133)

Dockerfile (1 issue)

Redundant packages — bash, ca-certificates, and curl are already present in the base image. Removing them trims a few seconds from every build. (Inline comment on line 29)

Documentation (1 issue)

Missing ANTHROPIC_BASE_URL in README env table — The env table in examples/pi-agent-integration/README.md omits ANTHROPIC_BASE_URL, which both the integration guide and .env.example document as a key variable for custom endpoints. (Inline comment on line 84)

Performance (minor)

Extra sandbox round-trip for pi --version — Both run_pi_agent.py and resume_pi_agent.py issue a separate sandbox.commands.run() call purely for a version check, adding ~200-500ms of gRPC overhead. This can be inlined into the main command chain. (Inline comments on line 161 of both scripts)

Positive highlights

• Clear, explicit security commentary in every script that handles credentials, directing users to the vault pattern for production.
• Duck-typed SDK abstraction (_pi_common.py) works with both e2b and cubesandbox SDKs — well designed.
• Excellent Docker layer separation (Pi version bumps don't invalidate the OS layer).
• Bilingual docs are consistent and cross-linked correctly; all code snippets match the implementation.
• --ignore-scripts on npm install and allow_internet_access=False in the vault pattern show solid security hygiene.

[kinwin-ustc]

Thanks for your contribution