common-qa-mcp 0.5.0 → 0.7.0

package/dist/tools/run.tools.js

@@ -14,6 +14,14 @@ function localAgentLine(a) {
     const host = a.host && a.host !== a.name ? ` · ${a.host}` : '';
     return `- ${a.online ? '🟢' : '⚪'} ${a.name ?? a.id}${host} \`${a.id}\`${a.status ? ` (${a.status})` : ''}`;
 }
+function mobileDeviceLine(d) {
+    // `active` here is the last-known connection flag from the SQA DB (stale by design). Show it as
+    // a hint, not a gate — a device the user just plugged in may still read `active:false` here.
+    const dot = d.active ? '🟢' : '⚪';
+    const os = d.osVersion ? ` · ${d.platform.toLowerCase()} ${d.osVersion}` : ` · ${d.platform.toLowerCase()}`;
+    const status = d.status ? ` (${d.status})` : '';
+    return `- ${dot} ${d.name}${os} \`${d.id}\`${status}`;
+}
 /** One line per schedule for management listings — what it runs, cadence, where + pinned agent,
  *  browser, next run, status; the credential-free id in backticks is what the management tools take. */
 function scheduleLine(s) {
@@ -88,8 +96,12 @@ function statusText(s) {
             return parts.length ? ` · ${parts.join(', ')}` : '';
         })()
         : '';
-    const kids = s.children?.length
-        ? '\n\n' + s.children.map((c) => `- ${icon(c.state)} ${c.id}${c.title ? ` — ${c.title}` : ''} (${c.state})`).join('\n')
+    const CHILD_CAP = 100;
+    const total = s.children?.length ?? 0;
+    const shown = s.children?.slice(0, CHILD_CAP) ?? [];
+    const kids = shown.length
+        ? '\n\n' + shown.map((c) => `- ${icon(c.state)} ${c.id}${c.title ? ` — ${c.title}` : ''} (${c.state})`).join('\n') +
+            (total > CHILD_CAP ? `\n… and ${total - CHILD_CAP} more (${total} total)` : '')
         : '';
     return `Run ${s.runId} · **${s.state}**${prog}${tally}${link}${kids}`;
 }
