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

package/build/types/RepositoryAnalysis.d.ts

@@ -927,15 +927,15 @@ export declare const chainingRefSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sourceStep: number;
     sourceField: string;
-    sourceLocation: "body" | "header" | "cookie";
+    sourceLocation: "cookie" | "body" | "header";
     targetParam: string;
-    targetLocation: "path" | "body" | "header" | "cookie" | "query";
+    targetLocation: "path" | "cookie" | "body" | "header" | "query";
 }, {
     sourceStep: number;
     sourceField: string;
-    sourceLocation: "body" | "header" | "cookie";
+    sourceLocation: "cookie" | "body" | "header";
     targetParam: string;
-    targetLocation: "path" | "body" | "header" | "cookie" | "query";
+    targetLocation: "path" | "cookie" | "body" | "header" | "query";
 }>;
 export declare const scenarioStepSchema: z.ZodObject<{
     order: z.ZodNumber;
@@ -957,15 +957,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }>, z.ZodArray<z.ZodObject<{
         sourceStep: z.ZodNumber;
         sourceField: z.ZodString;
@@ -975,15 +975,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }, {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }>, "many">]>>;
     bodyMustInclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
@@ -1000,15 +1000,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     chainsFrom?: {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     } | {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }[] | undefined;
     bodyMustInclude?: string[] | undefined;
 }, {
@@ -1025,15 +1025,15 @@ export declare const scenarioStepSchema: z.ZodObject<{
     chainsFrom?: {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     } | {
         sourceStep: number;
         sourceField: string;
-        sourceLocation: "body" | "header" | "cookie";
+        sourceLocation: "cookie" | "body" | "header";
         targetParam: string;
-        targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        targetLocation: "path" | "cookie" | "body" | "header" | "query";
     }[] | undefined;
     bodyMustInclude?: string[] | undefined;
 }>;
@@ -1184,14 +1184,14 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }, {
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }>, "many">;
         playwrightRecordings: z.ZodArray<z.ZodObject<{
             path: z.ZodString;
@@ -1225,8 +1225,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1244,8 +1244,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1389,6 +1389,9 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         scanDepth: "quick" | "full";
         analysisScope?: AnalysisScope | undefined;
     };
+    workspace: {
+        baseUrl: string;
+    };
     projectClassification: {
         projectType: "rest-api" | "frontend" | "full-stack" | "microservices" | "library" | "cli" | "other";
         primaryLanguage: string;
@@ -1416,8 +1419,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1431,9 +1434,6 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         }[];
         notFound: string[];
     };
-    workspace: {
-        baseUrl: string;
-    };
     authentication: {
         method: string;
         configLocation: string;
@@ -1477,6 +1477,9 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         scanDepth: "quick" | "full";
         analysisScope?: AnalysisScope | undefined;
     };
+    workspace: {
+        baseUrl: string;
+    };
     projectClassification: {
         projectType: "rest-api" | "frontend" | "full-stack" | "microservices" | "library" | "cli" | "other";
         primaryLanguage: string;
@@ -1504,8 +1507,8 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             path: string;
             version: string;
             authType: string;
-            endpointCount: number;
             baseUrl: string;
+            endpointCount: number;
         }[];
         playwrightRecordings: {
             path: string;
@@ -1519,9 +1522,6 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         }[];
         notFound: string[];
     };
-    workspace: {
-        baseUrl: string;
-    };
     authentication: {
         method: string;
         configLocation: string;

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",
@@ -252,13 +255,6 @@ export declare const codeRefactoringSchema: z.ZodObject<{
     codeReuse?: boolean | undefined;
     modularizeCode?: boolean | undefined;
 }>;
-/** The `testName` field for a recording-driven generation tool.
- *
- *  Single-sourced because the description is prompt text: it is the only thing
- *  steering the agent's choice of title, it gets re-tuned against eval results,
- *  and two copies would let the UI and E2E tools drift apart silently. Each
- *  tool passes the title its own generator falls back to (SKYR-4468). */
-export declare const testNameField: (fallbackTitle: string) => z.ZodOptional<z.ZodString>;
 /** Test types skyramp_enhance_assertions supports — single-sourced so the
  *  tool's schema enum and generation-time baseline seeding cannot drift
  *  (contract additionally requires provider mode at the seeding site). */

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";
@@ -285,26 +291,6 @@ export const codeRefactoringSchema = z.object({
         .default(false)
         .describe("Whether to modularize the code"),
 });
-/** The `testName` field for a recording-driven generation tool.
- *
- *  Single-sourced because the description is prompt text: it is the only thing
- *  steering the agent's choice of title, it gets re-tuned against eval results,
- *  and two copies would let the UI and E2E tools drift apart silently. Each
- *  tool passes the title its own generator falls back to (SKYR-4468). */
-export const testNameField = (fallbackTitle) => z
-    .string()
-    // .trim() normalises incidental whitespace and, combined with .min(1),
-    // rejects a whitespace-only title, which would otherwise produce a
-    // meaningless test title and identifier (SKYR-4468).
-    .trim()
-    .min(1)
-    .optional()
-    .describe("Title for the generated test. Name the BEHAVIOUR this recording verifies, " +
-    "taken from the recommendation the recording came from — not the page it happens on. " +
-    'Example: "Add to cart from search results", not "Search page". ' +
-    "Skyramp emits it verbatim as the Playwright test title for TypeScript/JavaScript, " +
-    "and as a snake_case `def test_<name>` identifier for Python. " +
-    `Omit it and the test stays titled \`${fallbackTitle}\`, which claims nothing.`);
 /** Test types skyramp_enhance_assertions supports — single-sourced so the
  *  tool's schema enum and generation-time baseline seeding cannot drift
  *  (contract additionally requires provider mode at the seeding site). */

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;