common-qa-mcp 0.2.0 → 0.4.0

package/dist/tools/run.tools.js

@@ -5,7 +5,63 @@ function describeError(e) {
     return e instanceof Error ? e.message : String(e);
 }
 function runnerLine(r) {
-    return `- ${r.online ? '🟢' : '⚪'} ${r.name} \`${r.id}\`${r.status ? ` (${r.status})` : ''}`;
+    const host = r.os ? ` · ${r.os}` : '';
+    return `- ${r.online ? '🟢' : '⚪'} ${r.name}${host} \`${r.id}\`${r.status ? ` (${r.status})` : ''}`;
+}
+function localAgentLine(a) {
+    // Show the machine hostname next to the owner (like the product UI) so the user can tell apart
+    // several agents owned by the same person; the credential_id in backticks is for the tool call.
+    const host = a.host && a.host !== a.name ? ` · ${a.host}` : '';
+    return `- ${a.online ? '🟢' : '⚪'} ${a.name ?? a.id}${host} \`${a.id}\`${a.status ? ` (${a.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) {
+    const where = s.executionTarget === 'cloud_runner' ? 'cloud' : 'local';
+    const agent = s.agent ? ` → ${s.agent}` : '';
+    const br = s.browser ? ` · ${s.browser}` : '';
+    const next = s.nextRunAt ? ` · next ${s.nextRunAt}` : s.scheduledFor ? ` · at ${s.scheduledFor}` : '';
+    const paused = s.active === false ? ' [paused]' : '';
+    return `- ${s.target} — ${s.scheduleType}, ${where}${agent}${br}${next} · **${s.status}**${paused} \`${s.id}\``;
+}
+/** A schedule fires detached from any live session, so a LOCAL schedule must target a specific
+ *  agent — there is no "your online agent" at fire time. Build the "pick an agent" message, offering
+ *  ALL agents (online AND offline): a scheduled run can target an agent that is offline right now,
+ *  because it runs when it fires — this mirrors the product's scheduler picker. */
+async function localScheduleNeedsAgent(adapter) {
+    let list = '';
+    if (adapter.listLocalAgents) {
+        try {
+            const agents = await adapter.listLocalAgents();
+            list = agents.length
+                ? '\n\nAgents (a scheduled run can target an offline one — it runs when it fires):\n' +
+                    agents.map(localAgentLine).join('\n')
+                : '\n\nNo local agents are registered to this project.';
+        }
+        catch { /* best-effort listing — the core message still stands */ }
+    }
+    return ('A LOCAL schedule runs detached from any live session, so it must target a specific agent. ' +
+        'Call again with `agentId` set to a credential_id from local_agents.' + list);
+}
+/** A run-NOW to a specific LOCAL agent cannot target an offline one (mirrors the product UI, which
+ *  offers only ONLINE agents for an immediate run). Returns an error message when the picked agent is
+ *  known-offline, else null. Roster errors are swallowed — the backend still validates at reserve. */
+async function localAgentOfflineForNow(adapter, agentId) {
+    if (!adapter.listLocalAgents)
+        return null;
+    try {
+        const agents = await adapter.listLocalAgents();
+        const picked = agents.find((a) => a.id === agentId);
+        if (picked && !picked.online) {
+            const online = agents.filter((a) => a.online);
+            return (`Agent \`${agentId}\`${picked.name ? ` (${picked.name})` : ''} is offline — a run-now needs an ONLINE agent. ` +
+                (online.length
+                    ? 'Online now:\n' + online.map(localAgentLine).join('\n')
+                    : 'No local agents are online right now — schedule it instead, or bring an agent online.'));
+        }
+    }
+    catch { /* roster unavailable — let the backend validate at reserve */ }
+    return null;
 }
 /** Human summary of a run's status. For a SUITE run `children` carries the per-test-case rollup and
  *  `progress` counts TEST CASES; a single test-case run has neither (progress counts steps). */
@@ -14,10 +70,22 @@ function statusText(s) {
     const prog = s.progress ? ` · ${s.progress.done}/${s.progress.total} ${unit}` : '';
     const link = s.reportUrl ? `\n${s.reportUrl}` : '';
     const icon = (state) => (state === 'passed' ? '✅' : state === 'failed' ? '❌' : state === 'running' ? '⏳' : '•');
+    // Per-state tally across children (suite runs only). Kept concise — only non-zero buckets, in a
+    // stable order so the header reads the same every poll.
+    const tally = s.children?.length
+        ? (() => {
+            const order = ['passed', 'failed', 'running', 'queued', 'stopped', 'error'];
+            const counts = new Map();
+            for (const c of s.children)
+                counts.set(c.state, (counts.get(c.state) ?? 0) + 1);
+            const parts = order.filter((k) => counts.get(k)).map((k) => `${counts.get(k)} ${k}`);
+            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')
         : '';
-    return `Run ${s.runId} · **${s.state}**${prog}${link}${kids}`;
+    return `Run ${s.runId} · **${s.state}**${prog}${tally}${link}${kids}`;
 }
 export function registerRunTools(server, deps) {
     server.registerTool('cloud_runners', {
@@ -45,32 +113,118 @@ export function registerRunTools(server, deps) {
             return err(describeError(e));
         }
     });
+    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.',
+        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 agents = await adapter.listLocalAgents();
+            const online = agents.filter((a) => a.online);
+            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` +
+                agents.map(localAgentLine).join('\n');
+            return ok(text, { agents, online: online.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
     server.registerTool('tc_run', {
-        title: 'Run a test case (local or cloud)',
-        description: 'Execute ONE existing test case in the connected product. `mode` decides WHERE it runs:\n' +
-            "  • 'local' — the connected agent's own browser\n" +
-            "  • 'cloud' — an online cloud runner VM\n" +
-            'IF THE USER HAS NOT SAID local or cloud, ASK THEM before calling — do not guess. When mode is ' +
-            'omitted this tool refuses with that instruction. For cloud, if no runner is online it reports that ' +
-            'there are no active cloud runners (nothing is run). Returns the run id — poll run_status for the result.',
+        title: 'Run a test case (local or 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" +
+            "  • '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' +
+            '`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, " +
+            'end date and timezone BEFORE offering an agent. Returns the schedule id.\n' +
+            '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 in practice — ask the user if unstated."),
-            environment: z.string().optional().describe('Environment id (Mongo id); a name is ignored and the project default is used.'),
-            browser: z.string().optional().describe("Browser, default 'chromium' (bundled + isolated). Others: 'chrome'/'msedge' (installed channel), 'firefox', 'webkit'."),
-            headless: z.boolean().optional().describe('Headless. Defaults: cloud=true, local=false.'),
-            cloudRunnerId: z.string().optional().describe('For cloud: a specific runner id (from cloud_runners). Omit to auto-pick an online one.'),
+            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)."),
+            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."),
+            environment: z.string().optional().describe('Environment key (from tc_list_environments). ASK the user before running — the UI marks this required.'),
+            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."),
+            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."),
+            endDate: z.string().optional().describe('For a recurring schedule — ISO end date (required for hourly/daily/weekdays).'),
+            timezone: z.string().optional().describe("IANA timezone for a schedule (e.g. 'Asia/Kolkata'). Default 'UTC'."),
         },
         annotations: { readOnlyHint: false },
-    }, async ({ tcId, mode, environment, browser, headless, cloudRunnerId }) => {
+    }, async ({ tcId, mode, agentId, environment, browser, headless, cloudRunnerId, deviceId, when, scheduledFor, scheduleType, endDate, timezone, releaseId, sprintId, versionId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
+        // Mirror the Execute-dialog required-field enforcement — ASK the user for every field the UI
+        // asks. Release/sprint/version are optional in the UI; pass '' after asking to accept the
+        // default (untagged / TC's current version). Environment and browser have red asterisks.
+        if (releaseId === undefined) {
+            return err("ASK the user which RELEASE this run belongs to (from list_releases), then call tc_run " +
+                "again with releaseId. If the user wants no release, pass releaseId: '' (empty string).");
+        }
+        if (sprintId === undefined) {
+            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).");
+        }
+        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).");
+        }
+        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) {
+            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 the connected agent, ' +
+                'If the user has not said which, ask them first — local runs on a local 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.
+        if (!when) {
+            return err("Specify WHEN to run: call tc_run again with when: 'immediate' (run now) or when: 'schedule' " +
+                '(create a schedule). If the user has not said, ask them first — never assume.');
+        }
         let resolvedRunner;
         if (mode === 'cloud') {
             if (!adapter.listCloudRunners)
@@ -82,6 +236,7 @@ export function registerRunTools(server, deps) {
             catch (e) {
                 return err(describeError(e));
             }
+            // Cloud is ONLINE-only whether now or scheduled (a schedule pin to an offline VM is rejected).
             const online = runners.filter((r) => r.online);
             if (!online.length) {
                 return err('Currently there are no active cloud runners in your project.');
@@ -92,22 +247,74 @@ export function registerRunTools(server, deps) {
                     return err(`Cloud runner "${cloudRunnerId}" is not online. Online now:\n` + online.map(runnerLine).join('\n'));
                 }
             }
-            else {
-                resolvedRunner = online[0]; // auto-pick the first online runner
+            else if (when === 'immediate') {
+                resolvedRunner = online[0]; // run-now with no pick → auto-pick the first online runner
+            }
+            // 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) {
+            const offlineMsg = await localAgentOfflineForNow(adapter, agentId);
+            if (offlineMsg)
+                return err(offlineMsg);
+        }
+        if (when === 'schedule') {
+            if (!adapter.createSchedule)
+                return err('This product does not support scheduling runs.');
+            if (!scheduledFor) {
+                return err("Scheduling needs a start time: call tc_run again with when: 'schedule' and scheduledFor as an " +
+                    "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.
+            if (mode === 'local' && !agentId)
+                return err(await localScheduleNeedsAgent(adapter));
+            // Cloud: pin the runner's CREDENTIAL only when the user explicitly picked one; otherwise leave
+            // it unpinned so the backend auto-picks a live VM at fire time (don't freeze today's online[0]).
+            const pinnedRunner = mode === 'cloud' && cloudRunnerId ? resolvedRunner : undefined;
+            const schedOpts = {
+                mode,
+                scheduledFor,
+                ...(mode === 'local' && agentId ? { agentId } : {}),
+                ...(pinnedRunner?.credentialId ? { cloudRunnerCredentialId: pinnedRunner.credentialId } : {}),
+                ...(browser !== undefined ? { browser } : {}),
+                ...(environment !== undefined ? { environmentId: environment } : {}),
+                ...(releaseId ? { releaseId } : {}),
+                ...(sprintId ? { sprintId } : {}),
+                ...(scheduleType !== undefined ? { scheduleType } : {}),
+                ...(endDate !== undefined ? { endDate } : {}),
+                ...(timezone !== undefined ? { timezone } : {}),
+            };
+            try {
+                const sched = await adapter.createSchedule({ tcId }, schedOpts);
+                const next = sched.nextRunAt ? ` · first run ${sched.nextRunAt}` : '';
+                const where = mode === 'cloud'
+                    ? (pinnedRunner ? `cloud runner **${pinnedRunner.name}**` : 'cloud (auto-pick a live VM at run time)')
+                    : `agent \`${agentId}\``;
+                return ok(`Scheduled ${tcId} (${scheduleType ?? 'once'}, ${mode}) for ${scheduledFor}${next} → ${where}. Schedule id \`${sched.id}\`.`, { schedule: sched, mode, when: 'schedule', ...(pinnedRunner ? { runner: pinnedRunner } : {}) });
+            }
+            catch (e) {
+                return err(describeError(e));
             }
         }
         const opts = {
             mode,
+            ...(mode === 'local' && agentId ? { agentId } : {}),
             ...(environment !== undefined ? { environment } : {}),
             ...(browser !== undefined ? { browser } : {}),
             ...(headless !== undefined ? { headless } : {}),
             ...(resolvedRunner ? { cloudRunnerId: resolvedRunner.id } : {}),
+            ...(deviceId !== undefined ? { deviceId } : {}),
+            ...(releaseId ? { releaseId } : {}),
+            ...(sprintId ? { sprintId } : {}),
+            ...(versionId ? { versionId } : {}),
         };
         try {
             const run = await adapter.startRun({ tcId }, opts);
             const where = mode === 'cloud'
                 ? `on cloud runner ${resolvedRunner ? `**${resolvedRunner.name}**` : ''}`
-                : 'locally on the connected agent';
+                : `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) {
@@ -115,36 +322,83 @@ export function registerRunTools(server, deps) {
         }
     });
     server.registerTool('suite_run', {
-        title: 'Run a test suite (local or cloud)',
+        title: 'Run a test suite (local or 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, ' +
+            '(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' — the connected agent's own browser (always serial)\n" +
-            "  • 'cloud' — online cloud runner VM(s)\n" +
-            'IF THE USER HAS NOT SAID local or cloud, ASK THEM before calling — do not guess (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). Returns the suite-run id — poll run_status for progress (it reports ' +
-            'per-test-case results under `children`) and run_stop to cancel.',
+            "  • '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" +
+            "  • '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' +
+            '`when` decides WHEN it runs:\n' +
+            "  • 'immediate' — dispatch now; returns the suite-run id — poll run_status for progress " +
+            '(per-test-case results under `children`) and run_stop to cancel.\n' +
+            "  • 'schedule' — create a schedule instead (requires `scheduledFor`); ASK the start time, recurrence, " +
+            'end date and timezone BEFORE offering an agent. Returns the schedule id.\n' +
+            'NOTE: a suite of only MANUAL test cases cannot be run or scheduled by an agent — the backend rejects it.',
         inputSchema: {
             suiteId: z.string().describe('The suite id to run (from suite_list / suite_get).'),
-            mode: z.enum(['local', 'cloud']).optional().describe('Where to run. REQUIRED in practice — ask the user if unstated.'),
-            environment: z.string().optional().describe('Environment id (Mongo id); a name is ignored and the project default is used.'),
-            browser: z.string().optional().describe("Browser, default 'chromium'. Others: 'chrome'/'msedge', 'firefox', 'webkit'."),
-            headless: z.boolean().optional().describe('Headless. Defaults: cloud=true, local=false.'),
-            cloudRunnerId: z.string().optional().describe('For cloud: a specific runner id (from cloud_runners). Omit to auto-pick an online one.'),
-            strategy: z.enum(['serial', 'batch', 'dynamic']).optional().describe('Cloud dispatch order across the suite. Default serial; local is always serial.'),
-            maxConcurrent: z.number().int().positive().optional().describe('Cloud batch/dynamic only — max test cases running at once.'),
-            terminateOnFailure: z.boolean().optional().describe('Stop dispatching remaining test cases after the first failure.'),
+            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."),
+            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.)'),
+            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."),
+            strategy: z.enum(['serial', 'batch', 'dynamic']).optional().describe('Cloud dispatch order across the suite (immediate runs). Default serial; local is always serial.'),
+            maxConcurrent: z.number().int().positive().optional().describe('Cloud batch/dynamic only — max test cases running at once (immediate runs).'),
+            terminateOnFailure: z.boolean().optional().describe('Stop dispatching remaining test cases after the first failure (immediate runs).'),
+            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."),
+            endDate: z.string().optional().describe('For a recurring schedule — ISO end date (required for hourly/daily/weekdays).'),
+            timezone: z.string().optional().describe("IANA timezone for a schedule (e.g. 'Asia/Kolkata'). Default 'UTC'."),
         },
         annotations: { readOnlyHint: false },
-    }, async ({ suiteId, mode, environment, browser, headless, cloudRunnerId, strategy, maxConcurrent, terminateOnFailure }) => {
+    }, async ({ suiteId, releaseId, sprintId, mode, agentId, environment, browser, headless, cloudRunnerId, strategy, maxConcurrent, terminateOnFailure, when, scheduledFor, scheduleType, endDate, timezone }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
+        // Mirror the Execute-suite dialog required-field enforcement (_parentComponent==='SU' branch of
+        // execution-popup-modal.component.html) — release, sprint, environment all carry a red `*` for
+        // a suite. UNLIKE tc_run, empty-string is NOT accepted: the UI blocks form submit until each is
+        // picked. `versionId` and `browser` are TC-level in a suite (each row has its own) so we
+        // don't ask for them.
+        if (!releaseId) {
+            return err("ASK the user which RELEASE this suite run belongs to (from list_releases), then call " +
+                'suite_run again with releaseId. Required for a suite — the UI marks it with a red asterisk.');
+        }
+        if (!sprintId) {
+            return err("ASK the user which SPRINT this suite run belongs to (from list_sprints, filtered by " +
+                'releaseId), then call suite_run again with sprintId. Required for a suite — the UI marks it ' +
+                'with a red asterisk.');
+        }
+        if (!environment) {
+            return err('ASK the user which ENVIRONMENT to run against (from tc_list_environments), then call ' +
+                'suite_run again with environment set to the chosen env key. Required — the UI marks this ' +
+                '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 the connected agent, ' +
+                'If the user has not said which, ask them first — local runs on a local 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.
+        if (!when) {
+            return err("Specify WHEN to run: call suite_run again with when: 'immediate' (run now) or when: 'schedule' " +
+                '(create a schedule). If the user has not said, ask them first — never assume.');
+        }
         let resolvedRunner;
         if (mode === 'cloud') {
             if (!adapter.listCloudRunners)
@@ -156,6 +410,7 @@ export function registerRunTools(server, deps) {
             catch (e) {
                 return err(describeError(e));
             }
+            // Cloud is ONLINE-only whether now or scheduled (a schedule pin to an offline VM is rejected).
             const online = runners.filter((r) => r.online);
             if (!online.length) {
                 return err('Currently there are no active cloud runners in your project.');
@@ -166,16 +421,67 @@ export function registerRunTools(server, deps) {
                     return err(`Cloud runner "${cloudRunnerId}" is not online. Online now:\n` + online.map(runnerLine).join('\n'));
                 }
             }
-            else {
-                resolvedRunner = online[0]; // auto-pick the first online runner
+            else if (when === 'immediate') {
+                resolvedRunner = online[0]; // run-now with no pick → auto-pick the first online runner
+            }
+            // 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) {
+            const offlineMsg = await localAgentOfflineForNow(adapter, agentId);
+            if (offlineMsg)
+                return err(offlineMsg);
+        }
+        if (when === 'schedule') {
+            if (!adapter.createSchedule)
+                return err('This product does not support scheduling runs.');
+            if (!scheduledFor) {
+                return err("Scheduling needs a start time: call suite_run again with when: 'schedule' and scheduledFor as an " +
+                    "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). 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.
+            if (mode === 'local' && !agentId)
+                return err(await localScheduleNeedsAgent(adapter));
+            // Cloud: pin the runner's CREDENTIAL only when the user explicitly picked one; otherwise leave
+            // it unpinned so the backend auto-picks a live VM at fire time (don't freeze today's online[0]).
+            const pinnedRunner = mode === 'cloud' && cloudRunnerId ? resolvedRunner : undefined;
+            const schedOpts = {
+                mode,
+                scheduledFor,
+                ...(mode === 'local' && agentId ? { agentId } : {}),
+                ...(pinnedRunner?.credentialId ? { cloudRunnerCredentialId: pinnedRunner.credentialId } : {}),
+                ...(browser !== undefined ? { browser } : {}),
+                ...(environment !== undefined ? { environmentId: environment } : {}),
+                ...(releaseId ? { releaseId } : {}),
+                ...(sprintId ? { sprintId } : {}),
+                ...(scheduleType !== undefined ? { scheduleType } : {}),
+                ...(endDate !== undefined ? { endDate } : {}),
+                ...(timezone !== undefined ? { timezone } : {}),
+            };
+            try {
+                const sched = await adapter.createSchedule({ suiteId }, schedOpts);
+                const next = sched.nextRunAt ? ` · first run ${sched.nextRunAt}` : '';
+                const where = mode === 'cloud'
+                    ? (pinnedRunner ? `cloud runner **${pinnedRunner.name}**` : 'cloud (auto-pick a live VM at run time)')
+                    : `agent \`${agentId}\``;
+                return ok(`Scheduled suite ${suiteId} (${scheduleType ?? 'once'}, ${mode}) for ${scheduledFor}${next} → ${where}. Schedule id \`${sched.id}\`.`, { schedule: sched, mode, when: 'schedule', ...(pinnedRunner ? { runner: pinnedRunner } : {}) });
+            }
+            catch (e) {
+                return err(describeError(e));
             }
         }
         const opts = {
             mode,
+            ...(mode === 'local' && agentId ? { agentId } : {}),
             ...(environment !== undefined ? { environment } : {}),
             ...(browser !== undefined ? { browser } : {}),
             ...(headless !== undefined ? { headless } : {}),
             ...(resolvedRunner ? { cloudRunnerId: resolvedRunner.id } : {}),
+            ...(releaseId ? { releaseId } : {}),
+            ...(sprintId ? { sprintId } : {}),
             ...(strategy !== undefined ? { strategy } : {}),
             ...(maxConcurrent !== undefined ? { maxConcurrent } : {}),
             ...(terminateOnFailure !== undefined ? { terminateOnFailure } : {}),
@@ -184,7 +490,7 @@ export function registerRunTools(server, deps) {
             const run = await adapter.startRun({ suiteId }, opts);
             const where = mode === 'cloud'
                 ? `on cloud runner ${resolvedRunner ? `**${resolvedRunner.name}**` : ''}`
-                : 'locally on the connected agent';
+                : `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) {
@@ -226,5 +532,124 @@ export function registerRunTools(server, deps) {
             return err(describeError(e));
         }
     });
+    server.registerTool('schedule_list', {
+        title: 'List schedules',
+        description: 'List the scheduled runs in the connected project — each with WHAT it runs (test case / suite), ' +
+            'its cadence, next run time, status (scheduled / running / paused / cancelled), where it runs + the ' +
+            'pinned agent, and its browser. Use this to find a schedule to edit, pause/resume, cancel, or delete. ' +
+            'Requires a live connection.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.listSchedules)
+            return err('This product does not support listing schedules.');
+        try {
+            const schedules = await adapter.listSchedules();
+            if (!schedules.length)
+                return ok('No schedules in this project.', { schedules: [] });
+            const text = `${schedules.length} schedule${schedules.length === 1 ? '' : 's'}:\n\n` +
+                schedules.map(scheduleLine).join('\n');
+            return ok(text, { schedules });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('schedule_update', {
+        title: 'Edit a schedule',
+        description: "Change a schedule's time / recurrence / end date / timezone / browser / environment, or RE-PIN its " +
+            'agent. Pass `scheduleId` (from schedule_list) and ONLY the fields to change. To re-pin: ' +
+            "mode:'local' + `agentId` (from local_agents), or mode:'cloud' + a runner's `cloudRunnerCredentialId` " +
+            '(the `credentialId` from cloud_runners). Requires a live connection.',
+        inputSchema: {
+            scheduleId: z.string().describe('The schedule id (from schedule_list).'),
+            scheduledFor: z.string().optional().describe('New start / next-run ISO datetime.'),
+            scheduleType: z.enum(['once', 'hourly', 'daily', 'weekdays', 'weekly', 'monthly']).optional().describe('New recurrence.'),
+            endDate: z.string().optional().describe('New ISO end date (for recurring schedules).'),
+            timezone: z.string().optional().describe("New IANA timezone (e.g. 'Asia/Kolkata')."),
+            browser: z.enum(['chromium', 'msedge', 'firefox', 'webkit']).optional().describe('New browser (schedules accept chromium/msedge/firefox/webkit, not chrome).'),
+            environment: z.string().optional().describe('New environment id (Mongo id).'),
+            mode: z.enum(['local', 'cloud']).optional().describe('Re-pin target: pair with agentId (local) or cloudRunnerCredentialId (cloud).'),
+            agentId: z.string().optional().describe('Local re-pin: an agent credential_id from local_agents.'),
+            cloudRunnerCredentialId: z.string().optional().describe("Cloud re-pin: a runner's credentialId from cloud_runners."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ scheduleId, scheduledFor, scheduleType, endDate, timezone, browser, environment, mode, agentId, cloudRunnerCredentialId }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.updateSchedule)
+            return err('This product does not support editing schedules.');
+        const changes = {
+            ...(scheduledFor !== undefined ? { scheduledFor } : {}),
+            ...(scheduleType !== undefined ? { scheduleType } : {}),
+            ...(endDate !== undefined ? { endDate } : {}),
+            ...(timezone !== undefined ? { timezone } : {}),
+            ...(browser !== undefined ? { browser } : {}),
+            ...(environment !== undefined ? { environmentId: environment } : {}),
+            ...(mode !== undefined ? { mode } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+            ...(cloudRunnerCredentialId !== undefined ? { cloudRunnerCredentialId } : {}),
+        };
+        if (Object.keys(changes).length === 0) {
+            return err('Nothing to change — pass at least one field to edit (e.g. scheduledFor, scheduleType, browser, or a re-pin via mode + agentId/cloudRunnerCredentialId).');
+        }
+        try {
+            const ref = await adapter.updateSchedule(scheduleId, changes);
+            return ok(`Updated schedule \`${ref.id}\`${ref.nextRunAt ? ` · next run ${ref.nextRunAt}` : ''}.`, { schedule: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('schedule_control', {
+        title: 'Pause / resume / cancel a schedule',
+        description: "Change a schedule's state: `pause` (stop it firing but keep it — reversible with `resume`), " +
+            '`resume` (re-enable a paused schedule), or `cancel` (stop its pending / live run). To remove a ' +
+            'schedule entirely, use schedule_delete instead. Requires a live connection.',
+        inputSchema: {
+            scheduleId: z.string().describe('The schedule id (from schedule_list).'),
+            action: z.enum(['pause', 'resume', 'cancel']).describe('pause / resume / cancel.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ scheduleId, action }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.controlSchedule)
+            return err('This product does not support pausing / resuming / cancelling schedules.');
+        try {
+            const ref = await adapter.controlSchedule(scheduleId, action);
+            const verb = action === 'pause' ? 'Paused' : action === 'resume' ? 'Resumed' : 'Cancelled';
+            return ok(`${verb} schedule \`${ref.id}\`${ref.status ? ` · status ${ref.status}` : ''}.`, { schedule: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('schedule_delete', {
+        title: 'Delete a schedule',
+        description: 'Permanently DELETE a schedule (and tear down any run it currently owns). This cannot be undone — ' +
+            'to only stop it temporarily use schedule_control (pause / cancel). CONFIRM with the user before ' +
+            'deleting. Requires a live connection.',
+        inputSchema: { scheduleId: z.string().describe('The schedule id (from schedule_list).') },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ scheduleId }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.deleteSchedule)
+            return err('This product does not support deleting schedules.');
+        try {
+            await adapter.deleteSchedule(scheduleId);
+            return ok(`Deleted schedule \`${scheduleId}\`.`);
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
 }
 //# sourceMappingURL=run.tools.js.map