@skyramp/mcp 0.4.2-rc.1 → 0.4.2-rc.2

package/build/types/ReuseOutcome.d.ts

@@ -154,9 +154,10 @@ export interface HelperReuseOutcome {
      *  TODO: remove `helpersImported` once the testbot renderer reads this field. The
      *  two carry one fact; the count stays only because testbot#349 reads it today. */
     helperNames: string[];
-    /** Inline request calls in OTHER Skyramp-generated tests beside this one that a
-     *  helper in `utilsFile` already wraps — reuse that was available and not taken.
-     *  Omitted at zero. Informational, like {@link ReuseOutcome.missedReuse}. */
+    /** Inline request calls (integration) or inline action sequences (UI) in OTHER
+     *  Skyramp-generated tests beside this one that a helper in `utilsFile` already
+     *  wraps — reuse that was available and not taken. Omitted at zero. Informational,
+     *  like {@link ReuseOutcome.missedReuse}. */
     siblingInlineCallSites?: number;
     /** Whether the delivered utils file holds the shared-helper invariants: one helper
      *  per method+path, status-code-only assertions, method+resource names — with

package/build/types/TestExecution.d.ts

@@ -41,8 +41,8 @@ export interface TestExecutionRecord {
     executedAt: string;
     duration: number;
     /** The process's real exit code, or -1 when none was produced — a timeout
-     *  kill or a thrown error before the process exited (an Error-status run;
-     *  see TestExecutionService's timeout and catch paths). Never a real exit
+     *  kill or a spawn error before the process exited (an Error-status run;
+     *  see runTest in skyramp_execute_test). Never a real exit
      *  code, which is always 0-255. */
     exitCode: number;
     errors: string[];

package/build/types/TestTypes.d.ts

@@ -7,6 +7,9 @@ export declare enum ProgrammingLanguage {
     JAVASCRIPT = "javascript",
     JAVA = "java"
 }
+/** The languages skyramp_execute_test accepts, as prose for a prompt. Rendered from
+ *  the enum so the text and the gate that reads it cannot disagree. */
+export declare function runnableLanguagesText(): string;
 export declare enum TestType {
     SMOKE = "smoke",
     FUZZ = "fuzz",

package/build/types/TestTypes.js

@@ -9,6 +9,12 @@ export var ProgrammingLanguage;
     ProgrammingLanguage["JAVASCRIPT"] = "javascript";
     ProgrammingLanguage["JAVA"] = "java";
 })(ProgrammingLanguage || (ProgrammingLanguage = {}));