@@ -120,13 +132,12 @@ export function registerRunTools(server, deps) {
         }
     });
     server.registerTool('local_agents', {
-        title: 'List local agents (and which are online)',
-        description: 'List the LOCAL agents registered to the connected customer and which are online. Use this ' +
-            'to show the user their local run options, or to pick a specific agent id (its credential_id) to ' +
-            'pass as `agentId` to a LOCAL tc_run / suite_run. Requires a live connection. ' +
-            'NOTE on online status: agents whose `machineName` matches this MCP host are reported online ' +
-            '(mirrors sqa-ui\'s own-machine override — the DB `active` flag is only refreshed at first ' +
-            'registration + a stale cron, so it lags behind). Other agents\' status still comes from the DB.',
+        title: "List THIS machine's local agent(s)",
+        description: "List the LOCAL agent(s) registered from THIS machine — the desktop agent running on the box " +
+            "this MCP is on. Use for a LOCAL tc_run / suite_run. There is exactly one desktop agent per " +
+            "machine, so this is 0 or 1 row: empty means no agent is registered from this box (start the " +
+            "SimplifyQA desktop agent, or use mode:'remote' to dispatch to a teammate's). Use `remote_agents` " +
+            "for the other registered machines. Requires a live connection.",
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, async () => {
@@ -136,11 +147,43 @@ export function registerRunTools(server, deps) {
         if (!adapter.listLocalAgents)
             return err('This product has no local agents to list.');
         try {
-            const agents = await adapter.listLocalAgents();
+            const all = await adapter.listLocalAgents();
+            const agents = all.filter((a) => a.isThisMachine);
+            if (!agents.length) {
+                return ok("No local agent is registered from this machine. Start the SimplifyQA desktop agent on " +
+                    "this box, or use remote_agents + mode:'remote' to run on a teammate's machine.", { agents: [] });
+            }
             const online = agents.filter((a) => a.online);
+            const text = `${agents.length} local agent${agents.length === 1 ? '' : 's'} on this machine · ${online.length} online:\n\n` +
+                agents.map(localAgentLine).join('\n');
+            return ok(text, { agents, online: online.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('remote_agents', {
+        title: 'List REMOTE agents (other registered machines)',
+        description: "List the LOCAL agents registered on OTHER machines (teammates' boxes) — the pool a REMOTE " +
+            "run dispatches to. Use to pick an `agentId` for a REMOTE tc_run / suite_run. Excludes this " +
+            "machine's own agent (that's `local_agents`). REMOTE dispatches to a specific teammate's " +
+            "registered desktop agent through the SimplifyQA queue; the picked agent's browsers / adb " +
+            "devices are what actually execute. Requires a live connection.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.listLocalAgents)
+            return err('This product has no local agents to list.');
+        try {
+            const all = await adapter.listLocalAgents();
+            const agents = all.filter((a) => !a.isThisMachine);
             if (!agents.length)
-                return ok('No local agents are registered to this project.', { agents: [] });
-            const text = `${agents.length} local agent${agents.length === 1 ? '' : 's'} · ${online.length} online:\n\n` +
+                return ok('No other machines are registered as agents for this customer.', { agents: [] });
+            const online = agents.filter((a) => a.online);
+            const text = `${agents.length} remote agent${agents.length === 1 ? '' : 's'} · ${online.length} online:\n\n` +
                 agents.map(localAgentLine).join('\n');
             return ok(text, { agents, online: online.length });
         }
@@ -148,24 +191,81 @@ export function registerRunTools(server, deps) {
             return err(describeError(e));
         }
     });
+    server.registerTool('mobile_list_devices', {
+        title: 'List mobile devices (Android or iOS)',
+        description: "List MOBILE devices available to the project — union of the LOCAL roster (real devices + " +
+            "emulators/simulators registered via the desktop agent, from `/tm/mobileDevices/search`) " +
+            "and the CLOUD roster (whichever farm the project has integrated: LambdaTest / " +
+            "BrowserStack / SauceLabs / SimplifyQA Device Farm — the first non-empty one wins, " +
+            "matching the UI's single-provider-per-project model). Use before `tc_run` for an ANDROID " +
+            "or IOS test case to pick a `deviceId` (and read `deviceType` + `cloudDeviceType` off the " +
+            "same row). The `active` flag on local rows is last-known: stale by design (the SQA " +
+            "backend writes it when the desktop agent connects/disconnects, and a 7s-stale cron flips " +
+            "it back); a device the user just plugged in may still read `active:false` here. Cloud " +
+            "rows don't carry `active` — cloud farms are always assumed reachable. Requires a live " +
+            "connection.",
+        inputSchema: {
+            platform: z.enum(['android', 'ios']).describe("Which mobile platform to list devices for."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ platform }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.listMobileDevices)
+            return err('This product has no mobile device roster to list.');
+        try {
+            const devices = await adapter.listMobileDevices(platform.toUpperCase());
+            if (!devices.length) {
+                return ok(`No ${platform.toUpperCase()} devices are registered to this project. Connect a device ` +
+                    `via the SimplifyQA desktop agent, then try again.`, { devices: [] });
+            }
+            // Group by deviceType so the client can present the same tabs the UI does (Real / Emulator
+            // / Simulator / Cloud Device). Cloud rows come from the configured farm (LT / BS / SL / SQA
+            // Device Farm); the row's `cloudDeviceType` names which one — pass it back on `tc_run`.
+            const groups = {};
+            for (const d of devices) {
+                if (!groups[d.deviceType])
+                    groups[d.deviceType] = [];
+                groups[d.deviceType].push(d);
+            }
+            const active = devices.filter((d) => d.active).length;
+            const sections = Object.entries(groups)
+                .map(([type, rows]) => `**${type}** (${rows.length})\n${rows.map(mobileDeviceLine).join('\n')}`)
+                .join('\n\n');
+            const text = `${devices.length} ${platform.toUpperCase()} device${devices.length === 1 ? '' : 's'} · ${active} active:\n\n` +
+                sections;
+            return ok(text, { devices, active });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
     server.registerTool('tc_run', {
-        title: 'Run a test case (local or cloud; now or scheduled)',
+        title: 'Run a test case (local / remote / cloud; now or scheduled)',
         description: "Execute ONE existing test case in the connected product. ASK the user for EVERY field the " +
             "Execute dialog asks — never assume — and in ORDER: (1) `releaseId` (from list_releases; " +
             "pass '' if the user skips), (2) `sprintId` (from list_sprints; pass '' if the user skips), " +
             "(3) `versionId` (from tc_get's `versions[]`; pass '' to accept the TC's current version), " +
-            '(4) `environment` (from tc_list_environments — required), (5) `browser` (required), ' +
-            '(6) `mode` local/cloud, (7) `when` immediate/schedule, (8) for a schedule the start time + ' +
-            'recurrence + timezone, (9) THEN offer the eligible agent/runner and pass the pick. The tool ' +
-            'REFUSES when any of (1)-(7) is omitted — that is deliberate; it forces the ask instead of ' +
-            'silently defaulting. `mode` decides WHERE it runs:\n' +
-            "  • 'local' — a local agent's own browser. Pass `agentId` from local_agents. For when:'immediate' only " +
-            "ONLINE agents are eligible (a run-now can't target an offline agent; omit to auto-pick your own online " +
-            "agent). For when:'schedule' ANY agent (online OR offline) is eligible and `agentId` is REQUIRED.\n" +
+            '(4) `environment` (from tc_list_environments — required), (5) FOR WEB TCs: `browser` ' +
+            '(required); FOR ANDROID/IOS TCs: skip browser — `deviceType` + `deviceId` are asked in step ' +
+            "(9) instead (call `mobile_list_devices` to enumerate), (6) `mode` local/remote/cloud, (7) " +
+            "`when` immediate/schedule, (8) for a schedule the start time + recurrence + timezone, (9) " +
+            'THEN offer the eligible agent/runner and (for mobile) the device — pass the picks. The tool ' +
+            'REFUSES when any of (1)-(7) is omitted, and additionally when `deviceType`/`deviceId` are ' +
+            'omitted on a mobile TC — that is deliberate; it forces the ask instead of silently ' +
+            'defaulting. `mode` decides WHERE it runs:\n' +
+            "  • 'local' — THIS machine's desktop agent (its own browser). Call `local_agents` (0 or 1 row per box). " +
+            "For when:'immediate' the tool first probes the desktop agent (:4040) and refuses cleanly if it's not up. " +
+            "Omit `agentId` to auto-pick this machine's agent (or pass it explicitly — must be this machine's row). " +
+            "For when:'schedule' `agentId` is REQUIRED.\n" +
+            "  • 'remote' — ANOTHER registered machine's desktop agent (a teammate's box). Call `remote_agents` and " +
+            "OFFER the list; `agentId` is REQUIRED (no auto-pick across boxes). For when:'immediate' only ONLINE " +
+            "remote agents are eligible; for when:'schedule' ANY remote agent works (it runs when it fires).\n" +
             "  • 'cloud' — an online cloud runner VM (ONLINE-only whether now or scheduled). Pass `cloudRunnerId` " +
             'from cloud_runners; for a schedule omit it to let the backend auto-pick a live VM at fire time.\n' +
-            'IF THE USER HAS NOT SAID local or cloud, ASK — this tool refuses when `mode` is omitted. For cloud, if ' +
-            'no runner is online it reports that there are no active cloud runners (nothing is run).\n' +
+            'IF THE USER HAS NOT SAID local, remote, or cloud, ASK — this tool refuses when `mode` is omitted. For cloud, ' +
+            'if no runner is online it reports that there are no active cloud runners (nothing is run).\n' +
             '`when` decides WHEN it runs (this tool REFUSES when `when` is omitted — ASK the user):\n' +
             "  • 'immediate' — dispatch now; returns the run id — poll run_status for the result.\n" +
             "  • 'schedule' — create a schedule instead (requires `scheduledFor`); ASK the start time, recurrence, " +
@@ -173,8 +273,8 @@ export function registerRunTools(server, deps) {
             'NOTE: MANUAL test cases cannot be run or scheduled by an agent — the backend rejects them.',
         inputSchema: {
             tcId: z.string().describe('The test case id (or business key) to run.'),
-            mode: z.enum(['local', 'cloud']).optional().describe("Where to run. REQUIRED — ASK the user if unstated (the tool refuses when omitted)."),
-            agentId: z.string().optional().describe("For local: a specific agent credential_id (from local_agents). when:'immediate' → must be an ONLINE agent (or omit to auto-pick your own online agent); when:'schedule' → REQUIRED, and may be an offline agent (it runs when it fires)."),
+            mode: z.enum(['local', 'remote', 'cloud']).optional().describe("Where to run. REQUIRED — ASK the user if unstated (the tool refuses when omitted)."),
+            agentId: z.string().optional().describe("For local: a specific agent credential_id from `local_agents` (must be THIS machine's row; omit to auto-pick). For remote: REQUIRED — a credential_id from `remote_agents` (a teammate's row). when:'immediate' → the picked agent must be ONLINE; when:'schedule' → offline agents are OK (they run when they fire) and `agentId` is REQUIRED for both local and remote."),
             releaseId: z.string().optional().describe('Tag the run with a RELEASE (from list_releases). Optional in the UI; omit to leave untagged.'),
             sprintId: z.string().optional().describe('Tag the run with a SPRINT (from list_sprints). Optional in the UI; omit to leave untagged.'),
             versionId: z.string().optional().describe("Override the TC's currently-selected VERSION for this run (an id from the TC's `versions[]`). Omit to run the current version — that's what the UI's Version chip defaults to."),
@@ -182,7 +282,10 @@ export function registerRunTools(server, deps) {
             browser: z.string().optional().describe("Browser, default 'chromium' (bundled + isolated). Others: 'chrome'/'msedge' (installed channel), 'firefox', 'webkit'. NOTE: a schedule accepts only chromium/msedge/firefox/webkit."),
             headless: z.boolean().optional().describe('Headless. Defaults: cloud=true, local=false. (Immediate runs only.)'),
             cloudRunnerId: z.string().optional().describe("For cloud: a specific ONLINE runner id (from cloud_runners). For when:'schedule' omit to auto-pick a live VM at fire time."),
-            deviceId: z.string().optional().describe("REQUIRED for ANDROID/IOS test cases — the target device id. LOCAL: adb serial or emulator name. CLOUD: the marketplace device name. Enumerate with android_list_devices."),
+            deviceId: z.string().optional().describe("REQUIRED for ANDROID/IOS test cases — the target device id. LOCAL: adb serial or emulator name. CLOUD: the marketplace device name. Enumerate with `mobile_list_devices`."),
+            deviceType: z.enum(['real_device', 'emulator', 'simulator', 'cloud_device', 'cloud_emulator', 'cloud_simulator']).optional().describe("REQUIRED for ANDROID/IOS test cases — the KIND of device the picked `deviceId` is (read off the matching row from `mobile_list_devices`). Drives the wire execution platform's `type` field."),
+            cloudDeviceType: z.enum(['lambda_test', 'browser_stack', 'sauce_labs', 'simplify_qa_device_form']).optional().describe("REQUIRED when `deviceType` is cloud_* — which cloud farm the device came from (read off the matching row's `cloudDeviceType` from `mobile_list_devices`). Note SIMPLIFY_QA_DEVICE_FORM's legacy 'FORM' spelling — mirrors the SQA wire schema exactly."),
+            osVersion: z.string().optional().describe("Optional OS version to stamp on the wire platform object for ANDROID/IOS — read off the matching row from `mobile_list_devices`. Ignored for non-mobile tcTypes."),
             when: z.enum(['immediate', 'schedule']).optional().describe("When to run — REQUIRED, ASK the user if unstated (the tool refuses when omitted). 'immediate' dispatches now; 'schedule' creates a schedule (needs scheduledFor)."),
             scheduledFor: z.string().optional().describe("REQUIRED for when:'schedule' — ISO datetime of the first/only run (e.g. '2026-08-20T09:00:00Z')."),
             scheduleType: z.enum(['once', 'hourly', 'daily', 'weekdays', 'weekly', 'monthly']).optional().describe("Recurrence for a schedule. Default 'once'. hourly/daily/weekdays require an endDate."),
@@ -190,7 +293,7 @@ export function registerRunTools(server, deps) {
             timezone: z.string().optional().describe("IANA timezone for a schedule (e.g. 'Asia/Kolkata'). Default 'UTC'."),
         },
         annotations: { readOnlyHint: false },
-    }, async ({ tcId, mode, agentId, environment, browser, headless, cloudRunnerId, deviceId, when, scheduledFor, scheduleType, endDate, timezone, releaseId, sprintId, versionId }) => {
+    }, async ({ tcId, mode, agentId, environment, browser, headless, cloudRunnerId, deviceId, deviceType, cloudDeviceType, osVersion, when, scheduledFor, scheduleType, endDate, timezone, releaseId, sprintId, versionId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
@@ -205,25 +308,49 @@ export function registerRunTools(server, deps) {
             return err("ASK the user which SPRINT this run belongs to (from list_sprints), then call tc_run " +
                 "again with sprintId. If the user wants no sprint, pass sprintId: '' (empty string).");
         }
+        // Pre-flight the TC once — needed both to inline the version list (below) and to know the
+        // tcType (WEB vs ANDROID/IOS/…) so the refuse cascade asks the right platform-specific
+        // fields: browser for WEB, deviceType + deviceId for mobile. Mirrors tc_get's refusal at
+        // discovery.tools.ts:226; without this the model guesses a version NAME and the backend 500s.
+        let preview;
+        try {
+            preview = await adapter.getTestCase(tcId);
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+        const tcType = (preview.technologyType ?? 'WEB').toUpperCase();
+        const isMobile = tcType === 'ANDROID' || tcType === 'IOS';
         if (versionId === undefined) {
-            return err("ASK the user which VERSION of the test case to run (from tc_get's `versions[]`), then " +
-                "call tc_run again with versionId. To accept the TC's currently-selected version, " +
-                "pass versionId: '' (empty string).");
+            const vs = preview.versions ?? [];
+            if (vs.length > 1) {
+                const listing = vs
+                    .map((v) => `  • \`${v.id}\` — **${v.name}**${v.isCurrent ? ' (current)' : ''}`)
+                    .join('\n');
+                return err(`Test case ${preview.id ?? tcId} has ${vs.length} versions — ASK the user which ` +
+                    `one to run, then call tc_run again with versionId (pass the version id OR its ` +
+                    `name — either resolves). Pass versionId: '' to accept the TC's current ` +
+                    `version.\n\n${listing}`);
+            }
+            versionId = '';
         }
         if (!environment) {
             return err('ASK the user which ENVIRONMENT to run against (from tc_list_environments), then call ' +
                 'tc_run again with environment set to the chosen env key. Required — the UI marks this ' +
                 'field with a red asterisk.');
         }
-        if (!browser) {
+        // Browser is a WEB-only field — the SQA Execute dialog doesn't render it for mobile TCs
+        // (they show a device picker instead). Skip the refuse for ANDROID/IOS; the adapter's
+        // buildRunPlatform will ignore any browser passed alongside a mobile deviceId.
+        if (!isMobile && !browser) {
             return err("ASK the user which BROWSER to run in (chromium / chrome / msedge / firefox / webkit), " +
                 'then call tc_run again with browser set. Required — the UI marks this field with a ' +
                 'red asterisk.');
         }
         if (!mode) {
-            return err("Specify where to run: call tc_run again with mode: 'local' or 'cloud'. " +
-                'If the user has not said which, ask them first — local runs on a local agent, ' +
-                'cloud runs on an online cloud runner VM.');
+            return err("Specify where to run: call tc_run again with mode: 'local', 'remote', or 'cloud'. " +
+                "If the user has not said which, ASK them first — local runs on THIS machine's agent, " +
+                "remote runs on a teammate's registered agent, cloud runs on an online cloud runner VM.");
         }
         // Never assume now-vs-scheduled — it decides which agents are eligible (online-only for now,
         // online+offline for a local schedule) and, for a schedule, the start time asked next.
@@ -258,13 +385,48 @@ export function registerRunTools(server, deps) {
             }
             // when:'schedule' with no cloudRunnerId → leave unpinned; the backend auto-picks a live VM at fire time.
         }
-        // LOCAL run-NOW to a specific agent must be online (can't dispatch to an offline agent). A local
-        // SCHEDULE may target an offline agent — that path is handled in the schedule branch below.
-        if (mode === 'local' && when === 'immediate' && agentId) {
+        // LOCAL/REMOTE run-NOW to a specific agent must be online (can't dispatch to an offline agent).
+        // The SCHEDULE branch below allows an offline agent since it runs when it fires. REMOTE also
+        // REQUIRES an explicit agentId at all times — auto-pick across teammate boxes is unsafe.
+        if (mode === 'remote' && !agentId) {
+            return err("REMOTE runs need an explicit agentId. Call remote_agents to see the teammate machines, " +
+                "then pass one as agentId (must be an ONLINE row for when:'immediate').");
+        }
+        if ((mode === 'local' || mode === 'remote') && when === 'immediate' && agentId) {
             const offlineMsg = await localAgentOfflineForNow(adapter, agentId);
             if (offlineMsg)
                 return err(offlineMsg);
         }
+        // Mobile refuse cascade — asked AFTER mode/when so the client can filter the device list by
+        // where it's going to run. Order mirrors the UI: pick the KIND of device (Real / Emulator /
+        // Cloud …), then the specific device off the matching tab. Cloud tabs show even in LOCAL
+        // mode (see device-dropdown.component.html:104-111) — LOCAL orchestrator can drive a cloud
+        // device via Appium.
+        if (isMobile) {
+            if (!deviceType) {
+                const platform = tcType.toLowerCase();
+                const localKinds = platform === 'ios' ? "'real_device', 'simulator'" : "'real_device', 'emulator'";
+                return err(`ASK the user which DEVICE TYPE this ${tcType} run should use: ${localKinds}, or ` +
+                    `'cloud_device' / 'cloud_emulator' / 'cloud_simulator' for a farm device. Then call ` +
+                    `tc_run again with deviceType set. (Also call mobile_list_devices({ platform: '${platform}' }) ` +
+                    `to show the available devices grouped by kind — the user picks a device and passes ` +
+                    `\`id\` as deviceId, its \`deviceType\`, and — for cloud rows — its \`cloudDeviceType\`.)`);
+            }
+            const isCloudPick = deviceType.startsWith('cloud_');
+            if (isCloudPick && !cloudDeviceType) {
+                const platform = tcType.toLowerCase();
+                return err(`Cloud device picks need \`cloudDeviceType\` — which farm the device came from. Call ` +
+                    `mobile_list_devices({ platform: '${platform}' }); the matching row's \`cloudDeviceType\` ` +
+                    `is one of 'lambda_test' / 'browser_stack' / 'sauce_labs' / 'simplify_qa_device_form'. ` +
+                    `Pass it alongside deviceType and deviceId.`);
+            }
+            if (!deviceId) {
+                const platform = tcType.toLowerCase();
+                return err(`ASK the user which DEVICE to run on. Call mobile_list_devices({ platform: '${platform}' }) ` +
+                    `and offer the rows whose deviceType matches '${deviceType}' — the user picks one; pass its ` +
+                    `\`id\` as deviceId (and optionally its \`osVersion\`) to tc_run.`);
+            }
+        }
         if (when === 'schedule') {
             if (!adapter.createSchedule)
                 return err('This product does not support scheduling runs.');
@@ -273,7 +435,8 @@ export function registerRunTools(server, deps) {
                     "ISO datetime (e.g. '2026-08-20T09:00:00Z'). Ask the user when the run should start (and the " +
                     'recurrence, end date and timezone if any).');
             }
-            // A schedule fires detached from any live session — a LOCAL schedule must pin a specific agent.
+            // A schedule fires detached from any live session — a LOCAL or REMOTE schedule must pin a
+            // specific agent (mode:'remote' already fenced above, so this catches LOCAL).
             if (mode === 'local' && !agentId)
                 return err(await localScheduleNeedsAgent(adapter));
             // Cloud: pin the runner's CREDENTIAL only when the user explicitly picked one; otherwise leave
@@ -282,7 +445,7 @@ export function registerRunTools(server, deps) {
             const schedOpts = {
                 mode,
                 scheduledFor,
-                ...(mode === 'local' && agentId ? { agentId } : {}),
+                ...((mode === 'local' || mode === 'remote') && agentId ? { agentId } : {}),
                 ...(pinnedRunner?.credentialId ? { cloudRunnerCredentialId: pinnedRunner.credentialId } : {}),
                 ...(browser !== undefined ? { browser } : {}),
                 ...(environment !== undefined ? { environmentId: environment } : {}),
@@ -306,12 +469,15 @@ export function registerRunTools(server, deps) {
         }
         const opts = {
             mode,
-            ...(mode === 'local' && agentId ? { agentId } : {}),
+            ...((mode === 'local' || mode === 'remote') && agentId ? { agentId } : {}),
             ...(environment !== undefined ? { environment } : {}),
             ...(browser !== undefined ? { browser } : {}),
             ...(headless !== undefined ? { headless } : {}),
             ...(resolvedRunner ? { cloudRunnerId: resolvedRunner.id } : {}),
             ...(deviceId !== undefined ? { deviceId } : {}),
+            ...(deviceType !== undefined ? { deviceType: deviceType.toUpperCase() } : {}),
+            ...(cloudDeviceType !== undefined ? { cloudDeviceType: cloudDeviceType.toUpperCase() } : {}),
+            ...(osVersion !== undefined ? { osVersion } : {}),
             ...(releaseId ? { releaseId } : {}),
             ...(sprintId ? { sprintId } : {}),
             ...(versionId ? { versionId } : {}),
@@ -320,7 +486,9 @@ export function registerRunTools(server, deps) {
             const run = await adapter.startRun({ tcId }, opts);
             const where = mode === 'cloud'
                 ? `on cloud runner ${resolvedRunner ? `**${resolvedRunner.name}**` : ''}`
-                : `locally${agentId ? ` on agent \`${agentId}\`` : ' on your online agent'}`;
+                : mode === 'remote'
+                    ? `on remote agent \`${agentId}\``
+                    : `locally${agentId ? ` on agent \`${agentId}\`` : ' on your online agent'}`;
             return ok(`Started ${tcId} ${where}. Run id \`${run.runId}\` — poll run_status({ runId: "${run.runId}" }) for progress.`, { run, mode, ...(resolvedRunner ? { runner: resolvedRunner } : {}) });
         }
         catch (e) {
@@ -328,20 +496,22 @@ export function registerRunTools(server, deps) {
         }
     });
     server.registerTool('suite_run', {
-        title: 'Run a test suite (local or cloud; now or scheduled)',
+        title: 'Run a test suite (local / remote / cloud; now or scheduled)',
         description: 'Execute an existing test SUITE — all its member test cases, in order — in the connected product. ' +
             'ASK the user for EVERY field the UI\'s Execute-suite dialog asks — never assume — and in ORDER ' +
             '(mirrors the product UI, `_parentComponent==="SU"`): (1) `releaseId` (from list_releases — the UI ' +
             'marks it required with `*` for a suite), (2) `sprintId` (from list_sprints — also `*` for a suite), ' +
-            '(3) `environment` (from tc_list_environments — `*`), (4) `mode` local/cloud, (5) `when` immediate/schedule, ' +
+            '(3) `environment` (from tc_list_environments — `*`), (4) `mode` local/remote/cloud, (5) `when` immediate/schedule, ' +
             '(6) for a schedule the start time + recurrence + timezone, (7) THEN offer the eligible agent/runner. ' +
             'The tool REFUSES when any of (1)–(5) is omitted — that is deliberate; it forces the ask instead of ' +
             'silently defaulting. UNLIKE `tc_run`, a suite does NOT ask for `versionId` or `browser` — each TC ' +
             "in the suite carries its own pinned version + execution platform (that's what the suite editor picks per row). " +
             '`mode` decides WHERE it runs:\n' +
-            "  • 'local' — a local agent's own browser, always serial. Pass `agentId` from local_agents. For " +
-            "when:'immediate' only ONLINE agents are eligible (omit to auto-pick your own online agent); for " +
-            "when:'schedule' ANY agent (online OR offline) is eligible and `agentId` is REQUIRED.\n" +
+            "  • 'local' — THIS machine's desktop agent, always serial. Call `local_agents` (0 or 1 row). For " +
+            "when:'immediate' the tool probes :4040 and refuses if the desktop agent is down. Omit `agentId` to " +
+            "auto-pick this machine's agent; for when:'schedule' `agentId` is REQUIRED.\n" +
+            "  • 'remote' — ANOTHER registered machine's desktop agent, always serial. Call `remote_agents`; " +
+            "`agentId` is REQUIRED (no auto-pick). when:'immediate' → ONLINE only; when:'schedule' → offline OK.\n" +
             "  • 'cloud' — online cloud runner VM(s) (ONLINE-only whether now or scheduled). Pass `cloudRunnerId` " +
             'from cloud_runners; for a schedule omit it to auto-pick a live VM at fire time.\n' +
             'For cloud, if no runner is online it reports that there are no active cloud runners (nothing is run).\n' +
@@ -355,8 +525,8 @@ export function registerRunTools(server, deps) {
             suiteId: z.string().describe('The suite id to run (from suite_list / suite_get).'),
             releaseId: z.string().optional().describe('REQUIRED for a suite (UI marks it `*` for _parentComponent==="SU"). A release id from list_releases. Ask the user.'),
             sprintId: z.string().optional().describe('REQUIRED for a suite (UI marks it `*` for _parentComponent==="SU"). A sprint id from list_sprints (scoped to the picked release). Ask the user.'),
-            mode: z.enum(['local', 'cloud']).optional().describe('Where to run. REQUIRED — ASK the user if unstated (the tool refuses when omitted).'),
-            agentId: z.string().optional().describe("For local: a specific agent credential_id (from local_agents). when:'immediate' → must be ONLINE (or omit to auto-pick your own online agent); when:'schedule' → REQUIRED, may be offline."),
+            mode: z.enum(['local', 'remote', 'cloud']).optional().describe('Where to run. REQUIRED — ASK the user if unstated (the tool refuses when omitted).'),
+            agentId: z.string().optional().describe("For local: a credential_id from `local_agents` (this machine only; omit to auto-pick). For remote: REQUIRED — a credential_id from `remote_agents`. when:'immediate' → picked agent must be ONLINE; when:'schedule' → offline OK, agentId REQUIRED for both local and remote."),
             environment: z.string().optional().describe('Environment key (from tc_list_environments). REQUIRED — the UI marks this with a red asterisk for a suite.'),
             browser: z.string().optional().describe("Optional at the SUITE level — each TC in the suite has its own execution platform (that's the suite-editor pick per row). Provide only to OVERRIDE for every WEB TC. Values: 'chromium' (default), 'chrome'/'msedge', 'firefox', 'webkit'. NOTE: a schedule accepts only chromium/msedge/firefox/webkit."),
             headless: z.boolean().optional().describe('Headless. Defaults: cloud=true, local=false. (Immediate runs only.)'),
@@ -395,9 +565,9 @@ export function registerRunTools(server, deps) {
                 'field with a red asterisk for a suite.');
         }
         if (!mode) {
-            return err("Specify where to run: call suite_run again with mode: 'local' or 'cloud'. " +
-                'If the user has not said which, ask them first — local runs on a local agent, ' +
-                'cloud runs on online cloud runner VM(s).');
+            return err("Specify where to run: call suite_run again with mode: 'local', 'remote', or 'cloud'. " +
+                "If the user has not said which, ASK them first — local runs on THIS machine's agent, " +
+                "remote runs on a teammate's registered agent, cloud runs on online cloud runner VM(s).");
         }
         // Never assume now-vs-scheduled — it decides which agents are eligible (online-only for now,
         // online+offline for a local schedule) and, for a schedule, the start time asked next.
@@ -432,9 +602,13 @@ export function registerRunTools(server, deps) {
             }
             // when:'schedule' with no cloudRunnerId → leave unpinned; the backend auto-picks a live VM at fire time.
         }
-        // LOCAL run-NOW to a specific agent must be online (can't dispatch to an offline agent). A local
-        // SCHEDULE may target an offline agent — that path is handled in the schedule branch below.
-        if (mode === 'local' && when === 'immediate' && agentId) {
+        // LOCAL/REMOTE run-NOW to a specific agent must be online. SCHEDULE branch below allows offline.
+        // REMOTE always requires an explicit agentId (auto-pick across teammate boxes is unsafe).
+        if (mode === 'remote' && !agentId) {
+            return err("REMOTE runs need an explicit agentId. Call remote_agents to see the teammate machines, " +
+                "then pass one as agentId (must be an ONLINE row for when:'immediate').");
+        }
+        if ((mode === 'local' || mode === 'remote') && when === 'immediate' && agentId) {
             const offlineMsg = await localAgentOfflineForNow(adapter, agentId);
             if (offlineMsg)
                 return err(offlineMsg);
@@ -448,7 +622,8 @@ export function registerRunTools(server, deps) {
                     'recurrence, end date and timezone if any). NOTE: strategy/maxConcurrent/terminateOnFailure are ' +
                     "immediate-run only — a schedule uses the suite's own settings.");
             }
-            // A schedule fires detached from any live session — a LOCAL schedule must pin a specific agent.
+            // A schedule fires detached from any live session — LOCAL and REMOTE schedules must pin a
+            // specific agent. REMOTE was already fenced above; this catches LOCAL.
             if (mode === 'local' && !agentId)
                 return err(await localScheduleNeedsAgent(adapter));
             // Cloud: pin the runner's CREDENTIAL only when the user explicitly picked one; otherwise leave
@@ -457,7 +632,7 @@ export function registerRunTools(server, deps) {
             const schedOpts = {
                 mode,
                 scheduledFor,
-                ...(mode === 'local' && agentId ? { agentId } : {}),
+                ...((mode === 'local' || mode === 'remote') && agentId ? { agentId } : {}),
                 ...(pinnedRunner?.credentialId ? { cloudRunnerCredentialId: pinnedRunner.credentialId } : {}),
                 ...(browser !== undefined ? { browser } : {}),
                 ...(environment !== undefined ? { environmentId: environment } : {}),
@@ -481,7 +656,7 @@ export function registerRunTools(server, deps) {
         }
         const opts = {
             mode,
-            ...(mode === 'local' && agentId ? { agentId } : {}),
+            ...((mode === 'local' || mode === 'remote') && agentId ? { agentId } : {}),
             ...(environment !== undefined ? { environment } : {}),
             ...(browser !== undefined ? { browser } : {}),
             ...(headless !== undefined ? { headless } : {}),
@@ -496,7 +671,9 @@ export function registerRunTools(server, deps) {
             const run = await adapter.startRun({ suiteId }, opts);
             const where = mode === 'cloud'
                 ? `on cloud runner ${resolvedRunner ? `**${resolvedRunner.name}**` : ''}`
-                : `locally${agentId ? ` on agent \`${agentId}\`` : ' on your online agent'}`;
+                : mode === 'remote'
+                    ? `on remote agent \`${agentId}\``
+                    : `locally${agentId ? ` on agent \`${agentId}\`` : ' on your online agent'}`;
             return ok(`Started suite ${suiteId} ${where}. Run id \`${run.runId}\` — poll run_status({ runId: "${run.runId}" }) for progress.`, { run, mode, ...(resolvedRunner ? { runner: resolvedRunner } : {}) });
         }
         catch (e) {
@@ -505,16 +682,33 @@ export function registerRunTools(server, deps) {
     });
     server.registerTool('run_status', {
         title: 'Get a run status',
-        description: 'Read the status of a run started by tc_run — state (queued/running/passed/failed/stopped/error), ' +
-            'step progress, and a link. Requires a live connection.',
-        inputSchema: { runId: z.string().describe('The run id returned by tc_run.') },
+        description: 'Read the status of a run — state (queued/running/passed/failed/stopped/error), progress, ' +
+            'per-test-case rollup for a SUITE run (capped at 100 shown), and a link. Pass EITHER `runId` ' +
+            '(from tc_run / suite_run) or `suiteId` (from suite_list) to read that suite\'s LATEST ' +
+            'execution. Requires a live connection.',
+        inputSchema: {
+            runId: z.string().optional().describe('The run id returned by tc_run or suite_run.'),
+            suiteId: z.string().optional().describe('A suite id (from suite_list) — resolves to the suite\'s latest execution.'),
+        },
         annotations: { readOnlyHint: true },
-    }, async ({ runId }) => {
+    }, async ({ runId, suiteId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
+        if ((runId && suiteId) || (!runId && !suiteId)) {
+            return err('Pass exactly one of `runId` or `suiteId`.');
+        }
         try {
-            const status = await adapter.getRun(runId);
+            let effectiveRunId = runId;
+            if (suiteId) {
+                if (!adapter.getLatestSuiteRun)
+                    return err('This product does not support latest-suite-run lookup — pass `runId` instead.');
+                const latest = await adapter.getLatestSuiteRun(suiteId);
+                if (!latest)
+                    return ok(`Suite ${suiteId} has no executions yet.`);
+                effectiveRunId = latest;
+            }
+            const status = await adapter.getRun(effectiveRunId);
             return ok(statusText(status), { run: status });
         }
         catch (e) {