Merge pull request opensandbox-group#839 from alibaba/codex/update-agent-guidance

Docs: Update agent guidance docs

Author: ninan-nn

AGENTS.md

@@ -4,20 +4,37 @@ Use this file as the root router for the monorepo. Prefer the nearest `AGENTS.md
 
 ## Repository Map
 
-- `server/`: lifecycle control plane and server tests
+- `server/`: FastAPI lifecycle control plane, Docker/Kubernetes runtime integration, snapshot metadata, and server tests
 - `components/execd/`: in-sandbox execution daemon
-- `sdks/`: language SDKs and generated clients
-- `specs/`: public API contracts
-- `components/`, `cli/`, `docs/`, `kubernetes/`, `sandboxes/`: runtime, tooling, and deployment surfaces
+- `components/egress/`: per-sandbox network egress policy sidecar
+- `components/ingress/`: ingress gateway and endpoint routing
+- `components/internal/`: shared Go helpers used by runtime components
+- `sdks/`: sandbox, code-interpreter, and MCP SDKs plus generated clients
+- `specs/`: public OpenAPI contracts and examples
+- `kubernetes/`: Kubernetes operator, CRDs, task-executor, Helm charts, and Kind e2e tests
+- `cli/`: `osb` command-line client and bundled CLI skills
+- `tests/`: cross-language end-to-end SDK tests
+- `docs/`, `examples/`, `sandboxes/`, `oseps/`: documentation, samples, images/environments, and proposals
 
 ## Routing
 
 - For `server/**`, or lifecycle server behavior, sandbox creation flow, or user-visible server config, read `server/AGENTS.md`.
 - For `sdks/**`, or SDK generation, handwritten adapters, or cross-language SDK alignment, read `sdks/AGENTS.md`.
 - For `specs/**`, or API contract, schema, or example changes, read `specs/AGENTS.md`.
+- For `kubernetes/**`, or CRDs, controller behavior, task execution, Helm/Kustomize deployment, pool scheduling, pause/resume snapshots, or Kind e2e tests, read `kubernetes/AGENTS.md`.
 - For cross-cutting changes spanning spec, server, and SDKs, start with `specs/AGENTS.md` and then read affected consumer guides.
+- For runtime component changes under `components/**`, read the nearest `README.md` or `DEVELOPMENT.md`; keep component APIs aligned with `specs/` and SDK consumers.
+- For CLI changes under `cli/**`, read `cli/README.md` and verify command help/output behavior alongside unit tests.
+- For cross-language e2e tests under `tests/**`, read the language-local README and keep test assumptions aligned with current server and SDK behavior.
 - For areas without a local `AGENTS.md`, use the nearest `README.md`, `DEVELOPMENT.md`, and CI workflow as the next source of truth.
 
+## Working Principles
+
+- Think before coding: state assumptions, surface ambiguity, and ask or push back when the request has conflicting interpretations.
+- Simplicity first: implement the smallest solution that satisfies the request; avoid speculative features, one-off abstractions, and unnecessary configurability.
+- Surgical changes: touch only files and lines needed for the task, match local style, and do not refactor or delete unrelated pre-existing code.
+- Goal-driven execution: translate non-trivial work into verifiable success criteria, add or update focused tests when behavior changes, and loop until checks pass or blockers are clear.
+
 ## Guardrails
 
 Always:
@@ -26,6 +43,7 @@ Always:
 - Treat `specs/*` as public contract sources.
 - Keep spec, implementation, SDKs, docs, examples, config, and CLI behavior aligned when user-visible behavior changes.
 - When changing `specs/*`, also update or verify affected server, SDK, docs, and release outputs when practical.
+- When changing CRDs or Kubernetes public behavior, update or verify generated manifests, Helm/Kustomize deployment output, server Kubernetes integration, and docs when practical.
 - Prefer additive, backward-compatible changes for public interfaces.
 - Regenerate derived outputs when the source-of-truth file changes.
 - Update tests when behavior changes or bugs are fixed.
@@ -35,6 +53,7 @@ Always:
 Ask first:
 
 - Breaking public API, SDK, config, protocol, or CLI changes
+- Breaking CRD, annotation, label, Helm values, or Kubernetes deployment changes
 - Intentional drift between a public contract and its implementation
 - User-visible config or behavior changes without a clear migration story
 

CLAUDE.md

@@ -0,0 +1,63 @@
+# OpenSandbox Claude Guide
+
+Use this file as the Claude Code entry point for the OpenSandbox monorepo. Treat `AGENTS.md` as the canonical router and prefer the nearest local `AGENTS.md` for task-specific rules.
+
+## Read First
+
+- Root rules: `AGENTS.md`
+- Server changes: `server/AGENTS.md`
+- SDK changes: `sdks/AGENTS.md`
+- Spec changes: `specs/AGENTS.md`
+- Kubernetes changes: `kubernetes/AGENTS.md`
+- Areas without a local `AGENTS.md`: read the nearest `README.md`, `DEVELOPMENT.md`, and relevant CI workflow.
+
+## Repository Map
+
+- `server/`: FastAPI lifecycle control plane, Docker/Kubernetes runtime integration, snapshot metadata, and server tests
+- `components/execd/`: in-sandbox execution daemon
+- `components/egress/`: per-sandbox network egress policy sidecar
+- `components/ingress/`: ingress gateway and endpoint routing
+- `sdks/`: sandbox, code-interpreter, and MCP SDKs plus generated clients
+- `specs/`: public OpenAPI contracts and examples
+- `kubernetes/`: Kubernetes operator, CRDs, task-executor, Helm charts, and Kind e2e tests
+- `cli/`: `osb` command-line client and bundled CLI skills
+- `tests/`: cross-language end-to-end SDK tests
+- `docs/`, `examples/`, `sandboxes/`, `oseps/`: documentation, samples, images/environments, and proposals
+
+## Working Principles
+
+- Think before coding: state assumptions, surface ambiguity, and ask or push back when the request has conflicting interpretations.
+- Simplicity first: implement the smallest solution that satisfies the request; avoid speculative features, one-off abstractions, and unnecessary configurability.
+- Surgical changes: touch only files and lines needed for the task, match local style, and do not refactor or delete unrelated pre-existing code.
+- Goal-driven execution: translate non-trivial work into verifiable success criteria, add or update focused tests when behavior changes, and loop until checks pass or blockers are clear.
+
+## Guardrails
+
+Always:
+
+- Keep changes focused on the user request.
+- Keep spec, implementation, SDKs, docs, examples, config, CLI, and Kubernetes behavior aligned when user-visible behavior changes.
+- Prefer additive, backward-compatible changes for public interfaces.
+- Regenerate derived outputs when source-of-truth files change.
+- Update tests when behavior changes or bugs are fixed.
+- Prefer focused package/file checks before full-suite validation.
+- Mention unrun or blocked verification in the final handoff.
+
+Ask first:
+
+- Breaking public API, SDK, config, protocol, CLI, CRD, annotation, label, Helm value, or deployment changes
+- Intentional drift between a public contract and its implementation
+- User-visible config or behavior changes without a clear migration story
+
+Never:
+
+- Edit generated output as the only fix.
+- Mix unrelated component work into the same change.
+- Refactor adjacent code just because it is nearby.
+
+## Review Focus
+
+- Prioritize breaking changes in specs, SDK interfaces, config, CLI behavior, CRDs, annotations, labels, and protocols.
+- Flag protocol changes that are unnecessary, inconsistent, or hard to implement.
+- Flag source-of-truth boundary violations and missing downstream updates.
+- Call out missing tests and compatibility risks explicitly.

kubernetes/AGENTS.md

@@ -1,22 +1,25 @@
 # Kubernetes AGENTS
 
-You are working on the OpenSandbox Kubernetes operator and task-executor. Treat CRD types and annotation contracts as public interfaces, and prefer additive, backward-compatible changes.
+You are working on the OpenSandbox Kubernetes operator, snapshot controller flow, and task-executor. Treat CRD types and annotation/label contracts as public interfaces, and prefer additive, backward-compatible changes.
 
 For detailed development setup, architecture deep-dive, coding standards, testing guide, and deployment workflows, see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
 ## Scope
 
-- `apis/`: CRD type definitions (BatchSandbox, Pool)
+- `apis/`: CRD type definitions (BatchSandbox, Pool, SandboxSnapshot)
 - `cmd/controller/`: controller manager entry point
 - `cmd/task-executor/`: task-executor entry point
 - `internal/controller/`: BatchSandbox and Pool reconcilers, allocator, eviction, update, and strategy logic
+- `internal/controller/*pause*`, `internal/controller/*snapshot*`: pause/resume and rootfs snapshot reconciliation
 - `internal/scheduler/`: in-process task scheduler (assigns tasks to sandbox pods)
 - `internal/task-executor/`: task execution runtime (process/container), manager, and HTTP server
 - `internal/utils/`: shared helpers (pod, finalizer, field index, expectations, logging)
 - `pkg/client/`: generated clientset, informer, and lister
 - `pkg/task-executor/`: task-executor public types and config
+- `pkg/utils/`: public-ish helper contracts used by server-side Kubernetes integration
 - `config/`: Kustomize overlays, RBAC, CRD bases, samples
 - `charts/opensandbox-controller/`: Helm chart for deployment
+- `cmd/image-committer/` and `Dockerfile.image-committer`: image used by pause/resume rootfs commit jobs
 - `test/e2e/`: end-to-end tests (Kind-based)
 - `test/e2e_task/`: task-executor e2e tests
 - `test/e2e_runtime/`: runtime-class e2e tests (gVisor)
@@ -45,14 +48,17 @@ The controller communicates allocation state through annotations on BatchSandbox
 
 - `sandbox.opensandbox.io/alloc-status`: JSON `{"pods":["pod-1","pod-2"]}` — current pod allocation
 - `sandbox.opensandbox.io/alloc-release`: JSON `{"pods":["pod-3"]}` — pods released back to pool
+- `sandbox.opensandbox.io/endpoints`: JSON endpoint list consumed by server-side endpoint resolution
 
-Do not change annotation keys or JSON shapes without updating both the writer (`allocator.go`, `apis.go`) and all readers (`batchsandbox_controller.go`, `allocation_store_test.go`).
+Do not change annotation keys or JSON shapes without updating both writers and all readers, including controller tests and any server-side Kubernetes integration that parses them.
 
 ## Label Contracts
 
 - `sandbox.opensandbox.io/pool-name`: labels pool-owned pods
 - `sandbox.opensandbox.io/pool-revision`: revision hash for rolling updates
 - `batch-sandbox.sandbox.opensandbox.io/pod-index`: pod index within a BatchSandbox
+- `pool.opensandbox.io/evict`: marks idle pool pods for eviction
+- `pool.opensandbox.io/eviction-handler`: selects pool eviction handler implementation
 
 ## Commands
 
@@ -129,12 +135,21 @@ cd kubernetes
 make manifests generate
 ```
 
+Pause/resume focused checks:
+
+```bash
+cd kubernetes
+go test ./internal/controller/ -run 'Test(DispatchPauseResume|HandlePause|HandleResume|ContinueResume|CompletePause|SyncPauseOrClear|SandboxSnapshot)' -v
+make test-e2e-pause-resume
+```
+
 ## Architecture Overview
 
-Two controllers run inside the controller manager:
+Core reconciliation flows:
 
-1. **BatchSandboxReconciler**: Owns Pod objects. Handles pod scaling (non-pooled mode), pool allocation parsing, task scheduling, status updates, and expiry cleanup.
+1. **BatchSandboxReconciler**: Owns Pod objects. Handles pod scaling (non-pooled mode), pool allocation parsing, task scheduling, status updates, expiry cleanup, and pause/resume handoff.
 2. **PoolReconciler**: Owns Pod objects and watches BatchSandbox objects. Handles pod allocation to sandboxes, pool scaling (buffer/pool min/max), rolling updates, eviction, and status.
+3. **SandboxSnapshot flow**: Internal CR and commit Job orchestration used by pause/resume to persist and restore root filesystems.
 
 Allocation flow: PoolReconciler.Schedule → Allocator.Schedule → allocate/deallocate → PersistPoolAllocation → SyncSandboxAllocation (writes annotation to BatchSandbox).
 
@@ -146,6 +161,7 @@ Always:
 
 - Run `make manifests generate` after changing `apis/` types.
 - Run `make test` after controller or allocator changes.
+- Update CRD YAML, Helm values/templates, Kustomize manifests, and docs together when controller flags or CRD behavior changes.
 - Add focused regression tests for bug fixes in controller or allocator logic.
 - Keep reconciler logic idempotent — controllers may reconcile the same object concurrently.
 - Preserve annotation backward compatibility; add new fields rather than renaming existing ones.
@@ -156,6 +172,7 @@ Ask first:
 - Changing CRD spec fields (additive changes are fine; removal or renaming is breaking)
 - Changing annotation keys or JSON shapes
 - Changing pool allocation or scheduling semantics
+- Changing pause/resume snapshot semantics, controller snapshot flags, or image-committer trust assumptions
 - Large reorganizations across `controller/`, `scheduler/`, and `task-executor/`
 
 Never:

sdks/AGENTS.md

@@ -7,14 +7,15 @@ You are working on OpenSandbox SDKs. Keep generated and handwritten code separat
 - `sandbox/**`
 - `code-interpreter/**`
 - `mcp/**`
+- workspace-level SDK build and release metadata
 
 If the task is driven by spec changes, also read `../specs/AGENTS.md`.
 
 ## Key Areas
 
-- `sandbox/python`, `sandbox/javascript`, `sandbox/kotlin`, `sandbox/csharp`
+- `sandbox/python`, `sandbox/javascript`, `sandbox/kotlin`, `sandbox/csharp`, `sandbox/go`
 - `code-interpreter/python`, `code-interpreter/javascript`, `code-interpreter/kotlin`, `code-interpreter/csharp`
-- `mcp/`
+- `mcp/sandbox/python`
 - Workspace config in `package.json`, `pnpm-workspace.yaml`, and shared build files
 
 ## Generated Code
@@ -26,6 +27,7 @@ Generator-owned paths include:
 - `sandbox/python/src/opensandbox/api/**`
 - `sandbox/javascript/src/api/*.ts`
 - `sandbox/kotlin/sandbox-api/build/generated/**`
+- language-specific OpenAPI outputs produced by local generator scripts or Gradle tasks
 
 Handwritten logic belongs in adapters, services, facades, converters, and stable SDK models.
 
@@ -60,6 +62,17 @@ uv run pytest tests/ -v
 uv build
 ```
 
+Python code-interpreter SDK:
+
+```bash
+cd sdks/code-interpreter/python
+uv sync
+uv run ruff check
+uv run pyright
+uv run pytest
+uv build
+```
+
 JavaScript sandbox SDK:
 
 ```bash
@@ -71,6 +84,16 @@ pnpm run build
 pnpm run test
 ```
 
+JavaScript code-interpreter SDK:
+
+```bash
+cd sdks/code-interpreter/javascript
+pnpm run lint
+pnpm run typecheck
+pnpm run build
+pnpm run test
+```
+
 Kotlin sandbox SDK:
 
 ```bash
@@ -79,11 +102,19 @@ cd sdks/sandbox/kotlin
 ./gradlew spotlessApply :sandbox:test
 ```
 
+Go sandbox SDK:
+
+```bash
+cd sdks/sandbox/go
+go test ./...
+```
+
 ## Guardrails
 
 Always:
 
 - For spec-driven changes, regenerate affected SDK code, update handwritten layers, then run affected language checks.
+- For MCP changes, keep tool schemas, client setup docs, and sandbox SDK dependency behavior aligned.
 - Add a regression test for every bug fix.
 - Prefer tests for request mapping, response conversion, error mapping, streaming behavior, and resource cleanup.
 - Keep package-local validation fast before widening to multi-language verification.

server/AGENTS.md

@@ -1,20 +1,29 @@
 # Server AGENTS
 
-You are working on the OpenSandbox lifecycle server. Keep the route layer thin and put behavior in services, validators, or runtime helpers.
+You are working on the OpenSandbox lifecycle server. Keep the route layer thin and put behavior in services, validators, repositories, or runtime helpers.
 
 ## Scope
 
 - `opensandbox_server/**`
 - `tests/**`
+- `configuration.md`, `docker-compose.example.yaml`, and other server-facing docs/examples
 
 If the task changes lifecycle API contracts in `../specs/sandbox-lifecycle.yml`, also read `../specs/AGENTS.md`.
+If the task changes Kubernetes runtime behavior, also read `../kubernetes/AGENTS.md`.
 
 ## Key Paths
 
-- `opensandbox_server/main.py`: app entry point and startup wiring
+- `opensandbox_server/cli.py`: `opensandbox-server` CLI entry point and config initialization
+- `opensandbox_server/main.py`: FastAPI app entry point and startup wiring
 - `opensandbox_server/api/`: FastAPI routes and request/response schemas
 - `opensandbox_server/services/`: business logic and runtime integration
+- `opensandbox_server/services/docker/`: Docker runtime, endpoints, port allocation, diagnostics, and snapshot runtime
+- `opensandbox_server/services/k8s/`: Kubernetes providers, templates, informer, egress, pool, diagnostics, and pause/resume runtime integration
+- `opensandbox_server/repositories/`: persistence backends, including snapshot metadata
 - `opensandbox_server/integrations/`: optional external integrations
+- `opensandbox_server/extensions/`: extension loading and optional behavior hooks
+- `opensandbox_server/middleware/`: authentication and request middleware
+- `opensandbox_server/config.py`: TOML config model, defaults, validation, and environment integration
 - `tests/`: unit, integration, smoke, and Kubernetes-focused tests
 
 ## Commands
@@ -29,6 +38,14 @@ uv run pytest tests/test_docker_service.py
 uv run pytest tests/test_schema.py
 ```
 
+Kubernetes-focused checks:
+
+```bash
+cd server
+uv run pytest tests/k8s
+uv run pytest tests/test_routes_pause_resume.py tests/test_routes_snapshots.py tests/test_snapshot_service.py
+```
+
 Typed or broader validation:
 
 ```bash
@@ -40,8 +57,8 @@ uv run pytest
 Local startup:
 
 ```bash
-cp server/opensandbox_server/examples/example.config.toml ~/.sandbox.toml
 cd server
+uv run opensandbox-server init-config ~/.sandbox.toml --example docker
 uv run python -m opensandbox_server.main
 ```
 
@@ -58,6 +75,9 @@ chmod +x tests/smoke.sh
 Always:
 
 - Keep FastAPI routes thin and delegate behavior to services, validators, or runtime helpers.
+- Keep runtime-specific behavior in Docker/Kubernetes service modules; shared API behavior belongs in common services or validators.
+- Keep snapshot state changes coordinated across route handlers, services, repositories, and runtime-specific snapshot implementations.
+- Keep TOML config defaults, config examples, README/configuration docs, and CLI `init-config` output aligned.
 - Extend existing fixtures and helpers before adding parallel abstractions.
 - Add focused regression tests with every bug fix or behavior change.
 
@@ -66,6 +86,7 @@ Ask first:
 - Removing or renaming public endpoints
 - Changing config shape or defaults in a user-visible way
 - Introducing new external service dependencies
+- Changing snapshot, pause/resume, renew-intent, ingress, egress, or pool semantics
 - Large reorganizations across `api/`, `services/`, and `tests/`
 
 Never:

specs/AGENTS.md

@@ -5,6 +5,7 @@ You are maintaining OpenSandbox public API contracts. Treat the spec files in th
 ## Scope
 
 - `sandbox-lifecycle.yml`
+- `diagnostic-api.yml`
 - `execd-api.yaml`
 - `egress-api.yaml`
 - `README*.md`
@@ -13,10 +14,13 @@ When a contract change affects downstream code, also read the nearest consumer g
 
 - `../server/AGENTS.md` for lifecycle server impact
 - `../sdks/AGENTS.md` for SDK-facing contract changes
+- component README/DEVELOPMENT files under `../components/` for execd or egress impact
+- `../cli/README.md` for CLI-visible diagnostics, lifecycle, or egress changes
 
 ## Contract Map
 
-- `sandbox-lifecycle.yml`: lifecycle API used by `server/` and sandbox SDKs
+- `sandbox-lifecycle.yml`: lifecycle API used by `server/`, `cli/`, and sandbox SDKs
+- `diagnostic-api.yml`: diagnostics API used by server diagnostics, CLI diagnostics, and troubleshooting flows
 - `execd-api.yaml`: execution API used by `components/execd/` and code-interpreter SDKs
 - `egress-api.yaml`: egress sidecar API and related docs
 
@@ -53,6 +57,7 @@ Always:
 - Keep operation IDs, schema names, examples, and descriptions consistent with existing naming.
 - Regenerate derived outputs after spec edits.
 - Update affected consumers in the same change when practical.
+- Keep spec examples aligned with server schemas and generated SDK models.
 - Call out downstream areas you did not verify.
 
 Ask first: