qualty 0.1.6 → 0.1.8

package/bin/local-runner.js

@@ -0,0 +1,1091 @@
+import { mkdirSync, writeFileSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+async function downloadProjectAttachments({ apiUrl, token, orgId, projectId, specs }) {
+  const labelToPath = {};
+  if (!projectId || !Array.isArray(specs) || specs.length === 0) return labelToPath;
+  const dir = mkdtempSync(join(tmpdir(), "qualty-attach-"));
+  const orgHeader = String(orgId || "").trim();
+  for (const spec of specs) {
+    const fileId = spec.id;
+    const label = spec.runner_key || spec.label;
+    if (!fileId || !label) continue;
+    const response = await fetch(
+      `${apiUrl}/api/v1/projects/${projectId}/upload-files/${encodeURIComponent(fileId)}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...(orgHeader ? { "X-Qualty-Org-Id": orgHeader } : {}),
+        },
+      }
+    );
+    if (!response.ok) continue;
+    const buf = Buffer.from(await response.arrayBuffer());
+    const name = spec.original_filename || `${label}.bin`;
+    const localPath = join(dir, name.replace(/[^a-zA-Z0-9._-]+/g, "_"));
+    writeFileSync(localPath, buf);
+    labelToPath[label] = localPath;
+    if (spec.label && spec.label !== label) labelToPath[spec.label] = localPath;
+  }
+  return labelToPath;
+}
+
+function attachNetworkCollector(page) {
+  const events = [];
+  const onRequest = (req) => {
+    try {
+      events.push({
+        url: req.url(),
+        method: req.method(),
+        resource_type: req.resourceType(),
+        failed: false,
+      });
+    } catch {
+      /* ignore */
+    }
+  };
+  const onRequestFailed = (req) => {
+    try {
+      events.push({
+        url: req.url(),
+        method: req.method(),
+        resource_type: req.resourceType(),
+        failed: true,
+      });
+    } catch {
+      /* ignore */
+    }
+  };
+  page.on("request", onRequest);
+  page.on("requestfailed", onRequestFailed);
+  return {
+    snapshot() {
+      return { events_app_related: events.slice(-500) };
+    },
+  };
+}
+
+function resolveFileUploadArguments(action, labelToPath) {
+  if (!action || !Array.isArray(action.arguments)) return action;
+  const method = String(action.method || "").toLowerCase();
+  if (method !== "file_upload" && method !== "set_input_files") return action;
+  const resolved = action.arguments.map((arg) => {
+    const key = String(arg || "").trim();
+    if (labelToPath[key]) return labelToPath[key];
+    return key;
+  });
+  return { ...action, arguments: resolved };
+}
+
+export async function capturePageContext(page) {
+  try {
+    const text = await page.evaluate(() => {
+      const body = document.body;
+      return body ? body.innerText.slice(0, 12000) : "";
+    });
+    return { page_text: String(text || ""), interactive_summary: "" };
+  } catch {
+    return { page_text: "", interactive_summary: "" };
+  }
+}
+
+function _actLog(stepIndex, attempt, message) {
+  const stepLabel = Number.isFinite(stepIndex) ? stepIndex + 1 : stepIndex;
+  console.log(`[qualty][act][step ${stepLabel}][attempt ${attempt}] ${message}`);
+}
+
+function _summarizeAction(action) {
+  if (!action || typeof action !== "object") return "no-action";
+  const method = String(action.method || "").trim() || "unknown";
+  const selector = String(action.selector || "").trim();
+  return selector ? `${method} selector=${selector}` : method;
+}
+
+async function capturePageContextViaApi({
+  page,
+}) {
+  return capturePageContext(page);
+}
+
+async function _extractInteractiveCandidates(page, limit = 200) {
+  try {
+    const rows = await page.evaluate((maxRows) => {
+      const normalizeText = (v) => (v || "").replace(/\s+/g, " ").trim();
+      const getXPath = (element) => {
+        if (!element || !element.tagName) return "";
+        if (element.id) return `//*[@id="${element.id}"]`;
+        if (element === document.body) return "/html/body";
+        const parent = element.parentElement;
+        if (!parent) return "";
+        const tag = element.tagName.toLowerCase();
+        const sameTag = Array.from(parent.children).filter((c) => c.tagName === element.tagName);
+        const index = sameTag.length > 1 ? `[${sameTag.indexOf(element) + 1}]` : "";
+        const parentXPath = getXPath(parent);
+        return parentXPath ? `${parentXPath}/${tag}${index}` : `//${tag}${index}`;
+      };
+      const isVisible = (el) => {
+        if (!el) return false;
+        const style = window.getComputedStyle(el);
+        if (!style) return false;
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return false;
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      };
+      const inferRole = (el) => {
+        const explicit = el.getAttribute("role");
+        if (explicit) return explicit;
+        const tag = (el.tagName || "").toLowerCase();
+        if (tag === "a") return "link";
+        if (tag === "button") return "button";
+        if (tag === "input") return "textbox";
+        if (tag === "select") return "listbox";
+        if (tag === "textarea") return "textbox";
+        return null;
+      };
+      const getTestId = (el) =>
+        el.getAttribute("data-testid") ||
+        el.getAttribute("data-test-id") ||
+        el.getAttribute("data-test") ||
+        el.getAttribute("data-qa") ||
+        null;
+
+      const selector =
+        "a,button,input,select,textarea,[role],[tabindex],[onclick],[contenteditable='true']";
+      const nodes = Array.from(document.querySelectorAll(selector));
+      const seen = new Set();
+
+      const out = [];
+      for (const el of nodes) {
+        if (seen.has(el) || !isVisible(el) || out.length >= maxRows) continue;
+        seen.add(el);
+        if (!el || out.length >= maxRows) break;
+        const xpath = getXPath(el);
+        if (!xpath) continue;
+        const rect = el.getBoundingClientRect();
+        const tag = (el.tagName || "").toLowerCase();
+        const role = inferRole(el);
+        const text = normalizeText(el.innerText || el.textContent || "").slice(0, 120) || null;
+        const className =
+          typeof el.className === "string" ? normalizeText(el.className).slice(0, 120) : null;
+        const bbox = {
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+          right: Math.round(rect.right),
+          bottom: Math.round(rect.bottom),
+        };
+        const midpoint = {
+          x: Math.round(rect.x + rect.width / 2),
+          y: Math.round(rect.y + rect.height / 2),
+        };
+        out.push({
+          selector: xpath,
+          id: el.id || null,
+          tag: tag || null,
+          role: role || null,
+          text,
+          type: el.getAttribute("type") || null,
+          title: el.getAttribute("title") || null,
+          test_id: getTestId(el),
+          name_attr: el.getAttribute("name") || null,
+          aria_label: el.getAttribute("aria-label") || null,
+          placeholder: el.getAttribute("placeholder") || null,
+          href: el.getAttribute("href") || null,
+          class_name: className,
+          bbox,
+          midpoint,
+          target_coordinate: `${midpoint.x},${midpoint.y}`,
+        });
+      }
+      return out.slice(0, 400);
+    }, Math.max(1, Math.min(500, Number(limit) || 200)));
+    return Array.isArray(rows) ? rows : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Cloud ActHandler parity: attempt 1 (cache / bundle resolve) → 2 (selector LLM) → 3 (heal).
+ */
+async function runActStep({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  executionId,
+  stepIndex,
+  page,
+  credentials,
+  labelToPath,
+  step,
+}) {
+  const attemptHistory = [];
+  const excluded = [];
+  let topCandidatesCache = null;
+  let lastErr = null;
+  let action = null;
+  const maxAttempts = 3;
+  let executionSource = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    _actLog(stepIndex, attempt, "observe: requesting plan");
+    let ctx = await capturePageContextViaApi({
+      page,
+    });
+
+    const observeRequest = async (extraBody = null) =>
+      apiRequest({
+        apiUrl,
+        token,
+        orgId,
+        path: `/api/v1/cli/executions/${executionId}/observe`,
+        method: "POST",
+        body: {
+          step_index: stepIndex,
+          attempt,
+          page_text: ctx.page_text,
+          interactive_summary: ctx.interactive_summary,
+          attempt_history: attemptHistory,
+          excluded_selectors: excluded,
+          top_candidates_cache: topCandidatesCache,
+          ...(extraBody && typeof extraBody === "object" ? extraBody : {}),
+        },
+      });
+
+    let observe = await observeRequest();
+
+    const status = String(observe.status || "");
+    const source = String(observe.resolution_source || "").trim();
+    _actLog(
+      stepIndex,
+      attempt,
+      `observe: status=${status || "unknown"}${source ? ` source=${source}` : ""}`
+    );
+    if (Array.isArray(observe.top_candidates_cache)) {
+      topCandidatesCache = observe.top_candidates_cache;
+    }
+    if (observe.step_kind === "done" || status === "done") {
+      break;
+    }
+    if (observe.step_kind === "agent" || observe.step_kind === "login" || status === "agent") {
+      throw new Error(observe.error || `${observe.step_kind} steps require agent path`);
+    }
+    if (observe.step_kind === "check" || status === "check") {
+      throw new Error(observe.error || "Check steps are not supported in local CLI yet");
+    }
+    if (status === "heal") {
+      _actLog(stepIndex, attempt, "escalating to agent heal");
+      const healResult = await runAgentStep({
+        apiRequest,
+        apiUrl,
+        token,
+        orgId,
+        executionId,
+        stepIndex,
+        instruction: String(observe.remainder_instruction || ""),
+        page,
+        credentials,
+        labelToPath,
+        instructionOverride: true,
+      });
+      return {
+        ok: healResult.ok,
+        error: healResult.error,
+        action: { method: "agent_heal", description: observe.remainder_instruction || "" },
+        skipRemainingSteps: healResult.ok,
+        source: "agent_heal",
+      };
+    }
+    if (status === "retry") {
+      _actLog(stepIndex, attempt, `retry: ${observe.error || "planner requested retry"}`);
+      attemptHistory.push({ attempt, error: observe.error || "retry" });
+      continue;
+    }
+    if (status === "needs_bundle_resolve") {
+      const collectedCandidates = await _extractInteractiveCandidates(page, 200);
+      _actLog(
+        stepIndex,
+        attempt,
+        `needs_bundle_resolve: collected ${collectedCandidates.length} candidates, retrying observe`
+      );
+      observe = await observeRequest({
+        collected_candidates: collectedCandidates,
+        collector_version: "candidate_js_v1",
+      });
+      if (Array.isArray(observe.top_candidates_cache)) {
+        topCandidatesCache = observe.top_candidates_cache;
+      }
+      const retryStatus = String(observe.status || "");
+      const retrySource = String(observe.resolution_source || "").trim();
+      _actLog(
+        stepIndex,
+        attempt,
+        `observe(after candidates): status=${retryStatus || "unknown"}${
+          retrySource ? ` source=${retrySource}` : ""
+        }`
+      );
+      if (retryStatus === "action" && observe.action) {
+        action = resolveFileUploadArguments(observe.action, labelToPath);
+        executionSource = retrySource || source || null;
+        _actLog(stepIndex, attempt, `execute: ${_summarizeAction(action)} source=${executionSource || "unknown"}`);
+        try {
+          await executeAction(page, action, credentials);
+          _actLog(stepIndex, attempt, "execute: success");
+          lastErr = null;
+          break;
+        } catch (err) {
+          lastErr = err.message || String(err);
+          _actLog(stepIndex, attempt, `execute: failed error=${lastErr}`);
+          attemptHistory.push({
+            attempt,
+            method: action.method,
+            selector: action.selector,
+            error: lastErr,
+          });
+          if (action.selector) excluded.push(action.selector);
+          continue;
+        }
+      }
+      if (retryStatus === "retry") {
+        _actLog(stepIndex, attempt, `retry(after candidates): ${observe.error || "planner requested retry"}`);
+        attemptHistory.push({ attempt, error: observe.error || "retry" });
+        continue;
+      }
+      if (retryStatus === "heal") {
+        _actLog(stepIndex, attempt, "escalating to agent heal");
+        const healResult = await runAgentStep({
+          apiRequest,
+          apiUrl,
+          token,
+          orgId,
+          executionId,
+          stepIndex,
+          instruction: String(observe.remainder_instruction || ""),
+          page,
+          credentials,
+          labelToPath,
+          instructionOverride: true,
+        });
+        return {
+          ok: healResult.ok,
+          error: healResult.error,
+          action: { method: "agent_heal", description: observe.remainder_instruction || "" },
+          skipRemainingSteps: healResult.ok,
+          source: "agent_heal",
+        };
+      }
+      lastErr = observe.error || "No action returned after bundle resolve";
+      _actLog(stepIndex, attempt, `retry(after candidates): ${lastErr}`);
+      attemptHistory.push({ attempt, error: lastErr });
+      continue;
+    }
+    if (status === "action" && observe.action) {
+      action = resolveFileUploadArguments(observe.action, labelToPath);
+      executionSource = source || null;
+      _actLog(stepIndex, attempt, `execute: ${_summarizeAction(action)} source=${executionSource || "unknown"}`);
+      try {
+        await executeAction(page, action, credentials);
+        _actLog(stepIndex, attempt, "execute: success");
+        lastErr = null;
+        break;
+      } catch (err) {
+        lastErr = err.message || String(err);
+        _actLog(stepIndex, attempt, `execute: failed error=${lastErr}`);
+        attemptHistory.push({
+          attempt,
+          method: action.method,
+          selector: action.selector,
+          error: lastErr,
+        });
+        if (action.selector) excluded.push(action.selector);
+        continue;
+      }
+    }
+    lastErr = observe.error || "No action returned";
+    _actLog(stepIndex, attempt, `retry: ${lastErr}`);
+    attemptHistory.push({ attempt, error: lastErr });
+  }
+
+  return {
+    ok: !lastErr,
+    error: lastErr,
+    action,
+    skipRemainingSteps: false,
+    source: executionSource,
+  };
+}
+
+async function clickAtCoordinate(page, coord, button = "left") {
+  const [x, y] = coord.split(",").map((v) => Number(v.trim()));
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    throw new Error(`Invalid target_coordinate: ${coord}`);
+  }
+  if (button === "right") {
+    await page.mouse.click(x, y, { button: "right" });
+  } else {
+    await page.mouse.click(x, y);
+  }
+}
+
+async function resolveFileInputAtCoordinate(page, x, y) {
+  return page.evaluate(
+    ({ px, py }) => {
+      const el = document.elementFromPoint(px, py);
+      if (!el) return null;
+      const walk = (node) => {
+        if (!node) return null;
+        if (node.tagName && String(node.tagName).toLowerCase() === "input") {
+          const t = (node.getAttribute("type") || "").toLowerCase();
+          if (t === "file") return node;
+        }
+        const label = node.closest && node.closest("label");
+        if (label && label.control && label.control.type === "file") return label.control;
+        return node.parentElement ? walk(node.parentElement) : null;
+      };
+      const found = walk(el);
+      if (!found) return null;
+      if (found.id) return `#${found.id}`;
+      return null;
+    },
+    { px: x, py: y }
+  );
+}
+
+export async function executeAction(page, action, credentials = null) {
+  const method = String(action.method || "click").toLowerCase();
+  const selector = String(action.selector || "").trim();
+  const args = Array.isArray(action.arguments) ? action.arguments.map(String) : [];
+  const coord = String(action.target_coordinate || "").trim();
+
+  if (method === "wait") {
+    const ms = Math.max(0, Number(args[0] || 500));
+    await page.waitForTimeout(ms);
+    return;
+  }
+
+  if (method === "scrollto" && coord) {
+    const [x, y] = coord.split(",").map((v) => Number(v.trim()));
+    await page.evaluate(
+      ({ x, y }) => window.scrollTo(Number(x) || 0, Number(y) || 0),
+      { x, y }
+    );
+    return;
+  }
+
+  if (method === "scroll") {
+    const [x, y] = coord
+      ? coord.split(",").map((v) => Number(v.trim()))
+      : [null, null];
+    const deltaX = Number(args[0] || 0);
+    const deltaY = Number(args[1] || 700);
+    if (Number.isFinite(x) && Number.isFinite(y)) {
+      await page.mouse.move(x, y);
+    }
+    await page.mouse.wheel(deltaX, deltaY);
+    return;
+  }
+
+  if (method === "focused_keypress") {
+    for (const key of args) {
+      if (key) await page.keyboard.press(key);
+    }
+    return;
+  }
+
+  if (method === "fill_sensitive_field" && credentials) {
+    const fieldType = String(action.field_type || "").toLowerCase();
+    const value =
+      fieldType === "password"
+        ? credentials.password || ""
+        : credentials.username || "";
+    if (!value) throw new Error(`No ${fieldType} credential available`);
+    if (coord) await clickAtCoordinate(page, coord);
+    await page.waitForTimeout(200);
+    const isMac = process.platform === "darwin";
+    const selectAll = isMac ? "Meta+A" : "Control+A";
+    await page.keyboard.press(selectAll);
+    await page.keyboard.press("Backspace");
+    await page.keyboard.type(value, { delay: 40 });
+    if (action.press_enter) await page.keyboard.press("Enter");
+    return;
+  }
+
+  const coordinateMethods = new Set([
+    "click",
+    "dblclick",
+    "rightclick",
+    "hover",
+    "dragdrop",
+  ]);
+  if (coord && coordinateMethods.has(method)) {
+    if (method === "click") {
+      await clickAtCoordinate(page, coord, "left");
+      return;
+    }
+    if (method === "rightclick") {
+      await clickAtCoordinate(page, coord, "right");
+      return;
+    }
+    if (method === "dblclick") {
+      const [x, y] = coord.split(",").map((v) => Number(v.trim()));
+      await page.mouse.dblclick(x, y);
+      return;
+    }
+    if (method === "hover") {
+      const [x, y] = coord.split(",").map((v) => Number(v.trim()));
+      await page.mouse.move(x, y);
+      return;
+    }
+    if (method === "dragdrop") {
+      const [sx, sy] = coord.split(",").map((v) => Number(v.trim()));
+      const ex = Number(args[0]);
+      const ey = Number(args[1]);
+      await page.mouse.move(sx, sy);
+      await page.mouse.down();
+      await page.mouse.move(ex, ey);
+      await page.mouse.up();
+      return;
+    }
+  }
+
+  if (method === "file_upload" && coord && !selector) {
+    const [x, y] = coord.split(",").map((v) => Number(v.trim()));
+    const sel = await resolveFileInputAtCoordinate(page, x, y);
+    if (!sel) throw new Error("file_upload: no file input at coordinate");
+    await page.locator(sel).first().setInputFiles(args, { timeout: 30000 });
+    return;
+  }
+
+  if (method === "type" && !selector && coord) {
+    await clickAtCoordinate(page, coord);
+    await page.waitForTimeout(200);
+    await page.keyboard.type(args[0] || "", { delay: 40 });
+    return;
+  }
+
+  if (method === "type" && !selector && !coord) {
+    await page.keyboard.type(args[0] || "", { delay: 40 });
+    return;
+  }
+
+  if (!selector && method !== "focused_keypress") {
+    throw new Error(`Action ${method} requires a selector or target_coordinate`);
+  }
+
+  const locator = page.locator(selector).first();
+
+  switch (method) {
+    case "click":
+      await locator.click({ timeout: 15000 });
+      break;
+    case "dblclick":
+      await locator.dblclick({ timeout: 15000 });
+      break;
+    case "rightclick":
+      await locator.click({ button: "right", timeout: 15000 });
+      break;
+    case "hover":
+      await locator.hover({ timeout: 15000 });
+      break;
+    case "fill":
+    case "type":
+      await locator.fill(args[0] || "", { timeout: 15000 });
+      break;
+    case "press":
+      for (const key of args) {
+        if (key) await locator.press(key, { timeout: 15000 });
+      }
+      break;
+    case "file_upload":
+    case "set_input_files":
+      await locator.setInputFiles(args, { timeout: 30000 });
+      break;
+    case "scroll":
+      await locator.scrollIntoViewIfNeeded({ timeout: 15000 });
+      break;
+    case "scrollto":
+      await locator.scrollIntoViewIfNeeded({ timeout: 15000 });
+      break;
+    case "dragdrop": {
+      const box = await locator.boundingBox();
+      if (!box) throw new Error("dragdrop: element not visible");
+      const sx = box.x + box.width / 2;
+      const sy = box.y + box.height / 2;
+      const ex = Number(args[0]);
+      const ey = Number(args[1]);
+      await page.mouse.move(sx, sy);
+      await page.mouse.down();
+      await page.mouse.move(ex, ey);
+      await page.mouse.up();
+      break;
+    }
+    default:
+      throw new Error(`Unsupported action method: ${method}`);
+  }
+}
+
+async function runAgentStep({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  executionId,
+  stepIndex,
+  instruction,
+  page,
+  credentials,
+  labelToPath,
+  maxTurns = 100,
+  instructionOverride = false,
+}) {
+  let reset = true;
+  let lastErr = null;
+  let turnCount = 0;
+  const pendingFunctionResults = [];
+
+  while (turnCount < maxTurns) {
+    const screenshotB64 = (await page.screenshot({ type: "png" })).toString("base64");
+    const turnBody = {
+      step_index: stepIndex,
+      screenshot_b64: screenshotB64,
+      page_url: page.url(),
+      reset,
+      function_results: pendingFunctionResults.length ? pendingFunctionResults : undefined,
+    };
+    if (instructionOverride && instruction) {
+      turnBody.instruction_override = instruction;
+    }
+    const turn = await apiRequest({
+      apiUrl,
+      token,
+      orgId,
+      path: `/api/v1/cli/executions/${executionId}/agent-turn`,
+      method: "POST",
+      body: turnBody,
+    });
+    reset = false;
+    pendingFunctionResults.length = 0;
+    turnCount += 1;
+
+    if (turn.status === "error") {
+      lastErr = turn.error || "Agent turn failed";
+      break;
+    }
+    if (turn.status === "done") {
+      lastErr = null;
+      break;
+    }
+    if (turn.status === "continue") {
+      continue;
+    }
+    if (turn.status !== "actions" || !Array.isArray(turn.actions) || !turn.actions.length) {
+      lastErr = turn.error || "Agent returned no actions";
+      break;
+    }
+
+    for (const raw of turn.actions) {
+      const action = resolveFileUploadArguments(raw, labelToPath);
+      let actionOk = true;
+      let actionErr = null;
+      try {
+        if (action.method === "fill_sensitive_field") {
+          await executeAction(page, action, credentials);
+          const fnId = action._function_call_id;
+          if (fnId) {
+            pendingFunctionResults.push({
+              call_id: fnId,
+              success: true,
+              message: "fill_sensitive_field executed locally",
+            });
+          }
+        } else {
+          await executeAction(page, action, credentials);
+        }
+        await page.waitForTimeout(200);
+      } catch (err) {
+        actionOk = false;
+        actionErr = err.message || String(err);
+        lastErr = actionErr;
+      }
+
+      const afterB64 = (await page.screenshot({ type: "png" })).toString("base64");
+      try {
+        await apiRequest({
+          apiUrl,
+          token,
+          orgId,
+          path: `/api/v1/cli/executions/${executionId}/agent-segment`,
+          method: "POST",
+          body: {
+            step_index: stepIndex,
+            turn: turnCount,
+            turn_thought: turn.turn_thought || "",
+            action,
+            executor_ok: actionOk,
+            error: actionErr || undefined,
+            screenshot_b64: afterB64,
+            page_url: page.url(),
+          },
+        });
+      } catch (segErr) {
+        console.warn("[CLI] agent-segment upload failed:", segErr.message || segErr);
+      }
+
+      if (!actionOk) break;
+    }
+    if (lastErr) break;
+  }
+
+  if (!lastErr && turnCount >= maxTurns) {
+    lastErr = `Agent exceeded ${maxTurns} turns`;
+  }
+  return { ok: !lastErr, error: lastErr, turns: turnCount };
+}
+
+export async function runLocalExecution({
+  apiRequest,
+  apiUrl,
+  token,
+  orgId,
+  executionId,
+  device,
+  headless,
+}) {
+  const { chromium } = await import("playwright");
+
+  const claim = await apiRequest({
+    apiUrl,
+    token,
+    orgId,
+    path: `/api/v1/cli/executions/${executionId}/claim`,
+    method: "POST",
+    body: { device },
+  });
+
+  const url = claim.url;
+  const viewport = claim.viewport || { width: 1440, height: 900 };
+  const steps = Array.isArray(claim.steps) ? claim.steps : [];
+  const totalSteps = claim.total_steps || steps.length;
+
+  const browserServer = await chromium.launchServer({
+    headless: headless !== false,
+    host: "127.0.0.1",
+  });
+  const cdpEndpoint = browserServer.wsEndpoint();
+  const browser = await chromium.connect(cdpEndpoint);
+  const context = await browser.newContext({
+    viewport: { width: viewport.width || 1440, height: viewport.height || 900 },
+  });
+  const page = await context.newPage();
+  const networkCollector = attachNetworkCollector(page);
+  const labelToPath = await downloadProjectAttachments({
+    apiUrl,
+    token,
+    orgId,
+    projectId: claim.project_id,
+    specs: claim.file_attachments,
+  });
+  const credentials = claim.credentials || null;
+
+  const stepsJson = [];
+  let runSuccess = true;
+  let runError = null;
+  const started = Date.now();
+  let lastPrevScreenshotB64 = null;
+  let lastCurrScreenshotB64 = null;
+  let firstPrevScreenshotB64 = null;
+
+  try {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60000 });
+    await page.waitForTimeout(500);
+
+    for (let stepIndex = 0; stepIndex < totalSteps; stepIndex += 1) {
+      const step = steps[stepIndex] || {};
+      const kind = String(step.kind || "act").toLowerCase();
+      const instruction = step.instruction || step.name || `Step ${stepIndex + 1}`;
+      let action = null;
+      let lastErr = null;
+      const prevBuf = await page.screenshot({ type: "png" });
+
+      if (kind === "agent" || kind === "login") {
+        console.log(`[qualty][agent][step ${stepIndex + 1}] mode=pure_agent kind=${kind}`);
+        const agentResult = await runAgentStep({
+          apiRequest,
+          apiUrl,
+          token,
+          orgId,
+          executionId,
+          stepIndex,
+          instruction,
+          page,
+          credentials,
+          labelToPath,
+        });
+        lastErr = agentResult.ok ? null : agentResult.error;
+        action = { method: "agent", description: instruction };
+      } else if (kind === "check") {
+        lastErr = "Check steps are not supported in local CLI yet; use cloud run or act steps.";
+      } else {
+        console.log(`[qualty][act][step ${stepIndex + 1}] mode=act`);
+        const actResult = await runActStep({
+          apiRequest,
+          apiUrl,
+          token,
+          orgId,
+          executionId,
+          stepIndex,
+          page,
+          credentials,
+          labelToPath,
+          step,
+        });
+        lastErr = actResult.ok ? null : actResult.error;
+        action = actResult.action;
+        if (actResult.source) {
+          console.log(`[qualty][act][step ${stepIndex + 1}] resolved_source=${actResult.source}`);
+        }
+        if (actResult.skipRemainingSteps && actResult.ok) {
+          const executorOk = true;
+          const currBuf = await page.screenshot({ type: "png" });
+          const prevB64 = prevBuf.toString("base64");
+          const currB64 = currBuf.toString("base64");
+          lastPrevScreenshotB64 = prevB64;
+          lastCurrScreenshotB64 = currB64;
+          if (firstPrevScreenshotB64 == null) firstPrevScreenshotB64 = prevB64;
+          let row = {
+            name: instruction,
+            description: instruction,
+            status: "passed",
+            action: action
+              ? `${action.method}${action.selector ? ` ${action.selector}` : ""}`
+              : "agent_heal",
+          };
+          const stepResp = await apiRequest({
+            apiUrl,
+            token,
+            orgId,
+            path: `/api/v1/cli/executions/${executionId}/step-result`,
+            method: "POST",
+            body: {
+              step_index: stepIndex,
+              executor_ok: executorOk,
+              action,
+              result: row,
+              prev_screenshot_b64: prevB64,
+              curr_screenshot_b64: currB64,
+            },
+          });
+          if (stepResp && stepResp.result && typeof stepResp.result === "object") {
+            row = { ...row, ...stepResp.result };
+          }
+          stepsJson.push(row);
+          break;
+        }
+      }
+
+      const executorOk = !lastErr;
+      const currBuf = await page.screenshot({ type: "png" });
+      const prevB64 = prevBuf.toString("base64");
+      const currB64 = currBuf.toString("base64");
+      lastPrevScreenshotB64 = prevB64;
+      lastCurrScreenshotB64 = currB64;
+      if (firstPrevScreenshotB64 == null) firstPrevScreenshotB64 = prevB64;
+
+      let row = {
+        name: instruction,
+        description: instruction,
+        status: executorOk ? "passed" : "failed",
+        action: action
+          ? `${action.method}${action.selector ? ` ${action.selector}` : ""}`
+          : "",
+        error: lastErr || undefined,
+      };
+
+      const stepResp = await apiRequest({
+        apiUrl,
+        token,
+        orgId,
+        path: `/api/v1/cli/executions/${executionId}/step-result`,
+        method: "POST",
+        body: {
+          step_index: stepIndex,
+          executor_ok: executorOk,
+          action,
+          result: row,
+          prev_screenshot_b64: prevB64,
+          curr_screenshot_b64: currB64,
+        },
+      });
+
+      if (stepResp && stepResp.result && typeof stepResp.result === "object") {
+        row = { ...row, ...stepResp.result };
+      }
+      const passed = row.status === "passed";
+      if (!passed) runSuccess = false;
+      stepsJson.push(row);
+
+      if (!passed) {
+        runError = lastErr || row.step_thought || "Step failed";
+        break;
+      }
+      await page.waitForTimeout(300);
+    }
+
+    try {
+      lastCurrScreenshotB64 = (await page.screenshot({ type: "png" })).toString("base64");
+    } catch {
+      /* keep last step screenshot */
+    }
+  } finally {
+    await context.close().catch(() => {});
+    await browser.close().catch(() => {});
+    await browserServer.close().catch(() => {});
+  }
+
+  const runtimeSec = (Date.now() - started) / 1000;
+  const completeResp = await apiRequest({
+    apiUrl,
+    token,
+    orgId,
+    path: `/api/v1/cli/executions/${executionId}/complete`,
+    method: "POST",
+    body: {
+      success: runSuccess,
+      steps_json: stepsJson,
+      explanation: runSuccess ? "Local run completed" : runError || "Local run failed",
+      runtime_sec: runtimeSec,
+      error_message: runError,
+      final_screenshot_b64: lastCurrScreenshotB64,
+      prev_screenshot_b64: firstPrevScreenshotB64 || lastPrevScreenshotB64,
+      network_report: networkCollector.snapshot(),
+    },
+  });
+
+  if (completeResp && completeResp.status) {
+    runSuccess = completeResp.status === "completed";
+  }
+
+  return { success: runSuccess, stepsJson, error: runError };
+}
+
+export async function runLocalCi({
+  apiUrl,
+  token,
+  orgId,
+  projectId,
+  suiteId,
+  explicitIds,
+  resolveSavedJobs,
+  apiRequest,
+  failOnFailure,
+  device,
+  headless,
+  localConcurrency = 4,
+}) {
+  const savedJobs = await resolveSavedJobs({ apiUrl, token, orgId, projectId, suiteId, explicitIds });
+  if (!Array.isArray(savedJobs) || savedJobs.length === 0) {
+    throw new Error("No saved tests matched your selector.");
+  }
+
+  const startResp = await apiRequest({
+    apiUrl,
+    token,
+    orgId,
+    path: "/api/v1/ci/run",
+    method: "POST",
+    body: {
+      project_id: projectId ? String(projectId) : undefined,
+      suite_id: suiteId ? String(suiteId) : undefined,
+      job_ids: explicitIds.length > 0 ? explicitIds : savedJobs.map((j) => j.id),
+      execution_backend: "cli_local",
+    },
+  });
+
+  const runs = Array.isArray(startResp.runs) ? startResp.runs : [];
+  const started = runs.filter((r) => r.execution_job_id);
+  if (started.length === 0) throw new Error("Failed to start any local runs.");
+
+  const concurrency = Math.max(1, Number(localConcurrency) || 4);
+  const workerCount = Math.min(concurrency, started.length);
+
+  let passed = 0;
+  let failed = 0;
+
+  // eslint-disable-next-line no-console
+  console.log(`[qualty] Running ${started.length} local run(s) with concurrency=${workerCount}`);
+
+  let cursor = 0;
+  const worker = async (workerId) => {
+    while (true) {
+      const idx = cursor;
+      cursor += 1;
+      const run = started[idx];
+      if (!run) return;
+
+      const id = run.execution_job_id;
+      // eslint-disable-next-line no-console
+      console.log(
+        `[qualty][worker ${workerId}] Local run ${id} (${run.saved_job_name || run.saved_job_id})`
+      );
+      try {
+        const result = await runLocalExecution({
+          apiRequest,
+          apiUrl,
+          token,
+          orgId,
+          executionId: id,
+          device,
+          headless,
+        });
+        if (result.success) {
+          passed += 1;
+          // eslint-disable-next-line no-console
+          console.log(`[qualty] ${id} => passed`);
+        } else {
+          failed += 1;
+          // eslint-disable-next-line no-console
+          console.log(`[qualty] ${id} => failed: ${result.error || "unknown"}`);
+        }
+      } catch (err) {
+        failed += 1;
+        // eslint-disable-next-line no-console
+        console.error(`[qualty] ${id} => error: ${err.message || err}`);
+        try {
+          await apiRequest({
+            apiUrl,
+            token,
+            orgId,
+            path: `/api/v1/cli/executions/${id}/complete`,
+            method: "POST",
+            body: {
+              success: false,
+              steps_json: [],
+              explanation: String(err.message || err),
+              runtime_sec: 0,
+              error_message: String(err.message || err),
+            },
+          });
+        } catch {
+          /* best effort */
+        }
+      }
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: workerCount }, (_, idx) => worker(idx + 1))
+  );
+
+  if (started.length > 1) {
+    // eslint-disable-next-line no-console
+    console.log(`[qualty] Parallel local runs complete (${started.length} total).`);
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[qualty] Local summary: ${passed} passed, ${failed} failed.`);
+  if (failOnFailure && failed > 0) process.exit(1);
+}

package/bin/qualty.js

@@ -3,6 +3,7 @@
 import { appendFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import process from "node:process";
+import { runLocalCi } from "./local-runner.js";
 
 /** When unset, CLI uses Qualty development API. Override for production: QUALTY_API_URL=https://qualty-api-production.up.railway.app or local: http://localhost:8000 */
 const DEFAULT_QUALTY_API_URL = "https://qualty-api-development.up.railway.app";
@@ -38,9 +39,10 @@ function usage() {
   console.log(
     [
       "Usage:",
-      "  qualty connect --project <project-id> [--port 3000] [--api https://your-api] [--token <bearer-token>]",
-      "  qualty run --project <project-id> [--suite-id <suite-id>] [--ids <id1,id2>] [--api https://your-api] [--token <bearer-token>]",
+      "  qualty connect --project <project-id> [--port 3000] [--api https://your-api] [--token <bearer-token>] [--org <org-id>]",
+      "  qualty run --project <project-id> [--suite-id <suite-id>] [--ids <id1,id2>] [--local] [--api https://your-api] [--token <bearer-token>] [--org <org-id>]",
       "             [--poll-interval 5] [--timeout 30] [--fail-on-failure true] [--no-view-logs]",
+      "             [--local] [--device 1440x900] [--headed] [--local-concurrency 4]",
       "",
       "  After each run, logs include step results, explanation, and final evaluator output (dashboard \"View logs\" data).",
       "  Pass --no-view-logs for a short log only (e.g. very large evaluator text).",
@@ -49,16 +51,20 @@ function usage() {
       "Env vars:",
       `  QUALTY_API_URL    Backend API URL (default: ${DEFAULT_QUALTY_API_URL}; set for local/self-hosted)`,
       "  QUALTY_API_TOKEN  Bearer token used for auth",
+      "  QUALTY_ORG_ID     Org context for scoped API requests",
+      "  QUALTY_LOCAL_CONCURRENCY  Local parallel workers for --local runs (default: 4)",
     ].join("\n")
   );
 }
 
-async function apiRequest({ apiUrl, token, path, method = "GET", body }) {
+async function apiRequest({ apiUrl, token, orgId, path, method = "GET", body }) {
+  const normalizedOrgId = String(orgId || "").trim();
   const response = await fetch(`${apiUrl}${path}`, {
     method,
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${token}`,
+      ...(normalizedOrgId ? { "X-Qualty-Org-Id": normalizedOrgId } : {}),
     },
     body: body ? JSON.stringify(body) : undefined,
   });
