feat(runtime): add ar runtime command group for declarative AgentRuntime deploy

AGENTS.md

@@ -14,8 +14,12 @@ make dev                  # Create venv + install editable with dev deps
 make install              # Install without dev deps
 
 # Development
-make lint                 # Run ruff linter
+make lint                 # Run ruff linter (ruff check)
+make format-check         # Verify code is ruff-formatted (no rewrite)
+.venv/bin/ruff format src/ tests/   # Apply ruff formatting in place
+.venv/bin/mypy src/agentrun_cli     # Static type check (CI runs this verbatim)
 make test                 # Run all tests
+make coverage             # Run tests with the >=95% coverage gate (matches CI)
 .venv/bin/pytest tests/test_cli_basic.py -v              # Run a single test file
 .venv/bin/pytest tests/test_cli_basic.py::TestConfigCommands::test_set_and_get -v  # Single test
 
@@ -41,6 +45,42 @@ make build-all            # macOS + Linux (via Docker)
 
 **Error handling** (`_utils/error.py`): The `@handle_errors` decorator catches SDK exceptions by class name pattern (no hard import) and maps them to deterministic exit codes (0=success, 1=not found, 2=bad input, 3=auth, 4=server). Errors go to stderr as JSON.
 
+## CI Lint Gate (must pass locally before pushing)
+
+The GitHub Actions `CI` workflow (`.github/workflows/ci.yml`) blocks merges on
+**all four** of these checks, run in dedicated jobs against Python 3.10–3.13.
+Run them locally before pushing — failing any one of them produces a red PR.
+
+| CI job | Command (run from repo root) | Make target |
+|---|---|---|
+| Lint (ruff) — lint rules | `ruff check src/ tests/` | `make lint` |
+| Lint (ruff) — format check | `ruff format --check src/ tests/` | `make format-check` |
+| Type check (mypy) | `mypy src/agentrun_cli` | *(no make target — run directly)* |
+| Test + coverage | `pytest tests/unit tests/integration --cov=agentrun_cli --cov-fail-under=95` | `make coverage` |
+
+Rules:
+
+- **Ruff format is non-negotiable.** CI runs `ruff format --check`, not
+  `ruff format` — it will not auto-fix. Run `ruff format src/ tests/` locally
+  (or `make format-check` to verify) before every commit. Configuration lives
+  in `pyproject.toml` under `[tool.ruff]`.
+- **Mypy must stay green.** Mypy config is in `pyproject.toml` under
+  `[tool.mypy]` (`python_version = "3.10"`, `warn_unreachable = true`,
+  `ignore_missing_imports = true`). Prefer narrowing types (`cast`, explicit
+  annotations) over `# type: ignore`; suppressions need a `[code]` selector
+  and a one-line comment justifying them.
+- **Coverage threshold is 95%.** Every code change must keep incremental
+  coverage at or above 95% — `make coverage` enforces it. A Claude Code hook
+  (`.claude/settings.json`) also runs this automatically after edits to
+  `src/` files. See [Integration Test Requirement](#integration-test-requirement)
+  for the test-coverage rules that feed this gate.
+- **No `--no-verify` / `--no-gpg-sign` shortcuts.** If a hook or lint check
+  fails, fix the underlying issue and create a new commit.
+
+The CI workflow also runs a Smoke job on macOS + Windows (`make build` of the
+PyInstaller binary) and a `pip-audit` security scan — both are advisory but
+should not regress.
+
 ## Testing
 
 Tests use `click.testing.CliRunner` and `unittest.mock.patch` to swap `CONFIG_FILE`/`CONFIG_DIR` with `tmp_path` fixtures, so no real `~/.agentrun/` is touched. Model commands that hit the SDK are not tested in the basic suite — they require credentials.
@@ -83,6 +123,8 @@ docs/
 │   ├── index.md     # install / auth / global options / output / exit codes / group nav
 │   ├── config.md    # one file per command group
 │   ├── model.md
+│   ├── runtime.md
+│   ├── runtime-yaml.md   # detailed YAML field reference for `ar runtime apply`
 │   ├── sandbox.md
 │   ├── skill.md
 │   ├── super-agent.md

README.md

@@ -13,7 +13,8 @@ agents that you configure declaratively without writing or deploying any runtime
 
 - **One-command super agent** — `ar super-agent run` creates a hosted agent and drops you into a chat REPL in seconds.
 - **Declarative deployment** — Kubernetes-style YAML (`ar sa apply -f superagent.yaml`) for reproducible, version-controlled agents.
-- **Six resource groups** — `config`, `model`, `sandbox`, `tool`, `skill`, `super-agent`, all following the same `ar <group> <action>` pattern.
+- **Runtime declarative deploy** — `ar runtime apply -f runtime.yaml` builds an Agent Runtime from a container image and waits for it to reach `READY`.
+- **Seven resource groups** — `config`, `model`, `sandbox`, `tool`, `skill`, `super-agent`, `runtime`, all following the same `ar <group> <action>` pattern.
 - **Multi-profile config** — store multiple sets of credentials in `~/.agentrun/config.json` and switch with `--profile`.
 - **Multiple output formats** — `json` (default), `table`, `yaml`, and `quiet` for shell piping.
 - **Agent-friendly** — JSON-by-default output, deterministic exit codes, no interactive prompts when stdin isn't a TTY.
@@ -176,6 +177,20 @@ ar sa invoke my-helper -m "Plan my day" --text-only
 
 Multi-document YAMLs (`---` separated) let you deploy many agents in one call.
 
+### Deploy a runtime from an image
+
+```bash
+cat > runtime.yaml <<'EOF'
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata: {name: my-agent}
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+EOF
+ar runtime apply -f runtime.yaml
+```
+
 ## Command groups
 
 | Group | Alias | Purpose | Docs |
@@ -186,6 +201,7 @@ Multi-document YAMLs (`---` separated) let you deploy many agents in one call.
 | `tool` |  | MCP and FunctionCall tools | [en](./docs/en/tool.md) · [zh](./docs/zh/tool.md) |
 | `skill` |  | Platform skill packages + local execution | [en](./docs/en/skill.md) · [zh](./docs/zh/skill.md) |
 | `super-agent` | `sa` | Quickstart / CRUD / declarative / conversation | [en](./docs/en/super-agent.md) · [zh](./docs/zh/super-agent.md) |
+| `runtime` | `rt` | Declarative Agent Runtime deploy (container mode) | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
 
 ## Documentation
 

README_zh.md

@@ -12,7 +12,8 @@ Agent）**：一种由平台托管、用户只需声明配置、无需编写或
 
 - **一键拉起超级 Agent** — `ar super-agent run` 一条命令创建托管 Agent 并进入 REPL 对话。
 - **声明式部署** — Kubernetes 风格 YAML（`ar sa apply -f superagent.yaml`），可版本化、可重复部署。
-- **六大资源组** — `config`、`model`、`sandbox`、`tool`、`skill`、`super-agent`，统一 `ar <group> <action>` 模式。
+- **Runtime 声明式部署** — `ar runtime apply -f runtime.yaml` 从容器镜像创建 Agent Runtime 并等待 `READY`。
+- **七大资源组** — `config`、`model`、`sandbox`、`tool`、`skill`、`super-agent`、`runtime`，统一 `ar <group> <action>` 模式。
 - **多 Profile 配置** — `~/.agentrun/config.json` 支持多套凭证，通过 `--profile` 切换。
 - **多种输出格式** — 默认 `json`，支持 `table` / `yaml` / `quiet`（适合 shell 管道）。
 - **对 Agent 友好** — 默认 JSON 输出、确定性退出码、非 TTY 下不弹交互提示。
@@ -172,6 +173,20 @@ ar sa invoke my-helper -m "帮我规划今天的事情" --text-only
 
 多文档 YAML（用 `---` 分隔）可以一次部署多个 Agent。
 
+### 从镜像部署一个 Runtime
+
+```bash
+cat > runtime.yaml <<'EOF'
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata: {name: my-agent}
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+EOF
+ar runtime apply -f runtime.yaml
+```
+
 ## 命令组总览
 
 | 命令组 | 别名 | 用途 | 文档 |
@@ -182,6 +197,7 @@ ar sa invoke my-helper -m "帮我规划今天的事情" --text-only
 | `tool` |  | MCP 与 FunctionCall 工具 | [en](./docs/en/tool.md) · [zh](./docs/zh/tool.md) |
 | `skill` |  | 平台技能包 + 本地执行 | [en](./docs/en/skill.md) · [zh](./docs/zh/skill.md) |
 | `super-agent` | `sa` | 一键拉起 / CRUD / 声明式 / 会话管理 | [en](./docs/en/super-agent.md) · [zh](./docs/zh/super-agent.md) |
+| `runtime` | `rt` | 声明式 Agent Runtime 部署（容器模式） | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
 
 ## 文档
 

agentruntime.yaml

@@ -0,0 +1,52 @@
+# Sample AgentRuntime spec for `ar runtime apply -f agentruntime.yaml`.
+# Full field reference: docs/en/runtime-yaml.md (zh: docs/zh/runtime-yaml.md)
+#
+# Quick usage:
+#   ar runtime render -f agentruntime.yaml   # dry-run, prints SDK input
+#   ar runtime apply  -f agentruntime.yaml   # create-or-update, waits to READY
+#
+# The CLI auto-injects system_tags=["x-agentrun-cli"] and artifact_type=Container.
+# When spec.endpoints is omitted, a default endpoint (targetVersion=LATEST) is
+# also injected — this sample defines an explicit one to make the shape clear.
+
+apiVersion: agentrun/v1
+kind: AgentRuntime
+
+metadata:
+  name: my-agent                          # required, matches [a-z0-9-]{1,63}
+  description: "Example AgentRuntime"
+  # workspace: default                    # optional; mutually exclusive with workspaceId
+
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    # command: ["python", "app.py"]       # optional, overrides image CMD/ENTRYPOINT
+    # port: 9000                          # optional; spec.port below also works
+
+  # ───── resources ─────
+  cpu: 2                                  # default 2 cores
+  memory: 4096                            # default 4096 MB
+  # diskSize: 10240                       # optional, MB (10 GiB)
+
+  # ───── network (default PUBLIC; uncomment for VPC) ─────
+  # network:
+  #   mode: PUBLIC_AND_PRIVATE
+  #   vpcId: vpc-xxxxxxxx
+  #   vswitchIds: [vsw-xxxxxxxx]
+  #   securityGroupId: sg-xxxxxxxx
+
+  # ───── log to SLS (project + logstore must be set together) ─────
+  # log:
+  #   project: my-agent-logs
+  #   logstore: runtime
+
+  # ───── environment variables ─────
+  env:
+    LOG_LEVEL: info
+
+  # ───── endpoints (omit to auto-inject `default` / LATEST) ─────
+  endpoints:
+    - name: default
+      targetVersion: LATEST
+      # scaling:
+      #   minInstances: 1

docs/en/index.md

@@ -180,6 +180,8 @@ ar sandbox exec "$SANDBOX" --code "print('hello')"
 | `2` | Bad input | Missing required flag, invalid JSON, mutually-exclusive flags combined, non-TTY missing model. |
 | `3` | Authentication failure | Invalid AK/SK or insufficient permissions. |
 | `4` | Server error or timeout | Backend API exception, SSE stream error, `apply --wait` timeout. |
+| `5` | Resource failed | `apply` ran and the Runtime/Endpoint reached `*_FAILED`. |
+| `6` | Polling timeout | `apply --wait` exceeded `--timeout`. |
 | `130` | User interrupt | REPL received two Ctrl+C or Ctrl+D. |
 
 Errors are written to stderr as JSON:
@@ -197,4 +199,5 @@ Errors are written to stderr as JSON:
 | `sandbox` | `sb` | Sandboxes plus file, process, context, template and browser sub-groups | [sandbox.md](./sandbox.md) |
 | `tool` |  | MCP and FunctionCall tools + sub-tool invocation | [tool.md](./tool.md) |
 | `skill` |  | Platform skill packages + local scan/load/exec | [skill.md](./skill.md) |
+| `runtime` | `rt` | Declarative Agent Runtime deploy (container mode) | [runtime.md](./runtime.md) · [YAML reference](./runtime-yaml.md) |
 | `super-agent` | `sa` | Quickstart REPL, declarative deploy, CRUD, conversations | [super-agent.md](./super-agent.md) |