@skyramp/mcp 0.3.3 → 0.3.5

package/build/utils/AnalysisStateManager.d.ts

@@ -7,13 +7,45 @@ import type { CandidateUiPage } from "./uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
+import type { VideoRecord } from "../types/TestExecution.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
+/**
+ * Record the run's tests repo without ever clearing a known value.
+ *
+ * The tests repo is a RUN-scoped fact, but analyze_changes is called once per
+ * repository and only the PRIMARY call carries `testsRepoDir` — a related
+ * repo's call omits it. An unconditional set therefore wiped the primary's
+ * value on the second call of every multi-repo run, and by report time the
+ * tests repo was unknown: a UI test generated there looked unbacked by any
+ * working tree and the agent demoted it out of newTestsCreated (SKYR-4204,
+ * run 32536569467). Callers that mean to clear it use setTestsRepoDir.
+ */
+export declare function rememberTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
-/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+/** Filename of the run-scoped analysis state file under `runArtifactDir()`.
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
  *  which LOOKS there cannot drift apart. */
 export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
+/**
+ * Directory holding this run's Skyramp artifacts — the state file, and the report written
+ * beside it (SKYR-4147) — or undefined outside a run.
+ *
+ * `RUNNER_TEMP` is a fresh directory per CI job, and the caller and this server can each
+ * work it out from the environment on their own. So neither has to tell the other where
+ * the run's files live, and the path never passes through the model.
+ *
+ * The GitHub Action is the only caller customers run, and GitHub sets `RUNNER_TEMP` for
+ * it; the eval harness sets it itself. Nothing customers run is on another CI system, so
+ * the GitHub-specific name is only a naming problem — it does not break anything today.
+ * If a caller on another CI system is added, rename this then, or let it read that
+ * system's variable. Do not add a second variable for a caller that does not exist.
+ *
+ * Kept in one place for the same reason `RUN_STATE_FILE_NAME` is: the directory used to be
+ * written out at three call sites, so only the filename was safe from the three copies
+ * drifting apart. testbot keeps its matching copy in one place too, in `skyrampTempDir()`.
+ */
+export declare function runArtifactDir(): string | undefined;
 export declare function setActiveRunStatePath(stateFilePath: string): void;
 export declare function getActiveRunStatePath(): string | undefined;
 /** Reset the run anchor — for tests, and as a safety hook between runs. */
@@ -25,7 +57,7 @@ export declare function clearActiveRunStatePath(): void;
  * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
  * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
  * path is still deterministic in CI: the StateManager constructor above roots
- * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * "analysis" state under `runArtifactDir()`. Falling back to that covers
  * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
  * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
  *
@@ -166,6 +198,20 @@ export interface UnifiedAnalysisState {
      *  which computes every value in-process; skyramp_submit_report merges it into
      *  the report's `reuse` field. Never supplied by the LLM. */
     reuseOutcomes?: Record<string, ReuseRecord>;
+    /**
+     * SKYR-4156. Recorded video per executed browser test, keyed by test-file
+     * BASENAME (the same key `reuseOutcomes` uses, so matching needs no path
+     * normalization). Written in-process by skyramp_execute_test — the only place
+     * the path is known — and merged into the report's `testResults[].videoPath` by
+     * skyramp_submit_report. Never supplied by the LLM.
+     *
+     * Deliberately separate from `existingTests[].executionBefore/After`: those only
+     * exist for tests skyramp_analyze_changes discovered, so a NEWLY generated spec
+     * has nowhere to record into — which is exactly how one run recorded three videos
+     * and referenced none of them. Last write wins, so a retried execution replaces
+     * the earlier attempt's now-stale directory.
+     */
+    executionVideos?: Record<string, VideoRecord>;
 }
 /**
  * State file metadata

package/build/utils/AnalysisStateManager.js

@@ -19,6 +19,21 @@ let _testsRepoDir;
 export function setTestsRepoDir(dir) {
     _testsRepoDir = dir;
 }
+/**
+ * Record the run's tests repo without ever clearing a known value.
+ *
+ * The tests repo is a RUN-scoped fact, but analyze_changes is called once per
+ * repository and only the PRIMARY call carries `testsRepoDir` — a related
+ * repo's call omits it. An unconditional set therefore wiped the primary's
+ * value on the second call of every multi-repo run, and by report time the
+ * tests repo was unknown: a UI test generated there looked unbacked by any
+ * working tree and the agent demoted it out of newTestsCreated (SKYR-4204,
+ * run 32536569467). Callers that mean to clear it use setTestsRepoDir.
+ */
+export function rememberTestsRepoDir(dir) {
+    if (dir)
+        _testsRepoDir = dir;
+}
 export function getTestsRepoDir() {
     return _testsRepoDir;
 }