+/** The languages skyramp_execute_test accepts, as prose for a prompt. Rendered from
+ *  the enum so the text and the gate that reads it cannot disagree. */
+export function runnableLanguagesText() {
+    const names = Object.values(ProgrammingLanguage);
+    return `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
+}
 export var TestType;
 (function (TestType) {
     TestType["SMOKE"] = "smoke";

package/build/utils/AnalysisStateManager.d.ts

@@ -5,7 +5,6 @@ import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
 import type { RemovedUiElement } from "./removedUiElements.js";
-import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
 import type { TestExecutionRecord, VideoRecord } from "../types/TestExecution.js";
 import type { RepoCheckout } from "./reportVerification.js";
 import type { Plan } from "../recommendation/registerPlan.js";
@@ -209,12 +208,6 @@ export interface UnifiedAnalysisState {
     /** Maintenance actions applied via skyramp_actions — skyramp_submit_report derives
      *  testMaintenance from this. */
     maintenanceVerdicts?: MaintenanceActionCore[];
-    /**
-     * External (repo-owned) test runs recorded by skyramp_run_existing_tests, one
-     * record per confirm/verify invocation. Drift analysis and the report fold in
-     * CONFIRMED failures from here instead of guessing. Absent until the tool runs.
-     */
-    externalTestResults?: ExternalTestRunRecord[];
     /** POM code-reuse outcome per generated UI spec, keyed by test-file BASENAME
      *  (what `newTestsCreated[].fileName` carries). Written by skyramp_reuse_code,
      *  which computes every value in-process; skyramp_submit_report merges it into

package/build/utils/AnalysisStateManager.js

@@ -603,7 +603,7 @@ export class StateManager {
                     updatedAt: new Date().toISOString(),
                     // Preserve the prior step when the caller omits one (matches
                     // repositoryPath/repository/createdAt above) so a metadata-agnostic
-                    // write — e.g. persistExternalRun appending externalTestResults —
+                    // write — e.g. skyramp_execute_test recording an execution —
                     // does not wipe the pipeline step recorded by an earlier phase.
                     step: options?.step ?? existingMetadata?.step,
                 },

package/build/utils/connectionErrors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one place a connection-level failure is spelled. Three callers match these
+ * and each reads them for its own purpose — a transient MCP error, an executor
+ * retry, and the drift prompt's "the application was unreachable" verdict — so
+ * they are kept here rather than written out three times and drifting apart.
+ */
+/** Refused, reset, or the socket dropped mid-request. */
+export declare const CONNECTION_DROPPED: RegExp;
+/** The application never answered in time. */
+export declare const CONNECTION_TIMED_OUT: RegExp;

package/build/utils/connectionErrors.js

@@ -0,0 +1,10 @@
+/**
+ * The one place a connection-level failure is spelled. Three callers match these
+ * and each reads them for its own purpose — a transient MCP error, an executor
+ * retry, and the drift prompt's "the application was unreachable" verdict — so
+ * they are kept here rather than written out three times and drifting apart.
+ */
+/** Refused, reset, or the socket dropped mid-request. */
+export const CONNECTION_DROPPED = /\bECONNREFUSED\b|\bECONNRESET\b|\bconnection refused\b|\bconnection reset\b|\bsocket hang up\b/i;
+/** The application never answered in time. */
+export const CONNECTION_TIMED_OUT = /\bETIMEDOUT\b|\bDEADLINE_EXCEEDED\b|\bconnect(?:ion)? timed? ?out\b/i;

package/build/utils/language-helper.js

@@ -1,9 +1,13 @@
+import { SKYRAMP_SDK_VERSION } from "./skyrampSdkVersion.js";
+/** The SDK spec the generated JavaScript and TypeScript tests need. */
+const npmSdkSpec = `@skyramp/skyramp@${SKYRAMP_SDK_VERSION}`;
 const pythonDependencyGuidance = `
 Persist each missing approved package in the development manifest:
 - Use \`uv add --dev <package>\` for a project using \`[dependency-groups].dev\`.
 - Use \`poetry add --group dev <package>\` for a Poetry project.
 - Add it to \`requirements-dev.txt\`, then run \`python3 -m pip install -r requirements-dev.txt\`.
 If no Python manifest exists at the test project root, create requirements-dev.txt and seed it with the missing approved package. Do not create it alongside pyproject.toml.
+If the repository commits poetry.lock or uv.lock, update it in the same change. Use \`poetry lock\` or \`uv lock\`; both keep the versions already locked.
 `;
 const javascriptDependencyGuidance = `
 Inspect package.json before installing anything.
@@ -11,19 +15,36 @@ Inspect package.json before installing anything.
 - If no JavaScript/TypeScript manifest exists at the test project root, create package.json with only \`{ "devDependencies": {} }\` before adding the missing approved package.
 - If an approved package is missing, add it as a devDependency with the repository's package manager. The npm equivalent is \`npm install --save-dev --legacy-peer-deps <package>\`.
 - Never add, upgrade, or downgrade Playwright or @playwright/test when either is already declared.
+- If the repository commits a lockfile, update it in the same change. Use \`npm install --package-lock-only\`, \`yarn install --mode update-lockfile\`, \`pnpm install --lockfile-only\`, or \`bun install --lockfile-only\` for the package manager the repository uses.
+- Do not change \`allowScripts\`, \`pnpm.onlyBuiltDependencies\`, or \`trustedDependencies\`.
 `;
 const javaDependencyGuidance = `
 Inspect existing Java build signals before adding a dependency. Use an existing manifest when present.
 - For Maven wrapper or settings signals, create a minimal pom.xml only when it is absent, and add approved dependencies with <scope>test</scope>.
 - For Gradle wrapper or settings signals, create the matching build.gradle or build.gradle.kts only when it is absent, and use testImplementation or testRuntimeOnly.
 - Do not introduce a competing build system. If neither build system is identified, keep the standalone runner instead of inventing one.
+- If the repository commits gradle.lockfile, update it in the same change with the repository's Gradle wrapper (\`./gradlew dependencies --write-locks\`), or \`gradle\` only when there is no wrapper.
 `;
 function getJavascriptSteps(extension) {
-    return `${javascriptDependencyGuidance}
+    return `${javascriptDependencyGuidance}${sdkDeclaration("javascript")}
 # Execute the test file
 npx playwright test <test-file>.spec.${extension} --reporter=list
 `;
 }
+/** How to declare the Skyramp SDK, per language. Kept out of the shared
+ *  dependency guidance because that guidance is also returned for `mock`, and
+ *  a mock is deployed rather than run as a test — it needs no SDK. */
+const SDK_DECLARATION = {
+    python: "Declare `skyramp` in the same development manifest.",
+    javascript: `If @skyramp/skyramp is not already declared, add ${npmSdkSpec} as a devDependency. If it is declared, leave its version alone and report the mismatch if the verifier refuses it.`,
+    java: "Declare `dev.skyramp:skyramp-library` with test scope. An existing manifest resolves the version through its own dependency management; a manifest you created has none, so give a concrete version there.",
+};
+/** The SDK line for a language, or nothing when the language has none. */
+function sdkDeclaration(language) {
+    const key = language === "typescript" ? "javascript" : language;
+    const line = SDK_DECLARATION[key];
+    return line ? `\n${line}\n` : "";
+}
 export function getLanguageSteps(params) {
     const { language, testType } = params;
     if (testType === "mock") {
@@ -50,7 +71,7 @@ node <mock-file>.js
     let steps = "";
     switch (language) {
         case "python":
-            steps = pythonDependencyGuidance;
+            steps = pythonDependencyGuidance + sdkDeclaration("python");
             // e2e and ui tests
             if (testType === "e2e" || testType === "ui") {
                 steps += `
@@ -80,7 +101,7 @@ python3 -m robot <robot-file>.robot
             steps = getJavascriptSteps("ts");
             break;
         case "java":
-            steps = `${javaDependencyGuidance}
+            steps = `${javaDependencyGuidance}${sdkDeclaration("java")}
 # Prerequisites
 # Compile the test file
 javac -cp "./lib/*" -d target <test-file>.java

package/build/utils/progress.d.ts

@@ -11,6 +11,6 @@ export type ProgressReporter = (progress: number, total: number, message: string
  * otherwise silently no-ops.
  *
  * Consolidates the identical closure that previously lived inline in multiple
- * progress-emitting tools (analyzeChanges, executeSkyrampTest, startTraceCollection).
+ * progress-emitting tools (analyzeChanges, startTraceCollection).
  */
 export declare function makeProgressReporter(extra: RequestHandlerExtra<ServerRequest, ServerNotification>): ProgressReporter;

package/build/utils/progress.js

@@ -4,7 +4,7 @@
  * otherwise silently no-ops.
  *
  * Consolidates the identical closure that previously lived inline in multiple
- * progress-emitting tools (analyzeChanges, executeSkyrampTest, startTraceCollection).
+ * progress-emitting tools (analyzeChanges, startTraceCollection).
  */
 export function makeProgressReporter(extra) {
     return async (progress, total, message) => {

package/build/utils/rebaselineSnapshots.d.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
  *
  * Bare filename only: no path separators, and no commas or whitespace, because the
  * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
- * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * test runtime, where `a,b.png` would read as two baselines. One definition shared by
  * both tools so they can never drift apart.
  */
 export declare const REBASELINE_SNAPSHOT_NAME_RE: RegExp;

package/build/utils/rebaselineSnapshots.js

@@ -7,7 +7,7 @@ import { z } from "zod";
  *
  * Bare filename only: no path separators, and no commas or whitespace, because the
  * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
- * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * test runtime, where `a,b.png` would read as two baselines. One definition shared by
  * both tools so they can never drift apart.
  */
 export const REBASELINE_SNAPSHOT_NAME_RE = /^[^/\\,\s]+\.png$/i;
@@ -22,21 +22,11 @@ export function baselineStem(name) {
     return path.basename(name).replace(/\.png$/i, "");
 }
 /**
- * Playwright's default snapshot layout, which is what the executor produces: the
- * baseline for `<stem>.png` lives in `<spec>-snapshots/` as `<stem>-<project>-<platform>.png`
- * (or `<stem>-<platform>.png` with no project, or `<stem>.png` under a custom
- * `snapshotPathTemplate`). Safe to assume here because TestExecutionService mounts
- * its own generated Playwright config over any the repo carries, so a repo cannot
- * relocate its snapshots out from under this rule.
- *
- * The executor's generated config declares no `projects`, but runner.sh passes
- * `--browser=chromium`, so Playwright names the implicit project "chromium" and a
- * refresh writes `<stem>-chromium-linux.png` (observed end to end on demoshop).
- * Baselines the Skyramp executor produced therefore round-trip exactly. A baseline
- * a repo's own CI wrote under another project name (`<stem>-Desktop-Chrome-linux.png`)
- * is a different file: the executor's refresh adds its own and leaves that one as
- * it was — the tool reports what it rewrote, and the repo's own suite is out of
- * scope for skyramp_execute_test (which never runs it).
+ * Playwright's default snapshot layout: the baseline for `<stem>.png` lives in
+ * `<spec>-snapshots/` as `<stem>-<project>-<platform>.png` (or `<stem>-<platform>.png`
+ * with no project, or `<stem>.png` under a custom `snapshotPathTemplate`). A repo
+ * config that sets another `snapshotPathTemplate` moves its baselines out from under
+ * this rule; the tool then reports them as not refreshed rather than claim a refresh.
  *
  * Anchored so a longer baseline cannot vouch for a shorter one: `page-001-wide-chromium-linux.png`
  * belongs to `page-001-wide.png` and must not satisfy a claim on `page-001.png`.

package/build/utils/reuseRouting.d.ts

@@ -1,3 +1,13 @@
 export declare function isBrowserTestType(testType?: string): boolean;
 export declare function isModularizeFirstTarget(testType?: string, language?: string): boolean;
 export declare function isPomAwareTarget(language: string, framework?: string, testType?: string): boolean;
+/**
+ * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
+ * for both. `api` for integration, whatever the flags (the rule is stated in API
+ * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
+ * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
+ * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * advisory would describe reuse the feature could not have taken. The prompt renders
+ * the rule and STEP 5c on it; the verify pass runs the scan on it.
+ */
+export declare function inlineCallSiteFamily(testType?: string, language?: string): "api" | "browser" | undefined;

package/build/utils/reuseRouting.js

@@ -52,3 +52,18 @@ export function isPomAwareTarget(language, framework, testType) {
     return ((lang === "typescript" || lang === "javascript") &&
         framework?.toLowerCase() === "playwright");
 }
+/**
+ * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
+ * for both. `api` for integration, whatever the flags (the rule is stated in API
+ * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
+ * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
+ * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * advisory would describe reuse the feature could not have taken. The prompt renders
+ * the rule and STEP 5c on it; the verify pass runs the scan on it.
+ */
+export function inlineCallSiteFamily(testType, language) {
+    if (testType?.toLowerCase() === "integration")
+        return "api";
+    // A modularize-first target that is not integration is the seeded UI flow.
+    return isModularizeFirstTarget(testType, language) ? "browser" : undefined;
+}

package/build/utils/runContextGauge.d.ts

@@ -0,0 +1,27 @@
+export interface ContextReading {
+    /** Tokens the last request actually carried: fresh input, cache reads and cache
+     *  writes together. This is the number that fills the window. */
+    tokens: number;
+    window: number;
+    /** `tokens` as a whole percentage of `window`, for printing. */
+    percent: number;
+}
+/** This run's context usage, or undefined when it cannot be read.
+ *
+ *  Undefined is ORDINARY, not an error: a local or IDE run has no `RUNNER_TEMP`
+ *  and no agent log, and an agent whose CLI writes no NDJSON log never produces
+ *  one. Every caller prints nothing and carries on. */
+export declare function readRunContext(): ContextReading | undefined;
+/** One sentence naming the measurement, for a refusal that has already told the
+ *  agent not to stop on a context it believes it is short of. Empty when there is
+ *  no reading — the refusal reads correctly without it.
+ *
+ *  It states the reading and nothing else. It does not say the run has room: the
+ *  reading can be 95% and the refusal still stands on its own grounds, and a
+ *  sentence that argued headroom would be wrong exactly when it mattered most.
+ *
+ *  CARRIES ITS OWN TRAILING SPACE, so a caller concatenates it unconditionally
+ *  and an empty reading leaves no gap. */
+export declare function contextGaugeSentence(): string;
+/** Test seam: drop the per-run window cache. */
+export declare function resetRunContextGaugeForTests(): void;

package/build/utils/runContextGauge.js

@@ -0,0 +1,181 @@
+import * as fs from "fs";
+import * as path from "path";
+import { runArtifactDir } from "./AnalysisStateManager.js";
+import { logger } from "./logger.js";
+/** What the agent's own context usage is, read from the agent log the Testbot
+ *  action streams beside this run's artifacts.
+ *
+ *  WHY THIS EXISTS. Two runs cut planned work citing a "context budget" they
+ *  could not measure: one declared itself out at 357k of a 1M window, the next at
+ *  457k, and neither had a warning from anywhere. The agent has no reading of its
+ *  own context and the prompt cannot give it one, so a refusal that says "do not
+ *  stop because you believe you are low on context" is arguing with a feeling.
+ *  This turns it into a number the server can put in the refusal.
+ *
+ *  It is a MEASUREMENT, never a limit. Nothing here refuses anything or decides
+ *  anything; the callers do, on grounds that hold without it, and every one of
+ *  them still works when this returns undefined. */
+/** The Testbot action streams the agent CLI's `--output-format stream-json` here,
+ *  live, in the same directory this server already writes `testbot-result.txt` to. */
+const AGENT_LOG_NAME = "agent-log.ndjson";
+/** Enough of the tail to hold the last assistant record with a usage block. These
+ *  records carry whole tool results, so a fixed slice can miss one — 512 KiB covers
+ *  it with room, and a miss costs a sentence, not a refusal. */
+const TAIL_BYTES = 512 * 1024;
+/** Enough of the head to hold the `init` record, which is the FIRST line. */
+const HEAD_BYTES = 64 * 1024;
+/** Windows for models with no `[1m]`-style suffix on the init record, first
+ *  match wins. Opus 5 and Sonnet 5 are 1M by default — reading them as
+ *  200k is the same error the suffix rule below guards against, one level up.
+ *  Bedrock prefixes the id (`us.anthropic.claude-opus-5`), so these match
+ *  anywhere in the string rather than at the start. */
+const MODEL_WINDOWS = [
+    [/claude-(opus|sonnet)-5/i, 1_000_000],
+    [/claude-haiku/i, 200_000],
+];
+/** A model none of the above names. ERRS LARGE on purpose: too small a window
+ *  overstates the percentage, which is how this file manufactures the scarcity
+ *  it exists to disprove, and no caller acts on the number — the refusals stand
+ *  on their own grounds. Too large only understates it. */
+const DEFAULT_CONTEXT_WINDOW = 1_000_000;
+function windowForModel(model) {
+    for (const [pattern, window] of MODEL_WINDOWS) {
+        if (pattern.test(model))
+            return window;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Window and log path do not change within a run, so they are read once and kept
+ *  against the directory they came from — a new run is a new directory. The token
+ *  count is NOT cached: it is the thing that moves. */
+let cachedForDir;
+let cachedWindow;
+function readSlice(file, bytes, fromEnd) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, bytes);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, fromEnd ? size - length : 0);
+        return buffer.toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The context window this run's model was started with.
+ *
+ *  READ FROM THE INIT RECORD, not from the per-message model. The two disagree:
+ *  `message.model` is `claude-opus-5` while the init record says
+ *  `claude-opus-5[1m]`, and taking the former turns 46% of a 1M window into 228%
+ *  of a 200k one — a gauge that manufactures the panic it exists to prevent. */
+function contextWindowFrom(head) {
+    for (const line of head.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            // The head slice ends mid-record on any file longer than it. Only the first
+            // line matters here and it is whole.
+            break;
+        }
+        if (record.type !== "system" || record.subtype !== "init")
+            break;
+        const model = typeof record.model === "string" ? record.model : "";
+        const suffix = /\[(\d+)(m|k)\]/i.exec(model);
+        if (!suffix)
+            return windowForModel(model);
+        const scale = suffix[2].toLowerCase() === "m" ? 1_000_000 : 1_000;
+        return Number(suffix[1]) * scale;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Tokens on the most recent assistant request in the log, or undefined.
+ *
+ *  Walks BACKWARDS to the first record that has them: the tail ends with the turn
+ *  that called the tool now running, and every later line is that turn's own
+ *  output. Records with no usage — heartbeats, progress, tool results — are
+ *  skipped, so the reading is always the newest real request. */
+function tokensFrom(tail) {
+    const lines = tail.split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index].trim();
+        // Cheap rejects first: this runs over a few thousand lines per call.
+        if (!line.startsWith("{") || !line.includes('"usage"'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const usage = record.message?.usage;
+        if (!usage)
+            continue;
+        const count = (key) => typeof usage[key] === "number" ? usage[key] : 0;
+        const tokens = count("input_tokens") +
+            count("cache_read_input_tokens") +
+            count("cache_creation_input_tokens");
+        if (tokens > 0)
+            return tokens;
+    }
+    return undefined;
+}
+/** This run's context usage, or undefined when it cannot be read.
+ *
+ *  Undefined is ORDINARY, not an error: a local or IDE run has no `RUNNER_TEMP`
+ *  and no agent log, and an agent whose CLI writes no NDJSON log never produces
+ *  one. Every caller prints nothing and carries on. */
+export function readRunContext() {
+    try {
+        const directory = runArtifactDir();
+        if (!directory)
+            return undefined;
+        const file = path.join(directory, AGENT_LOG_NAME);
+        if (!fs.existsSync(file))
+            return undefined;
+        if (directory !== cachedForDir) {
+            cachedForDir = directory;
+            cachedWindow = contextWindowFrom(readSlice(file, HEAD_BYTES, false));
+        }
+        const window = cachedWindow ?? DEFAULT_CONTEXT_WINDOW;
+        const tokens = tokensFrom(readSlice(file, TAIL_BYTES, true));
+        if (tokens === undefined || tokens <= 0)
+            return undefined;
+        return { tokens, window, percent: Math.round((tokens / window) * 100) };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`readRunContext failed: ${detail}`);
+        return undefined;
+    }
+}
+/** One sentence naming the measurement, for a refusal that has already told the
+ *  agent not to stop on a context it believes it is short of. Empty when there is
+ *  no reading — the refusal reads correctly without it.
+ *
+ *  It states the reading and nothing else. It does not say the run has room: the
+ *  reading can be 95% and the refusal still stands on its own grounds, and a
+ *  sentence that argued headroom would be wrong exactly when it mattered most.
+ *
+ *  CARRIES ITS OWN TRAILING SPACE, so a caller concatenates it unconditionally
+ *  and an empty reading leaves no gap. */
+export function contextGaugeSentence() {
+    const reading = readRunContext();
+    if (!reading)
+        return "";
+    const k = (value) => `${Math.round(value / 1000)}k`;
+    return (`Measured, not estimated: this run's last request carried ${k(reading.tokens)} of a ` +
+        `${k(reading.window)} token context window (${reading.percent}%). ` +
+        "Use that number rather than an impression of it. ");
+}
+/** Test seam: drop the per-run window cache. */
+export function resetRunContextGaugeForTests() {
+    cachedForDir = undefined;
+    cachedWindow = undefined;
+}

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`, `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 one test file and record the verdict from the exit code. Required: `testFile`, `language`, `testType`, `repository`. To run on this host, pass `commandOverride` (the command for that one file) with `cwd`. Omit `commandOverride` to run in the Skyramp executor instead, which needs `workspacePath`. Optional: `stateFile` (writes execution results back for health analysis). Output is capped at the last 200,000 characters.\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

@@ -34,7 +34,7 @@ Use this skill whenever the user asks to generate, run, or maintain API tests. A
 11. **\`skyramp_scenario_test_generation\`** — 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\`.
 
 ### Test Execution
-12. **\`skyramp_execute_test\`** — 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.
+12. **\`skyramp_execute_test\`** — Run one test file and record the verdict from the exit code. Required: \`testFile\`, \`language\`, \`testType\`, \`repository\`. To run on this host, pass \`commandOverride\` (the command for that one file) with \`cwd\`. Omit \`commandOverride\` to run in the Skyramp executor instead, which needs \`workspacePath\`. Optional: \`stateFile\` (writes execution results back for health analysis). Output is capped at the last 200,000 characters.
 
 ### Test Analysis & Maintenance
 13. **\`skyramp_analyze_changes\`** — Unified entry point: scans endpoints, discovers tests, computes diff. Takes \`repositoryPath\` and \`scope\`. Returns \`stateFile\` + recommendations.

package/build/utils/skyrampSdkVersion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Skyramp SDK version installed beside this server, which is the version the
+ * generated tests are written against.
+ *
+ * Read once: it cannot change while the process runs. The SDK is a direct
+ * dependency that this server imports at load time, so it is always installed
+ * here — a read failure is a broken install, not a state to degrade into.
+ */
+export declare const SKYRAMP_SDK_VERSION: string;

package/build/utils/skyrampSdkVersion.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "fs";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+/**
+ * The Skyramp SDK version installed beside this server, which is the version the
+ * generated tests are written against.
+ *
+ * Read once: it cannot change while the process runs. The SDK is a direct
+ * dependency that this server imports at load time, so it is always installed
+ * here — a read failure is a broken install, not a state to degrade into.
+ */
+export const SKYRAMP_SDK_VERSION = readInstalledSdkVersion();
+function readInstalledSdkVersion() {
+    const manifest = require.resolve("@skyramp/skyramp/package.json");
+    return JSON.parse(readFileSync(manifest, "utf8")).version;
+}

package/build/utils/testDependencyPolicy.js

@@ -6,6 +6,7 @@ import { promisify } from "util";
 import fg from "fast-glob";
 import { canonicalJson as canonical, isPlainObject as isObject, } from "./canonicalJson.js";
 import { listChangedFiles } from "./reportVerification.js";
+import { SKYRAMP_SDK_VERSION } from "./skyrampSdkVersion.js";
 const execFileAsync = promisify(execFile);
 export const NPM_TEST_PACKAGES = new Set([
     "@playwright/test",
@@ -48,6 +49,7 @@ export const JAVA_TEST_PACKAGES = new Set([
     "org.junit.platform:junit-platform-console-standalone",
     "org.mockito:mockito-core",
     "org.testng:testng",
+    "dev.skyramp:skyramp-library",
 ]);
 const DEPENDENCY_FILES = {
     javascript: {
@@ -57,6 +59,9 @@ const DEPENDENCY_FILES = {
             "npm-shrinkwrap.json",
             "yarn.lock",
             "pnpm-lock.yaml",
+            // Named in the fix-errors guidance, so it must not bypass validation.
+            "bun.lock",
+            "bun.lockb",
         ],
     },
     python: {
@@ -277,10 +282,26 @@ function verifyPackageJson(file, beforeRaw, afterRaw, violations) {
         else if (!isSafeNpmSpecifier(afterDev[name])) {
             violations.push(`${file}: ${name} must use a registry version, not an alias, URL, git, or local package source.`);
         }
+        else if (!declaresServerSdkVersion(name, afterDev[name])) {
+            violations.push(`${file}: ${name} is declared as ${afterDev[name]}, but the tests were generated by ${SKYRAMP_SDK_VERSION}. Declare exactly ${SKYRAMP_SDK_VERSION}, with no range operator: a range lets a clean install resolve a different SDK.`);
+        }
     }
     return (canonical(beforeRuntime) !== canonical(afterRuntime) ||
         canonical(beforeDev) !== canonical(afterDev));
 }
+/** The SDK the tests were generated by is the one this server imports, so the
+ *  repository must declare exactly that version. Only the npm spelling carries
+ *  a version: the Python and Java manifests declare the SDK without one, so
+ *  neither is checked here.
+ *
+ *  The specifier must be the bare version. A range is refused, including
+ *  `^1.2.3`: it permits 1.3.0, so a clean install elsewhere can resolve an SDK
+ *  that did not write these tests, which is the whole thing this prevents. */
+function declaresServerSdkVersion(name, specifier) {
+    if (name !== "@skyramp/skyramp")
+        return true;
+    return specifier.trim() === SKYRAMP_SDK_VERSION;
+}
 function verifyPyproject(file, beforeRaw, afterRaw, violations) {
     const before = pythonDevView(beforeRaw);
     const after = pythonDevView(afterRaw);

package/build/utils/testExecutionRecord.d.ts

@@ -79,6 +79,7 @@ export declare function reserveTestExecutionAttempt(stateFile: string, repo: str
  * per-file testExecutions record (every file, keyed by canonical path — see
  * executionRecordFrom), plus the maintained-test executionBefore/After row
  * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
  *
  * Extracted from skyramp_execute_test's own state-write block so the
  * behavior that makes a file's result available to the post-execution
@@ -87,4 +88,7 @@ export declare function reserveTestExecutionAttempt(stateFile: string, repo: str
  */
 export declare function persistTestExecutionResult(stateFile: string, repo: string, testType: TestType, phase: "before" | "after", result: TestExecutionResult, options?: {
     reserved?: boolean;
-}): Promise<void>;
+}): Promise<{
+    saved: boolean;
+    matchedExistingTest: boolean;
+}>;