@testchimp/cli 0.1.29 → 0.1.31

package/README.md

@@ -42,10 +42,17 @@ testchimp get-requirement-coverage --branch-name main --help
 testchimp create-user-story --platform-file-path plans/stories/foo.md --title "Checkout"
 testchimp list-screen-states --json-input '{}'
 testchimp upsert-screen-states --json-input '{"screenStates":[{"screen":"Checkout","states":["empty","filled"]}]}'
+testchimp list-perf-runs --testchimp-id TC-123 --kind JOURNEY --limit 20
+testchimp get-perf-run --run-id 01ABC --include-raw
+testchimp promote-perf-baseline --run-id 01ABC --env-class CI
+testchimp compare-perf-to-baseline --run-id 01ABC --max-p95-regression-percent 10
+testchimp list-related-perf-tests --scenario-titles "Checkout,Refund"
+testchimp list-api-operation-interactions --operation-id 01XYZ --interaction-type REAL --limit 100
 ```
 
 - **stdout:** API response JSON.
 - **stderr:** progress for `provision-ephemeral-environment-and-wait` (“still waiting…” polls).
+- **performance gate:** `compare-perf-to-baseline` still prints its JSON response but exits nonzero when `regressed` is `true` (top-level or under `comparison`).
 - **Flags:** default for each subcommand; **`--json-input '<json>'`** or **`--json-input @file.json`** merges over flags (JSON wins on conflicts). Use JSON for nested bodies (e.g. TrueCoverage scopes).
 
 ## Migration from `testchimp-mcp-client`

package/dist/cli/program.js

@@ -8,6 +8,13 @@ import { TOOL_DEFINITIONS } from "../core/tools.js";
 import { resolveGitHeadSha } from "../core/gitSha.js";
 import { PACKAGE_VERSION } from "../core/version.js";
 export { PACKAGE_VERSION };
+/** True when ComparePerfToBaselineResponse (or a flat PerfComparison) reports a regression. */
+function isPerfComparisonRegressed(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return false;
+    const body = parsed;
+    return body.regressed === true || body.comparison?.regressed === true;
+}
 function parseRecordTypesCsv(raw) {
     return String(raw)
         .split(",")
@@ -23,9 +30,11 @@ function parseRecordTypesCsv(raw) {
             return "smart_test";
         if (s === "manual")
             return "manual";
+        if (s === "perf" || s === "perftest" || s === "perf_test")
+            return "perf_test";
         return s;
     })
-        .filter((v) => v === "smart_test" || v === "manual");
+        .filter((v) => v === "smart_test" || v === "manual" || v === "perf_test");
 }
 function parseJsonInput(raw) {
     if (raw == null || raw.trim() === "")
@@ -55,7 +64,9 @@ function addAgentTraceabilityOptions(cmd) {
         .option("--actor-type <type>", "LOCAL_AGENT | CLOUD_AGENT")
         .option("--user-id <id>", "Optional user id")
         .option("--branch-name <name>", "Git branch name")
-        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)");
+        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
+        .option("--skill-version <semver>", "TestChimp skill version from SKILL.md frontmatter")
+        .option("--cli-version <semver>", "CLI version (defaults to this package version)");
 }
 function collectAgentTraceabilityFlags(opts) {
     const body = {};
@@ -77,6 +88,10 @@ function collectAgentTraceabilityFlags(opts) {
         body.branchName = String(opts.branchName).trim();
     if (opts.agentModel)
         body.agentModel = String(opts.agentModel).trim();
+    if (opts.skillVersion)
+        body.skillVersion = String(opts.skillVersion).trim();
+    if (opts.cliVersion)
+        body.cliVersion = String(opts.cliVersion).trim();
     return body;
 }
 function stderrProgress(msg) {
@@ -126,8 +141,9 @@ export function buildCliProgram() {
         .option("--environment <s>")
         .option("--branch-name <s>")
         .option("--platform <web|ios|android>")
-        .option("--record-types <csv>", "coverage sources: smart_test,manual (aliases: automated,smarttest)")
+        .option("--record-types <csv>", "coverage sources: smart_test,manual,perf_test (aliases: automated,smarttest,perf)")
         .option("--include-manual", "include manual session coverage in addition to automated SmartTests")
+        .option("--include-perf", "include PERF_TEST journey coverage in addition to automated SmartTests")
         .option("--manual-only", "manual-only coverage (no automated)")
         .option("--lifecycle-statuses <csv>", "scenario lifecycle allowlist (e.g. ready or draft,ready)")
         .option("--limit <n>", "top N gaps after filter+rank into rankedScenarios (max 200)", (v) => parseInt(v, 10))
@@ -154,6 +170,9 @@ export function buildCliProgram() {
             recordTypes = Array.from(new Set([...(recordTypes ?? ["smart_test"]), "manual"]));
         if (opts.manualOnly)
             recordTypes = ["manual"];
+        if (opts.includePerf) {
+            recordTypes = Array.from(new Set([...(recordTypes ?? ["smart_test"]), "perf_test"]));
+        }
         if (recordTypes && recordTypes.length > 0)
             body.recordTypes = recordTypes;
         if (opts.lifecycleStatuses) {
@@ -1119,6 +1138,8 @@ export function buildCliProgram() {
         .option("--user-id <id>", "Optional user id for traceability")
         .option("--branch-name <name>", "Git branch")
         .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
+        .option("--skill-version <semver>", "TestChimp skill version from SKILL.md frontmatter")
+        .option("--cli-version <semver>", "CLI version (defaults to this package version)")
         .requiredOption("--entity-type <type>", "USER_STORY|SCENARIO|SMART_TEST|POLICY|ISSUE|TEST_EXECUTION|TEST_INVOCATION_BATCH|EXPLORATION|EVENT|WORKFLOW")
         .option("--entity-identity <ordinal>", "Project-scoped ordinal id (mutually exclusive with --test-json)")
         .option("--test-json <json>", "TestLocator JSON (folderPath/fileName/testSuite/testName)")
@@ -1144,6 +1165,10 @@ export function buildCliProgram() {
             body.branchName = String(opts.branchName);
         if (opts.agentModel)
             body.agentModel = String(opts.agentModel).trim();
+        if (opts.skillVersion)
+            body.skillVersion = String(opts.skillVersion).trim();
+        if (opts.cliVersion)
+            body.cliVersion = String(opts.cliVersion).trim();
         if (opts.entityIdentity)
             body.entityIdentity = String(opts.entityIdentity);
         if (opts.testJson)
@@ -1290,6 +1315,174 @@ export function buildCliProgram() {
         const merged = mergeBodies(body, opts.jsonInput);
         console.log(await runTool("get-api-operation-detail", merged, { postMcp }));
     });
+    program
+        .command("list-perf-runs")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-perf-runs").description)
+        .addOption(jsonInputOption())
+        .option("--testchimp-id <id>")
+        .option("--kind <kind>", "JOURNEY | COMPOSITE")
+        .option("--branch-name <name>")
+        .option("--profile <name>")
+        .option("--dataset <name>")
+        .option("--llm-mode <mode>")
+        .option("--environment <name>")
+        .option("--limit <n>", "Maximum results", (v) => Number(v))
+        .option("--offset <n>", "Pagination offset", (v) => Number(v))
+        .action(async (opts) => {
+        const body = {};
+        if (opts.testchimpId)
+            body.testchimpId = String(opts.testchimpId);
+        if (opts.kind)
+            body.kind = String(opts.kind);
+        if (opts.branchName)
+            body.branchName = String(opts.branchName);
+        if (opts.profile)
+            body.profile = String(opts.profile);
+        if (opts.dataset)
+            body.dataset = String(opts.dataset);
+        if (opts.llmMode)
+            body.llmMode = String(opts.llmMode);
+        if (opts.environment)
+            body.environment = String(opts.environment);
+        if (opts.limit != null)
+            body.limit = opts.limit;
+        if (opts.offset != null)
+            body.offset = opts.offset;
+        console.log(await runTool("list-perf-runs", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("get-perf-run")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-perf-run").description)
+        .addOption(jsonInputOption())
+        .option("--run-id <id>")
+        .option("--include-raw", "Include the raw performance payload")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.runId)
+            body.runId = String(opts.runId);
+        if (opts.includeRaw)
+            body.includeRaw = true;
+        console.log(await runTool("get-perf-run", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("list-perf-baselines")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-perf-baselines").description)
+        .addOption(jsonInputOption())
+        .option("--testchimp-id <id>")
+        .option("--limit <n>", "Maximum results", (v) => Number(v))
+        .option("--offset <n>", "Pagination offset", (v) => Number(v))
+        .action(async (opts) => {
+        const body = {};
+        if (opts.testchimpId)
+            body.testchimpId = String(opts.testchimpId);
+        if (opts.limit != null)
+            body.limit = opts.limit;
+        if (opts.offset != null)
+            body.offset = opts.offset;
+        console.log(await runTool("list-perf-baselines", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    addAgentTraceabilityOptions(program
+        .command("promote-perf-baseline")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "promote-perf-baseline").description)
+        .addOption(jsonInputOption())
+        .option("--run-id <id>")
+        .option("--env-class <name>")).action(async (opts) => {
+        const body = {
+            ...collectAgentTraceabilityFlags(opts),
+        };
+        if (opts.runId)
+            body.runId = String(opts.runId);
+        if (opts.envClass)
+            body.envClass = String(opts.envClass);
+        console.log(await runTool("promote-perf-baseline", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("compare-perf-to-baseline")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "compare-perf-to-baseline").description)
+        .addOption(jsonInputOption())
+        .option("--run-id <id>")
+        .option("--testchimp-id <id>")
+        .option("--profile <name>")
+        .option("--dataset <name>")
+        .option("--llm-mode <mode>")
+        .option("--environment <name>")
+        .option("--env-class <name>", "Baseline environment class (required)")
+        .option("--max-p95-regression-percent <n>", "Allowed p95 regression percent", (v) => Number(v))
+        .option("--max-fail-rate-increase <n>", "Allowed fail-rate increase", (v) => Number(v))
+        .action(async (opts) => {
+        const body = {};
+        if (opts.runId)
+            body.runId = String(opts.runId);
+        if (opts.testchimpId)
+            body.testchimpId = String(opts.testchimpId);
+        if (opts.profile)
+            body.profile = String(opts.profile);
+        if (opts.dataset)
+            body.dataset = String(opts.dataset);
+        if (opts.llmMode)
+            body.llmMode = String(opts.llmMode);
+        if (opts.environment)
+            body.environment = String(opts.environment);
+        if (opts.envClass)
+            body.envClass = String(opts.envClass);
+        if (opts.maxP95RegressionPercent != null) {
+            body.maxP95RegressionPercent = opts.maxP95RegressionPercent;
+        }
+        if (opts.maxFailRateIncrease != null)
+            body.maxFailRateIncrease = opts.maxFailRateIncrease;
+        const out = await runTool("compare-perf-to-baseline", mergeBodies(body, opts.jsonInput), { postMcp });
+        // Always print response JSON; gate CI on regressed after stdout flush.
+        console.log(out);
+        try {
+            if (isPerfComparisonRegressed(JSON.parse(out)))
+                process.exitCode = 1;
+        }
+        catch {
+            /* non-JSON responses still printed; leave exit 0 unless runTool threw */
+        }
+    });
+    program
+        .command("list-related-perf-tests")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-related-perf-tests").description)
+        .addOption(jsonInputOption())
+        .option("--scenario-titles <csv>", "Comma-separated scenario titles")
+        .option("--testchimp-ids <csv>", "Comma-separated TestChimp ids")
+        .option("--no-include-composites", "Exclude COMPOSITE tests")
+        .option("--limit <n>", "Maximum results (max 100)", (v) => Number(v))
+        .action(async (opts) => {
+        const body = {
+            includeComposites: opts.includeComposites,
+        };
+        if (opts.scenarioTitles) {
+            body.scenarioTitles = String(opts.scenarioTitles).split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        if (opts.testchimpIds) {
+            body.testchimpIds = String(opts.testchimpIds).split(",").map((s) => s.trim()).filter(Boolean);
+        }
+        if (opts.limit != null)
+            body.limit = opts.limit;
+        console.log(await runTool("list-related-perf-tests", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("list-api-operation-interactions")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-api-operation-interactions").description)
+        .addOption(jsonInputOption())
+        .option("--test-id <id>")
+        .option("--operation-id <id>")
+        .option("--interaction-type <type>", "REAL | MOCKED", "REAL")
+        .option("--limit <n>", "Maximum results (max 100)", (v) => Number(v))
+        .action(async (opts) => {
+        const body = {
+            interactionType: opts.interactionType,
+        };
+        if (opts.testId)
+            body.testId = String(opts.testId);
+        if (opts.operationId)
+            body.operationId = String(opts.operationId);
+        if (opts.limit != null)
+            body.limit = opts.limit;
+        console.log(await runTool("list-api-operation-interactions", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
     program.on("--help", () => {
         /* default */
     });

package/dist/core/agentTraceability.d.ts

@@ -9,9 +9,23 @@ export type AgentTraceabilityFields = {
     userId?: string;
     branchName?: string;
     agentModel?: string;
+    skillVersion?: string;
+    cliVersion?: string;
     /** Nested form (wins over flat when both present and non-empty). */
     agentTraceability?: Record<string, unknown>;
 };
+/**
+ * Resolve skill / CLI versions for traceability payloads.
+ * CLI version defaults to this package's version; skill version from flag/env only.
+ */
+export declare function resolveToolchainVersions(a: {
+    skillVersion?: string;
+    cliVersion?: string;
+    nested?: Record<string, unknown> | null;
+}): {
+    skillVersion?: string;
+    cliVersion?: string;
+};
 /**
  * Build camelCase AgentActionTraceability for MCP JSON bodies.
  * Returns undefined unless the caller supplied explicit traceability intent
@@ -19,7 +33,7 @@ export type AgentTraceabilityFields = {
  * For Activity/timeline attachment the server also requires workflowExecutionId
  * (stable Plan ULID for the whole run) — omit it and the mutation still succeeds
  * but no workflow_executions / Activity row is recorded (server does not auto-mint).
- * Auto-fills gitSha / agentModel / userId only after the workflowId bar is met.
+ * Auto-fills gitSha / agentModel / userId / cliVersion only after the workflowId bar is met.
  * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
  */
 export declare function buildAgentTraceabilityPayload(a: AgentTraceabilityFields): Record<string, unknown> | undefined;

package/dist/core/agentTraceability.js

@@ -1,4 +1,5 @@
 import { resolveGitHeadSha } from "./gitSha.js";
+import { PACKAGE_VERSION } from "./version.js";
 function nonEmptyString(v) {
     if (v == null)
         return undefined;
@@ -24,6 +25,10 @@ function hasExplicitTraceabilityIntent(a) {
         return true;
     if (nonEmptyString(a.agentModel))
         return true;
+    if (nonEmptyString(a.skillVersion))
+        return true;
+    if (nonEmptyString(a.cliVersion))
+        return true;
     if (a.agentTraceability && typeof a.agentTraceability === "object") {
         return Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null);
     }
@@ -39,6 +44,20 @@ function normalizeActorType(raw) {
         return "LOCAL_AGENT";
     return undefined;
 }
+/**
+ * Resolve skill / CLI versions for traceability payloads.
+ * CLI version defaults to this package's version; skill version from flag/env only.
+ */
+export function resolveToolchainVersions(a) {
+    const skillVersion = nonEmptyString(a.nested?.skillVersion) ??
+        nonEmptyString(a.skillVersion) ??
+        nonEmptyString(process.env.TESTCHIMP_SKILL_VERSION);
+    const cliVersion = nonEmptyString(a.nested?.cliVersion) ??
+        nonEmptyString(a.cliVersion) ??
+        nonEmptyString(process.env.TESTCHIMP_CLI_VERSION) ??
+        PACKAGE_VERSION;
+    return { skillVersion, cliVersion };
+}
 /**
  * Build camelCase AgentActionTraceability for MCP JSON bodies.
  * Returns undefined unless the caller supplied explicit traceability intent
@@ -46,7 +65,7 @@ function normalizeActorType(raw) {
  * For Activity/timeline attachment the server also requires workflowExecutionId
  * (stable Plan ULID for the whole run) — omit it and the mutation still succeeds
  * but no workflow_executions / Activity row is recorded (server does not auto-mint).
- * Auto-fills gitSha / agentModel / userId only after the workflowId bar is met.
+ * Auto-fills gitSha / agentModel / userId / cliVersion only after the workflowId bar is met.
  * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
  */
 export function buildAgentTraceabilityPayload(a) {
@@ -72,6 +91,11 @@ export function buildAgentTraceabilityPayload(a) {
     const agentModel = nonEmptyString(nested?.agentModel) ??
         nonEmptyString(a.agentModel) ??
         nonEmptyString(process.env.TESTCHIMP_AGENT_MODEL);
+    const { skillVersion, cliVersion } = resolveToolchainVersions({
+        skillVersion: a.skillVersion,
+        cliVersion: a.cliVersion,
+        nested,
+    });
     // Server requires workflow_id for inline mutation Activity — do not send orphan payloads.
     if (!workflowId) {
         return undefined;
@@ -94,5 +118,9 @@ export function buildAgentTraceabilityPayload(a) {
         out.branchName = branchName;
     if (agentModel)
         out.agentModel = agentModel;
+    if (skillVersion)
+        out.skillVersion = skillVersion;
+    if (cliVersion)
+        out.cliVersion = cliVersion;
     return out;
 }

package/dist/core/schemas.d.ts

@@ -25,8 +25,10 @@ export declare const listCoverageInput: z.ZodObject<{
     recordTypes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         smart_test: "smart_test";
         manual: "manual";
+        perf_test: "perf_test";
         SMART_TEST: "SMART_TEST";
         MANUAL: "MANUAL";
+        PERF_TEST: "PERF_TEST";
     }>>>;
     scenarioLifecycleStatuses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     limit: z.ZodOptional<z.ZodNumber>;
@@ -105,6 +107,8 @@ export declare const agentActionTraceabilitySchema: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** Flat + nested traceability fields shared by create/update MCP tools. */
 export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
@@ -122,6 +126,8 @@ export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -137,6 +143,8 @@ export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createUserStoryInput: z.ZodObject<{
@@ -156,6 +164,8 @@ export declare const createUserStoryInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -171,6 +181,8 @@ export declare const createUserStoryInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createTestScenarioInput: z.ZodObject<{
@@ -191,6 +203,8 @@ export declare const createTestScenarioInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -206,6 +220,8 @@ export declare const createTestScenarioInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const updatePlanMarkdownInput: z.ZodObject<{
@@ -224,6 +240,8 @@ export declare const updatePlanMarkdownInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -239,6 +257,8 @@ export declare const updatePlanMarkdownInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const markPlanItemsImplementationDoneInput: z.ZodObject<{
@@ -297,6 +317,8 @@ export declare const updateIssueStatusInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -312,6 +334,8 @@ export declare const updateIssueStatusInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createIssueInput: z.ZodObject<{
@@ -393,6 +417,8 @@ export declare const createIssueInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -408,6 +434,8 @@ export declare const createIssueInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const emptyInput: z.ZodObject<{}, z.core.$strip>;
@@ -1364,6 +1392,8 @@ export declare const reportAgentActionInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     traceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -1379,6 +1409,8 @@ export declare const reportAgentActionInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     entityType: z.ZodEnum<{
         SMART_TEST: "SMART_TEST";
@@ -1465,3 +1497,95 @@ export declare const getApiOperationDetailInput: z.ZodObject<{
     includeManual: z.ZodOptional<z.ZodBoolean>;
     includeRemoved: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+/** Performance run kind persisted by the Phase 2 performance API. */
+export declare const perfRunKindSchema: z.ZodEnum<{
+    JOURNEY: "JOURNEY";
+    COMPOSITE: "COMPOSITE";
+}>;
+export declare const listPerfRunsInput: z.ZodObject<{
+    testchimpId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        JOURNEY: "JOURNEY";
+        COMPOSITE: "COMPOSITE";
+    }>>;
+    branchName: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodOptional<z.ZodString>;
+    llmMode: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const getPerfRunInput: z.ZodObject<{
+    runId: z.ZodString;
+    includeRaw: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const listPerfBaselinesInput: z.ZodObject<{
+    testchimpId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const promotePerfBaselineInput: z.ZodObject<{
+    runId: z.ZodString;
+    envClass: z.ZodString;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export declare const comparePerfToBaselineInput: z.ZodObject<{
+    runId: z.ZodOptional<z.ZodString>;
+    testchimpId: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodOptional<z.ZodString>;
+    llmMode: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    envClass: z.ZodString;
+    maxP95RegressionPercent: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    maxFailRateIncrease: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const listRelatedPerfTestsInput: z.ZodObject<{
+    scenarioTitles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    testchimpIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    includeComposites: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const listApiOperationInteractionsInput: z.ZodObject<{
+    testId: z.ZodOptional<z.ZodString>;
+    operationId: z.ZodOptional<z.ZodString>;
+    interactionType: z.ZodDefault<z.ZodEnum<{
+        REAL: "REAL";
+        MOCKED: "MOCKED";
+    }>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;

package/dist/core/schemas.js

@@ -6,7 +6,14 @@ export const scopeSchema = z
 })
     .optional();
 const executionPlatformSchema = z.enum(["web", "ios", "android"]);
-const requirementCoverageRecordTypeSchema = z.enum(["smart_test", "manual", "SMART_TEST", "MANUAL"]);
+const requirementCoverageRecordTypeSchema = z.enum([
+    "smart_test",
+    "manual",
+    "perf_test",
+    "SMART_TEST",
+    "MANUAL",
+    "PERF_TEST",
+]);
 export const executionJobDimensionFilterSchema = z.object({
     dimension: z.string().min(1),
     values: z.array(z.string()).min(1),
@@ -23,7 +30,8 @@ export const listCoverageInput = z.object({
      * Which coverage sources to include.
      *
      * Omit for legacy default: SMART_TEST only.
-     * When provided, send proto enum names ("SMART_TEST", "MANUAL") or CLI-friendly aliases ("smart_test", "manual").
+     * When provided, send proto enum names ("SMART_TEST", "MANUAL", "PERF_TEST")
+     * or CLI-friendly aliases ("smart_test", "manual", "perf_test").
      */
     recordTypes: z.array(requirementCoverageRecordTypeSchema).optional(),
     /** Allowlist of scenario lifecycle statuses (e.g. ["ready"] or ["draft","ready"]). Empty/omit = no status filter. */
@@ -82,6 +90,8 @@ export const agentActionTraceabilitySchema = z
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
 })
     .strict();
 /** Flat + nested traceability fields shared by create/update MCP tools. */
@@ -95,6 +105,8 @@ export const agentTraceabilityFieldsSchema = z.object({
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
     agentTraceability: agentActionTraceabilitySchema.optional(),
 });
 export const createUserStoryInput = z.object({
@@ -687,6 +699,8 @@ export const reportAgentActionInput = z
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
     traceability: agentActionTraceabilitySchema.optional(),
     entityType: agentActionEntityTypeSchema,
     /** Project-scoped ordinal id (or explicitly provided execution/batch id). Mutually exclusive with `test`. */
@@ -842,3 +856,81 @@ export const getApiOperationDetailInput = z
             "or --root-file-path/--service-key with --http-method and --path-template",
     });
 });
+/** Performance run kind persisted by the Phase 2 performance API. */
+export const perfRunKindSchema = z.enum(["JOURNEY", "COMPOSITE"]);
+export const listPerfRunsInput = z.object({
+    testchimpId: z.string().min(1).optional(),
+    kind: perfRunKindSchema.optional(),
+    branchName: z.string().min(1).optional(),
+    profile: z.string().min(1).optional(),
+    dataset: z.string().min(1).optional(),
+    llmMode: z.string().min(1).optional(),
+    environment: z.string().min(1).optional(),
+    limit: z.coerce.number().int().positive().max(100).optional(),
+    offset: z.coerce.number().int().nonnegative().optional(),
+});
+export const getPerfRunInput = z.object({
+    runId: z.string().min(1),
+    includeRaw: z.boolean().optional(),
+});
+export const listPerfBaselinesInput = z.object({
+    testchimpId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().positive().max(100).optional(),
+    offset: z.coerce.number().int().nonnegative().optional(),
+});
+export const promotePerfBaselineInput = z
+    .object({
+    runId: z.string().min(1),
+    envClass: z.string().min(1),
+})
+    .merge(agentTraceabilityFieldsSchema);
+export const comparePerfToBaselineInput = z
+    .object({
+    runId: z.string().min(1).optional(),
+    testchimpId: z.string().min(1).optional(),
+    profile: z.string().min(1).optional(),
+    dataset: z.string().min(1).optional(),
+    llmMode: z.string().min(1).optional(),
+    environment: z.string().min(1).optional(),
+    envClass: z.string().min(1),
+    maxP95RegressionPercent: z.coerce.number().nonnegative().optional(),
+    maxFailRateIncrease: z.coerce.number().nonnegative().optional(),
+})
+    .superRefine((v, ctx) => {
+    if (!(v.runId ?? "").trim() && !(v.testchimpId ?? "").trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide runId or testchimpId",
+        });
+    }
+});
+export const listRelatedPerfTestsInput = z
+    .object({
+    scenarioTitles: z.array(z.string().min(1)).min(1).optional(),
+    testchimpIds: z.array(z.string().min(1)).min(1).optional(),
+    includeComposites: z.boolean().default(true),
+    limit: z.coerce.number().int().positive().max(100).optional(),
+})
+    .superRefine((v, ctx) => {
+    if (!v.scenarioTitles?.length && !v.testchimpIds?.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide scenarioTitles and/or testchimpIds",
+        });
+    }
+});
+export const listApiOperationInteractionsInput = z
+    .object({
+    testId: z.string().min(1).optional(),
+    operationId: z.string().min(1).optional(),
+    interactionType: z.enum(["REAL", "MOCKED"]).default("REAL"),
+    limit: z.coerce.number().int().positive().max(100).optional(),
+})
+    .superRefine((v, ctx) => {
+    if (!(v.testId ?? "").trim() && !(v.operationId ?? "").trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide testId and/or operationId",
+        });
+    }
+});

package/dist/core/tools.js

@@ -2,7 +2,7 @@ import { normalizeScope } from "./normalize.js";
 import { runProvisionEphemeralEnvironmentAndWait } from "./ephemeralWait.js";
 import * as S from "./schemas.js";
 import { resolveGitHeadSha } from "./gitSha.js";
-import { buildAgentTraceabilityPayload } from "./agentTraceability.js";
+import { buildAgentTraceabilityPayload, resolveToolchainVersions } from "./agentTraceability.js";
 function platformToProtoEnum(platform) {
     switch (platform) {
         case "ios":
@@ -51,6 +51,8 @@ function listCoverageBody(args) {
                 return "MANUAL";
             if (raw === "smart_test")
                 return "SMART_TEST";
+            if (raw === "perf_test")
+                return "PERF_TEST";
             return raw;
         });
         body.recordTypes = normalized;
@@ -1040,7 +1042,15 @@ export const TOOL_DEFINITIONS = [
                 body.userId = process.env.TESTCHIMP_USER_ID;
             if (a.branchName)
                 body.branchName = a.branchName;
-            // Nested traceability wins for agentModel; only fill from flat/env when nested omits it.
+            // Nested traceability wins for agentModel / skillVersion / cliVersion;
+            // fill from flat/env/package when nested omits them.
+            const { skillVersion, cliVersion } = resolveToolchainVersions({
+                skillVersion: a.skillVersion,
+                cliVersion: a.cliVersion,
+                nested: a.traceability && typeof a.traceability === "object"
+                    ? a.traceability
+                    : null,
+            });
             if (a.traceability && typeof a.traceability === "object") {
                 const nested = { ...a.traceability };
                 const nestedModel = nested.agentModel != null && String(nested.agentModel).trim() !== ""
@@ -1053,12 +1063,23 @@ export const TOOL_DEFINITIONS = [
                 else if (flatModel) {
                     nested.agentModel = flatModel;
                 }
+                if (skillVersion)
+                    nested.skillVersion = skillVersion;
+                if (cliVersion)
+                    nested.cliVersion = cliVersion;
                 body.traceability = nested;
             }
             else {
                 const model = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
-                if (model) {
-                    body.traceability = { agentModel: model };
+                const nested = {};
+                if (model)
+                    nested.agentModel = model;
+                if (skillVersion)
+                    nested.skillVersion = skillVersion;
+                if (cliVersion)
+                    nested.cliVersion = cliVersion;
+                if (Object.keys(nested).length > 0) {
+                    body.traceability = nested;
                 }
             }
             if (a.test) {
@@ -1222,6 +1243,143 @@ export const TOOL_DEFINITIONS = [
             return postMcp("/api/mcp/get_api_operation_detail", body);
         },
     },
+    {
+        kebab: "list-perf-runs",
+        description: "List performance runs, optionally filtered by TestChimp id, JOURNEY/COMPOSITE kind, branch, profile, dataset, LLM mode, or environment.",
+        inputSchema: S.listPerfRunsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.testchimpId)
+                body.testchimpId = a.testchimpId;
+            if (a.kind)
+                body.kind = a.kind;
+            if (a.branchName)
+                body.branchName = a.branchName;
+            if (a.profile)
+                body.profile = a.profile;
+            if (a.dataset)
+                body.dataset = a.dataset;
+            if (a.llmMode)
+                body.llmMode = a.llmMode;
+            if (a.environment)
+                body.environment = a.environment;
+            if (a.limit != null)
+                body.limit = a.limit;
+            if (a.offset != null)
+                body.offset = a.offset;
+            return postMcp("/api/mcp/list_perf_runs", body);
+        },
+    },
+    {
+        kebab: "get-perf-run",
+        description: "Fetch one performance run by runId; set includeRaw to include its raw payload.",
+        inputSchema: S.getPerfRunInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_perf_run", {
+                runId: a.runId,
+                ...(a.includeRaw != null ? { includeRaw: a.includeRaw } : {}),
+            });
+        },
+    },
+    {
+        kebab: "list-perf-baselines",
+        description: "List promoted performance baselines, optionally filtered by TestChimp id.",
+        inputSchema: S.listPerfBaselinesInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.testchimpId)
+                body.testchimpId = a.testchimpId;
+            if (a.limit != null)
+                body.limit = a.limit;
+            if (a.offset != null)
+                body.offset = a.offset;
+            return postMcp("/api/mcp/list_perf_baselines", body);
+        },
+    },
+    {
+        kebab: "promote-perf-baseline",
+        description: "Promote a performance run as the baseline for an environment class. Optional agent traceability records the mutation.",
+        inputSchema: S.promotePerfBaselineInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {
+                runId: a.runId,
+                envClass: a.envClass,
+            };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/promote_perf_baseline", body);
+        },
+    },
+    {
+        kebab: "compare-perf-to-baseline",
+        description: "Compare a run (runId) or filtered target (testchimpId plus optional dimensions) to its promoted baseline. " +
+            "envClass is required. Optional thresholds override max p95 regression percent and maximum fail-rate increase.",
+        inputSchema: S.comparePerfToBaselineInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.runId)
+                body.runId = a.runId;
+            if (a.testchimpId)
+                body.testchimpId = a.testchimpId;
+            if (a.profile)
+                body.profile = a.profile;
+            if (a.dataset)
+                body.dataset = a.dataset;
+            if (a.llmMode)
+                body.llmMode = a.llmMode;
+            if (a.environment)
+                body.environment = a.environment;
+            body.envClass = a.envClass;
+            if (a.maxP95RegressionPercent != null)
+                body.maxP95RegressionPercent = a.maxP95RegressionPercent;
+            if (a.maxFailRateIncrease != null)
+                body.maxFailRateIncrease = a.maxFailRateIncrease;
+            return postMcp("/api/mcp/compare_perf_to_baseline", body);
+        },
+    },
+    {
+        kebab: "list-related-perf-tests",
+        description: "Find JOURNEY and, by default, COMPOSITE performance tests related to scenario titles and/or TestChimp ids.",
+        inputSchema: S.listRelatedPerfTestsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {
+                includeComposites: a.includeComposites,
+            };
+            if (a.scenarioTitles?.length)
+                body.scenarioTitles = a.scenarioTitles;
+            if (a.testchimpIds?.length)
+                body.testchimpIds = a.testchimpIds;
+            if (a.limit != null)
+                body.limit = a.limit;
+            return postMcp("/api/mcp/list_related_perf_tests", body);
+        },
+    },
+    {
+        kebab: "list-api-operation-interactions",
+        description: "List recorded API operation interactions. Requires testId and/or operationId. " +
+            "Defaults to REAL interactions; limit is capped at 100.",
+        inputSchema: S.listApiOperationInteractionsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {
+                interactionType: a.interactionType,
+            };
+            if (a.testId)
+                body.testId = a.testId;
+            if (a.operationId)
+                body.operationId = a.operationId;
+            if (a.limit != null)
+                body.limit = a.limit;
+            return postMcp("/api/mcp/list_api_operation_interactions", body);
+        },
+    },
 ];
 const TOOL_BY_KEBAB = new Map(TOOL_DEFINITIONS.map((t) => [t.kebab, t]));
 export function getToolDefinition(kebab) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",