@@ -35,10 +50,32 @@ export function getTestsRepoDir() {
  * Single-repo / standalone calls (no `repository`) never set or read this.
  */
 let _activeRunStatePath;
-/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+/** Filename of the run-scoped analysis state file under `runArtifactDir()`.
  *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
  *  which LOOKS there cannot drift apart. */
 export const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
+/**
+ * Directory holding this run's Skyramp artifacts — the state file, and the report written
+ * beside it (SKYR-4147) — or undefined outside a run.
+ *
+ * `RUNNER_TEMP` is a fresh directory per CI job, and the caller and this server can each
+ * work it out from the environment on their own. So neither has to tell the other where
+ * the run's files live, and the path never passes through the model.
+ *
+ * The GitHub Action is the only caller customers run, and GitHub sets `RUNNER_TEMP` for
+ * it; the eval harness sets it itself. Nothing customers run is on another CI system, so
+ * the GitHub-specific name is only a naming problem — it does not break anything today.
+ * If a caller on another CI system is added, rename this then, or let it read that
+ * system's variable. Do not add a second variable for a caller that does not exist.
+ *
+ * Kept in one place for the same reason `RUN_STATE_FILE_NAME` is: the directory used to be
+ * written out at three call sites, so only the filename was safe from the three copies
+ * drifting apart. testbot keeps its matching copy in one place too, in `skyrampTempDir()`.
+ */
+export function runArtifactDir() {
+    const runnerTemp = process.env.RUNNER_TEMP?.trim();
+    return runnerTemp ? path.join(runnerTemp, "skyramp") : undefined;
+}
 export function setActiveRunStatePath(stateFilePath) {
     _activeRunStatePath = stateFilePath;
 }
@@ -56,7 +93,7 @@ export function clearActiveRunStatePath() {
  * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
  * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
  * path is still deterministic in CI: the StateManager constructor above roots
- * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * "analysis" state under `runArtifactDir()`. Falling back to that covers
  * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
  * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
  *
@@ -70,8 +107,9 @@ export function resolveRunStatePath(explicitPath) {
     const anchored = getActiveRunStatePath();
     if (anchored)
         return anchored;
-    if (process.env.RUNNER_TEMP) {
-        return path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+    const runDir = runArtifactDir();
+    if (runDir) {
+        return path.join(runDir, RUN_STATE_FILE_NAME);
     }
     return undefined;
 }
@@ -169,17 +207,15 @@ export class StateManager {
     constructor(stateType = "analysis", sessionId, stateDir, stateFilePath) {
         this.stateType = stateType;
         this.sessionId = sessionId || crypto.randomUUID();
+        const runDir = stateType === "analysis" ? runArtifactDir() : undefined;
         if (stateFilePath) {
             this.stateFile = stateFilePath;
         }
-        else if (stateType === "analysis" && process.env.RUNNER_TEMP) {
-            // In CI (testbot action), RUNNER_TEMP is a job-isolated dir that both the
-            // action and this tool can independently derive — no LLM input needed.
-            // TODO: interim step — remove this branch when stateFile and summaryOutputFile are merged
-            // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
-            // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
-            // summaryOutputFile which is already testbot-controlled and CI-agnostic.
-            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+        else if (runDir) {
+            // In CI, the run directory is fresh per job and the caller and this tool each work
+            // it out from the environment — no LLM input needed. It is also where
+            // skyramp_submit_report writes the report (SKYR-4147).
+            this.stateFile = path.join(runDir, RUN_STATE_FILE_NAME);
         }
         else {
             const baseDir = stateDir || os.tmpdir();
@@ -435,7 +471,7 @@ export class StateManager {
      * @returns Number of files deleted
      */
     static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
-        const baseDir = stateDir || (process.env.RUNNER_TEMP ? path.join(process.env.RUNNER_TEMP, "skyramp") : os.tmpdir());
+        const baseDir = stateDir || runArtifactDir() || os.tmpdir();
         const files = await fs.promises.readdir(baseDir).catch(() => []);
         const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])

package/build/utils/reportLanguage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Report-language enforcement for `skyramp_submit_report` (SKYR-4185).
+ *
+ * The report language (SKYR-4023) reaches the MCP server only as a testbot
+ * prompt/resource arg, and the instruction to write free-text report fields in
+ * that language is prose the agent sometimes ignores — the customer-visible
+ * failure this module exists to close. The prompt render captures the language
+ * here (same server process serves the prompt and later handles the report
+ * tool), and the report tool rejects submissions whose free-text fields leaked
+ * back into English.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served
+ * (local/IDE flows, or a run broken enough that the agent has no instructions),
+ * the language stays unset and no report is ever falsely rejected.
+ */
+/** Capture the report language at prompt-serve time. Last render wins:
+ *  `undefined` clears any earlier capture, so a long-lived server (IDE use)
+ *  that renders a ja prompt and later an English/argless one disarms the
+ *  guardrail rather than falsely rejecting a legitimately-English report. */
+export declare function setReportLanguage(language: string | undefined): void;
+export declare function getReportLanguage(): string | undefined;
+/** Test isolation only — module state persists across tests in one process. */
+export declare function resetReportLanguage(): void;
+export declare function isEnforcedReportLanguage(language: string | undefined): language is string;
+/** English display name for a language code, falling back to the raw code when
+ *  Intl rejects it as a structurally invalid tag (e.g. "ja_JP") — the code is
+ *  ultimately caller-supplied, and a name lookup must never throw. */
+export declare function reportLanguageDisplayName(language: string): string;
+export interface ReportTextField {
+    /** Where the text came from, in the tool's input terms (e.g. "testResults[2].details"). */
+    path: string;
+    text: string;
+}
+/** Field paths whose text leaked English under an enforced report language.
+ *  Empty for non-enforced languages — unknown languages are skipped, never guessed. */
+export declare function findLanguageViolations(fields: ReportTextField[], language: string): string[];
+/** Field paths in the deliberately-lenient band: some English prose, but under
+ *  the rejection threshold (i.e. exactly one stray word at the current
+ *  MIN_PROSE_WORDS of 2). These SHIP — the guardrail accepts them so a lone
+ *  technical word ("flaky", "timeout") never blocks a report. Counted into the
+ *  submit-report analytics event so the residual leak rate is measurable
+ *  before anyone tightens the threshold. */
+export declare function findLanguageNearMisses(fields: ReportTextField[], language: string): string[];

package/build/utils/reportLanguage.js

@@ -0,0 +1,125 @@
+/**
+ * Report-language enforcement for `skyramp_submit_report` (SKYR-4185).
+ *
+ * The report language (SKYR-4023) reaches the MCP server only as a testbot
+ * prompt/resource arg, and the instruction to write free-text report fields in
+ * that language is prose the agent sometimes ignores — the customer-visible
+ * failure this module exists to close. The prompt render captures the language
+ * here (same server process serves the prompt and later handles the report
+ * tool), and the report tool rejects submissions whose free-text fields leaked
+ * back into English.
+ *
+ * Capture is fail-open by design: if the testbot prompt was never served
+ * (local/IDE flows, or a run broken enough that the agent has no instructions),
+ * the language stays unset and no report is ever falsely rejected.
+ */
+let sessionReportLanguage;
+/** Capture the report language at prompt-serve time. Last render wins:
+ *  `undefined` clears any earlier capture, so a long-lived server (IDE use)
+ *  that renders a ja prompt and later an English/argless one disarms the
+ *  guardrail rather than falsely rejecting a legitimately-English report. */
+export function setReportLanguage(language) {
+    sessionReportLanguage = language;
+}
+export function getReportLanguage() {
+    return sessionReportLanguage;
+}
+/** Test isolation only — module state persists across tests in one process. */
+export function resetReportLanguage() {
+    sessionReportLanguage = undefined;
+}
+// Languages the guardrail can enforce: detection is script-presence-based, so a
+// language is enforceable only when its expected script is disjoint from Latin.
+// English ('en') is deliberately absent — it is the default, not enforced.
+// A Map, not a plain object: the key is caller-supplied, and object indexing
+// would resolve prototype keys ("toString") to inherited members whose later
+// .test() call crashes the tool.
+const TARGET_SCRIPTS = new Map([
+    // Hiragana, Katakana (incl. halfwidth), CJK ideographs (incl. ext A / compat).
+    ["ja", /[぀-ヿ㐀-䶿一-鿿豈-﫿ｦ-ﾟ]/],
+]);
+export function isEnforcedReportLanguage(language) {
+    return language !== undefined && TARGET_SCRIPTS.has(language);
+}
+/** English display name for a language code, falling back to the raw code when
+ *  Intl rejects it as a structurally invalid tag (e.g. "ja_JP") — the code is
+ *  ultimately caller-supplied, and a name lookup must never throw. */
+export function reportLanguageDisplayName(language) {
+    try {
+        return new Intl.DisplayNames(["en"], { type: "language" }).of(language) ?? language;
+    }
+    catch {
+        return language;
+    }
+}
+// Tokens that are legitimate untranslated content in any report language — the
+// prompt's own "do NOT translate" list: enum values, HTTP verbs, test types.
+const UNTRANSLATED_WORDS = new Set([
+    // Exact enum values only. NOT "passed"/"failed" — those are ordinary English
+    // prose and are exactly what leaks in pytest summaries ("1 passed in 0.88s",
+    // "failed: count was 13"; see letsramp/api-insight#215).
+    "pass", "fail", "skipped", "error", "unknown",
+    "critical", "high", "medium", "low",
+    "get", "post", "put", "patch", "delete", "head", "options",
+    "ui", "e2e", "api", "contract", "integration", "smoke", "fuzz", "load", "mock",
+    "http", "https", "json", "yaml", "ok",
+]);
+/** A field must contain at least this many plain English prose words (after the
+ *  stripping below) to be flagged — so identifier-and-timing-only details like
+ *  "10.8s, products_contract_test.py" stay legal, and one stray word ("flaky")
+ *  never rejects a report. Two is deliberate: the shortest real leak observed
+ *  ("1 passed in 0.88s", api-insight#215) has exactly two prose words. */
+const MIN_PROSE_WORDS = 2;
+/** Count the plain English prose words in `text`, or return 0 when the target
+ *  language's script is present (the field is compliant regardless of any
+ *  English around it). Backticked spans, file names/paths, identifiers
+ *  (snake_case/camelCase/ALL-CAPS), digit-bearing tokens, and the prompt's
+ *  untranslated vocabulary are all excluded from the count. */
+function countProseWords(text, script) {
+    if (script.test(text))
+        return 0;
+    const withoutCode = text.replace(/`[^`]*`/g, " ");
+    let proseWords = 0;
+    for (const raw of withoutCode.split(/\s+/)) {
+        const token = raw.replace(/^[^A-Za-z0-9]+/, "").replace(/[^A-Za-z0-9]+$/, "");
+        // Pure alphabetic words only: anything with digits or interior punctuation
+        // (paths, file names, snake_case, versions, "10.8s") is not prose.
+        if (token.length < 2 || !/^[A-Za-z]+$/.test(token))
+            continue;
+        if (/[a-z][A-Z]/.test(token))
+            continue; // camelCase identifier
+        if (token === token.toUpperCase())
+            continue; // acronym / enum shout (GET, FAILED)
+        if (UNTRANSLATED_WORDS.has(token.toLowerCase()))
+            continue;
+        proseWords++;
+    }
+    return proseWords;
+}
+/** Field paths whose text leaked English under an enforced report language.
+ *  Empty for non-enforced languages — unknown languages are skipped, never guessed. */
+export function findLanguageViolations(fields, language) {
+    const script = TARGET_SCRIPTS.get(language);
+    if (!script)
+        return [];
+    return fields
+        .filter((f) => countProseWords(f.text, script) >= MIN_PROSE_WORDS)
+        .map((f) => f.path);
+}
+/** Field paths in the deliberately-lenient band: some English prose, but under
+ *  the rejection threshold (i.e. exactly one stray word at the current
+ *  MIN_PROSE_WORDS of 2). These SHIP — the guardrail accepts them so a lone
+ *  technical word ("flaky", "timeout") never blocks a report. Counted into the
+ *  submit-report analytics event so the residual leak rate is measurable
+ *  before anyone tightens the threshold. */
+export function findLanguageNearMisses(fields, language) {
+    const script = TARGET_SCRIPTS.get(language);
+    if (!script)
+        return [];
+    return fields
+        .filter((f) => {
+        const words = countProseWords(f.text, script);
+        return words > 0 && words < MIN_PROSE_WORDS;
+    })
+        .map((f) => f.path);
+}

package/build/utils/reportVerification.d.ts

@@ -14,6 +14,16 @@ import { DriftAction } from "../types/TestAnalysis.js";
  * `--untracked-files=all` lists each untracked file individually (otherwise git
  * collapses a brand-new directory to "dir/", which would defeat path matching).
  */
+/**
+ * Union of listChangedFiles over every tree a run legitimately writes to —
+ * the primary checkout, the tests-repo checkout (testRepoPath), and related
+ * repos (SKYR-4204 reopen: the backing check scanned only the primary, so a
+ * UI test generated into the tests-repo checkout was rejected as unbacked and
+ * demoted out of the report — run 32510028428). Undefined and duplicate roots
+ * are skipped; a root where git fails (missing dir, not a repo) contributes
+ * nothing rather than failing the whole check.
+ */
+export declare function listChangedFilesAcross(roots: Array<string | undefined>): Promise<string[]>;
 export declare function listChangedFiles(repoRoot: string): Promise<string[]>;
 export interface UnbackedClaimsInput {
     /** Absolute path of the primary repo checkout the report pertains to. */

package/build/utils/reportVerification.js

@@ -19,6 +19,37 @@ const execFileAsync = promisify(execFile);
  * `--untracked-files=all` lists each untracked file individually (otherwise git
  * collapses a brand-new directory to "dir/", which would defeat path matching).
  */
+/**
+ * Union of listChangedFiles over every tree a run legitimately writes to —
+ * the primary checkout, the tests-repo checkout (testRepoPath), and related
+ * repos (SKYR-4204 reopen: the backing check scanned only the primary, so a
+ * UI test generated into the tests-repo checkout was rejected as unbacked and
+ * demoted out of the report — run 32510028428). Undefined and duplicate roots
+ * are skipped; a root where git fails (missing dir, not a repo) contributes
+ * nothing rather than failing the whole check.
+ */
+export async function listChangedFilesAcross(roots) {
+    const seenRoots = new Set();
+    const seenFiles = new Set();
+    const files = [];
+    for (const root of roots) {
+        if (!root || seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        try {
+            for (const f of await listChangedFiles(root)) {
+                if (seenFiles.has(f))
+                    continue;
+                seenFiles.add(f);
+                files.push(f);
+            }
+        }
+        catch {
+            // Non-git or missing tree — nothing to contribute.
+        }
+    }
+    return files;
+}
 export async function listChangedFiles(repoRoot) {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: repoRoot });
     const files = [];

package/build/utils/scenarioDrafting.js

@@ -905,7 +905,13 @@ export function draftResponseShapeScenarios(hopEndpoints, byFile, addedFieldsByF
                 : `reflects the change made in ${fileName}`;
             const nameSuffix = addedFields.length > 0 ? addedFields[0] : "response-change";
             scenarios.push({
-                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}`,
+                // The endpoint path is part of the name because one file can reach
+                // several GETs and neither the resource token (from the file) nor the
+                // suffix (a field name, or the constant "response-change" when the hunk
+                // yields none) varies between them. Two same-named candidates are
+                // merged by name in registerTestPlanTool, so a collision here loses a
+                // scenario outright rather than showing up as a duplicate.
+                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}-${slugify(ep.path)}`,
                 description: `Verify GET ${ep.path} response ${fieldsPhrase}.`,
                 category: "breaking_change",
                 priority: "high",

package/build/utils/skyrampMdContent.d.ts

@@ -2,4 +2,4 @@
  * Skill content for skyramp.md — installed at auto-discovery paths: ~/.claude/skills/skyramp/SKILLS.md, ~/.cursor/skills/skyramp/SKILLS.md, ~/.github/skills/skyramp.md
  * Follows the SKILL.md specification: https://agentskills.io/what-are-skills#the-skill-md-file
  */
-export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run a single Skyramp-generated test file. Required: `workspacePath`, `language`, `testType`, `testFile`. Optional: `stateFile` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `summaryOutputFile`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";
+export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run a single Skyramp-generated test file. Required: `workspacePath`, `language`, `testType`, `testFile`. Optional: `stateFile` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";

package/build/utils/skyrampMdContent.js

@@ -58,7 +58,7 @@ Prefer invoking a prompt over manually chaining tools — prompts run the full w
 
 - **\`skyramp_trace_prompt\`** — Trace collection setup and execution.
 - **\`skyramp_test_health_analysis\`** — Full maintenance flow (discover → drift → health → actions).
-- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`summaryOutputFile\`, \`repositoryPath\`.
+- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`repositoryPath\`.
 
 ---
 

package/build/utils/urlPath.d.ts

@@ -0,0 +1,37 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export declare function pathFromEndpointURL(endpointURL: string | undefined): string | undefined;
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export declare function deriveBasePath(baseURL: string | undefined): string;

package/build/utils/urlPath.js

@@ -0,0 +1,55 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export function pathFromEndpointURL(endpointURL) {
+    if (!endpointURL)
+        return undefined;
+    try {
+        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+    }
+    catch {
+        return endpointURL.startsWith("/") ? endpointURL : undefined;
+    }
+}
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export function deriveBasePath(baseURL) {
+    if (!baseURL)
+        return "";
+    try {
+        return new URL(baseURL).pathname.replace(/\/$/, "");
+    }
+    catch {
+        return "";
+    }
+}

package/build/utils/utils.d.ts

@@ -1,6 +1,51 @@
 import { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function readDiffFile(diffFilePath: string | undefined): string | undefined;
 export declare function toolError(message: string): CallToolResult;
+/**
+ * Build a successful tool result whose payload is delivered on BOTH MCP result
+ * channels — `structuredContent` and `content[]` — carrying the identical text.
+ * The counterpart to `toolError` for any tool that returns a large text payload.
+ *
+ * Use this for every non-error return of such a tool, and declare a matching
+ * `outputSchema`. Two separate failures make that necessary:
+ *
+ * 1. A result with no `structuredContent` is persisted by the agent harness as a
+ *    pretty-printed `.json` spill, which buries the payload inside an escaped
+ *    JSON string. Coming through `structuredContent` instead lands it as a
+ *    `.txt`. Measured on eval runs 32227152533 and 32283973875: the extension
+ *    follows the result shape, with no exceptions either way.
+ *
+ *    The extension is not cosmetic: it changes how the payload TOKENIZES. The
+ *    reader refuses any spill over 25,000 tokens, and pretty-printed JSON with
+ *    escaped quotes and newlines costs 2-3x the tokens of the same bytes in raw
+ *    form. Measured on one payload either way: 141.2KB of `.json` counted 72,318
+ *    tokens and was refused, while the same result at 142.0KB of `.txt` was read
+ *    back in full. A second: 54,085 tokens as `.json`, 26,950 as `.txt`.
+ *
+ *    So the shape raises the deliverable size ceiling by roughly 3x, but does not
+ *    remove it. That second payload still missed the cap by 1,950 tokens, and
+ *    `skyramp_actions` results of 178-621KB are 45,598-158,997 tokens even as
+ *    `.txt` — the agent then falls back to slicing the file with `head -c`. The
+ *    check covers the whole file, so a `limit:` on the read cannot evade it.
+ *    Payloads that big have to shrink (SKYR-4188 and its sibling); this shape is
+ *    what lets a shrunk payload actually arrive.
+ *
+ * 2. Each agent CLI testbot supports reads a different channel and none falls
+ *    back to the other: Claude Code takes `structuredContent` and drops
+ *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
+ *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
+ *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,
+ *    which would deliver the payload twice there. Trimming either channel
+ *    silently starves a client.
+ *
+ * Declaring the outputSchema also obliges every non-error return to come through
+ * here: the SDK rejects a successful result without `structuredContent`
+ * ("has an output schema but no structured content was provided"). Error results
+ * are exempt — that check returns early on `isError` — so they keep using
+ * `toolError`.
+ */
+export declare function dualChannelResult(structuredContent: Record<string, string>): CallToolResult;
 /**
  * Does `candidate` (an LLM- or caller-supplied name/path) identify `fullPath` (a known,
  * absolute test file path)? Exact match first, then a real path-segment boundary match