Skip to content

agent-integration.md

Latest commit

 

History

History
81 lines (67 loc) · 4.04 KB

agent-integration.md

File metadata and controls

81 lines (67 loc) · 4.04 KB
Raw

Agent integration

xprobe exposes shell commands, versioned JSON, JSON Schema, and one canonical Skill. It does not call model APIs or provide an agent daemon.

The canonical workflow is skills/xprobe-measure-latency/SKILL.md. AGENTS.md, CLAUDE.md, and .cursor/rules/xprobe.mdc are discovery points and must not duplicate command sequences or correlation rules.

Install the Skill

The canonical directory follows the open Agent Skills format and is shared by Codex, Claude Code, Cursor, and other compatible clients. The user installs the released Skill through the skills CLI; the activated Skill then bootstraps or repairs the matching xprobe CLI itself:

npx skills@1 add \
  https://github.com/itdevwu/xprobe/tree/v0.5.1/skills/xprobe-measure-latency \
  --global

For automation, add --agent codex|claude-code|cursor --copy --yes. Omit --global for repository-scoped installation. The Skill is self-contained; install its whole directory so its references, examples, and analysis script remain available.

The Skill routes setup, completed-artifact analysis, known-boundary measurement, unknown CPU/Python/GPU investigation, and multi-process work independently. It checks or installs the CLI only for live work. Unknown CPU work starts with sampled stacks, adds syscall aggregation or CPython GC only when supported by a hypothesis, and falls back visibly to native frames when Python semantics are unavailable. Unknown GPU work uses only relevant aggregates. Mixed CPU/GPU inventories may run concurrently with separate contracts, bounds, outputs, and failure handling. The bundled scripts/analyze_trace.py provides deterministic kernel, copy, overlap, stream, and gap summaries. The repository tests installation with skills CLI 1.5.20 in isolated home directories. This pinned test protects released behavior while the documented skills@1 selector receives compatible path updates.

For multi-process workloads, the Skill selects explicit PID/start-time identities, inventories a representative worker when homogeneity is supported by evidence, and asks the agent framework to launch one independent bounded measurement per selected worker concurrently. Results, warnings, failures, and artifacts remain per process; xprobe does not add a multi-process command or claim cross-process causality.

Inventory outputs are not event artifacts. CPU hotspots, syscall groups, and GPU groups produce selector hypotheses; every exact selector still passes read-only validate. The Agent must inspect the quality fields specific to each schema and cannot equate sample proportions, aggregate duration shares, or overlapping capture windows with exact causality.

For containerized live targets, the Skill keeps orchestration in the caller. It resolves an explicit application container, runs xprobe in the same PID and mount namespaces, reacquires PID plus procfs start time there, and preserves per-command artifacts outside the container. It never substitutes a sidecar or host PID, and reports capabilities that cannot be added to an already-running container. Narrow exact captures begin with bounded record headroom and an --events-out artifact instead of defaulting to six-figure capacity.

Contract test

just test-agent-contract
just test-skill-install

The test requires the visible command set to be exactly doctor, discover, validate, and measure. It invokes the first three in strict JSON mode, checks injection requirements, verifies schemas, exercises the bundled trace analyzer, and checks adaptive task routing for unknown CPU, Python, mixed, known-selector, existing-artifact, and unsupported-runtime scenarios, bounded live collection, mutation guards, and result quality/evidence. The installation test uses the real third-party CLI in isolated home directories and verifies byte-for-byte copies for Codex, Claude Code, and Cursor.

This is interface conformance, not model evaluation. External harnesses may evaluate task success, command count, cleanup, mutation disclosure, and result interpretation without adding model-specific behavior to xprobe.