@@ -77,7 +83,9 @@ function startCloudflared(token, port) {
     "--protocol",
     "http2",
     "--url",
-    `http://localhost:${port}`,
+    // Use 127.0.0.1 so cloudflared does not prefer [::1] (common on Linux/GitHub Actions) while
+    // Next/webpack dev servers often bind --hostname 127.0.0.1 only.
+    `http://127.0.0.1:${port}`,
     "run",
     "--token",
     token,
@@ -95,6 +103,7 @@ async function runConnect(args) {
   const port = Number(args.port || 3000);
   const apiUrl = resolveApiUrl(args);
   const token = args.token || process.env.QUALTY_API_TOKEN;
+  const orgId = args.org || process.env.QUALTY_ORG_ID;
 
   if (!projectId || !token) {
     usage();
@@ -107,6 +116,7 @@ async function runConnect(args) {
   const connect = await apiRequest({
     apiUrl,
     token,
+    orgId,
     path: "/api/v1/localhost/connect",
     method: "POST",
     body: { project_id: projectId, port },
@@ -114,7 +124,7 @@ async function runConnect(args) {
 
   const hostUrl = connect.localhost?.url;
   // eslint-disable-next-line no-console
-  console.log(`Connected ✅ ${hostUrl} -> http://localhost:${port}`);
+  console.log(`Connected ✅ ${hostUrl} -> http://127.0.0.1:${port}`);
 
   const cloudflaredToken = connect.tunnel?.token;
   if (!cloudflaredToken) {
@@ -127,6 +137,7 @@ async function runConnect(args) {
       await apiRequest({
         apiUrl,
         token,
+        orgId,
         path: "/api/v1/localhost/heartbeat",
         method: "POST",
         body: { project_id: projectId },
@@ -143,6 +154,7 @@ async function runConnect(args) {
       await apiRequest({
         apiUrl,
         token,
+        orgId,
         path: "/api/v1/localhost/disconnect",
         method: "POST",
         body: { project_id: projectId },
@@ -171,6 +183,17 @@ function parseBoolean(value, defaultValue) {
   throw new Error(`Invalid boolean value: ${value}`);
 }
 
+function resolveLocalConcurrency(args) {
+  const raw = args["local-concurrency"] ?? process.env.QUALTY_LOCAL_CONCURRENCY ?? 4;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(
+      `Invalid local concurrency: ${raw}. Use --local-concurrency <integer>=1 or QUALTY_LOCAL_CONCURRENCY>=1`
+    );
+  }
+  return n;
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -498,6 +521,7 @@ function printQualtyViewLogsReport(executionId, status) {
 async function runCi(args) {
   const apiUrl = resolveApiUrl(args);
   const token = args.token || process.env.QUALTY_API_TOKEN;
+  const orgId = args.org || process.env.QUALTY_ORG_ID;
   const projectId = args.project;
   const suiteId = args["suite-id"];
   const explicitIds = String(args.ids || "")
@@ -522,7 +546,7 @@ async function runCi(args) {
     throw new Error("Invalid --timeout. Must be > 0.");
   }
 
-  const savedJobs = await resolveSavedJobs({ apiUrl, token, projectId, suiteId, explicitIds });
+  const savedJobs = await resolveSavedJobs({ apiUrl, token, orgId, projectId, suiteId, explicitIds });
   if (!Array.isArray(savedJobs) || savedJobs.length === 0) {
     throw new Error(
       "No saved tests matched your selector. The test ID may be invalid, deleted, or outside your token authorization scope."
@@ -544,6 +568,7 @@ async function runCi(args) {
   const startResp = await apiRequest({
     apiUrl,
     token,
+    orgId,
     path: "/api/v1/ci/run",
     method: "POST",
     body: startPayload,
@@ -566,6 +591,7 @@ async function runCi(args) {
     const batch = await apiRequest({
       apiUrl,
       token,
+      orgId,
       path: "/api/v1/status/batch",
       method: "POST",
       body: { job_ids: executionJobIds },
@@ -631,7 +657,7 @@ async function runCi(args) {
   }
 }
 
-async function resolveSavedJobs({ apiUrl, token, projectId, suiteId, explicitIds }) {
+async function resolveSavedJobs({ apiUrl, token, orgId, projectId, suiteId, explicitIds }) {
   const query = new URLSearchParams();
   if (projectId) query.set("project_id", String(projectId));
   if (suiteId) query.set("suite_id", String(suiteId));
@@ -639,6 +665,7 @@ async function resolveSavedJobs({ apiUrl, token, projectId, suiteId, explicitIds
   return apiRequest({
     apiUrl,
     token,
+    orgId,
     path: `/api/v1/saved-jobs?${query.toString()}`,
   });
 }
@@ -646,6 +673,7 @@ async function resolveSavedJobs({ apiUrl, token, projectId, suiteId, explicitIds
 async function runResolve(args) {
   const apiUrl = resolveApiUrl(args);
   const token = args.token || process.env.QUALTY_API_TOKEN;
+  const orgId = args.org || process.env.QUALTY_ORG_ID;
   const projectId = args.project;
   const suiteId = args["suite-id"];
   const explicitIds = String(args.ids || "")
@@ -661,7 +689,7 @@ async function runResolve(args) {
     throw new Error("Provide --project, --suite-id, or --ids to select tests.");
   }
 
-  const savedJobs = await resolveSavedJobs({ apiUrl, token, projectId, suiteId, explicitIds });
+  const savedJobs = await resolveSavedJobs({ apiUrl, token, orgId, projectId, suiteId, explicitIds });
   if (!Array.isArray(savedJobs) || savedJobs.length === 0) {
     throw new Error(
       "No saved tests matched your selector. The test ID may be invalid, deleted, or outside your token authorization scope."
@@ -697,6 +725,26 @@ async function main() {
     return;
   }
   if (command === "run") {
+    if (parseBoolean(args.local, false)) {
+      await runLocalCi({
+        apiUrl: resolveApiUrl(args),
+        token: args.token || process.env.QUALTY_API_TOKEN,
+        orgId: args.org || process.env.QUALTY_ORG_ID,
+        projectId: args.project,
+        suiteId: args["suite-id"],
+        explicitIds: String(args.ids || "")
+          .split(",")
+          .map((id) => id.trim())
+          .filter(Boolean),
+        resolveSavedJobs,
+        apiRequest,
+        failOnFailure: parseBoolean(args["fail-on-failure"], true),
+        device: args.device || "1440x900",
+        headless: !parseBoolean(args.headed, false),
+        localConcurrency: resolveLocalConcurrency(args),
+      });
+      return;
+    }
     await runCi(args);
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualty",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Qualty CLI for localhost and CI test runs",
   "bin": {
     "qualty": "bin/qualty.js"
@@ -9,5 +9,8 @@
   "license": "UNLICENSED",
   "files": [
     "bin"
-  ]
+  ],
+  "dependencies": {
+    "playwright": "1.60.0"
+  }
 }