diff --git a/AGENTS.md b/AGENTS.md index 3a35636..261db8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ when they exist. | Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules | | Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures | | Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs | -| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Installation approval, Ascend NPU collection, and read-only memory-diagnostic workflows | +| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Helper routing, installation approval, Ascend NPU collection, and read-only memory-diagnostic workflows | ## Runtime Topology diff --git a/README.md b/README.md index c6234cf..d972d2e 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,8 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough. | `pt-snap skill` | List and install bundled agent skills | | `pt-snap-mcp` | Start the MCP server for agent integration | +`pt-snap --help` includes an agent hint: prefer `--json` where supported, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`. + ## MCP Server `pt-snap-cli` provides an MCP (Model Context Protocol) server so AI agents can interact with PyTorch memory snapshots programmatically. diff --git a/README_zh.md b/README_zh.md index 6a3f164..e1008fd 100644 --- a/README_zh.md +++ b/README_zh.md @@ -61,6 +61,8 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices | `pt-snap skill` | 列出并安装随包 agent skill | | `pt-snap-mcp` | 启动 MCP 服务器以支持 Agent 集成 | +`pt-snap --help` 含 Agent 提示:在当前已支持的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。 + ## MCP 服务器 `pt-snap-cli` 提供了 MCP(Model Context Protocol)服务器,使 AI Agent 能够以编程方式与 PyTorch 内存快照交互。 diff --git a/docs/en/AGENTS.md b/docs/en/AGENTS.md index 6647653..4f3521f 100644 --- a/docs/en/AGENTS.md +++ b/docs/en/AGENTS.md @@ -13,7 +13,7 @@ | `focus-management.md` | Focus resolution, project focus files, environment variables, and global config behavior. | | `querying.md` | Query listing, template info, parameter usage, result limits, and built-in templates. | | `splitting.md` | Snapshot slicing strategies, output formats, replay validation, and publication guarantees. | -| `skills.md` | Bundled agent-skill listing, install destinations, and status meanings. | +| `skills.md` | Bundled agent-skill listing, helper entry, install destinations, and status meanings. | | `mcp.md` | MCP server setup, tools, resources, prompts, and agent usage. | | `database.md` | Snapshot SQLite table/schema reference. | | `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. | diff --git a/docs/en/skills.md b/docs/en/skills.md index 84a0b80..ff4d994 100644 --- a/docs/en/skills.md +++ b/docs/en/skills.md @@ -2,7 +2,7 @@ [中文](../zh/skills.md) | English -`pt-snap-cli` ships agent skills for setup, Ascend NPU collection, and memory diagnostics. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires. +`pt-snap-cli` ships agent skills for routing (`pt-snap-helper`), setup, Ascend NPU collection, and memory diagnostics. Agents should start with `pt-snap-helper` and prefer `--json` on commands that currently support it. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires. ## List skills @@ -79,6 +79,7 @@ After an install, upgrade, or uninstall that changes skill files, restart the ag | Skill | Use when | |-------|----------| +| `pt-snap-helper` | Choosing the next skill from the user goal and input type | | `pt-snap-setup` | Installing or verifying `pt-snap-cli` in the active Python environment | | `pt-snap-ascend-npu-collect` | Collecting an Ascend NPU memory snapshot pickle | | `pt-snap-memory-leak` | Diagnosing live allocations and leak candidates in a SnapshotDB | diff --git a/docs/zh/AGENTS.md b/docs/zh/AGENTS.md index db95b41..174b895 100644 --- a/docs/zh/AGENTS.md +++ b/docs/zh/AGENTS.md @@ -13,7 +13,7 @@ | `focus-management.md` | Chinese guide to focus resolution and persistence. | | `querying.md` | Chinese guide to query templates, parameters, and output. | | `splitting.md` | Chinese guide to snapshot slicing, formats, replay validation, and publication. | -| `skills.md` | Chinese guide to bundled agent-skill listing and installation. | +| `skills.md` | Chinese guide to bundled agent-skill listing, helper entry, and installation. | | `mcp.md` | Chinese MCP server setup and tool reference. | | `database.md` | Chinese snapshot SQLite schema reference. | | `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, and metadata Python API. | diff --git a/docs/zh/skills.md b/docs/zh/skills.md index 78ae796..3077bf9 100644 --- a/docs/zh/skills.md +++ b/docs/zh/skills.md @@ -2,7 +2,7 @@ [English](../en/skills.md) | 中文 -`pt-snap-cli` 附带用于环境安装、昇腾 NPU 采集和内存诊断的 agent skill。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。 +`pt-snap-cli` 附带用于路由(`pt-snap-helper`)、环境安装、昇腾 NPU 采集和内存诊断的 agent skill。Agent 应先使用 `pt-snap-helper`,并在当前已支持的命令上优先使用 `--json`。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。 ## 列出 skill @@ -79,6 +79,7 @@ pt-snap skill uninstall --project --target cursor | Skill | 适用场景 | |-------|----------| +| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill | | `pt-snap-setup` | 在当前 Python 环境安装或验证 `pt-snap-cli` | | `pt-snap-ascend-npu-collect` | 采集昇腾 NPU 内存快照 pickle | | `pt-snap-memory-leak` | 在 SnapshotDB 中诊断仍存活分配和泄漏候选 | diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 144720c..cbaf42a 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -3,7 +3,8 @@ # skills ## Purpose -`skills` contains agent workflows shipped with the repository. Setup owns the +`skills` contains agent workflows shipped with the repository. The helper +skill is a read-only router by user goal and input type. Setup owns the only Python-environment mutation boundary and installs after explicit approval; collection skills guide Ascend NPU snapshot capture without importing or diagnosing the pickle; diagnostic skills consume installed `pt-snap` @@ -12,6 +13,7 @@ surfaces against existing SnapshotDB data without writes. ## Scope | Path | Responsibility | | --- | --- | +| `pt-snap-helper/SKILL.md` | Routes by user goal and input type to the five skills; checks `pt-snap skill list --json`; does not install, import, or persist focus. | | `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. | | `pt-snap-ascend-npu-collect/SKILL.md` | Collect Ascend NPU pickles via native APIs, framework config, or OOM env; inventory artifacts without import or diagnosis. | | `pt-snap-memory-leak/SKILL.md` | Diagnose end-of-trace live allocations, peak survival, callstack attribution, and release evidence without persisting analysis state. | @@ -32,6 +34,8 @@ surfaces against existing SnapshotDB data without writes. turn allocator gaps into definitive fragmentation claims. - Diagnostic skills pass the database and device explicitly and delegate missing tooling to `pt-snap-setup`. +- Helper skills stay read-only navigation. They must not install packages, copy + skills, import pickle, persist focus, or run diagnostic analysis. - Prefer packaged query templates for diagnostics. Any raw SQLite fallback must document why a template is insufficient and enforce read-only access. @@ -45,6 +49,9 @@ an explicit `--dir`. After install or upgrade, the host agent must be restarted. ## Focused Tests +- Run `pytest tests/skills/test_helper_contract.py` after helper-skill changes. + Static coverage checks routing names, current `--json` capability, skill-list + availability, and the pickle/focus/install read-only boundary. - Run `pytest tests/skills/test_setup_contract.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically. - Run `pytest tests/skills/test_ascend_npu_collect_contract.py` after collection-skill changes. The v1 evaluation harness accepts only diff --git a/skills/pt-snap-helper/SKILL.md b/skills/pt-snap-helper/SKILL.md new file mode 100644 index 0000000..70e8ed8 --- /dev/null +++ b/skills/pt-snap-helper/SKILL.md @@ -0,0 +1,169 @@ +--- +name: pt-snap-helper +description: Use as the first pt-snap entry when the next skill is unclear. Routes by user goal and input type (existing SnapshotDB, pickle-only, missing CLI, Ascend NPU collection) to pt-snap-setup, pt-snap-ascend-npu-collect, pt-snap-memory-leak, pt-snap-memory-peak-breakdown, or pt-snap-memory-fragmentation. Prefers --json on commands that currently support it. +--- + +# pt-snap-helper + +## Overview + +This is a read-only navigator. Choose the next skill from the user's goal and +input type. Do not install packages, do not copy skills into agent directories, +do not import or deserialize pickle, and do not persist focus. + +Use this skill when: + +- The user first asks about pt-snap and the next skill is unclear. +- The host has several pt-snap skills and needs a routing decision. +- The user has a SnapshotDB, a pickle, no CLI, or needs Ascend NPU collection. + +Do not use this skill to run leak, peak, or fragmentation analysis. Hand off to +the matching diagnostic skill after routing. + +## Prerequisite: check skill availability + +If `pt-snap` is on PATH, inspect bundled skill status with JSON: + +```bash +command -v pt-snap +pt-snap skill list --json +``` + +Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`, +or `missing`. + +If `pt-snap` is missing, stop routing diagnostics and hand off to +`pt-snap-setup`. Do not install the Python package from this skill. + +If a needed skill is `missing` or `outdated`, tell the user how to install or +upgrade it. Do not run install or upgrade from this skill. + +Install or upgrade examples the user can run after they confirm they want +the skills installed or updated. Do not run these commands from this skill: + +```bash +pt-snap skill install pt-snap-helper --json +pt-snap skill install --json +pt-snap skill upgrade pt-snap-helper --json +pt-snap skill upgrade --json +``` + +After any install, upgrade, or uninstall that changes skill files, the host +agent must be restarted before the change is visible: + +Restart the agent after install, upgrade, or uninstall so the skill change takes effect. + +`pt-snap skill list` does not require a restart. + +## Prefer `--json` where supported + +Prefer `--json` on commands that currently accept it: + +- `pt-snap skill list --json` +- `pt-snap skill install --json` +- `pt-snap skill upgrade --json` +- `pt-snap skill uninstall --json` +- `pt-snap metadata '' --json` +- `pt-snap report peak-memory '' --device --json` + +Do not add `--json` to `query`, `focus`, `import`, `split`, or `config`. Those +commands do not support it yet. Do not invent a global `--json` flag on `pt-snap`. + +This skill itself does not run analysis queries. The diagnostic skills own +those commands. + +## Routing matrix + +Choose one next skill. If the goal is still ambiguous after this table, ask +the user; do not start all diagnostic skills. + +| User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture | +| --- | --- | --- | --- | --- | +| Install or verify the CLI | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | +| Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-setup` first | `pt-snap-ascend-npu-collect` | +| Leak / live allocations at end of trace | `pt-snap-memory-leak` | Trusted import first, then leak | `pt-snap-setup` first | Collect first, then trusted import, then leak | +| What was live at a peak event | `pt-snap-memory-peak-breakdown` | Trusted import first, then peak | `pt-snap-setup` first | Collect first, then trusted import, then peak | +| Allocator gaps / reserved-pool pressure | `pt-snap-memory-fragmentation` | Trusted import first, then fragmentation | `pt-snap-setup` first | Collect first, then trusted import, then fragmentation | + +Exact next-skill names: + +- `pt-snap-setup` +- `pt-snap-ascend-npu-collect` +- `pt-snap-memory-leak` +- `pt-snap-memory-peak-breakdown` +- `pt-snap-memory-fragmentation` + +CSV, SVG, and other visualization files are not SnapshotDB input. If the user +only has those, stop and ask for a `.db` or a trusted pickle. + +### Existing SnapshotDB + +A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a +`dictionary` table. When the user already has one: + +1. Confirm the goal is leak, peak, or fragmentation. +2. Hand off to the matching diagnostic skill. Pass the database path and + device if the user supplied them. +3. Do not run `pt-snap focus ` to persist a new focus from this + skill. Diagnostic skills may read the current focus with no arguments. + +This helper may mention that `pt-snap metadata '' --json` exists. +Running that check belongs to the diagnostic skill. + +### Only pickle + +A `.pkl` / `.pickle` file is not a SnapshotDB. Pickle import is trusted-code +execution, not a sandbox. + +From this skill: + +- Do not open, import, inspect, or deserialize pickle input. +- Do not run `pt-snap import`. +- Do not run `pt-snap split`. +- Do not run `pt-snap focus` with a database path. + +Tell the user that import is an independent trusted-input decision. If they +confirm the pickle is trusted and they want a SnapshotDB, they can run: + +```bash +pt-snap import +``` + +That command currently has no `--json` option. Import may update focus unless +they pass `--no-focus`. This helper must not run that command or change focus. + +After the user has a SnapshotDB, route to the matching diagnostic skill. + +If they need to capture a pickle on Ascend NPU first, hand off to +`pt-snap-ascend-npu-collect` instead of importing. + +### `pt-snap` missing + +Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership +checks, and install approval. This helper must not run `pip` or assume Conda. + +### Need Ascend NPU collection + +Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists +on disk. It does not import or diagnose. + +## Boundaries + +- Keep this skill read-only. Do not install Python packages, and do not write files. +- Do not run `pt-snap skill install` / `upgrade` / `uninstall`. +- Do not persist focus or edit configuration. +- Do not start leak, peak, fragmentation, or OOM-root-cause analysis here. +- Do not classify allocations or allocator gaps. +- Use the five skill names above exactly; do not invent aliases. + +## Output + +Report: + +- `Goal` +- `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`) +- `Needed skills` and their `pt-snap skill list --json` status when available +- `Next skill` (one of the five names) +- `Install/restart notes` when a skill is missing or outdated +- `Trusted import notes` when the user only has pickle +- `Unknowns` diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md new file mode 100644 index 0000000..70e8ed8 --- /dev/null +++ b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md @@ -0,0 +1,169 @@ +--- +name: pt-snap-helper +description: Use as the first pt-snap entry when the next skill is unclear. Routes by user goal and input type (existing SnapshotDB, pickle-only, missing CLI, Ascend NPU collection) to pt-snap-setup, pt-snap-ascend-npu-collect, pt-snap-memory-leak, pt-snap-memory-peak-breakdown, or pt-snap-memory-fragmentation. Prefers --json on commands that currently support it. +--- + +# pt-snap-helper + +## Overview + +This is a read-only navigator. Choose the next skill from the user's goal and +input type. Do not install packages, do not copy skills into agent directories, +do not import or deserialize pickle, and do not persist focus. + +Use this skill when: + +- The user first asks about pt-snap and the next skill is unclear. +- The host has several pt-snap skills and needs a routing decision. +- The user has a SnapshotDB, a pickle, no CLI, or needs Ascend NPU collection. + +Do not use this skill to run leak, peak, or fragmentation analysis. Hand off to +the matching diagnostic skill after routing. + +## Prerequisite: check skill availability + +If `pt-snap` is on PATH, inspect bundled skill status with JSON: + +```bash +command -v pt-snap +pt-snap skill list --json +``` + +Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`, +or `missing`. + +If `pt-snap` is missing, stop routing diagnostics and hand off to +`pt-snap-setup`. Do not install the Python package from this skill. + +If a needed skill is `missing` or `outdated`, tell the user how to install or +upgrade it. Do not run install or upgrade from this skill. + +Install or upgrade examples the user can run after they confirm they want +the skills installed or updated. Do not run these commands from this skill: + +```bash +pt-snap skill install pt-snap-helper --json +pt-snap skill install --json +pt-snap skill upgrade pt-snap-helper --json +pt-snap skill upgrade --json +``` + +After any install, upgrade, or uninstall that changes skill files, the host +agent must be restarted before the change is visible: + +Restart the agent after install, upgrade, or uninstall so the skill change takes effect. + +`pt-snap skill list` does not require a restart. + +## Prefer `--json` where supported + +Prefer `--json` on commands that currently accept it: + +- `pt-snap skill list --json` +- `pt-snap skill install --json` +- `pt-snap skill upgrade --json` +- `pt-snap skill uninstall --json` +- `pt-snap metadata '' --json` +- `pt-snap report peak-memory '' --device --json` + +Do not add `--json` to `query`, `focus`, `import`, `split`, or `config`. Those +commands do not support it yet. Do not invent a global `--json` flag on `pt-snap`. + +This skill itself does not run analysis queries. The diagnostic skills own +those commands. + +## Routing matrix + +Choose one next skill. If the goal is still ambiguous after this table, ask +the user; do not start all diagnostic skills. + +| User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture | +| --- | --- | --- | --- | --- | +| Install or verify the CLI | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | +| Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-setup` first | `pt-snap-ascend-npu-collect` | +| Leak / live allocations at end of trace | `pt-snap-memory-leak` | Trusted import first, then leak | `pt-snap-setup` first | Collect first, then trusted import, then leak | +| What was live at a peak event | `pt-snap-memory-peak-breakdown` | Trusted import first, then peak | `pt-snap-setup` first | Collect first, then trusted import, then peak | +| Allocator gaps / reserved-pool pressure | `pt-snap-memory-fragmentation` | Trusted import first, then fragmentation | `pt-snap-setup` first | Collect first, then trusted import, then fragmentation | + +Exact next-skill names: + +- `pt-snap-setup` +- `pt-snap-ascend-npu-collect` +- `pt-snap-memory-leak` +- `pt-snap-memory-peak-breakdown` +- `pt-snap-memory-fragmentation` + +CSV, SVG, and other visualization files are not SnapshotDB input. If the user +only has those, stop and ask for a `.db` or a trusted pickle. + +### Existing SnapshotDB + +A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a +`dictionary` table. When the user already has one: + +1. Confirm the goal is leak, peak, or fragmentation. +2. Hand off to the matching diagnostic skill. Pass the database path and + device if the user supplied them. +3. Do not run `pt-snap focus ` to persist a new focus from this + skill. Diagnostic skills may read the current focus with no arguments. + +This helper may mention that `pt-snap metadata '' --json` exists. +Running that check belongs to the diagnostic skill. + +### Only pickle + +A `.pkl` / `.pickle` file is not a SnapshotDB. Pickle import is trusted-code +execution, not a sandbox. + +From this skill: + +- Do not open, import, inspect, or deserialize pickle input. +- Do not run `pt-snap import`. +- Do not run `pt-snap split`. +- Do not run `pt-snap focus` with a database path. + +Tell the user that import is an independent trusted-input decision. If they +confirm the pickle is trusted and they want a SnapshotDB, they can run: + +```bash +pt-snap import +``` + +That command currently has no `--json` option. Import may update focus unless +they pass `--no-focus`. This helper must not run that command or change focus. + +After the user has a SnapshotDB, route to the matching diagnostic skill. + +If they need to capture a pickle on Ascend NPU first, hand off to +`pt-snap-ascend-npu-collect` instead of importing. + +### `pt-snap` missing + +Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership +checks, and install approval. This helper must not run `pip` or assume Conda. + +### Need Ascend NPU collection + +Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists +on disk. It does not import or diagnose. + +## Boundaries + +- Keep this skill read-only. Do not install Python packages, and do not write files. +- Do not run `pt-snap skill install` / `upgrade` / `uninstall`. +- Do not persist focus or edit configuration. +- Do not start leak, peak, fragmentation, or OOM-root-cause analysis here. +- Do not classify allocations or allocator gaps. +- Use the five skill names above exactly; do not invent aliases. + +## Output + +Report: + +- `Goal` +- `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`) +- `Needed skills` and their `pt-snap skill list --json` status when available +- `Next skill` (one of the five names) +- `Install/restart notes` when a skill is missing or outdated +- `Trusted import notes` when the user only has pickle +- `Unknowns` diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 497cae2..6b4fc39 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -62,9 +62,16 @@ ) from pt_snap_cli.query.registry import discover_categories +AGENT_HELP_EPILOG = ( + "Agents: prefer --json where supported. " + "Start with the pt-snap-helper skill; " + "check availability with pt-snap skill list --json." +) + app = typer.Typer( name="pt-snap", help="PyTorch Memory Snapshot Analysis Tool", + epilog=AGENT_HELP_EPILOG, add_completion=True, context_settings={"help_option_names": ["-h", "--help"]}, ) diff --git a/tests/core/test_skill_service.py b/tests/core/test_skill_service.py index 1ff560a..977ea69 100644 --- a/tests/core/test_skill_service.py +++ b/tests/core/test_skill_service.py @@ -417,11 +417,13 @@ def test_default_catalog_includes_repo_skills() -> None: names = {spec.name for spec in SkillService(catalog_dir=catalog).list_catalog()} assert names == { "pt-snap-ascend-npu-collect", + "pt-snap-helper", "pt-snap-memory-fragmentation", "pt-snap-memory-leak", "pt-snap-memory-peak-breakdown", "pt-snap-setup", } + assert (catalog / "pt-snap-helper" / "SKILL.md").is_file() assert (catalog / "pt-snap-setup" / "SKILL.md").is_file() diff --git a/tests/skills/test_helper_contract.py b/tests/skills/test_helper_contract.py new file mode 100644 index 0000000..47dfaa0 --- /dev/null +++ b/tests/skills/test_helper_contract.py @@ -0,0 +1,111 @@ +from pathlib import Path + +from typer.main import get_command + +from pt_snap_cli.cli import app + +REPO_ROOT = Path(__file__).resolve().parents[2] +SKILL_PATH = REPO_ROOT / "skills" / "pt-snap-helper" / "SKILL.md" +AGENTS_PATH = REPO_ROOT / "skills" / "AGENTS.md" + +ROUTED_SKILLS = ( + "pt-snap-setup", + "pt-snap-ascend-npu-collect", + "pt-snap-memory-leak", + "pt-snap-memory-peak-breakdown", + "pt-snap-memory-fragmentation", +) + +JSON_COMMANDS = ( + ("metadata",), + ("report", "peak-memory"), + ("skill", "list"), + ("skill", "install"), + ("skill", "upgrade"), + ("skill", "uninstall"), +) +NO_JSON_COMMANDS = ( + ("query",), + ("focus",), + ("import",), + ("split",), + ("config",), +) + + +def _skill() -> str: + return SKILL_PATH.read_text(encoding="utf-8") + + +def _command_has_option(*path: str, option: str) -> bool: + command = get_command(app) + for name in path: + command = command.commands[name] + return any(option in param.opts for param in command.params) + + +def test_helper_skill_frontmatter_and_index() -> None: + skill = _skill() + agents = AGENTS_PATH.read_text(encoding="utf-8") + + assert skill.startswith("---\nname: pt-snap-helper\n") + assert "read-only navigator" in skill + assert "pt-snap-helper/SKILL.md" in agents + assert "Routes by user goal and input type" in agents + + +def test_helper_skill_checks_availability_and_restart() -> None: + skill = _skill() + + assert "pt-snap skill list --json" in skill + assert "pt-snap skill install pt-snap-helper --json" in skill + assert "pt-snap skill upgrade pt-snap-helper --json" in skill + assert "Do not run install or upgrade from this skill." in skill + assert ( + "Restart the agent after install, upgrade, or uninstall so the skill " + "change takes effect." + ) in skill + + +def test_helper_skill_uses_current_json_capability() -> None: + skill = _skill() + + assert "Prefer `--json` where supported" in skill + assert "pt-snap metadata '' --json" in skill + assert "pt-snap report peak-memory '' --device --json" in skill + assert "Do not add `--json` to `query`, `focus`, `import`, `split`, or `config`." in skill + assert "Do not invent a global `--json` flag on `pt-snap`." in skill + assert "pt-snap query --json" not in skill + assert "pt-snap import --json" not in skill + assert "pt-snap focus --json" not in skill + for path in JSON_COMMANDS: + assert _command_has_option(*path, option="--json") + for path in NO_JSON_COMMANDS: + assert not _command_has_option(*path, option="--json") + assert not _command_has_option(option="--json") + + +def test_helper_skill_routes_by_goal_and_input_type() -> None: + skill = _skill() + + assert "## Routing matrix" in skill + assert "Existing SnapshotDB" in skill + assert "Only pickle" in skill + assert "`pt-snap` missing" in skill + assert "Need Ascend NPU capture" in skill + for name in ROUTED_SKILLS: + assert f"`{name}`" in skill + assert "CSV, SVG, and other visualization files are not SnapshotDB input" in skill + + +def test_helper_skill_keeps_pickle_import_and_focus_as_handoffs() -> None: + skill = _skill() + + assert "import is an independent trusted-input decision" in skill + assert "Do not run `pt-snap import`." in skill + assert "Do not run `pt-snap focus` with a database path." in skill + assert "Do not persist focus" in skill + assert "This helper must not run that command or change focus." in skill + assert "pt-snap import " in skill + assert "That command currently has no `--json` option." in skill + assert "Do not run `pt-snap skill install`" in skill diff --git a/tests/test_cli.py b/tests/test_cli.py index 7c61261..bd7985a 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -10,7 +10,7 @@ from click import unstyle from typer.testing import CliRunner -from pt_snap_cli.cli import app +from pt_snap_cli.cli import AGENT_HELP_EPILOG, app from pt_snap_cli.query.config import QueryTemplate from pt_snap_cli.query.registry import QueryRegistry, register_query @@ -213,6 +213,33 @@ def test_short_help_flag(self) -> None: assert result.exit_code == 0 assert "PyTorch Memory Snapshot Analysis Tool" in result.stdout + def test_root_help_includes_agent_epilog(self) -> None: + for flag in ("--help", "-h"): + result = runner.invoke(app, [flag]) + assert result.exit_code == 0 + normalized = " ".join(unstyle(result.stdout).split()) + assert AGENT_HELP_EPILOG in normalized + assert normalized.index(AGENT_HELP_EPILOG) > normalized.index( + "PyTorch Memory Snapshot Analysis Tool" + ) + + def test_json_output_excludes_agent_help_epilog(self) -> None: + listed = runner.invoke(app, ["skill", "list", "--json", "--user", "--target", "claude"]) + assert listed.exit_code == 0 + listed_out = unstyle(listed.stdout) + assert "Agents: prefer --json where supported" not in listed_out + payload = json.loads(listed.stdout) + names = {item["name"] for item in payload["skills"]} + assert "pt-snap-helper" in names + + version = runner.invoke(app, ["--version"]) + assert version.exit_code == 0 + assert "Agents: prefer --json where supported" not in unstyle(version.stdout) + + query_help = runner.invoke(app, ["query", "-h"]) + assert query_help.exit_code == 0 + assert "Agents: prefer --json where supported" not in unstyle(query_help.stdout) + def test_subcommand_short_help_flag(self) -> None: """Test -h flag for subcommands.""" result = runner.invoke(app, ["query", "-h"]) @@ -1245,6 +1272,7 @@ def test_skill_list_json_and_install_roundtrip(self, tmp_path: Path) -> None: payload = json.loads(listed.stdout) names = {item["name"] for item in payload["skills"]} assert "pt-snap-setup" in names + assert "pt-snap-helper" in names setup = next(item for item in payload["skills"] if item["name"] == "pt-snap-setup") assert setup["status"] == "missing" assert setup["description"] diff --git a/tests/test_completion.py b/tests/test_completion.py index 65f2cd0..959824b 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -95,6 +95,7 @@ class TestCompleteSkillNames: def test_returns_bundled_skills(self) -> None: result = complete_skill_names() assert "pt-snap-setup" in result + assert "pt-snap-helper" in result assert result == sorted(result)