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

package/build/entitlements/entitlementGate.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type RunCodes } from "./runCodes.js";
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export declare function installEntitlementGate(server: McpServer, readCodes?: () => Promise<RunCodes>, token?: string | undefined): void;

package/build/entitlements/entitlementGate.js

@@ -0,0 +1,57 @@
+import { readRunCodes } from "./runCodes.js";
+import { NOT_GATED, TOOLS } from "../tool-phases.js";
+const FEATURE_NAMES = {
+    analyze: "change analysis",
+    recommend: "test recommendations",
+    generate: "test generation",
+    execute: "test execution",
+};
+function refusal(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Returns why `tool` may not run with these codes, or undefined if it may. */
+function refusalReason(tool, code, run) {
+    if ("refused" in run) {
+        return `Tool ${tool} is not available: Skyramp could not confirm what this run is allowed to do. ${run.refused}`;
+    }
+    if (run.codes.has(code))
+        return undefined;
+    return `Tool ${tool} is not available: your Skyramp plan does not include ${FEATURE_NAMES[code]}.`;
+}
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export function installEntitlementGate(server, readCodes = readRunCodes, token = process.env.SKYRAMP_RUN_TOKEN) {
+    if (!token?.trim())
+        return;
+    let codes;
+    const runCodes = () => (codes ??= readCodes()
+        .catch((err) => ({
+        refused: err instanceof Error ? err.message : String(err),
+    }))
+        .then((run) => {
+        // A refusal can be temporary, so the next tool call reads again.
+        if ("refused" in run)
+            codes = undefined;
+        return run;
+    }));
+    // Typed loosely: the gate forwards every argument as it came, whatever
+    // overload the tool used.
+    const target = server;
+    const register = target.registerTool.bind(target);
+    target.registerTool = (name, config, cb) => {
+        const code = TOOLS[name]?.entitlement;
+        if (code === NOT_GATED)
+            return register(name, config, cb);
+        const handler = cb;
+        return register(name, config, async (...args) => {
+            if (code === undefined) {
+                return refusal(`Tool ${name} is not available in this run.`);
+            }
+            const reason = refusalReason(name, code, await runCodes());
+            return reason ? refusal(reason) : handler(...args);
+        });
+    };
+}

package/build/entitlements/runCodes.d.ts

@@ -0,0 +1,18 @@
+export type RunCodes = {
+    codes: ReadonlySet<string>;
+}
+/** Core refused the run token; `refused` is its reason. */
+ | {
+    refused: string;
+};
+type Entitlements = {
+    codes: string[];
+} | {
+    error: string;
+};
+/** The part of SkyrampClient this file uses. Core releases before getEntitlements lack it. */
+export interface Core {
+    getEntitlements?: (repository: string) => Promise<Entitlements>;
+}
+export declare function readRunCodes(core?: Core, env?: NodeJS.ProcessEnv): Promise<RunCodes>;
+export {};

package/build/entitlements/runCodes.js

@@ -0,0 +1,15 @@
+/**
+ * The only file that may ask Skyramp core for the run's entitlement codes.
+ * Everything else in MCP reads them through `readRunCodes`, so a change on the
+ * core side changes this file and nothing else.
+ */
+import { SkyrampClient } from "@skyramp/skyramp";
+export async function readRunCodes(core = new SkyrampClient(), env = process.env) {
+    if (!core.getEntitlements) {
+        return { refused: "This Skyramp version does not support it yet." };
+    }
+    const answer = await core.getEntitlements(env.GITHUB_REPOSITORY ?? "");
+    return "error" in answer
+        ? { refused: answer.error }
+        : { codes: new Set(answer.codes) };
+}

package/build/index.js

@@ -7,9 +7,12 @@ import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
 import { registerExecuteFleetTool } from "./tools/executeFleetTool.js";
+import { registerFleetLifecycleTools } from "./tools/fleetLifecycleTools.js";
+import { fleetRuns } from "./services/FleetRunRegistry.js";
 import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "./prompts/test-recommendation/recommendationSections.js";
 import { logger } from "./utils/logger.js";
+import { installEntitlementGate } from "./entitlements/entitlementGate.js";
 import { registerUITestTool } from "./tools/generate-tests/generateUIRestTool.js";
 import { registerUILoadTestTool } from "./tools/generate-tests/generateUILoadRestTool.js";
 import { registerSmokeTestTool } from "./tools/generate-tests/generateSmokeRestTool.js";
@@ -155,6 +158,8 @@ async function createServer({ era }) {
   8. The user can always override workspace defaults by explicitly specifying values in their request.
   `,
     });
+    // Before any tool registers, so every tool goes through the check.
+    installEntitlementGate(server);
     // Register prompts
     logger.info("Starting prompt registration process");
     const prompts = [
@@ -239,6 +244,7 @@ async function createServer({ era }) {
         registerLogoutTool,
         registerExecuteSkyrampTestTool,
         registerExecuteFleetTool,
+        registerFleetLifecycleTools,
         registerTraceTool,
         registerTraceStopTool,
     ];
@@ -325,11 +331,18 @@ async function createServer({ era }) {
         runInitTrigger();
     return server;
 }
+// A crashing process must not stay alive anywhere near the full graceful
+// shutdown's 30s grace — it still gives workers a moment to cancel, but caps
+// it low enough that a crash can't hang the process.
+const CRASH_CLEANUP_WAIT_MS = 3_000;
+/** Interrupt running fleets (bounded wait) so an exit does not leave workers loading. */
+const cancelFleets = () => fleetRuns.cancelAll(CRASH_CLEANUP_WAIT_MS).catch(() => { });
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
     const isEpipeError = "code" in error && error.code === "EPIPE";
     if (isEpipeError) {
+        await cancelFleets();
         process.exit(0);
     }
     logger.critical("Uncaught exception - MCP server crashing", {
@@ -342,6 +355,7 @@ process.on("uncaughtException", async (error) => {
     catch (telemetryError) {
         logger.error("Failed to send crash telemetry", { telemetryError });
     }
+    await cancelFleets();
     process.exit(1);
 });
 // Handle unhandled promise rejections — without this handler Node.js 15+
@@ -351,6 +365,7 @@ process.on("unhandledRejection", async (reason) => {
     const error = reason instanceof Error ? reason : new Error(String(reason));
     // EPIPE means the client already disconnected — exit cleanly
     if ("code" in error && error.code === "EPIPE") {
+        await cancelFleets();
         process.exit(0);
     }
     // gRPC/Docker connectivity errors — log and survive.
@@ -397,7 +412,9 @@ async function main() {
         const cleanupPlaywright = playwrightService
             ? playwrightService.shutdown().catch(() => { })
             : Promise.resolve();
-        cleanupPlaywright.finally(() => {
+        // A running fleet is interrupted so it can cancel its workers, not left loading them.
+        const cleanupFleets = fleetRuns.cancelAll().catch(() => { });
+        Promise.all([cleanupPlaywright, cleanupFleets]).finally(() => {
             handle.close().finally(() => {
                 process.exit(0);
             });

package/build/playwright/essentialTools.d.ts

@@ -0,0 +1 @@
+export declare const ESSENTIAL_TOOLS: ReadonlySet<string>;

package/build/playwright/essentialTools.js

@@ -0,0 +1,43 @@
+// Only expose essential browser tools to reduce LLM confusion.
+// The full set (23 tools) overwhelms the LLM and causes it to use
+// browser_evaluate/browser_run_code instead of the simpler tools.
+//
+// browser_blueprint is the only DOM Analyzer tool registered — it handles
+// both full captures and same-URL deltas via the URL-cache (isFullCapture).
+// browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
+// 0 times in production evals and have no active call path in the testbot prompt.
+//
+// browser_widget_contract_lookup / browser_widget_contract_cache are
+// intentionally excluded: the curated fingerprint library only covers
+// test fixtures (not production widgets), and the LLM can handle custom
+// widgets via snapshot-driven trial-and-error without the tool.
+// The widgetType field on blueprint elements still signals "custom" to
+// the agent — no guidance is lost.
+export const ESSENTIAL_TOOLS = new Set([
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_click",
+    "browser_type",
+    "browser_press_key",
+    "browser_select_option",
+    "browser_hover",
+    "browser_drag",
+    "browser_file_upload",
+    "browser_evaluate",
+    "browser_tabs",
+    "browser_navigate_back",
+    "browser_wait_for",
+    "browser_take_screenshot",
+    "browser_assert",
+    "browser_assert_hidden",
+    "browser_assert_api_request",
+    "browser_assert_table_cell",
+    "browser_mouse_action",
+    "browser_visual_snapshot",
+    "browser_gojs_add_node",
+    "browser_gojs_link",
+    "skyramp_export_zip",
+    "skyramp_load_trace",
+    // DOM Analyzer: blueprint capture (capture-act-capture pattern)
+    "browser_blueprint",
+]);

package/build/playwright/registerPlaywrightTools.js

@@ -8,6 +8,7 @@ import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 import { blueprintJsonSpan } from "./blueprintDigest.js";
 import { recordBlueprintCapture, recordBrowserNavigation, } from "./blueprintDigestStore.js";
 import { recordTraceExport } from "./traceExportStore.js";
+import { ESSENTIAL_TOOLS } from "./essentialTools.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
@@ -169,49 +170,6 @@ export async function registerPlaywrightTools(server, options) {
     }
     const tools = _service.getTools();
     logger.info(`Registering ${tools.length} Playwright browser tools`);
-    // Only expose essential browser tools to reduce LLM confusion.
-    // The full set (23 tools) overwhelms the LLM and causes it to use
-    // browser_evaluate/browser_run_code instead of the simpler tools.
-    //
-    // browser_blueprint is the only DOM Analyzer tool registered — it handles
-    // both full captures and same-URL deltas via the URL-cache (isFullCapture).
-    // browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
-    // 0 times in production evals and have no active call path in the testbot prompt.
-    //
-    // browser_widget_contract_lookup / browser_widget_contract_cache are
-    // intentionally excluded: the curated fingerprint library only covers
-    // test fixtures (not production widgets), and the LLM can handle custom
-    // widgets via snapshot-driven trial-and-error without the tool.
-    // The widgetType field on blueprint elements still signals "custom" to
-    // the agent — no guidance is lost.
-    const ESSENTIAL_TOOLS = new Set([
-        "browser_navigate",
-        "browser_snapshot",
-        "browser_click",
-        "browser_type",
-        "browser_press_key",
-        "browser_select_option",
-        "browser_hover",
-        "browser_drag",
-        "browser_file_upload",
-        "browser_evaluate",
-        "browser_tabs",
-        "browser_navigate_back",
-        "browser_wait_for",
-        "browser_take_screenshot",
-        "browser_assert",
-        "browser_assert_hidden",
-        "browser_assert_api_request",
-        "browser_assert_table_cell",
-        "browser_mouse_action",
-        "browser_visual_snapshot",
-        "browser_gojs_add_node",
-        "browser_gojs_link",
-        "skyramp_export_zip",
-        "skyramp_load_trace",
-        // DOM Analyzer: blueprint capture (capture-act-capture pattern)
-        "browser_blueprint",
-    ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
     for (const tool of filteredTools) {

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -1,194 +1,21 @@
 import { getPersonaPrefix } from "../personas.js";
-import { AUTH_TYPES_PROMPT_LIST } from "../../utils/workspaceAuth.js";
-import { SUPPORTED_FRAMEWORKS } from "../../workspace/frameworks.js";
-export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Your task is to scan this repository, discover ALL services, and call the skyramp_init_workspace tool with the discovered services array and the scanToken.
-
-After scanning the workspace, before calling the skyramp_init_workspace tool, you MUST:
-1. For each discovered service, list where each field value came from: the file it was read from, or the documented inference or fallback rule below that produced it (for example the deterministic testDirectory fallback, or the authType fallback). Follow the scanning sections first, then field definitions, then verification.
-2. Then output a Discovery Summary with the exact services array you will pass to the tool:
-\`\`\`json
-[
-  {
-    "serviceName": "<name>",
-    "language": "<language>",
-    "framework": "<framework>",
-    "testDirectory": "<path>",
-    "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
-    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>", "testSuites": [{ "framework": "<framework>", "testRunCommand": "<command>", "pathGlobs": ["<dir>/**"] }] }
-  }
-]
-\`\`\`
-
-### List all top-level directories
-<list_directories>
-Run a directory listing of the workspace root. Every top-level directory is a potential service. Common layouts:
-| Layout | Example dirs | Expect |
-|--------|-------------|--------|
-| Monorepo | apps/web, apps/api, packages/shared | 1 service per app |
-| Microservices | services/auth, services/orders | 1 service per service dir |
-| Single service | src/, lib/ | 1 service (the root) |
-
-If the repo is a monorepo, check for workspace manifests BEFORE scanning individual directories:
-1. JavaScript/TypeScript monorepos:
-   - If pnpm-workspace.yaml exists, read the packages array to find all package directories (for example, ["apps/*", "packages/*"]).
-   - If turbo.json exists, read the root package.json workspaces field to enumerate all packages.
-   - If lerna.json exists, read the packages array in lerna.json (for example, ["packages/*"]).
-   - If the root package.json has a "workspaces" field, use the glob patterns to identify all packages.
-   - If nx.json exists, scan the projects in nx.json or project.json files in subdirectories.
-2. Java monorepos:
-   - If a parent pom.xml has a <modules> section, each listed module is a separate service (Maven multi-module project).
-   - If settings.gradle or settings.gradle.kts has include statements, each included project is a separate service (Gradle multi-project).
-3. Python monorepos:
-   - If a pyproject.toml has a [tool.poetry.packages] or [tool.setuptools.packages] section with multiple paths, each is a potential service.
-   - If multiple directories each contain their own pyproject.toml or requirements.txt, treat each as an independent service.
-When any of these exist, use the workspace manifest to enumerate ALL packages and apps. Each package with its own server entry point, API routes, or UI framework is a separate service. Do NOT skip frontend packages. A Next.js app, React SPA, or Vue app in the monorepo is a service.
-</list_directories>
-
-### Inspect every candidate directory
-<inspect_directories>
-For each top-level directory, check for service indicator files.
-
-Language indicators (presence of any means an independent service):
-1. package.json indicates typescript or javascript
-2. requirements.txt, pyproject.toml, or Pipfile indicates python
-3. pom.xml or build.gradle indicates java
-
-Test framework (look inside the service directory):
-1. playwright.config.* indicates playwright
-2. pytest.ini, conftest.py, or pyproject.toml [tool.pytest] indicates pytest
-3. junit in pom.xml indicates junit
-
-API schemas (look inside the service directory and check known framework defaults):
-1. openapi.json/yaml or swagger.json/yaml provides the schema file path
-2. FastAPI projects serve the schema at http://localhost:{port}/openapi.json
-3. Express with swagger-ui serves at http://localhost:{port}/api-docs
-4. Spring Boot serves at http://localhost:{port}/v3/api-docs
-</inspect_directories>
-
-### Check root-level runtime config
-<runtime_config>
-Inspect the repo root (and subdirectories like .devcontainer/) for shared runtime configuration:
-1. CLAUDE.md or AGENTS.md: if either file exists at the repo root, check it for dev/test/CI setup instructions including how to start services, required environment variables, and runtime configuration.
-2. Docker Compose files: scan for ALL compose files including docker-compose.yml, docker-compose.yaml, docker-compose.*.yml (such as docker-compose.testbot.yml or docker-compose.dev.yml), compose.yml, and compose.*.yaml in the repo root and subdirectories. Distinguish between application compose files and infrastructure-only compose files. Infrastructure compose files contain only supporting services like databases, Redis, Minio, mail servers, or message queues and do NOT run the application itself. Application compose files contain the actual application services that build from the repo source code (look for "build:" directives pointing to the repo, or services that map to discovered application directories). Only use application compose files for determining runtime, serverStartCommand, and serverStopCommand. When a non-default compose file is found, the serverStartCommand and serverStopCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d --build <service-name>" and "docker compose -f docker-compose.testbot.yml stop <service-name>"). Docker Compose ALWAYS prefixes the network name with the project name. If compose has "networks: { my-net: ... }", the actual network name is "<project-name>_my-net". If there is no explicit networks section, the default network is "<project-name>_default". The project name is the basename of the working directory where docker compose runs.
-3. Makefile: extract start and dev targets.
-4. Root package.json scripts: extract workspace-level commands.
-</runtime_config>
-
-### Build the complete services array
-<build_services>
-Create one service entry per deployable unit. You MUST include every backend/API service (Python, Java, Go, Node.js) and every frontend service (React, Vue, Angular, Next.js). Set runtime fields from docker-compose.yml if present.
-</build_services>
-
-### Basic fields
-<basic_fields>
-1. serviceName (required): A unique identifier for the service. Use the format <repoName>-<serviceDirName>-<frontend or backend> for consistency. For example: directus-api-backend, directus-app-frontend. If the directory name already ends with "backend" or "frontend", do not duplicate the suffix (use "demoshop-fullstack-backend" not "demoshop-fullstack-backend-backend"). For single-service repos where the service directory is the root, omit the directory portion such as onlineBoutique-frontend.
-2. language (required): One of python, typescript, javascript, or java. Detect from package.json (typescript or javascript), requirements.txt or pyproject.toml (python), or pom.xml or build.gradle (java).
-3. framework (required): One of playwright, pytest, robot, or junit. Detect from pytest.ini, playwright.config, jest.config, or junit in pom.xml. The framework MUST match the language: python uses pytest or robot, typescript or javascript uses playwright, and java uses junit.
-4. testDirectory (required): A stable path relative to the repo root where generated tests for this service will be placed. For each service, use the test directory configured by that service's test framework when one is discoverable:
-   - Playwright: Read playwright.config.ts (or .js/.mjs) and extract the testDir value.
-   - pytest: Read pytest.ini, pyproject.toml [tool.pytest.ini_options], or setup.cfg [tool:pytest] for testpaths.
-   - JUnit: Usually src/test/java. Check pom.xml or build.gradle for custom test source directories.
-   If no framework-configured test directory is available, use the Skyramp deterministic fallback:
-   - Single service: set testDirectory to tests/skyramp.
-   - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service's directory relative to its repository root with path separators and whitespace replaced by hyphens, or the repository's name for a service at the root.
-   Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
-   NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
-</basic_fields>
-
-### API fields
-<api_fields>
-1. api.schemaPath: Path or URL to an OpenAPI or Swagger schema. Search for openapi.json, openapi.yaml, swagger.json, or swagger.yaml files. Framework defaults are: FastAPI serves /openapi.json, Express serves /api-docs, and Spring serves /v3/api-docs. For locally-run services, use a localhost URL. For cloud or externally hosted services (such as Salesforce, Vercel, or Cloudflare), use the actual deployment URL found in config or documentation.
-2. api.baseUrl (required): The base URL where the service is reachable, such as "http://localhost:3000" or "https://api.example.com". Derive from docker-compose ports, app config, README, or environment variables. Use localhost for services run locally and the actual deployment URL for cloud or externally hosted services. NEVER fabricate a URL. Only use URLs found in config files, README, or environment variables.
-   Include the API path prefix (e.g. \`/api\`, \`/api/v1\`, \`/v1\`) when one applies — not just \`host:port\`. A bare host means every test request hits the root and 404s. Derive the prefix from the strongest available signal: OpenAPI \`servers[].url\` or \`basePath\`; the app's routing config (FastAPI \`root_path\`, Express \`app.use('/api/v1', ...)\`, Rails routes prefix, Django \`urlpatterns\` mount); or the longest common leading path across the existing test suite's endpoints. If none of those yield a prefix, leave it bare AND flag it in your summary so the user can review.
-3. api.authType (required): The authentication type. Valid values are: ${AUTH_TYPES_PROMPT_LIST}
-   Detect by checking in the following order (language-agnostic, apply whichever signals match):
-   a. Dependencies and packages (package.json, requirements.txt, go.mod, Gemfile, composer.json, pom.xml, build.gradle):
-      - jsonwebtoken, passport-jwt, @nestjs/jwt, jose, fastapi[security], PyJWT, python-jose, github.com/golang-jwt/jwt, jjwt, or spring-security-oauth2 indicates bearer. Spring exception: if spring-security is present but the security config uses HttpSecurity.formLogin() or sessionManagement() without a JwtDecoder bean, the actual auth is session cookies so use cookie. Check the SecurityConfig or WebSecurityConfigurerAdapter class before assigning bearer to any Spring service.
-      - passport-http or Spring basic auth indicates basic.
-      - passport-oauth2, openid-client, doorkeeper, keycloak-connect, spring-security-oauth2-resource-server, or github.com/coreos/go-oidc indicates oauth.
-      - rest_framework with TokenAuthentication or djangorestframework-simplejwt (Token scheme) indicates token.
-      - express-session, cookie-session, iron-session, next-auth, gorilla/sessions, or laravel/session indicates cookie.
-      - laravel/sanctum or laravel/passport on API routes indicates bearer; on frontend web routes indicates cookie.
-   b. Environment variables (.env, docker-compose, README):
-      - JWT_SECRET, ACCESS_TOKEN_SECRET, FIREBASE_SECRET, or SUPABASE_JWT_SECRET indicates bearer.
-      - API_KEY, X_API_KEY, ADMIN_KEY, or SERVICE_KEY (used as header value, not JWT signing) indicates apiKey.
-      - CLIENT_ID paired with CLIENT_SECRET, OAUTH_CLIENT_*, or OIDC_* indicates oauth.
-      - SESSION_SECRET, COOKIE_SECRET, or NEXTAUTH_SECRET indicates cookie.
-   c. Source code and middleware patterns (auth, middleware, or security config files):
-      - Node/Express: req.headers.authorization split "Bearer" indicates bearer. "Authorization: Token" indicates token. Custom header check indicates apiKey. Session or cookie middleware indicates cookie.
-      - FastAPI/Starlette: HTTPBearer, OAuth2PasswordBearer, or Depends(get_current_user) indicates bearer. SessionMiddleware indicates cookie.
-      - Django/DRF: TokenAuthentication indicates token. JWTAuthentication indicates bearer. SessionAuthentication indicates cookie.
-      - Spring: JwtDecoder or JwtAuthenticationFilter indicates bearer. HttpSecurity.formLogin() with sessions indicates cookie.
-      - Go: ParseWithClaims or GetHeader("Authorization") indicates bearer. gorilla/sessions indicates cookie.
-      - Rails: authenticate_or_request_with_http_token indicates bearer. before_action :authenticate_user! (Devise) indicates cookie.
-      - Laravel: auth:sanctum on API indicates bearer. middleware("auth") on web indicates cookie.
-      - Rust/Axum: Authorization<Bearer> extraction indicates bearer.
-   d. Query-parameter auth: Some APIs pass credentials as a URL query param rather than a header (such as ?key=<key>, ?api_key=<key>, or ?access_token=<token>). Signals include source code reading credentials from req.query.key, request.query_params["api_key"], or @RequestParam("token"), and API docs or README showing auth examples like /endpoint?key=<your-key>.
-   e. Fallback: when none of the signals above applies, use none, for any service. An API that answers without credentials is unauthenticated; never assume bearer without a signal.
-4. api.authHeader: The exact HTTP header name carrying the credential.
-   - For bearer, basic, oauth, or token: always "Authorization" (inferred automatically, so you may omit it).
-   - For cookie or session: always "Cookie" (also inferred automatically).
-   - For apiKey: this is required. Set to the actual custom header name such as "X-API-Key" or "X-Admin-Key".
-   - For none: set authHeader to "".
-5. api.authScheme: The Authorization header prefix (the word before the token). Standard types derive this automatically: bearer uses "Bearer", token uses "Token", and basic uses "Basic". Set explicitly only for custom or non-standard schemes (for example, Hawk uses "Hawk" and Digest uses "Digest"). Omit for cookie, session, or apiKey since they do not use the Authorization header.
-</api_fields>
-
-### Runtime fields
-<runtime_fields>
-1. runtimeDetails.runtime (required): One of local, docker, or k8s. Detect per service:
-   - If the service is listed in an application docker compose file (one that builds or runs the application, not infrastructure-only files containing only databases, caches, or queues) or has a Dockerfile as its intended run method, use "docker".
-   - If k8s manifests exist (charts/, k8s/, deploy/) AND the service is intended to run in K8s for local development, use "k8s".
-   - If the service has no Docker or k8s configuration and is run directly via a language runtime (npm, python, java, etc.), use "local".
-   A repo may have MIXED runtimes. A backend in docker-compose.yml uses "docker" while a frontend run with pnpm or npm locally uses "local". Include ALL services regardless of runtime.
-   If the frontend is bundled inside the API Docker container (no separate frontend service in the compose file), both frontend and backend services should use runtime "docker", share the same baseUrl (the container's exposed URL), and use the same serverStartCommand since they run in the same container.
-   IMPORTANT — proxy parameters are NOT runtime indicators: If proxyKubeconfig, proxyNamespace, or proxyUrl appear in the conversation context, they are for a Skyramp proxy worker that collects traffic samples for mock generation. They do NOT indicate the repo's runtime. Do not use proxy K8s params to set runtime, k8sNamespace, or k8sContext. Determine the runtime solely from the repo's own files (docker-compose.yml, Dockerfile, k8s manifests that are part of the repo's own local dev workflow). Note that many repos have K8s deployment manifests for staging/production but use Docker Compose for local development — check which setup the repo actually uses for local dev.
-2. runtimeDetails.serverStartCommand: The command to start or deploy the service. It MUST match the runtime:
-   - For "docker" runtime: Use a Docker command that rebuilds application services from the working tree before starting them, such as "docker compose up -d --build <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d --build <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name. If the compose service has no build context and only references an image, note that the command cannot rebuild local code.
-   - For "k8s" runtime: Use a deploy command such as "kubectl apply -f deploy/", "helm install myrelease .", or "skaffold run". This is always derivable from the manifests or charts present in the repo.
-   - For "local" runtime: Use an application command such as "uvicorn main:app", "npm run dev", or "java -jar app.jar". Derive from Makefile, package.json scripts, or README. If no start command is discoverable, omit this field entirely.
-   NEVER mix runtime types with incompatible commands (for example, using "uvicorn" with runtime "docker" will cause errors). For "local" runtime, NEVER fabricate a command. Only use commands found in Makefile, package.json scripts, or README.
-   When the SUT recipe (.skyramp/sut/setup.sh) is what brings a service up and no compose service in the repository runs it, set serverStartCommand to "bash .skyramp/sut/setup.sh" and serverStopCommand to "bash .skyramp/sut/teardown.sh". Never invent a container name or a hand-built docker build or docker run command.
-3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure, or to "bash .skyramp/sut/teardown.sh" when serverStartCommand runs the SUT recipe. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
-4. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
-5. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-6. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-</runtime_fields>
-
-### Existing test suites
-<test_suites>
-runtimeDetails.testSuites records the service's own existing tests, which later runs execute and maintain. They cannot find a suite missing from this list. Each distinct (runner, test directory) pair is one suite: a Mocha suite under packages/api/test/ and a Playwright suite under e2e/ are two. Find them in two places and record the union: every test-runner config in the test tree (playwright.config.*, cypress.config.*, vitest.config.*, pytest.ini, test projects, and so on), and every CI step that runs tests (npm test, pytest, go test, dotnet test, mvn test or verify, cypress run, and so on), including a separate integration-test step. Record each suite under the service it tests, even when there is only one, and every suite you run yourself. Omit testSuites only when the service has no existing tests. Each entry sets:
-1. framework: the suite's runner, one of ${SUPPORTED_FRAMEWORKS.join(", ")}. Leave it out when the runner is none of these; record the suite all the same.
-2. testRunCommand: the command that runs the suite, from the root of the repository the suite lives in, taken from its CI job or package scripts. A machine-readable reporter flag and the test file paths, relative to that root, are appended to the end of it, so it must accept appended arguments and must not cd into a subdirectory: point the runner at the suite instead, with the repository's own config file or a package filter (for example "npx playwright test --config e2e/playwright.config.ts" or "pnpm --filter @acme/api test").
-3. pathGlobs: the directories the suite owns, as globs relative to that same root (for example ["e2e/tests/**"]). Set it on every suite. Scope by directory, not by filename, and keep the suites' globs disjoint, so each test file belongs to exactly one suite.
-</test_suites>
-
-### Verification
-<verification>
-Before calling skyramp_init_workspace, confirm all of the following:
-1. Always scan the repo and find services. A repo should have at least one service.
-2. ALL services are included, both backend and frontend. The workspace config is a complete registry of the entire repo, not just the service relevant to your current task. A fullstack or monorepo MUST have multiple services. If you found only one, re-scan every top-level directory before proceeding.
-3. Services NOT in docker-compose.yml (such as a frontend run with pnpm or npm locally) MUST still be included with runtime "local".
-4. Every service has api.baseUrl set to a valid, discoverable URL. Use localhost for local services or the actual deployment URL for cloud or external services. Never fabricate a URL.
-5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
-6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
-7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services). No service uses \`.skyramp\`, \`.\` or the repo root.
-8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
-9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
-10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".
-11. For "local" runtime: if no start command is discoverable from Makefile, package.json scripts, or README, omit serverStartCommand rather than guessing.
-12. dockerNetwork is set only when runtime is "docker".
-13. k8sNamespace and k8sContext are set only when runtime is "k8s".
-14. Every existing test suite, from the test tree and from CI, is recorded under runtimeDetails.testSuites with its testRunCommand and pathGlobs.
-15. If force-recreating a workspace.yml due to a schema validation error, correct the schema error but keep any valid system-under-test setup (serviceName, baseUrl, auth config, runtime details) as it is.
-</verification>
-
-Once verified, call skyramp_init_workspace with:
-- workspacePath: the repository root path
-- services: the array built above
-- scanToken: the token returned by the first call to skyramp_init_scan
-- force: defaults to false. Set to true only if the user explicitly asks to overwrite an existing .skyramp/workspace.yml, or if the existing file must be regenerated due to a validation failure such as a schema mismatch, unknown fields, or a parse error.
-
-skyramp_init_workspace checks the services against these rules before writing anything. When it refuses, it lists each problem: fix every one and call it again with the full corrected services array and the same scanToken, which a refusal leaves valid.`;
+export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Scan this repository and register every component of the system under test in .skyramp/workspace.yml.
+
+### Find the components
+A component runs on its own: a backend API, a frontend app, or a worker with its own entry point. Shared libraries are not components. Read the workspace manifests, compose and container files, CI workflows, README, CLAUDE.md and AGENTS.md, then check every top-level directory. Register every component, frontends included; a monorepo usually has several.
+
+### Fields
+Take every value from a file you read or a rule below; never invent one. For each component:
+- serviceName: always \`<repoName>-<componentDir>\`, or \`<repoName>\` for a component at the root.
+- language: the language of its tests, or of its code when it has none, in lowercase.
+- framework: the framework of its API or UI tests; when it has none, the one its repository or language commonly uses. Never leave it out.
+- testDirectory: where generated tests go, relative to the repository root. Use the directory its test framework config names; otherwise \`tests/skyramp\` for a single component, or \`tests/skyramp/<componentDir>\` for several, with \`/\` in the directory replaced by \`-\`. Never \`.skyramp\`, a path inside it, or the root.
+- api.baseUrl: the URL its API paths are appended to: scheme, host and port where it runs locally (or its hosted URL), plus a base path only when its OpenAPI \`servers\` URL or \`basePath\` holds one the paths leave out. A frontend the backend serves shares the backend's. api.schemaPath: its OpenAPI file or URL, if any.
+- api.authType: from its auth code, dependencies or environment variables; \`none\` without a signal. For \`apiKey\`, set api.authHeader to the header name.
+- runtimeDetails.runtime: \`docker\` when it runs in containers, \`k8s\` when it runs on Kubernetes, else \`local\`, as the repository runs it. dockerNetwork: the network its containers join, if any.
+
+### Call the tool
+First write a Discovery Summary: the services array, and for each value the file or rule that set it. Then call skyramp_init_workspace with workspacePath (the repository root), services and scanToken. Set force only when the user asks to overwrite, or the existing file fails validation; then keep its valid values. When the tool refuses, fix every problem it lists and call it again with the full array and the same scanToken.`;
 /**
  * The scan instructions for one workspace. With related repositories, every
  * repository is scanned into the one workspace.yml at `workspacePath`, each
@@ -200,19 +27,18 @@ export function buildInitWorkspaceInstructions(target) {
     const deliveryRoot = target.testRepositoryPath ?? target.workspacePath;
     const blocks = [];
     if (related.length > 0) {
-        const count = related.length + 1;
         blocks.push(`### Target repositories
 <target_repositories>
-This workspace covers ${count} repositories. Scan EACH one with every section above, as if it were the only repository (its monorepo packages, frontend packages and CI test steps included), and pass the services of all ${count} to ONE skyramp_init_workspace call:
-- ${target.workspacePath}: this workspace's own repository. Its services carry no repository field.
-${related.map((r) => `- ${r.repositoryPath}: set repository to "${r.repository}" on every service found here.`).join("\n")}
-For a related repository's service, write every path and command as it reads from that repository's root (schemaPath, compose files, testRunCommand, pathGlobs), except testDirectory: every testDirectory is relative to ${deliveryRoot}, where generated tests are delivered. When no framework config sets it, a related repository's service uses tests/skyramp/<repoName>-<serviceDirName>, so services of two repositories never share one by accident. Call skyramp_init_workspace with workspacePath "${target.workspacePath}" only. A related repository gets no workspace.yml of its own.
+Scan each repository below as above; pass the components of all ${related.length + 1} to one skyramp_init_workspace call with workspacePath "${target.workspacePath}":
+- ${target.workspacePath}: this workspace's own, with no repository.
+${related.map((r) => `- ${r.repositoryPath}: set repository to "${r.repository}" on each of its components.`).join("\n")}
+Write a related repository's paths from its own root, except testDirectory: every testDirectory is relative to ${deliveryRoot}, and a related repository's fallback is \`tests/skyramp/<repoName>\`, or \`tests/skyramp/<repoName>-<componentDir>\` with several components.
 </target_repositories>`);
     }
     if (target.testRepositoryPath) {
         blocks.push(`### Test repository
 <test_repository>
-Generated tests are delivered into the test repository at ${target.testRepositoryPath}, not into the repository that holds the service. Read each service's testDirectory from the test repository's own framework config (Playwright testDir, pytest testpaths, the JUnit test source directory), relative to the test repository's root; the deterministic fallback applies there too. The test repository holds tests, not services: register no service for it. Record the suites it already has under the service each one tests, with testRunCommand and pathGlobs relative to the test repository's root.
+Generated tests go to the test repository at ${target.testRepositoryPath}. Read testDirectory from its framework config, relative to its root, with the same fallback. Register no component for it.
 </test_repository>`);
     }
     return blocks.length